Base Wrapper"] --> B["markdown.tsx
React Component Entry"] +B --> C["utils.ts
Parse/Highlight/Sanitize/Mermaid"] +B --> D["sanitize.ts
HTML Filtering"] +B --> E["markdown.less
General Styles"] +B --> F["prism.less
Code Highlight Theme"] +B --> G["html-tags.ts
Allowlisted Tags"] +end +subgraph "Backend" +H["backend/base/markdown/__init__.py
Gradio Component Definition"] +end +A --> H +H --> B +``` + +**Diagram sources** + +- [frontend/base/markdown/Index.svelte:1-63](file://frontend/base/markdown/Index.svelte#L1-L63) +- [frontend/base/markdown/markdown.tsx:1-34](file://frontend/base/markdown/markdown.tsx#L1-L34) +- [frontend/globals/components/markdown/index.tsx:1-272](file://frontend/globals/components/markdown/index.tsx#L1-L272) +- [frontend/globals/components/markdown/utils.ts:1-411](file://frontend/globals/components/markdown/utils.ts#L1-L411) +- [frontend/globals/components/markdown/sanitize.ts:1-26](file://frontend/globals/components/markdown/sanitize.ts#L1-L26) +- [frontend/globals/components/markdown/markdown.less:1-140](file://frontend/globals/components/markdown/markdown.less#L1-L140) +- [frontend/globals/components/markdown/prism.less:1-185](file://frontend/globals/components/markdown/prism.less#L1-L185) +- [frontend/globals/components/markdown/html-tags.ts:1-210](file://frontend/globals/components/markdown/html-tags.ts#L1-L210) +- [backend/modelscope_studio/components/base/markdown/**init**.py:1-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L1-L174) + +**Section sources** + +- [frontend/base/markdown/Index.svelte:1-63](file://frontend/base/markdown/Index.svelte#L1-L63) +- [frontend/base/markdown/markdown.tsx:1-34](file://frontend/base/markdown/markdown.tsx#L1-L34) +- [frontend/globals/components/markdown/index.tsx:1-272](file://frontend/globals/components/markdown/index.tsx#L1-L272) +- [backend/modelscope_studio/components/base/markdown/**init**.py:1-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L1-L174) + +## Core Components + +- Frontend React component: Responsible for Markdown parsing, code highlighting, math formula rendering, Mermaid diagram rendering, HTML security filtering, and copy button interactions. +- Backend Gradio component: Responsible for parameter passthrough, event binding (such as copy/change/mouse events), default values, and example data. + +Key responsibility division: + +- Parsing and rendering: Marked + marked-highlight (Prism) + custom extensions (LaTeX, Mermaid) +- Security filtering: Amuchina + external link handling +- Math formulas: KaTeX loaded on-demand with auto-rendering +- Diagrams: Mermaid loaded on-demand with error fallback +- Styles: General styles + Prism theme variables + +**Section sources** + +- [frontend/globals/components/markdown/index.tsx:27-48](file://frontend/globals/components/markdown/index.tsx#L27-L48) +- [frontend/globals/components/markdown/utils.ts:286-344](file://frontend/globals/components/markdown/utils.ts#L286-L344) +- [backend/modelscope_studio/components/base/markdown/**init**.py:11-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L11-L174) + +## Architecture Overview + +The Markdown component receives parameters from the backend, and after being wrapped by the frontend, performs parsing and rendering. The parsing phase can enable line breaks, header links, LaTeX, and Mermaid extensions; the rendering phase integrates Prism for code highlighting, KaTeX/Mermaid for math and diagram rendering, and applies security filtering to the output HTML. + +```mermaid +sequenceDiagram +participant Backend as "Backend Component" +participant Wrapper as "Frontend Wrapper (Svelte)" +participant ReactComp as "React Component" +participant Parser as "Marked/Prism/KaTeX/Mermaid" +participant Sanitizer as "HTML Filter" +Backend->>Wrapper : Pass parameters (value, config) +Wrapper->>ReactComp : Render component and inject props +ReactComp->>Parser : Initialize parser (with extensions/highlighting) +ReactComp->>Parser : Parse Markdown +Parser-->>ReactComp : Return HTML fragment +ReactComp->>Sanitizer : Optional security filtering +Sanitizer-->>ReactComp : Return safe HTML +ReactComp-->>Wrapper : Render final content +``` + +**Diagram sources** + +- [frontend/base/markdown/Index.svelte:19-62](file://frontend/base/markdown/Index.svelte#L19-L62) +- [frontend/globals/components/markdown/index.tsx:86-92](file://frontend/globals/components/markdown/index.tsx#L86-L92) +- [frontend/globals/components/markdown/utils.ts:286-344](file://frontend/globals/components/markdown/utils.ts#L286-L344) +- [frontend/globals/components/markdown/sanitize.ts:12-25](file://frontend/globals/components/markdown/sanitize.ts#L12-L25) + +## Detailed Component Analysis + +### Property Definitions and Default Values + +- `value`: String, Markdown content +- `sanitizeHtml`: Boolean, whether to enable HTML security filtering, enabled by default +- `latexDelimiters`: Array, custom LaTeX delimiters, containing left/right/display triplets +- `lineBreaks`: Boolean, whether to convert newlines to `
`, enabled by default +- `headerLinks`: Boolean, whether to generate header anchors and link icons, disabled by default +- `showCopyButton`: Boolean, whether to show the overall copy button +- `rtl`: Boolean, whether to enable right-to-left layout +- `themeMode`: String, theme mode (`light`/`dark`), used for styles and Mermaid theme +- `rootUrl`: String, root path, used for external link detection and resource location +- `allowTags`: Boolean or string array, controls the allowed HTML/SVG tags +- `onCopy`: Callback, triggered on successful copy +- `onChange`: Callback, triggered when rendering is complete +- `copyButtons`: Custom copy button collection (via slots) + +The default LaTeX delimiter set contains multiple common expression groups (inline/block, parenthesis variants, etc.). + +**Section sources** + +- [frontend/globals/components/markdown/index.tsx:27-48](file://frontend/globals/components/markdown/index.tsx#L27-L48) +- [frontend/globals/components/markdown/index.tsx:50-60](file://frontend/globals/components/markdown/index.tsx#L50-L60) +- [backend/modelscope_studio/components/base/markdown/**init**.py:54-141](file://backend/modelscope_studio/components/base/markdown/__init__.py#L54-L141) + +### Rendering Options and Parser Configuration + +- Line breaks: Controlled by the `breaks` option of Marked +- Header links: When `headerLinks` is enabled, IDs are generated for headers and anchor link icons are inserted +- LaTeX: Custom tokenizer supports multiple delimiter groups, rendered as block-level containers +- Mermaid: Custom tokenizer supports marking code blocks as `mermaid`, rendered as diagrams +- Code highlighting: Integrates Prism via `marked-highlight`, renders by language class name +- HTML sanitization: External links get `target`/`rel` attributes, and Amuchina allowlist filtering is applied + +```mermaid +flowchart TD +Start(["Start"]) --> Init["Initialize Marked
Enable GFM/line breaks/highlighting"] +Init --> Header{"Enable header links?"} +Header --> |Yes| AddHeader["Register header extension
Generate ID/anchor"] +Header --> |No| SkipHeader["Skip header extension"] +AddHeader --> Ext +SkipHeader --> Ext +Ext["Register LaTeX/Mermaid extensions"] --> Parse["Parse Markdown"] +Parse --> Math{"LaTeX syntax present?"} +Math --> |Yes| LoadKatex["Load KaTeX on-demand and render"] +Math --> |No| SkipMath["Skip math rendering"] +LoadKatex --> Safe{"HTML filtering enabled?"} +SkipMath --> Safe +Safe --> |Yes| Sanitize["External link handling / allowlist filtering"] +Safe --> |No| NoSanitize["Preserve original HTML"] +Sanitize --> Render["Render result"] +NoSanitize --> Render +Render --> End(["End"]) +``` + +**Diagram sources** + +- [frontend/globals/components/markdown/utils.ts:286-344](file://frontend/globals/components/markdown/utils.ts#L286-L344) +- [frontend/globals/components/markdown/index.tsx:107-138](file://frontend/globals/components/markdown/index.tsx#L107-L138) +- [frontend/globals/components/markdown/sanitize.ts:12-25](file://frontend/globals/components/markdown/sanitize.ts#L12-L25) + +**Section sources** + +- [frontend/globals/components/markdown/utils.ts:286-344](file://frontend/globals/components/markdown/utils.ts#L286-L344) +- [frontend/globals/components/markdown/index.tsx:107-138](file://frontend/globals/components/markdown/index.tsx#L107-L138) + +### Code Highlighting and Language Support + +- Highlighting library: Prism.js (integrated via `marked-highlight`) +- Language support: Built-in loading of commonly used languages including Python, LaTeX, Bash, JSX, TypeScript, and TSX +- Rendering method: Dynamically selects Prism language based on code block language; unrecognized languages are kept as-is +- Theme: Applied via `prism.less` theme variables, with dark color scheme in dark mode + +```mermaid +classDiagram +class Prism { ++highlight(code, lang, alias) ++languages +} +class MarkedHighlight { ++highlight(code, lang) +} +class MarkdownUtils { ++create_marked() +} +MarkdownUtils --> MarkedHighlight : "uses" +MarkedHighlight --> Prism : "calls" +``` + +**Diagram sources** + +- [frontend/globals/components/markdown/utils.ts:9-16](file://frontend/globals/components/markdown/utils.ts#L9-L16) +- [frontend/globals/components/markdown/utils.ts:303-310](file://frontend/globals/components/markdown/utils.ts#L303-L310) + +**Section sources** + +- [frontend/globals/components/markdown/utils.ts:9-16](file://frontend/globals/components/markdown/utils.ts#L9-L16) +- [frontend/globals/components/markdown/utils.ts:303-310](file://frontend/globals/components/markdown/utils.ts#L303-L310) + +### HTML Security Filtering and Allowlist + +- External link handling: Automatically sets `target="_blank"` and `rel="noopener noreferrer"` for external links +- Allowlist filtering: Uses Amuchina to sanitize HTML, retaining only standard HTML and SVG tags +- Allowed tags: Supports boolean toggle or explicit array; tags not in the allowlist are escaped + +```mermaid +flowchart TD +A["Input HTML"] --> B["Traverse nodes (A/IMG, etc.)"] +B --> C{"Is external link?"} +C --> |Yes| D["Set target/_blank + rel"] +C --> |No| E["Keep unchanged"] +D --> F["Amuchina allowlist filtering"] +E --> F +F --> G["Output safe HTML"] +``` + +**Diagram sources** + +- [frontend/globals/components/markdown/sanitize.ts:12-25](file://frontend/globals/components/markdown/sanitize.ts#L12-L25) +- [frontend/globals/components/markdown/html-tags.ts:206-210](file://frontend/globals/components/markdown/html-tags.ts#L206-L210) + +**Section sources** + +- [frontend/globals/components/markdown/sanitize.ts:1-26](file://frontend/globals/components/markdown/sanitize.ts#L1-L26) +- [frontend/globals/components/markdown/html-tags.ts:1-210](file://frontend/globals/components/markdown/html-tags.ts#L1-L210) + +### Style Customization and Theme Variables + +- CSS class names: The component root element includes classes such as `ms-gr-markdown`, `md`, and `prose`, making overrides easy +- Theme variables: CSS variables control colors, spacing, border radius, shadows, etc. +- Code highlighting theme: `prism.less` provides light and dark color schemes, switching with `themeMode` +- Copy button: Absolutely positioned with support for custom button collections (copy/copied states) + +```mermaid +classDiagram +class Styles { ++ms-gr-markdown ++md ++prose ++code_wrap ++copy_code_button +} +class ThemeVars { ++--block-background-fill ++--border-color-primary ++--body-text-color ++--code-background-fill ++... +} +Styles --> ThemeVars : "uses" +``` + +**Diagram sources** + +- [frontend/globals/components/markdown/markdown.less:1-140](file://frontend/globals/components/markdown/markdown.less#L1-L140) +- [frontend/globals/components/markdown/prism.less:1-185](file://frontend/globals/components/markdown/prism.less#L1-L185) + +**Section sources** + +- [frontend/globals/components/markdown/markdown.less:1-140](file://frontend/globals/components/markdown/markdown.less#L1-L140) +- [frontend/globals/components/markdown/prism.less:1-185](file://frontend/globals/components/markdown/prism.less#L1-L185) + +### Usage Examples + +- Basic text rendering: Pass a Markdown string directly +- Show copy button: Enable `showCopyButton` or provide custom buttons via slots +- Custom buttons: Use Slot to inject two buttons (e.g., copy/copied states) + +Reference example scripts and documentation: + +- Basic example: [basic.py:1-10](file://docs/components/base/markdown/demos/basic.py#L1-L10) +- Custom copy buttons: [custom_copy_buttons.py:1-21](file://docs/components/base/markdown/demos/custom_copy_buttons.py#L1-L21) +- Component description: [README.md:1-13](file://docs/components/base/markdown/README.md#L1-L13) + +**Section sources** + +- [docs/components/base/markdown/demos/basic.py:1-10](file://docs/components/base/markdown/demos/basic.py#L1-L10) +- [docs/components/base/markdown/demos/custom_copy_buttons.py:1-21](file://docs/components/base/markdown/demos/custom_copy_buttons.py#L1-L21) +- [docs/components/base/markdown/README.md:1-13](file://docs/components/base/markdown/README.md#L1-L13) + +## Dependency Analysis + +- Frontend dependencies + - Marked: Markdown parsing and rendering + - marked-highlight + Prism: Code highlighting + - KaTeX: Math formula rendering (loaded on-demand) + - Mermaid: Diagram rendering (loaded on-demand) + - Amuchina: HTML allowlist filtering + - github-slugger: Header ID generation +- Backend dependencies + - Gradio event listeners: copy/change/mouse series + - Frontend directory resolution: `resolve_frontend_dir("markdown")` + +```mermaid +graph LR +A["Marked"] --> B["marked-highlight"] +B --> C["Prism"] +A --> D["LaTeX Tokenizer"] +A --> E["Mermaid Tokenizer"] +A --> F["HTML Renderer"] +F --> G["Amuchina"] +A --> H["KaTeX (on-demand)"] +A --> I["Mermaid (on-demand)"] +``` + +**Diagram sources** + +- [frontend/globals/components/markdown/utils.ts:6-18](file://frontend/globals/components/markdown/utils.ts#L6-L18) +- [frontend/globals/components/markdown/utils.ts:286-344](file://frontend/globals/components/markdown/utils.ts#L286-L344) + +**Section sources** + +- [frontend/globals/components/markdown/utils.ts:6-18](file://frontend/globals/components/markdown/utils.ts#L6-L18) +- [backend/modelscope_studio/components/base/markdown/**init**.py:15-46](file://backend/modelscope_studio/components/base/markdown/__init__.py#L15-L46) + +## Performance Considerations + +- Lazy loading + - KaTeX: Styles and auto-render module are only loaded when math formulas first appear + - Mermaid: Loaded asynchronously and executed on the next frame before rendering + - Prism: Highlights on-demand during the parsing phase to avoid unnecessary overhead +- Caching strategy + - Loaded KaTeX modules are globally flagged to avoid duplicate imports + - Mermaid initialization parameters are fixed to reduce repeated initialization costs +- Rendering timing + - `requestAnimationFrame` is used to defer rendering to the browser's idle frame + - Re-parsing and re-rendering only occur when content changes +- Security filtering + - Filtering is only performed when `sanitizeHtml` is enabled, avoiding unnecessary DOM parsing + +**Section sources** + +- [frontend/globals/components/markdown/index.tsx:140-173](file://frontend/globals/components/markdown/index.tsx#L140-L173) +- [frontend/globals/components/markdown/utils.ts:177-223](file://frontend/globals/components/markdown/utils.ts#L177-L223) + +## Troubleshooting Guide + +- Copy button not working + - Check whether the container correctly binds the click event (`bind_copy_event`) + - Confirm whether the `copyButtons` slot is properly injected +- Math formulas not rendering + - Confirm whether `latexDelimiters` is correctly configured + - Check if `sanitizeHtml` is enabled and causing scripts to be removed +- Mermaid diagram errors + - Check the console error log + - Confirm that the mermaid code block is properly closed with correct syntax + - Check whether `themeMode` matches the page theme +- External links not opening in new window + - Confirm that `rootUrl` matches the link's origin + - Check whether `target`/`rel` is correctly set in the sanitize flow +- Code highlighting not working + - Confirm whether the language identifier is in the Prism supported list + - Check whether `prism.less` is correctly imported and theme variables are taking effect + +**Section sources** + +- [frontend/globals/components/markdown/utils.ts:346-380](file://frontend/globals/components/markdown/utils.ts#L346-L380) +- [frontend/globals/components/markdown/sanitize.ts:12-25](file://frontend/globals/components/markdown/sanitize.ts#L12-L25) +- [frontend/globals/components/markdown/utils.ts:177-223](file://frontend/globals/components/markdown/utils.ts#L177-L223) + +## Conclusion + +The Markdown component of ModelScope Studio provides rich rendering capabilities and a flexible customization interface while ensuring security and accessibility. Through the combination of Marked + Prism + KaTeX + Mermaid, it meets diverse needs from basic text to complex formulas and diagrams; allowlist filtering and external link handling ensure safe output; theme variables and style class names achieve consistent visual style and good customizability. + +## Appendix + +### Backend Component Parameter Overview + +- Parameter names: `value`, `rtl`, `latex_delimiters`, `sanitize_html`, `line_breaks`, `header_links`, `allow_tags`, `show_copy_button`, `copy_buttons` +- Events: `change`, `copy`, `click`, `dblclick`, `mousedown`, `mouseup`, `mouseover`, `mouseout`, `mousemove`, `scroll` +- Examples: `example_payload`/`example_value` returns a simple Markdown string + +**Section sources** + +- [backend/modelscope_studio/components/base/markdown/**init**.py:54-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L54-L174) + +### Frontend Component Property Overview + +- `value`, `sanitizeHtml`, `latexDelimiters`, `lineBreaks`, `headerLinks`, `showCopyButton`, `rtl`, `themeMode`, `rootUrl`, `allowTags`, `onCopy`, `onChange`, `copyButtons` +- Default LaTeX delimiter set, copy button icons and feedback, Mermaid error fallback + +**Section sources** + +- [frontend/globals/components/markdown/index.tsx:27-48](file://frontend/globals/components/markdown/index.tsx#L27-L48) +- [frontend/globals/components/markdown/index.tsx:50-60](file://frontend/globals/components/markdown/index.tsx#L50-L60) diff --git a/.wiki/en/API Reference/JavaScript API/React Component Bridge API.md b/.wiki/en/API Reference/JavaScript API/React Component Bridge API.md new file mode 100644 index 00000000..2861584f --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/React Component Bridge API.md @@ -0,0 +1,378 @@ +# React Component Bridge API + + +**Files referenced in this document** +- [frontend/svelte-preprocess-react/index.ts](file://frontend/svelte-preprocess-react/index.ts) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts](file://frontend/svelte-preprocess-react/sveltify.svelte.ts) +- [frontend/svelte-preprocess-react/inject.ts](file://frontend/svelte-preprocess-react/inject.ts) +- [frontend/svelte-preprocess-react/react-slot.tsx](file://frontend/svelte-preprocess-react/reactSlot.tsx) +- [frontend/svelte-preprocess-react/internal/types.ts](file://frontend/svelte-preprocess-react/internal/types.ts) +- [frontend/svelte-preprocess-react/react-contexts/index.ts](file://frontend/svelte-preprocess-react/react-contexts/index.ts) +- [frontend/utils/convertToCamelCase.ts](file://frontend/utils/convertToCamelCase.ts) +- [frontend/utils/createFunction.ts](file://frontend/utils/createFunction.ts) +- [frontend/utils/patchProps.tsx](file://frontend/utils/patchProps.tsx) +- [frontend/utils/hooks/useMemoizedEqualValue.ts](file://frontend/utils/hooks/useMemoizedEqualValue.ts) +- [frontend/utils/style.ts](file://frontend/utils/style.ts) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/base/text/text.tsx](file://frontend/base/text/text.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Standard Usage and Example Paths](#appendix-standard-usage-and-example-paths) + +## Introduction + +This document provides comprehensive API documentation for the React component bridge system in ModelScope Studio, focusing on the following aspects: + +- Conversion mechanism from React components to Svelte components (sveltify) +- Property mapping, event binding, and state synchronization +- Event handling (bubbling, delegation, custom events) +- Corresponding lifecycle hook implementations in Svelte +- Property conversion rules (camelCase, booleans, function properties) +- Context system (React Context and Svelte Context interoperability) +- Performance optimization (lazy loading, caching, memory management) +- Error handling and debugging techniques + +## Project Structure + +The bridge system consists of three main parts: + +- Injection layer: Initializes the global runtime environment and library bridging +- Conversion layer: `sveltify` wraps React components as Svelte components +- Rendering layer: `ReactSlot` renders Svelte slot content as React elements, with support for cloning and property injection + +```mermaid +graph TB +Inject["Injection Layer
inject.ts"] --> Types["Type Definitions
internal/types.ts"] +Inject --> ReactContexts["React Contexts
react-contexts/index.ts"] +Sveltify["Conversion Layer
sveltify.svelte.ts"] --> Bridge["Bridge
Bridge.svelte"] +Sveltify --> ReactWrapper["React Wrapper
ReactWrapper.svelte"] +ReactSlot["Rendering Layer
react-slot.tsx"] --> Portal["DOM Portal
createPortal"] +Utils["Utilities
convertToCamelCase.ts
createFunction.ts
patchProps.tsx
style.ts"] --> Sveltify +Utils --> ReactSlot +DemoBtn["Example Component
antd/button/button.tsx"] --> Sveltify +DemoForm["Example Component
antd/form/form.tsx"] --> Sveltify +DemoText["Example Component
base/text/text.tsx"] --> Sveltify +``` + +Diagram sources + +- [frontend/svelte-preprocess-react/inject.ts:1-103](file://frontend/svelte-preprocess-react/inject.ts#L1-L103) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/svelte-preprocess-react/internal/types.ts:1-79](file://frontend/svelte-preprocess-react/internal/types.ts#L1-L79) +- [frontend/svelte-preprocess-react/react-contexts/index.ts:1-123](file://frontend/svelte-preprocess-react/react-contexts/index.ts#L1-L123) +- [frontend/utils/convertToCamelCase.ts:1-22](file://frontend/utils/convertToCamelCase.ts#L1-L22) +- [frontend/utils/createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/base/text/text.tsx:1-11](file://frontend/base/text/text.tsx#L1-L11) + +Section sources + +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) +- [frontend/svelte-preprocess-react/inject.ts:1-103](file://frontend/svelte-preprocess-react/inject.ts#L1-L103) + +## Core Components + +- `sveltify`: Wraps any React component as a Svelte component; responsible for property passthrough, slot mapping, event bridging, and tree node construction. +- `ReactSlot`: Renders Svelte slot content as React elements, supporting DOM cloning, event listener migration, and style/class name injection. +- Type system: Unified event naming, property exclusion, and Svelte/SvelteKit type adaptation. +- Context system: Bridge and merge strategy between React Context and Svelte. + +Section sources + +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:27-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L27-L119) +- [frontend/svelte-preprocess-react/react-slot.tsx:8-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L8-L224) +- [frontend/svelte-preprocess-react/internal/types.ts:4-79](file://frontend/svelte-preprocess-react/internal/types.ts#L4-L79) +- [frontend/svelte-preprocess-react/react-contexts/index.ts:1-123](file://frontend/svelte-preprocess-react/react-contexts/index.ts#L1-L123) + +## Architecture Overview + +The following diagram shows the complete call chain and data flow from the Svelte consumer to the React component: + +```mermaid +sequenceDiagram +participant Svelte as "Svelte Component" +participant Sveltify as "sveltify Wrapper" +participant Bridge as "Bridge" +participant ReactWrapper as "ReactWrapper" +participant ReactComp as "React Component" +participant DOM as "DOM Portal" +Svelte->>Sveltify : Pass props and slots +Sveltify->>Bridge : Create/update tree node +Bridge->>ReactWrapper : Render ReactWrapper +ReactWrapper->>ReactComp : Pass props/events/slots +ReactComp-->>DOM : Render to target container via createPortal +DOM-->>Svelte : Slot content becomes visible +``` + +Diagram sources + +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:40-104](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L40-L104) +- [frontend/svelte-preprocess-react/react-slot.tsx:109-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L224) + +## Detailed Component Analysis + +### sveltify Function and Conversion Mechanism + +- Functional overview + - Wraps React components as Svelte components, automatically handling property passthrough, slot mapping, event bridging, and tree rendering. + - Supports an optional ignore-render option (`ignore`) to control whether a node participates in rendering. +- Key points + - Initializes shared root node and bridge container to ensure the React root is mounted at the document head. + - Generates a unique key for each Svelte instance and establishes parent-child node relationships. + - Completes rendering and updates through cooperation between `Bridge` and `ReactWrapper`. + - Provides a Promise-based return; can only be used after global initialization is complete. +- Parameters and return value + - First parameter: React component type (can include generic slot declarations). + - Second parameter: Optional configuration object, currently supporting the `ignore` field. + - Returns: `Sveltified` type Svelte component (Promise or already-initialized version). + +```mermaid +flowchart TD +Start(["Call sveltify"]) --> InitRoot["Initialize shared root node and bridge container"] +InitRoot --> BuildNode["Build tree node
Set key/ignore/reactComponent"] +BuildNode --> AttachParent["Attach to parent node
Add to nodes and trigger rerender"] +AttachParent --> Render["Call Bridge to render"] +Render --> Done(["Return Sveltified component"]) +``` + +Diagram sources + +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:40-104](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L40-L104) + +Section sources + +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:27-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L27-L119) +- [frontend/svelte-preprocess-react/index.ts:6-8](file://frontend/svelte-preprocess-react/index.ts#L6-L8) + +### ReactSlot Slot Rendering and Event Handling + +- Functional overview + - Renders Svelte slot content as React elements, supporting DOM cloning, event listener migration, and style/class name injection. + - Optionally observes attribute changes to accommodate dynamic rendering scenarios (such as table column rendering). +- Key points + - Cloning strategy: Traverses child nodes, copies text nodes and element nodes; deep-clones React elements and migrates internally registered side effects. + - Event migration: Reads the event listener list on elements and re-binds them to cloned nodes. + - Property injection: Supports injection of `className` and `style`, converting React style objects to inline styles. + - Observer: Uses a debounced `MutationObserver` to monitor slot changes, ensuring dynamic content is reflected in a timely manner. +- Parameters + - `slot`: The `HTMLElement` corresponding to the slot. + - `clone`: Whether to clone the DOM (default: `false`). + - `className`/`style`: Injected class name and style object. + - `observeAttributes`: Whether to observe attribute changes (default: `false`). + +```mermaid +flowchart TD +Enter(["ReactSlot Render"]) --> CheckSlot{"Does slot exist?"} +CheckSlot --> |No| Exit["Exit"] +CheckSlot --> |Yes| CloneMode{"clone is true?"} +CloneMode --> |Yes| Clone["Clone DOM tree
Migrate event listeners"] +CloneMode --> |No| Mount["Mount directly to container"] +Clone --> Observe{"Observer enabled?"} +Observe --> |Yes| Debounce["Re-render after debounce"] +Observe --> |No| MountProps["Inject className/style and mount"] +Debounce --> Render["Re-clone and render"] +Render --> MountProps +MountProps --> Cleanup["Clean up DOM and observer on unmount"] +Cleanup --> Exit +``` + +Diagram sources + +- [frontend/svelte-preprocess-react/react-slot.tsx:16-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L16-L224) + +Section sources + +- [frontend/svelte-preprocess-react/react-slot.tsx:8-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L8-L224) + +### Type System and Event Mapping + +- Event naming and mapping + - React-side event properties start with uppercase (e.g., `onClick`); Svelte-side event handlers use the `on` prefix (e.g., `onClick` corresponds to `on-click`). + - Type utilities map React event properties to Svelte event handler signatures. +- Property exclusion + - React event properties are excluded from regular properties to avoid conflicts when passed to Svelte components. +- Svelte Props adaptation + - The `children` property is adapted to Svelte's `Snippet` type to support slots and fragments. + +Section sources + +- [frontend/svelte-preprocess-react/internal/types.ts:4-79](file://frontend/svelte-preprocess-react/internal/types.ts#L4-L79) + +### Context System (React Context and Svelte Interoperability) + +- React Context + - Provides contexts such as `IconFont`, `FormItem`, `AutoComplete`, `Suggestion`, and `SuggestionOpen` for sharing state and callbacks between components. +- Svelte-side bridging + - `ContextPropsContext` reads context values inside `ReactSlot`, supporting force-clone and parameter change detection. + - Supports context merge strategy to prevent state loss caused by duplicate Providers. +- Usage recommendations + - In scenarios requiring dynamic rendering or DOM cloning, combine `forceClone` with `observeAttributes` for improved stability. + +Section sources + +- [frontend/svelte-preprocess-react/react-contexts/index.ts:1-123](file://frontend/svelte-preprocess-react/react-contexts/index.ts#L1-L123) + +### Property Conversion Rules and Utilities + +- CamelCase conversion + - Converts underscore-style keys to lowerCamelCase or UpperCamelCase to maintain consistency with React properties. +- Boolean value handling + - Utility functions correctly map boolean values to React properties. +- Function property binding + - Supports function definitions in string form, automatically parsed into executable functions, making it convenient to pass callback logic from the outside. +- Slot property patching + - Special properties like `key` are internally stashed and restored to avoid conflicts with Svelte's internal mechanisms. + +Section sources + +- [frontend/utils/convertToCamelCase.ts:1-22](file://frontend/utils/convertToCamelCase.ts#L1-L22) +- [frontend/utils/createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) + +### Event Handling Mechanism + +- Event bubbling and delegation + - `ReactSlot` migrates event listeners during cloning to ensure cloned elements can still respond to events. +- Custom events + - Custom callbacks are injected into React components as stable functions through `ContextPropsContext` and the `useFunction` hook. +- Styles and units + - React style objects are converted to inline style strings or objects, with pixel units automatically added (except for unitless properties). + +Section sources + +- [frontend/svelte-preprocess-react/react-slot.tsx:67-96](file://frontend/svelte-preprocess-react/react-slot.tsx#L67-L96) +- [frontend/utils/hooks/useMemoizedEqualValue.ts:1-15](file://frontend/utils/hooks/useMemoizedEqualValue.ts#L1-L15) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) + +### Lifecycle Hook Implementations in Svelte + +- Initialization + - A global initialization Promise ensures the runtime environment is ready before rendering. +- Update + - Each node change triggers a rerender; Bridge re-renders `ReactWrapper` and the subtree. +- Destruction + - Cleans up DOM nodes and observers, releasing resources. + +Section sources + +- [frontend/svelte-preprocess-react/inject.ts:95-103](file://frontend/svelte-preprocess-react/inject.ts#L95-L103) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:75-82](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L75-L82) +- [frontend/svelte-preprocess-react/react-slot.tsx:204-212](file://frontend/svelte-preprocess-react/react-slot.tsx#L204-L212) + +## Dependency Analysis + +- Runtime dependencies + - Libraries such as React, ReactDOM, `@ant-design/cssinjs`, `@ant-design/icons`, `@ant-design/x`, and `dayjs` are provided via global injection. +- Utility dependencies + - `lodash-es` provides utilities such as `isEqual`, `debounce`, and `noop`. +- Component dependencies + - `sveltify` depends on `Bridge` and `ReactWrapper` to complete rendering; `ReactSlot` depends on `createPortal` and style utilities. + +```mermaid +graph LR +Inject["inject.ts"] --> Libs["Global Library Injection"] +Sveltify["sveltify.svelte.ts"] --> Bridge["Bridge.svelte"] +Sveltify --> ReactWrapper["ReactWrapper.svelte"] +ReactSlot["react-slot.tsx"] --> Portal["createPortal"] +Utils["Utilities"] --> Sveltify +Utils --> ReactSlot +``` + +Diagram sources + +- [frontend/svelte-preprocess-react/inject.ts:20-85](file://frontend/svelte-preprocess-react/inject.ts#L20-L85) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-7](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L7) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-6](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L6) + +Section sources + +- [frontend/svelte-preprocess-react/inject.ts:1-103](file://frontend/svelte-preprocess-react/inject.ts#L1-L103) + +## Performance Considerations + +- Lazy loading and deferred initialization + - The global initialization Promise and shared root node prevent repeated mounting and multiple initializations. +- Caching and deduplication + - `useMemoizedEqualValue` and `ContextPropsContext` change detection reduce unnecessary re-renders. +- Memory management + - On unmount, disconnects `MutationObserver`, removes DOM nodes and bridge containers to prevent memory leaks. +- Rendering optimization + - `ReactSlot`'s cloning and observation use a debounce strategy to reduce performance pressure from frequent changes. + +Section sources + +- [frontend/svelte-preprocess-react/react-slot.tsx:180-198](file://frontend/svelte-preprocess-react/react-slot.tsx#L180-L198) +- [frontend/utils/hooks/useMemoizedEqualValue.ts:1-15](file://frontend/utils/hooks/useMemoizedEqualValue.ts#L1-L15) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:67-82](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L67-L82) + +## Troubleshooting Guide + +- Slot not displaying + - Check whether the slot exists and has not been destroyed; confirm `clone` mode and `observeAttributes` settings. +- Events not working + - Confirm whether event listeners are migrated along with cloning; check if event listeners are overwritten or removed. +- Style anomalies + - Check whether style objects are correctly converted to inline styles; confirm that units are as expected. +- Performance issues + - Use `forceClone` and debounced observers judiciously; avoid re-renders caused by frequent changes. +- Context conflicts + - Use the merge strategy and parameter change detection of `ContextPropsProvider` to prevent state loss from duplicate Providers. + +Section sources + +- [frontend/svelte-preprocess-react/react-slot.tsx:156-212](file://frontend/svelte-preprocess-react/react-slot.tsx#L156-L212) +- [frontend/utils/style.ts:39-77](file://frontend/utils/style.ts#L39-L77) +- [frontend/svelte-preprocess-react/react-contexts/index.ts:67-123](file://frontend/svelte-preprocess-react/react-contexts/index.ts#L67-L123) + +## Conclusion + +ModelScope Studio's React component bridge system achieves seamless collaboration between React and Svelte through `sveltify` and `ReactSlot`. Its design emphasizes: + +- Clear type constraints and event mapping +- Robust slot rendering and event migration +- Extensible context system and performance optimization strategies +- Clear lifecycle management and resource reclamation + +This system provides a unified component bridging solution for complex frontend applications, ensuring both a good development experience and runtime performance and stability. + +## Appendix: Standard Usage and Example Paths + +- Simple component bridging + - Example: Basic text component bridge + - Path: [frontend/base/text/text.tsx:1-11](file://frontend/base/text/text.tsx#L1-L11) +- Complex component bridging (with slots and events) + - Example: Button component bridge (icon and loading state slots) + - Path: [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- Form component bridging (with state synchronization and action dispatch) + - Example: Form component bridge (value synchronization, action reset, event forwarding) + - Path: [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- Key points for using sveltify + - Path: [frontend/svelte-preprocess-react/sveltify.svelte.ts:27-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L27-L119) +- Key points for using ReactSlot + - Path: [frontend/svelte-preprocess-react/react-slot.tsx:8-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L8-L224) +- Type and event mapping + - Path: [frontend/svelte-preprocess-react/internal/types.ts:4-79](file://frontend/svelte-preprocess-react/internal/types.ts#L4-L79) +- Context system + - Path: [frontend/svelte-preprocess-react/react-contexts/index.ts:1-123](file://frontend/svelte-preprocess-react/react-contexts/index.ts#L1-L123) +- Property conversion and function binding + - Path: [frontend/utils/convertToCamelCase.ts:1-22](file://frontend/utils/convertToCamelCase.ts#L1-L22) + - Path: [frontend/utils/createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) + - Path: [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- Style utilities + - Path: [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Ant Design Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Ant Design Components API.md new file mode 100644 index 00000000..3134655f --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Ant Design Components API.md @@ -0,0 +1,479 @@ +# Ant Design Components API + + +**Files referenced in this document** +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/form/Index.svelte](file://frontend/antd/form/Index.svelte) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/layout/Index.svelte](file://frontend/antd/layout/Index.svelte) +- [frontend/antd/layout/layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) +- [frontend/antd/table/table.tsx](file://frontend/antd/table/table.tsx) +- [frontend/antd/select/select.tsx](file://frontend/antd/select/select.tsx) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [frontend/antd/grid/context.ts](file://frontend/antd/grid/context.ts) +- [frontend/antd/table/context.ts](file://frontend/antd/table/context.ts) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the API reference for Ant Design Svelte-based components in ModelScope Studio. It systematically covers the encapsulation approach of Ant Design components at the frontend layer, spanning general components, layout components, navigation components, data entry components, data display components, feedback components, and more. It clarifies property definitions, event handling, slot system, style customization, state management, and data binding mechanisms for each component, providing correspondence with native Ant Design components and TypeScript type specifications. It also provides reference paths for instantiation and configuration, as well as performance optimization and best practice recommendations. + +## Project Structure + +ModelScope Studio's Ant Design Svelte components adopt a "Svelte shell + React component bridge" architecture: the Svelte layer handles property passthrough, slots, and visibility control; the React layer bridges Ant Design components into the Svelte ecosystem via `sveltify`. The utility layer provides unified function wrapping, slot rendering, and context injection capabilities. + +```mermaid +graph TB +subgraph "Svelte Shell Layer" +IDX_BTN["button/Index.svelte"] +IDX_FORM["form/Index.svelte"] +IDX_LAYOUT["layout/Index.svelte"] +end +subgraph "React Bridge Layer" +BTN_TSX["button/button.tsx"] +FORM_TSX["form/form.tsx"] +LAYOUT_BASE["layout/layout.base.tsx"] +TABLE_TSX["table/table.tsx"] +SELECT_TSX["select/select.tsx"] +end +subgraph "Utilities and Contexts" +USE_FN["utils/hooks/useFunction.ts"] +RENDER_ITEMS["utils/renderItems.tsx"] +RENDER_SLOT["utils/renderParamsSlot.tsx"] +GRID_CTX["antd/grid/context.ts"] +TABLE_CTX["antd/table/context.ts"] +end +IDX_BTN --> BTN_TSX +IDX_FORM --> FORM_TSX +IDX_LAYOUT --> LAYOUT_BASE +TABLE_TSX --> TABLE_CTX +SELECT_TSX --> GRID_CTX +BTN_TSX --> USE_FN +FORM_TSX --> USE_FN +TABLE_TSX --> USE_FN +SELECT_TSX --> USE_FN +TABLE_TSX --> RENDER_ITEMS +SELECT_TSX --> RENDER_ITEMS +TABLE_TSX --> RENDER_SLOT +SELECT_TSX --> RENDER_SLOT +``` + +Diagram sources + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [frontend/antd/table/context.ts:1-29](file://frontend/antd/table/context.ts#L1-L29) + +Section sources + +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) + +## Core Components + +This section provides an overview of responsibilities and typical usage highlights for each component layer: + +- General components: Such as Button, responsible for property passthrough, slots (icon, loading state icon), and visibility control. +- Form components: Such as Form, responsible for two-way form value binding, action triggers (reset/submit/validate), and callback merging. +- Layout components: Such as Layout, selecting specific Header/Footer/Content/Layout components on-demand via the Base component and injecting style class names. +- Data display components: Such as Table, supporting complex scenarios including columns, expand, row selection, pagination, sticky headers, summary, title/footer slots, etc. +- Selector components: Such as Select, supporting option lists, filtering, dropdown/popup rendering, tag/tag-item rendering, and other slots. + +Section sources + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) + +## Architecture Overview + +The Svelte shell collects and transforms properties via `getProps`/`processProps`/`importComponent`, and then the `sveltify`-wrapped React components carry the actual UI logic. The slot system implements parameterized rendering and context injection via `ReactSlot` and `renderItems`/`renderParamsSlot`. + +```mermaid +sequenceDiagram +participant Svelte as "Svelte Shell (Index.svelte)" +participant Utils as "Utilities (useFunction/renderItems/renderParamsSlot)" +participant Bridge as "sveltify-wrapped React Component" +participant AntD as "Ant Design Component" +Svelte->>Utils : "Use useFunction to wrap callbacks/function-type props" +Svelte->>Utils : "Use renderItems to render child items/slots" +Svelte->>Utils : "Use renderParamsSlot to render parameterized slots" +Svelte->>Bridge : "Import and await component loading (importComponent)" +Bridge->>AntD : "Pass through props/events/slots" +AntD-->>Bridge : "Return render result" +Bridge-->>Svelte : "Output final UI" +``` + +Diagram sources + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +## Detailed Component Analysis + +### Button Component + +- Property definitions + - Common properties: Inherits all properties of Ant Design Button. + - Slots: `icon`, `loading.icon`. + - Meta info: `elem_id`, `elem_classes`, `elem_style`, `visible` for visibility and style control. + - Link behavior: `href_target` maps to `target`. +- Event handling + - Passes through events such as `onClick` from Ant Design Button. +- Slot system + - Supports passing icons or loading state icons as slots, rendered internally via `ReactSlot`. +- Style customization + - Injects class names and inline styles via `elem_classes` and `elem_style`. +- State management and data binding + - No two-way binding; visibility can be controlled by updating props externally. +- TypeScript types + - Uses Ant Design Button's `GetProps` type alias for constraints. +- Correspondence + - React component: Ant Design Button. +- Example reference paths + - [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + - [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) + +```mermaid +sequenceDiagram +participant UI as "Caller" +participant Shell as "button/Index.svelte" +participant Btn as "button/button.tsx" +participant AntBtn as "Ant Design Button" +UI->>Shell : "Pass properties and slots" +Shell->>Btn : "Pass through after processProps" +Btn->>AntBtn : "Render Button and inject slots" +AntBtn-->>UI : "Trigger events / display content" +``` + +Diagram sources + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) + +Section sources + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) + +### Form Component + +- Property definitions + - `value`: Form initial or controlled value. + - `formAction`: `'reset'` | `'submit'` | `'validate'` | `null`, used to trigger actions. + - Callbacks: `onValueChange`, `onResetFormAction`. + - Others: `requiredMark`, `feedbackIcons`, `as_item`, `visible`, etc. +- Event handling + - `onValuesChange` merges `onValueChange` to implement value change notifications. + - Action execution: Calls `form.resetFields`/`form.submit`/`form.validateFields` based on `formAction`. +- Slot system + - `requiredMark` can be rendered via a slot. +- Style and visibility + - `elem_id`, `elem_classes`, `elem_style`, `visible` control appearance and display. +- State management and data binding + - Two-way binding: `onValueChange` updates the external `value`; external `value` changes sync back to the form. + - Action decoupling: `onResetFormAction` resets `formAction` after an action completes. +- TypeScript types + - `FormProps` extends Ant Design Form's `GetProps`, adding `value`, `onValueChange`, `formAction`, etc. +- Correspondence + - React component: Ant Design Form. +- Example reference paths + - [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) + - [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) + +```mermaid +sequenceDiagram +participant UI as "Caller" +participant Shell as "form/Index.svelte" +participant Form as "form/form.tsx" +participant AntForm as "Ant Design Form" +UI->>Shell : "Set value/formAction" +Shell->>Form : "Pass through properties and callbacks" +Form->>AntForm : "Create and operate Form instance" +AntForm-->>Form : "onValuesChange/value change" +Form-->>Shell : "onValueChange(value)" +Shell-->>UI : "updateProps({ value })" +UI->>Shell : "formAction='reset'/'submit'/'validate'" +Shell->>Form : "Trigger action" +Form-->>Shell : "onResetFormAction()" +``` + +Diagram sources + +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) + +Section sources + +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) + +### Layout Component + +- Property definitions + - `component`: `'header'` | `'footer'` | `'content'` | `'layout'`, determines the specific Ant Design component to render. + - Others: `className`, `id`, `style`, etc. are passed through. +- Slot system + - Receives `children` via the Base component and renders them. +- Style customization + - Base injects different class name prefixes for different `component` values to facilitate theming. +- Correspondence + - React component: Ant Design Layout and its Content/Header/Footer. +- Example reference paths + - [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) + - [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +```mermaid +flowchart TD +Start(["Start"]) --> Choose["Select specific component based on 'component'"] +Choose --> |header| Header["Ant Design Layout.Header"] +Choose --> |footer| Footer["Ant Design Layout.Footer"] +Choose --> |content| Content["Ant Design Layout.Content"] +Choose --> |layout| Layout["Ant Design Layout"] +Header --> Render["Render and inject class names"] +Footer --> Render +Content --> Render +Layout --> Render +Render --> End(["End"]) +``` + +Diagram sources + +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +Section sources + +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +### Table Component + +- Property definitions + - `columns`: Column definitions, supporting default columns and extended column constants. + - `rowSelection`, `expandable`: Row selection and expandable configuration, supporting slot injection. + - `pagination`: Pagination configuration, supporting slot injection for quick-jump buttons and page number rendering. + - `loading`: Supports `tip` and `indicator` slots. + - `sticky`, `showSorterTooltip`, `footer`, `title`, `summary`, etc. +- Slot system + - Injects column, row selection, and expandable items via `withColumnItemsContextProvider`/`withRowSelectionItemsContextProvider`/`withExpandableItemsContextProvider`. + - `renderItems` renders columns and child items; `renderParamsSlot` renders parameterized slots (such as pagination buttons, page number rendering, sorter tooltips, etc.). +- Function-type properties + - `useFunction` wraps function-type properties such as `getPopupContainer`, `rowClassName`, `rowKey`, `summary`, and `footer`. +- Performance notes + - Configurations such as columns and row selection are optimized with `useMemo`. +- Correspondence + - React component: Ant Design Table. +- Example reference paths + - [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) + - [frontend/antd/table/context.ts:1-29](file://frontend/antd/table/context.ts#L1-L29) + - [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + - [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +```mermaid +sequenceDiagram +participant UI as "Caller" +participant Shell as "table/Index.svelte" +participant Table as "table/table.tsx" +participant Ctx as "Context (columns/rowSelection/expandable)" +participant AntTable as "Ant Design Table" +UI->>Shell : "Pass columns/rowSelection/expandable/pagination, etc." +Shell->>Table : "processProps and slots" +Table->>Ctx : "Read columns/row selection/expandable items" +Table->>AntTable : "Render and inject slots/function-type properties" +AntTable-->>Table : "Events/render result" +Table-->>Shell : "Output final UI" +``` + +Diagram sources + +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/table/context.ts:1-29](file://frontend/antd/table/context.ts#L1-L29) + +Section sources + +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/table/context.ts:1-29](file://frontend/antd/table/context.ts#L1-L29) + +### Select Component + +- Property definitions + - `options`: Option list, supporting injection via slots. + - `onChange`/`onValueChange`: Value change callbacks. + - `filterOption`/`filterSort`: Filtering and sorting functions. + - `dropdownRender`/`popupRender`/`optionRender`/`tagRender`/`labelRender`: Slot-based rendering. + - `allowClear.prefix`/`removeIcon`/`suffixIcon`/`notFoundContent`/`menuItemSelectedIcon`: Slot-based icons and text. +- Slot system + - `withItemsContextProvider` injects `options`/`default` child items; `renderItems` renders options. + - `renderParamsSlot` renders parameterized slots (such as `maxTagPlaceholder`). +- Function-type properties + - `useFunction` wraps `getPopupContainer`, `dropdownRender`, `popupRender`, `optionRender`, `tagRender`, `labelRender`, `filterOption`, `filterSort`. +- Correspondence + - React component: Ant Design Select. +- Example reference paths + - [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) + - [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) + - [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + - [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +```mermaid +flowchart TD +Start(["Start"]) --> Options["Resolve options/default slot items"] +Options --> RenderOpts["renderItems renders options"] +RenderOpts --> Hooks["useFunction wraps function-type properties"] +Hooks --> Slots["Slot-based icons/text/renderers"] +Slots --> AntSelect["Render Ant Design Select"] +AntSelect --> End(["End"]) +``` + +Diagram sources + +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) + +Section sources + +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) + +## Dependency Analysis + +- Inter-component dependencies + - Button/Form/Layout/Table/Select all depend on `sveltify` to bridge Ant Design components to Svelte. + - Slots and contexts depend on `renderItems`/`renderParamsSlot` and `createItemsContext`. + - Function-type properties depend on `useFunction` to be wrapped as executable functions. +- External dependencies + - Ant Design: Provides UI foundation capabilities as a React component library. + - Utility libraries: `classnames`, `lodash-es`, etc. assist with styles and object handling. +- Circular dependencies + - No direct circular dependencies found; context injection is exported through independent modules. + +```mermaid +graph LR +Svelte["Svelte Shell"] --> Sveltify["sveltify wrapper"] +Sveltify --> AntD["Ant Design Components"] +Svelte --> Utils["Utility Functions"] +Utils --> RenderItems["renderItems"] +Utils --> RenderSlot["renderParamsSlot"] +Utils --> UseFunction["useFunction"] +Svelte --> Ctx["Context (createItemsContext)"] +``` + +Diagram sources + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +Section sources + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +## Performance Considerations + +- Function-type property wrapping + - Use `useFunction` to wrap incoming strings/functions as executable functions, avoiding recreation of closures on each render. +- Slots and contexts + - `renderItems` and `renderParamsSlot` support cloning and parameterized rendering to reduce redundant rendering overhead. +- Computation caching + - Table/Select extensively use `useMemo` to cache computation results (such as columns, row keys, container functions, etc.). +- Async loading + - The Svelte shell asynchronously loads React components via `importComponent` to reduce initial render pressure. +- Best practices + - Prefer using slots over inline JSX to improve reusability and maintainability. + - Use `$derived` or `useMemo` wrappers for frequently changing props to avoid unnecessary re-renders. + - Properly split components to avoid a single component taking on too many responsibilities. + +## Troubleshooting Guide + +- Slot not taking effect + - Check that the slot key is correct (e.g., `'loading.icon'`, `'pagination.showQuickJumper.goButton'`) and ensure the passed value is an `HTMLElement` or an object with `withParams`. + - Confirm the `forceClone` and `clone` settings for `renderParamsSlot`/`renderItems`. +- Function-type properties not working + - Ensure that the passed string expression is correctly wrapped by `useFunction`; pass `plainText=true` when necessary. +- Form action not triggered + - Confirm the `formAction` value is `'reset'` | `'submit'` | `'validate'` | `null`, and reset `formAction` after the action completes. +- Style anomalies + - Check that `elem_classes` and `elem_style` are correctly injected; for Layout components, ensure the `component` parameter matches the actual layout element. + +Section sources + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +## Conclusion + +ModelScope Studio's Ant Design Svelte components achieve high-fidelity encapsulation of Ant Design components through clear layered design and a powerful slot/context system. Developers can use Ant Design's rich capabilities in Svelte at minimal cost while maintaining good maintainability and performance. It is recommended to prioritize slots and contexts in complex scenarios, combined with function-type property wrapping and `useMemo` caching, for a better development experience and runtime efficiency. + +## Appendix + +- Component inventory (categorized by module) + - General components: Button, Icon, Spin, Space, Typography, etc. + - Layout components: Layout (Header/Footer/Content/Layout), Grid (Row/Col), etc. + - Navigation components: Anchor, Breadcrumb, Dropdown, Menu, Pagination, Steps, Tabs, Tour, etc. + - Data entry components: AutoComplete, Cascader, Checkbox, ColorPicker, DatePicker, Mentions, Radio, Rate, Select, Slider, Switch, TimePicker, TreeSelect, Upload, Input/InputNumber/TextArea/Search/Password/OTP, etc. + - Data display components: Avatar, Badge, Calendar, Card/Card.Grid/Card.Meta, Carousel, Descriptions, Divider, Empty, Image/Image.PreviewGroup, List/List.Item/List.Item.Meta, Masonry/Masonry.Item, Result, Statistical/Countdown/Timer, Table/Table.Column/Table.ColumnGroup/Table.Expandable/Table.RowSelection, etc. + - Feedback components: Alert, Drawer, FloatButton/BackTop/Group, Modal/Static, Message, Notification, Popconfirm, Popover, Progress, QRCode, Result, Tour, Tooltip, Tour/Step, etc. +- Correspondence with native Ant Design + - Each Svelte component wraps the corresponding Ant Design React component via `sveltify`, with consistent properties and events. +- TypeScript type specifications + - Component types are all extended from Ant Design's `GetProps` type alias to ensure type safety. +- Example reference paths + - General components: [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + - Form components: [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) + - Layout components: [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) + - Data display components: [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) + - Selector components: [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Data Display Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Data Display Components API.md new file mode 100644 index 00000000..04812ea8 --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Data Display Components API.md @@ -0,0 +1,578 @@ +# Data Display Components API + + +**Files referenced in this document** +- [avatar.tsx](file://frontend/antd/avatar/avatar.tsx) +- [badge.tsx](file://frontend/antd/badge/badge.tsx) +- [calendar.tsx](file://frontend/antd/calendar/calendar.tsx) +- [card.tsx](file://frontend/antd/card/card.tsx) +- [carousel.tsx](file://frontend/antd/carousel/carousel.tsx) +- [collapse.tsx](file://frontend/antd/collapse/collapse.tsx) +- [descriptions.tsx](file://frontend/antd/descriptions/descriptions.tsx) +- [empty.tsx](file://frontend/antd/empty/empty.tsx) +- [image.tsx](file://frontend/antd/image/image.tsx) +- [list.tsx](file://frontend/antd/list/list.tsx) +- [popover.tsx](file://frontend/antd/popover/popover.tsx) +- [qr-code.tsx](file://frontend/antd/qr-code/qr-code.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [statistic.tsx](file://frontend/antd/statistic/statistic.tsx) +- [table.tsx](file://frontend/antd/table/table.tsx) +- [tabs.tsx](file://frontend/antd/tabs/tabs.tsx) +- [tag.tsx](file://frontend/antd/tag/tag.tsx) +- [timeline.tsx](file://frontend/antd/timeline/timeline.tsx) +- [tooltip.tsx](file://frontend/antd/tooltip/tooltip.tsx) +- [tour.tsx](file://frontend/antd/tour/tour.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the API reference for Ant Design-based data display components in ModelScope Studio, covering: Avatar, Badge, Calendar, Card, Carousel, Collapse, Descriptions, Empty, Image, List, Popover, QRCode, Segmented, Statistic, Table, Tabs, Tag, Timeline, Tooltip, Tour, and Tree. It includes: + +- Property definitions and data format requirements +- Display logic and interaction behaviors +- Standard instantiation and configuration examples (provided as paths) +- Data binding, virtual scrolling, lazy loading, and performance optimization mechanisms +- Key TypeScript type definitions, data transformation, and chart library integration ideas +- Visual design principles and user experience optimization recommendations + +## Project Structure + +These components reside in the `antd` submodule of the frontend directory and follow a unified wrapping pattern: bridging Ant Design components into the Svelte ecosystem via `sveltify`, and implementing flexible content slots and function parameter rendering using `slots` and `renderParamsSlot`. + +```mermaid +graph TB +subgraph "Ant Design Component Layer" +AD_Avatar["Avatar"] +AD_Badge["Badge"] +AD_Calendar["Calendar"] +AD_Card["Card"] +AD_Carousel["Carousel"] +AD_Collapse["Collapse"] +AD_Descriptions["Descriptions"] +AD_Empty["Empty"] +AD_Image["Image"] +AD_List["List"] +AD_Popover["Popover"] +AD_QRCode["QRCode"] +AD_Segmented["Segmented"] +AD_Statistic["Statistic"] +AD_Table["Table"] +AD_Tabs["Tabs"] +AD_Tag["Tag"] +AD_Timeline["Timeline"] +AD_Tooltip["Tooltip"] +AD_Tour["Tour"] +AD_Tree["Tree"] +end +subgraph "sveltify Wrapper Layer" +S_Avatar["avatar.tsx"] +S_Badge["badge.tsx"] +S_Calendar["calendar.tsx"] +S_Card["card.tsx"] +S_Carousel["carousel.tsx"] +S_Collapse["collapse.tsx"] +S_Descriptions["descriptions.tsx"] +S_Empty["empty.tsx"] +S_Image["image.tsx"] +S_List["list.tsx"] +S_Popover["popover.tsx"] +S_QRCode["qr-code.tsx"] +S_Segmented["segmented.tsx"] +S_Statistic["statistic.tsx"] +S_Table["table.tsx"] +S_Tabs["tabs.tsx"] +S_Tag["tag.tsx"] +S_Timeline["timeline.tsx"] +S_Tooltip["tooltip.tsx"] +S_Tour["tour.tsx"] +S_Tree["tree.tsx"] +end +S_Avatar --> AD_Avatar +S_Badge --> AD_Badge +S_Calendar --> AD_Calendar +S_Card --> AD_Card +S_Carousel --> AD_Carousel +S_Collapse --> AD_Collapse +S_Descriptions --> AD_Descriptions +S_Empty --> AD_Empty +S_Image --> AD_Image +S_List --> AD_List +S_Popover --> AD_Popover +S_QRCode --> AD_QRCode +S_Segmented --> AD_Segmented +S_Statistic --> AD_Statistic +S_Table --> AD_Table +S_Tabs --> AD_Tabs +S_Tag --> AD_Tag +S_Timeline --> AD_Timeline +S_Tooltip --> AD_Tooltip +S_Tour --> AD_Tour +S_Tree --> AD_Tree +``` + +Diagram sources + +- [avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) +- [calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) +- [carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) +- [image.tsx:1-89](file://frontend/antd/image/image.tsx#L1-L89) +- [list.tsx:1-36](file://frontend/antd/list/list.tsx#L1-L36) +- [popover.tsx:1-37](file://frontend/antd/popover/popover.tsx#L1-L37) +- [qr-code.tsx:1-200](file://frontend/antd/qr-code/qr-code.tsx#L1-L200) +- [segmented.tsx:1-47](file://frontend/antd/segmented/segmented.tsx#L1-L47) +- [statistic.tsx:1-34](file://frontend/antd/statistic/statistic.tsx#L1-L34) +- [table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [tabs.tsx:1-121](file://frontend/antd/tabs/tabs.tsx#L1-L121) +- [tag.tsx:1-200](file://frontend/antd/tag/tag.tsx#L1-L200) +- [timeline.tsx:1-200](file://frontend/antd/timeline/timeline.tsx#L1-L200) +- [tooltip.tsx:1-200](file://frontend/antd/tooltip/tooltip.tsx#L1-L200) +- [tour.tsx:1-200](file://frontend/antd/tour/tour.tsx#L1-L200) +- [tree.tsx:1-200](file://frontend/antd/tree/tree.tsx#L1-L200) + +Section sources + +- [avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) +- [calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) +- [carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) +- [image.tsx:1-89](file://frontend/antd/image/image.tsx#L1-L89) +- [list.tsx:1-36](file://frontend/antd/list/list.tsx#L1-L36) +- [popover.tsx:1-37](file://frontend/antd/popover/popover.tsx#L1-L37) +- [segmented.tsx:1-47](file://frontend/antd/segmented/segmented.tsx#L1-L47) +- [statistic.tsx:1-34](file://frontend/antd/statistic/statistic.tsx#L1-L34) +- [table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [tabs.tsx:1-121](file://frontend/antd/tabs/tabs.tsx#L1-L121) + +## Core Components + +This section provides an overview of each component's responsibility and common wrapping strategy: + +- All components use `sveltify` to wrap Ant Design components, supporting `slots` and `renderParamsSlot` render function parameters. +- Most components support `children` forwarding and various named slots (e.g., `title`, `extra`, `footer`, `header`, `content`, `image`, `description`, `placeholder`, `mask`, `toolbarRender`, `imageRender`, `tabBarExtraContent`, `tabProps.*`, etc.) for flexible appearance and behavior customization. +- Some components wrap event callbacks to ensure correct execution in the Svelte environment. + +Section sources + +- [avatar.tsx:6-25](file://frontend/antd/avatar/avatar.tsx#L6-L25) +- [badge.tsx:6-18](file://frontend/antd/badge/badge.tsx#L6-L18) +- [card.tsx:37-146](file://frontend/antd/card/card.tsx#L37-L146) +- [carousel.tsx:8-28](file://frontend/antd/carousel/carousel.tsx#L8-L28) +- [collapse.tsx:11-49](file://frontend/antd/collapse/collapse.tsx#L11-L49) +- [descriptions.tsx:10-37](file://frontend/antd/descriptions/descriptions.tsx#L10-L37) +- [empty.tsx:6-49](file://frontend/antd/empty/empty.tsx#L6-L49) +- [image.tsx:15-85](file://frontend/antd/image/image.tsx#L15-L85) +- [list.tsx:8-33](file://frontend/antd/list/list.tsx#L8-L33) +- [popover.tsx:7-34](file://frontend/antd/popover/popover.tsx#L7-L34) +- [segmented.tsx:10-43](file://frontend/antd/segmented/segmented.tsx#L10-L43) +- [statistic.tsx:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) +- [table.tsx:28-275](file://frontend/antd/table/table.tsx#L28-L275) +- [tabs.tsx:12-117](file://frontend/antd/tabs/tabs.tsx#L12-L117) + +## Architecture Overview + +The following sequence diagram illustrates the key flow from component wrapping to rendering: Svelte converts props and slots into Ant Design component props via `sveltify`; functional parameters are wrapped with `useFunction` or `createFunction`; complex configuration objects are merged with `omitUndefinedProps` and slots are injected. + +```mermaid +sequenceDiagram +participant Svelte as "Svelte Component" +participant Sveltify as "sveltify Wrapper" +participant AntD as "Ant Design Component" +participant Utils as "Utility Functions
useFunction/createFunction/renderParamsSlot" +Svelte->>Sveltify : Passes props and slots +Sveltify->>Utils : Wraps function params / merges config +Utils-->>Sveltify : Returns executable functions or config objects +Sveltify->>AntD : Renders and passes props +AntD-->>Svelte : Fires callbacks / returns render result +``` + +Diagram sources + +- [table.tsx:76-134](file://frontend/antd/table/table.tsx#L76-L134) +- [card.tsx:40-49](file://frontend/antd/card/card.tsx#L40-L49) +- [image.tsx:32-34](file://frontend/antd/image/image.tsx#L32-L34) +- [popover.tsx:10-12](file://frontend/antd/popover/popover.tsx#L10-L12) + +## Component Details + +### Avatar + +- **Purpose**: Displays user avatars or icons; supports `icon` and `src` slots. +- **Key Points**: + - Supports `slots.icon` and `slots.src`; slot content takes priority if present, otherwise falls back to props. + - Slots are rendered via `ReactSlot`. +- **Typical usage path**: + - [Avatar basic usage:6-25](file://frontend/antd/avatar/avatar.tsx#L6-L25) + +Section sources + +- [avatar.tsx:6-25](file://frontend/antd/avatar/avatar.tsx#L6-L25) + +### Badge + +- **Purpose**: Displays a badge count or text on avatars, buttons, and other elements. +- **Key Points**: + - Supports `slots.count` and `slots.text` for dynamic badge content rendering. +- **Typical usage path**: + - [Badge count and text:6-18](file://frontend/antd/badge/badge.tsx#L6-L18) + +Section sources + +- [badge.tsx:6-18](file://frontend/antd/badge/badge.tsx#L6-L18) + +### Calendar + +- **Purpose**: Date selection and schedule display. +- **Key Points**: + - `value`/`defaultValue`/`validRange` are processed with `dayjs` formatting. + - `onChange`/`onPanelChange`/`onSelect` callbacks are uniformly converted to second-level timestamps. + - Supports `slots.cellRender`/`fullCellRender`/`headerRender` function slots. +- **Typical usage path**: + - [Calendar date formatting and callbacks:17-98](file://frontend/antd/calendar/calendar.tsx#L17-L98) + +Section sources + +- [calendar.tsx:17-98](file://frontend/antd/calendar/calendar.tsx#L17-L98) + +### Card + +- **Purpose**: Container component supporting title, extra actions, cover image, action area, and tab pages. +- **Key Points**: + - Supports `slots.title`/`extra`/`cover`/`tabBarExtraContent`/`left`/`right`, etc. + - `actions` are automatically collected from child nodes via `useTargets`. + - `tabList` is resolved from context via `renderItems`. + - `tabProps.indicator.size`, `more.icon`, `tabProps.renderTabBar`, `tabProps.tabBarExtraContent.*`, etc. can all be slotted. +- **Typical usage path**: + - [Card with tab pages and action area:37-146](file://frontend/antd/card/card.tsx#L37-L146) + +Section sources + +- [card.tsx:37-146](file://frontend/antd/card/card.tsx#L37-L146) + +### Carousel + +- **Purpose**: Carousel display of multiple images or content panels. +- **Key Points**: + - Uses `useTargets` to extract child nodes as carousel items. + - `afterChange`/`beforeChange` are wrapped via `useFunction`. +- **Typical usage path**: + - [Carousel item rendering:8-28](file://frontend/antd/carousel/carousel.tsx#L8-L28) + +Section sources + +- [carousel.tsx:8-28](file://frontend/antd/carousel/carousel.tsx#L8-L28) + +### Collapse + +- **Purpose**: Grouping content with collapse/expand behavior. +- **Key Points**: + - Supports `slots.expandIcon` function slot. + - `items` are resolved from context via `renderItems`, supporting `label`/`extra`/`children` structure. +- **Typical usage path**: + - [Collapse items and expand icon:11-49](file://frontend/antd/collapse/collapse.tsx#L11-L49) + +Section sources + +- [collapse.tsx:11-49](file://frontend/antd/collapse/collapse.tsx#L11-L49) + +### Descriptions + +- **Purpose**: Displays information in key-value pairs. +- **Key Points**: + - Supports `slots.title`/`extra`; `items` are resolved via `renderItems` with `label`/`children` fields. +- **Typical usage path**: + - [Descriptions item rendering:10-37](file://frontend/antd/descriptions/descriptions.tsx#L10-L37) + +Section sources + +- [descriptions.tsx:10-37](file://frontend/antd/descriptions/descriptions.tsx#L10-L37) + +### Empty + +- **Purpose**: Placeholder displayed when there is no data. +- **Key Points**: + - Supports `slots.description`/`image`; `image` supports default constant mapping. + - `styles` supports a function that returns a style object. +- **Typical usage path**: + - [Empty with custom image and description:6-49](file://frontend/antd/empty/empty.tsx#L6-L49) + +Section sources + +- [empty.tsx:6-49](file://frontend/antd/empty/empty.tsx#L6-L49) + +### Image + +- **Purpose**: Image display and preview. +- **Key Points**: + - Supports `slots.placeholder`, `preview.mask`, `preview.closeIcon`, `preview.toolbarRender`, `preview.imageRender`. + - `preview` configuration is merged via `getConfig`/`omitUndefinedProps`; `getContainer`/`toolbarRender`/`imageRender` are wrapped via `useFunction`. +- **Typical usage path**: + - [Image preview and toolbar rendering:15-85](file://frontend/antd/image/image.tsx#L15-L85) + +Section sources + +- [image.tsx:15-85](file://frontend/antd/image/image.tsx#L15-L85) + +### List + +- **Purpose**: Long list display with load-more support. +- **Key Points**: + - Supports `slots.footer`/`header`/`loadMore`/`renderItem`; `renderItem` is rendered via `renderParamsSlot` with forced cloning. +- **Typical usage path**: + - [List header, footer, and load more:8-33](file://frontend/antd/list/list.tsx#L8-L33) + +Section sources + +- [list.tsx:8-33](file://frontend/antd/list/list.tsx#L8-L33) + +### Popover + +- **Purpose**: Floating bubble card displaying a title and content. +- **Key Points**: + - Supports `slots.title`/`content`; `title`/`content` are cloned via `ReactSlot`. + - `afterOpenChange`/`getPopupContainer` are wrapped via `useFunction`. +- **Typical usage path**: + - [Popover title and content:7-34](file://frontend/antd/popover/popover.tsx#L7-L34) + +Section sources + +- [popover.tsx:7-34](file://frontend/antd/popover/popover.tsx#L7-L34) + +### QRCode + +- **Purpose**: Generate and display QR codes. +- **Typical usage path**: + - [QRCode component:1-200](file://frontend/antd/qr-code/qr-code.tsx#L1-L200) + +Section sources + +- [qr-code.tsx:1-200](file://frontend/antd/qr-code/qr-code.tsx#L1-L200) + +### Segmented + +- **Purpose**: Switching between multiple options. +- **Key Points**: + - Supports resolving `options`/`default` from context; `onChange` exposes the selected value via `onValueChange`. +- **Typical usage path**: + - [Segmented option rendering:10-43](file://frontend/antd/segmented/segmented.tsx#L10-L43) + +Section sources + +- [segmented.tsx:10-43](file://frontend/antd/segmented/segmented.tsx#L10-L43) + +### Statistic + +- **Purpose**: Displays numeric values with units, prefix, and suffix. +- **Key Points**: + - Supports `slots.prefix`/`suffix`/`title`/`formatter`; `formatter` is rendered via `renderParamsSlot`. +- **Typical usage path**: + - [Statistic value formatting:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) + +Section sources + +- [statistic.tsx:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) + +### Table + +- **Purpose**: Data table display and interaction. +- **Key Points**: + - Supports complex configurations including `columns`, `rowSelection`, `expandable`, `sticky`, `pagination`, `loading`, `footer`, `title`, `summary`, `showSorterTooltip`, etc. + - Injects column, expand, and row-selection contexts via multiple `with*ContextProvider` layers. + - Uses `renderItems` and `renderParamsSlot` to dynamically resolve items and function parameters; uses `createFunction`/`omitUndefinedProps` to wrap and merge configuration. +- **Typical usage path**: + - [Table columns and pagination slots:28-275](file://frontend/antd/table/table.tsx#L28-L275) + +Section sources + +- [table.tsx:28-275](file://frontend/antd/table/table.tsx#L28-L275) + +### Tabs + +- **Purpose**: Tab container and switching. +- **Key Points**: + - Supports `slots.addIcon`/`removeIcon`/`renderTabBar`/`tabBarExtraContent`/`left`/`right`/`more.icon`. + - `indicator.size`, `more.getPopupContainer`, `renderTabBar` are wrapped via `useFunction`; `items` are resolved via `renderItems`. +- **Typical usage path**: + - [Tabs with extra content:12-117](file://frontend/antd/tabs/tabs.tsx#L12-L117) + +Section sources + +- [tabs.tsx:12-117](file://frontend/antd/tabs/tabs.tsx#L12-L117) + +### Tag + +- **Purpose**: Marking and categorization. +- **Typical usage path**: + - [Tag component:1-200](file://frontend/antd/tag/tag.tsx#L1-L200) + +Section sources + +- [tag.tsx:1-200](file://frontend/antd/tag/tag.tsx#L1-L200) + +### Timeline + +- **Purpose**: Displays events in chronological order. +- **Typical usage path**: + - [Timeline component:1-200](file://frontend/antd/timeline/timeline.tsx#L1-L200) + +Section sources + +- [timeline.tsx:1-200](file://frontend/antd/timeline/timeline.tsx#L1-L200) + +### Tooltip + +- **Purpose**: Concise hint text. +- **Typical usage path**: + - [Tooltip component:1-200](file://frontend/antd/tooltip/tooltip.tsx#L1-L200) + +Section sources + +- [tooltip.tsx:1-200](file://frontend/antd/tooltip/tooltip.tsx#L1-L200) + +### Tour + +- **Purpose**: Guided tutorial. +- **Typical usage path**: + - [Tour component:1-200](file://frontend/antd/tour/tour.tsx#L1-L200) + +Section sources + +- [tour.tsx:1-200](file://frontend/antd/tour/tour.tsx#L1-L200) + +### Tree + +- **Purpose**: Hierarchical data display and selection. +- **Typical usage path**: + - [Tree component:1-200](file://frontend/antd/tree/tree.tsx#L1-L200) + +Section sources + +- [tree.tsx:1-200](file://frontend/antd/tree/tree.tsx#L1-L200) + +## Dependency Analysis + +- **Inter-component Coupling**: + - Card and Tabs share context (the `tabList` context is reused when Card embeds Tabs). + - Table injects column, expand, and row-selection contexts via multiple context providers. + - Most components share utilities such as `renderItems`, `renderParamsSlot`, `useFunction`, and `omitUndefinedProps`. +- **External Dependencies**: + - Ant Design component library and `dayjs` (for the Calendar component). + - `lodash-es` (for type checking in the Empty component). + +```mermaid +graph LR +RenderItems["renderItems"] +RenderParam["renderParamsSlot"] +UseFunc["useFunction"] +OmitUndef["omitUndefinedProps"] +Card["card.tsx"] --> RenderItems +Card --> UseFunc +Tabs["tabs.tsx"] --> RenderItems +Tabs --> UseFunc +Collapse["collapse.tsx"] --> RenderItems +Collapse --> UseFunc +Descriptions["descriptions.tsx"] --> RenderItems +Table["table.tsx"] --> RenderItems +Table --> RenderParam +Table --> UseFunc +Table --> OmitUndef +Image["image.tsx"] --> UseFunc +Image --> OmitUndef +Popover["popover.tsx"] --> UseFunc +Statistic["statistic.tsx"] --> UseFunc +Segmented["segmented.tsx"] --> RenderItems +Calendar["calendar.tsx"] --> UseFunc +``` + +Diagram sources + +- [card.tsx:10-14](file://frontend/antd/card/card.tsx#L10-L14) +- [tabs.tsx:6-10](file://frontend/antd/tabs/tabs.tsx#L6-L10) +- [collapse.tsx:4-8](file://frontend/antd/collapse/collapse.tsx#L4-L8) +- [descriptions.tsx:4-7](file://frontend/antd/descriptions/descriptions.tsx#L4-L7) +- [table.tsx:7-18](file://frontend/antd/table/table.tsx#L7-L18) +- [image.tsx:3-6](file://frontend/antd/image/image.tsx#L3-L6) +- [popover.tsx:4-5](file://frontend/antd/popover/popover.tsx#L4-L5) +- [statistic.tsx:4-6](file://frontend/antd/statistic/statistic.tsx#L4-L6) +- [segmented.tsx:3-6](file://frontend/antd/segmented/segmented.tsx#L3-L6) +- [calendar.tsx:3-4](file://frontend/antd/calendar/calendar.tsx#L3-L4) + +Section sources + +- [card.tsx:10-14](file://frontend/antd/card/card.tsx#L10-L14) +- [tabs.tsx:6-10](file://frontend/antd/tabs/tabs.tsx#L6-L10) +- [table.tsx:7-18](file://frontend/antd/table/table.tsx#L7-L18) + +## Performance Considerations + +- **Virtual Scrolling and Lazy Loading** + - List-type components (List, Table) can enable virtual scrolling and lazy loading via external configuration to reduce DOM count and reflow overhead. + - It is recommended to enable virtualization and paginated loading for large data sets. +- **Render Optimization** + - Use `useMemo` to cache computed results (e.g., Table's `columns`, `rowSelection`, `expandable`). + - Split slot rendering appropriately to avoid unnecessary repeated rendering. +- **Event and Function Wrapping** + - Use `useFunction`/`createFunction` to wrap callbacks, ensuring stable execution within the Svelte lifecycle and avoiding closure pitfalls. +- **Image and Preview** + - The Image component supports `placeholder` and preview toolbar customization; set dimensions and lazy loading strategies appropriately to reduce initial page load pressure. + +## Troubleshooting Guide + +- **Slot Not Working** + - Confirm that the slot name is correct (e.g., `preview.mask`, `tabProps.renderTabBar`, `loading.tip`, etc.). + - Check for missing combinations of `slots.*` and props. +- **Callback Not Firing** + - Ensure callbacks are wrapped via `useFunction`; verify event naming and parameter signatures. +- **Date Format Issues (Calendar)** + - The Calendar component internally converts time to second-level timestamps; confirm the input value type and range. +- **Table Columns and Expand Configuration** + - When `columns` is empty, the component attempts to resolve from context; confirm that the context correctly provides `default`/`items`. +- **Style Overrides** + - Empty's `styles` supports functional returns; pay attention to the return object structure and key names. + +Section sources + +- [image.tsx:32-34](file://frontend/antd/image/image.tsx#L32-L34) +- [popover.tsx:10-12](file://frontend/antd/popover/popover.tsx#L10-L12) +- [calendar.tsx:85-94](file://frontend/antd/calendar/calendar.tsx#L85-L94) +- [table.tsx:67-75](file://frontend/antd/table/table.tsx#L67-L75) +- [empty.tsx:34-45](file://frontend/antd/empty/empty.tsx#L34-L45) + +## Conclusion + +ModelScope Studio's data display components achieve seamless integration with Ant Design through a unified `sveltify` wrapper, providing powerful slot and function parameter extension capabilities. With context resolution and utility functions, developers can quickly build card layouts, carousels, collapse panels, description lists, image previews, data tables, tag clouds, and other common data display scenarios. It is recommended to combine virtual scrolling, lazy loading, and style optimization strategies in real-world projects to further improve performance and user experience. + +## Appendix + +- **TypeScript Type Definition Key Points** + - Most components obtain types via `GetProps
Exports each AntD component"] +end +subgraph "Frontend Wrapper Layer" +F_FORM["form/form.tsx"] +F_AUTO["auto-complete/auto-complete.tsx"] +F_CASCADE["cascader/cascader.tsx"] +F_CHECK["checkbox/checkbox.tsx"] +F_COLOR["color-picker/color-picker.tsx"] +F_DATE["date-picker/date-picker.tsx"] +F_INPUT["input/input.tsx"] +F_NUM["input-number/input-number.tsx"] +F_MENTIONS["mentions/mentions.tsx"] +F_RADIO["radio/radio.tsx"] +F_RATE["rate/rate.tsx"] +F_SELECT["select/select.tsx"] +F_SLIDER["slider/slider.tsx"] +F_SWITCH["switch/switch.tsx"] +F_TIME["time-picker/time-picker.tsx"] +F_TRANS["transfer/transfer.tsx"] +F_TSELECT["tree-select/tree-select.tsx"] +end +PY --> F_FORM +PY --> F_AUTO +PY --> F_CASCADE +PY --> F_CHECK +PY --> F_COLOR +PY --> F_DATE +PY --> F_INPUT +PY --> F_NUM +PY --> F_MENTIONS +PY --> F_RADIO +PY --> F_RATE +PY --> F_SELECT +PY --> F_SLIDER +PY --> F_SWITCH +PY --> F_TIME +PY --> F_TRANS +PY --> F_TSELECT +``` + +Diagram sources + +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/auto-complete/auto-complete.tsx:1-151](file://frontend/antd/auto-complete/auto-complete.tsx#L1-L151) +- [frontend/antd/cascader/cascader.tsx:1-207](file://frontend/antd/cascader/cascader.tsx#L1-L207) +- [frontend/antd/checkbox/checkbox.tsx:1-22](file://frontend/antd/checkbox/checkbox.tsx#L1-L22) +- [frontend/antd/color-picker/color-picker.tsx:1-106](file://frontend/antd/color-picker/color-picker.tsx#L1-L106) +- [frontend/antd/date-picker/date-picker.tsx:1-234](file://frontend/antd/date-picker/date-picker.tsx#L1-L234) +- [frontend/antd/input/input.tsx:1-119](file://frontend/antd/input/input.tsx#L1-L119) +- [frontend/antd/input-number/input-number.tsx:1-92](file://frontend/antd/input-number/input-number.tsx#L1-L92) +- [frontend/antd/mentions/mentions.tsx:1-80](file://frontend/antd/mentions/mentions.tsx#L1-L80) +- [frontend/antd/radio/radio.tsx:1-32](file://frontend/antd/radio/radio.tsx#L1-L32) +- [frontend/antd/rate/rate.tsx:1-45](file://frontend/antd/rate/rate.tsx#L1-L45) +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/antd/slider/slider.tsx:1-97](file://frontend/antd/slider/slider.tsx#L1-L97) +- [frontend/antd/switch/switch.tsx:1-42](file://frontend/antd/switch/switch.tsx#L1-L42) +- [frontend/antd/time-picker/time-picker.tsx:1-201](file://frontend/antd/time-picker/time-picker.tsx#L1-L201) +- [frontend/antd/transfer/transfer.tsx:1-112](file://frontend/antd/transfer/transfer.tsx#L1-L112) +- [frontend/antd/tree-select/tree-select.tsx:1-163](file://frontend/antd/tree-select/tree-select.tsx#L1-L163) + +Section sources + +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +## Core Components + +This section provides an overview of the common patterns and key interfaces for all data entry components: + +- **Value binding**: All support `value` and `onValueChange` for controlled/uncontrolled switching and two-way binding. +- **Slot system**: Many components support `slots` (e.g., `allowClear.clearIcon`, `prefix`, `suffix`, `popupRender`, etc.) for custom rendering. +- **Functional props**: Some props support function values (e.g., `formatter`, `parser`, `disabledDate`, etc.), wrapped via `useFunction`. +- **Options/tree data**: Select, Cascader, TreeSelect, AutoComplete, Mentions, etc. support rendering items via `children` or `options`/`treeData`. +- **Form integration**: Form provides global form state management, reset, submit, validate actions, and `requiredMark`/`feedbackIcons` support. + +Section sources + +- [frontend/antd/form/form.tsx:8-76](file://frontend/antd/form/form.tsx#L8-L76) +- [frontend/antd/select/select.tsx:11-178](file://frontend/antd/select/select.tsx#L11-L178) +- [frontend/antd/cascader/cascader.tsx:19-204](file://frontend/antd/cascader/cascader.tsx#L19-L204) +- [frontend/antd/tree-select/tree-select.tsx:14-161](file://frontend/antd/tree-select/tree-select.tsx#L14-L161) +- [frontend/antd/auto-complete/auto-complete.tsx:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) +- [frontend/antd/mentions/mentions.tsx:11-77](file://frontend/antd/mentions/mentions.tsx#L11-L77) + +## Architecture Overview + +The following diagram shows the common call chain for data entry components: frontend components pass values upstream via the `onValueChange` callback; the Form component handles form-level actions (reset/submit/validate) and global `requiredMark`/`feedbackIcons`; some components format values internally (e.g., date/time components). + +```mermaid +sequenceDiagram +participant U as "User" +participant C as "Data Entry Component" +participant F as "Form Component" +participant B as "Backend Service" +U->>C : Input/Select/Change +C->>C : Triggers onChange/onValueChange +C-->>F : onValueChange(value) +F->>F : setFieldsValue / submit / validate +F-->>B : Submits form data +B-->>F : Returns result/error +F-->>U : Displays feedback/error message +``` + +Diagram sources + +- [frontend/antd/form/form.tsx:27-76](file://frontend/antd/form/form.tsx#L27-L76) +- [frontend/antd/date-picker/date-picker.tsx:162-170](file://frontend/antd/date-picker/date-picker.tsx#L162-L170) +- [frontend/antd/time-picker/time-picker.tsx:131-143](file://frontend/antd/time-picker/time-picker.tsx#L131-L143) + +## Component Details + +### Form + +- **Responsibility**: Wraps AntD Form, providing `value`, `onValueChange`, `formAction` (reset/submit/validate), `requiredMark`, and `feedbackIcons` capabilities. +- **Key Points**: + - Creates a form instance via `AForm.useForm`. + - Executes reset/submit/validate when `formAction` changes. + - Syncs upstream value via `onValuesChange` and triggers `onValueChange`. +- **Typical usage path** + - [Form container implementation:15-76](file://frontend/antd/form/form.tsx#L15-L76) + +Section sources + +- [frontend/antd/form/form.tsx:8-76](file://frontend/antd/form/form.tsx#L8-L76) + +### AutoComplete + +- **Capabilities**: Supports options list, filtering, popup rendering, clear icon, empty placeholder, etc. +- **Key Points**: + - Uses `useValueChange` for controlled `value`. + - Supports slots: `allowClear.clearIcon`, `dropdownRender`, `popupRender`, `notFoundContent`. + - Supports `filterOption` function and `getPopupContainer`. +- **Typical usage path** + - [AutoComplete component:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) + +Section sources + +- [frontend/antd/auto-complete/auto-complete.tsx:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) + +### Cascader + +- **Capabilities**: Multi-level cascading selection; supports dynamic loading, search, tag rendering, and custom dropdown panel. +- **Key Points**: + - Supports two data sources: `options` and `children`. + - `showSearch` supports object configuration and `slots['showSearch.render']`. + - Supports `onLoadData` for dynamic loading. +- **Typical usage path** + - [Cascader component:19-204](file://frontend/antd/cascader/cascader.tsx#L19-L204) + +Section sources + +- [frontend/antd/cascader/cascader.tsx:19-204](file://frontend/antd/cascader/cascader.tsx#L19-L204) + +### Checkbox + +- **Capabilities**: Boolean selection; supports `onValueChange`. +- **Key Points**: + - Forwards the native event in `onChange` and triggers `onValueChange(value)`. +- **Typical usage path** + - [Checkbox component:4-19](file://frontend/antd/checkbox/checkbox.tsx#L4-L19) + +Section sources + +- [frontend/antd/checkbox/checkbox.tsx:4-19](file://frontend/antd/checkbox/checkbox.tsx#L4-L19) + +### ColorPicker + +- **Capabilities**: Supports solid color/gradient, preset colors, and multiple output formats (rgb/hex/hsb). +- **Key Points**: + - `onChange` returns different format arrays or a single string depending on whether gradient mode is active. + - Supports `presets` slot and `panelRender`/`showText` customization. +- **Typical usage path** + - [ColorPicker component:11-103](file://frontend/antd/color-picker/color-picker.tsx#L11-L103) + +Section sources + +- [frontend/antd/color-picker/color-picker.tsx:11-103](file://frontend/antd/color-picker/color-picker.tsx#L11-L103) + +### DatePicker + +- **Capabilities**: Single-date/range selection, time selection, preset shortcuts, disabled dates/times, custom cell/panel rendering. +- **Key Points**: + - Internally formats input values as `dayjs` and outputs second-level timestamps in `onChange`/`onPanelChange`. + - Supports `defaultValue` formatting within the `showTime` object. + - Supports slots: `presets`, `cellRender`, `panelRender`, `renderExtraFooter`, etc. +- **Typical usage path** + - [DatePicker component:40-231](file://frontend/antd/date-picker/date-picker.tsx#L40-L231) + +Section sources + +- [frontend/antd/date-picker/date-picker.tsx:40-231](file://frontend/antd/date-picker/date-picker.tsx#L40-L231) + +### Input + +- **Capabilities**: Basic text input; supports prefix/suffix, character counter, clear icon, and slot extensions. +- **Key Points**: + - `useValueChange` for controlled `value`. + - Supports `showCount.formatter` slot and `count`-series functions. + - Supports `addonBefore`/`addonAfter`, `prefix`/`suffix`, `allowClear.clearIcon`. +- **Typical usage path** + - [Input component:10-116](file://frontend/antd/input/input.tsx#L10-L116) + +Section sources + +- [frontend/antd/input/input.tsx:10-116](file://frontend/antd/input/input.tsx#L10-L116) + +### InputNumber + +- **Capabilities**: Numeric input; supports custom step buttons, prefix/suffix, `formatter`/`parser`. +- **Key Points**: + - `useValueChange` for controlled `value`. + - Supports `controls.upIcon`/`downIcon` slots and `addonBefore`/`addonAfter`, `prefix`/`suffix`. +- **Typical usage path** + - [InputNumber component:7-91](file://frontend/antd/input-number/input-number.tsx#L7-L91) + +Section sources + +- [frontend/antd/input-number/input-number.tsx:7-91](file://frontend/antd/input-number/input-number.tsx#L7-L91) + +### Mentions + +- **Capabilities**: `@` mention functionality; supports options list, filtering, and popup rendering. +- **Key Points**: + - `useValueChange` for controlled `value`. + - Supports `options`, `filterOption`, `validateSearch`, `getPopupContainer`. +- **Typical usage path** + - [Mentions component:11-77](file://frontend/antd/mentions/mentions.tsx#L11-L77) + +Section sources + +- [frontend/antd/mentions/mentions.tsx:11-77](file://frontend/antd/mentions/mentions.tsx#L11-L77) + +### Radio + +- **Capabilities**: Single-choice selection; supports `onValueChange`. +- **Key Points**: + - Forwards the native event in `onChange` and triggers `onValueChange(value)`. + - Injects theme tokens to adapt to style variables. +- **Typical usage path** + - [Radio component:6-29](file://frontend/antd/radio/radio.tsx#L6-L29) + +Section sources + +- [frontend/antd/radio/radio.tsx:6-29](file://frontend/antd/radio/radio.tsx#L6-L29) + +### Rate + +- **Capabilities**: Star rating; supports custom characters. +- **Key Points**: + - Supports `character` slot and functional configuration. + - `onChange` triggers `onValueChange`. +- **Typical usage path** + - [Rate component:6-42](file://frontend/antd/rate/rate.tsx#L6-L42) + +Section sources + +- [frontend/antd/rate/rate.tsx:6-42](file://frontend/antd/rate/rate.tsx#L6-L42) + +### Select + +- **Capabilities**: Single/multi-select; supports tag rendering, custom dropdown panel, filtering and sorting. +- **Key Points**: + - Supports two data sources: `options` and `children`. + - Supports `allowClear.clearIcon`, `prefix`/`removeIcon`/`suffixIcon`, `notFoundContent`, `menuItemSelectedIcon`. + - Supports `dropdownRender`/`popupRender`/`optionRender`/`tagRender`/`labelRender`. + - Supports `filterOption`/`filterSort`. +- **Typical usage path** + - [Select component:11-178](file://frontend/antd/select/select.tsx#L11-L178) + +Section sources + +- [frontend/antd/select/select.tsx:11-178](file://frontend/antd/select/select.tsx#L11-L178) + +### Slider + +- **Capabilities**: Single/double sliders; supports tick mark labels and tooltip formatting. +- **Key Points**: + - `marks` are rendered via `children`, supporting a `label` child slot. + - `tooltip` supports a `formatter` slot and function. +- **Typical usage path** + - [Slider component:37-94](file://frontend/antd/slider/slider.tsx#L37-L94) + +Section sources + +- [frontend/antd/slider/slider.tsx:37-94](file://frontend/antd/slider/slider.tsx#L37-L94) + +### Switch + +- **Capabilities**: Boolean toggle; supports custom label slots. +- **Key Points**: + - Supports `checkedChildren`/`unCheckedChildren` slots. + - `onChange` triggers `onValueChange`. +- **Typical usage path** + - [Switch component:6-39](file://frontend/antd/switch/switch.tsx#L6-L39) + +Section sources + +- [frontend/antd/switch/switch.tsx:6-39](file://frontend/antd/switch/switch.tsx#L6-L39) + +### TimePicker + +- **Capabilities**: Time selection, range selection, custom panel, disabled times. +- **Key Points**: + - Internally formats input values as `dayjs` and outputs second-level timestamps in `onChange`/`onPanelChange`/`onCalendarChange`. + - Supports slots: `cellRender`, `panelRender`, `renderExtraFooter`, etc. +- **Typical usage path** + - [TimePicker component:37-198](file://frontend/antd/time-picker/time-picker.tsx#L37-L198) + +Section sources + +- [frontend/antd/time-picker/time-picker.tsx:37-198](file://frontend/antd/time-picker/time-picker.tsx#L37-L198) + +### Transfer + +- **Capabilities**: Left-right list transfer; supports titles, select-all labels, action buttons, custom rendering and filtering. +- **Key Points**: + - `onChange` returns `targetKeys`. + - Supports `titles`/`selectAllLabels`/`actions` slots. + - Supports `render`/`footer`/`locale.notFoundContent`. +- **Typical usage path** + - [Transfer component:9-110](file://frontend/antd/transfer/transfer.tsx#L9-L110) + +Section sources + +- [frontend/antd/transfer/transfer.tsx:9-110](file://frontend/antd/transfer/transfer.tsx#L9-L110) + +### TreeSelect + +- **Capabilities**: Tree-structured selection; supports dynamic loading, filtering, tag rendering, and custom dropdown panel. +- **Key Points**: + - Supports two data sources: `treeData` and `children`. + - Supports `dropdownRender`/`popupRender`/`tagRender`/`treeTitleRender`. + - Supports `allowClear.clearIcon`, `prefix`/`suffix`, `switcherIcon`, `maxTagPlaceholder`, `notFoundContent`. + - `onLoadData` is integrated via a wrapper function. +- **Typical usage path** + - [TreeSelect component:14-161](file://frontend/antd/tree-select/tree-select.tsx#L14-L161) + +Section sources + +- [frontend/antd/tree-select/tree-select.tsx:14-161](file://frontend/antd/tree-select/tree-select.tsx#L14-L161) + +### Upload (pending) + +- The current repository does not provide a frontend wrapper implementation for Upload; API details and example paths are not available. +- It is recommended to refer to the official Ant Design Upload component and add `onValueChange` and slot support following the existing wrapper pattern. + +[No file analysis for this section; no section sources] + +## Dependency Analysis + +- **Inter-component Coupling**: Most components are decoupled via the unified `sveltify` wrapper and hooks (`useValueChange`, `useFunction`, `renderItems`, `renderParamsSlot`). +- **External Dependencies**: Ant Design React component library, `dayjs` (date/time formatting), React Slot/Svelte Preprocess (slot system). +- **Form Integration**: The Form component centrally manages form state and actions; other components collaborate with it via `onValueChange`. + +```mermaid +graph LR +A["AntD React Component Library"] --> B["sveltify wrapper"] +B --> C["Each data entry component"] +C --> D["hooks: useValueChange/useFunction"] +C --> E["renderItems/renderParamsSlot"] +F["Form Component"] --> C +``` + +Diagram sources + +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/input/input.tsx:3-42](file://frontend/antd/input/input.tsx#L3-L42) +- [frontend/antd/select/select.tsx:49-56](file://frontend/antd/select/select.tsx#L49-L56) + +Section sources + +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/input/input.tsx:3-42](file://frontend/antd/input/input.tsx#L3-L42) +- [frontend/antd/select/select.tsx:49-56](file://frontend/antd/select/select.tsx#L49-L56) + +## Performance Considerations + +- **Controlled vs. Uncontrolled**: Prefer controlled components (`value` + `onValueChange`) to avoid redundant rendering and state drift. +- **Slots and Functions**: Externalize complex slot logic as functions where possible to reduce unnecessary re-renders. +- **Option Rendering**: For Select/Cascader/TreeSelect/Mentions etc., it is recommended to pass static `options` to avoid generating new arrays on every render. +- **Date/Time**: DatePicker/TimePicker internally format `dayjs`; avoid redundant conversions in the parent component. +- **Slider and Rate**: Custom characters/labels in Rate/Slider should be kept lightweight to avoid heavy DOM structures. + +[This section provides general guidance; no specific file analysis] + +## Troubleshooting Guide + +- **Form Action Not Working** + - Confirm that Form's `formAction` is set to `reset`/`submit`/`validate` and reset the value after the action completes. + - Reference path: [Form action handling:32-45](file://frontend/antd/form/form.tsx#L32-L45) +- **Value Not Updating** + - Ensure `onValueChange` has been correctly set and triggered. + - Reference path: [Input value change:49-54](file://frontend/antd/input/input.tsx#L49-L54) +- **Date/Time Format Abnormality** + - DatePicker/TimePicker output second-level timestamps; ensure the backend converts them as needed. + - Reference path: [Date formatting:26-38](file://frontend/antd/date-picker/date-picker.tsx#L26-L38) +- **Options Not Displaying or Filter Not Working** + - Check that `options` have been passed or that `children` are rendering correctly. + - Reference path: [Select option rendering:64-77](file://frontend/antd/select/select.tsx#L64-L77) +- **Inconsistent Color Format** + - ColorPicker supports rgb/hex/hsb output; confirm the `value_format` configuration. + - Reference path: [Color formatting:71-95](file://frontend/antd/color-picker/color-picker.tsx#L71-L95) + +Section sources + +- [frontend/antd/form/form.tsx:32-45](file://frontend/antd/form/form.tsx#L32-L45) +- [frontend/antd/input/input.tsx:49-54](file://frontend/antd/input/input.tsx#L49-L54) +- [frontend/antd/date-picker/date-picker.tsx:26-38](file://frontend/antd/date-picker/date-picker.tsx#L26-L38) +- [frontend/antd/select/select.tsx:64-77](file://frontend/antd/select/select.tsx#L64-L77) +- [frontend/antd/color-picker/color-picker.tsx:71-95](file://frontend/antd/color-picker/color-picker.tsx#L71-L95) + +## Conclusion + +ModelScope Studio's data entry components achieve seamless integration with Ant Design through a unified wrapper pattern, providing rich slots and functional props to meet diverse business requirements. In practice, it is recommended to follow the controlled component principle, make good use of slots and functions, pay attention to date/time and color format conversion, and use the Form component to complete the full form interaction loop. + +[This section provides summary content; no specific file analysis] + +## Appendix + +### Component API Overview (by theme) + +- **Text Input** + - **Input**: Supports `value`, `onValueChange`, `addonBefore`/`addonAfter`, `prefix`/`suffix`, `allowClear.clearIcon`, `showCount.formatter` + - Reference path: [Input component:10-116](file://frontend/antd/input/input.tsx#L10-L116) + - **InputNumber**: Supports `value`, `onValueChange`, `formatter`, `parser`, `controls.upIcon`/`downIcon`, `addonBefore`/`addonAfter`, `prefix`/`suffix` + - Reference path: [InputNumber component:7-91](file://frontend/antd/input-number/input-number.tsx#L7-L91) + - **AutoComplete**: Supports `value`, `onValueChange`, `options`, `filterOption`, `dropdownRender`, `popupRender`, `allowClear.clearIcon`, `notFoundContent` + - Reference path: [AutoComplete component:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) + - **Mentions**: Supports `value`, `onValueChange`, `options`, `filterOption`, `validateSearch`, `getPopupContainer`, `notFoundContent` + - Reference path: [Mentions component:11-77](file://frontend/antd/mentions/mentions.tsx#L11-L77) + +- **Selectors** + - **Select**: Supports `value`, `onValueChange`, `options`, `filterOption`, `filterSort`, `allowClear.clearIcon`, `prefix`/`removeIcon`/`suffixIcon`, `notFoundContent`, `menuItemSelectedIcon`, `dropdownRender`/`popupRender`/`optionRender`/`tagRender`/`labelRender` + - Reference path: [Select component:11-178](file://frontend/antd/select/select.tsx#L11-L178) + - **Cascader**: Supports `value`, `onValueChange`, `options`, `showSearch`, `loadData`, `displayRender`/`tagRender`/`optionRender`, `dropdownRender`/`popupRender`, `allowClear.clearIcon`, `prefix`/`suffixIcon`, `expandIcon`, `removeIcon`, `notFoundContent`, `maxTagPlaceholder` + - Reference path: [Cascader component:19-204](file://frontend/antd/cascader/cascader.tsx#L19-L204) + - **TreeSelect**: Supports `value`, `onValueChange`, `treeData`, `filterTreeNode`, `loadData`, `dropdownRender`/`popupRender`/`tagRender`/`treeTitleRender`, `allowClear.clearIcon`, `prefix`/`suffix`, `switcherIcon`, `notFoundContent`, `maxTagPlaceholder` + - Reference path: [TreeSelect component:14-161](file://frontend/antd/tree-select/tree-select.tsx#L14-L161) + +- **Date and Time** + - **DatePicker**: Supports `value`, `onChange`/`onPanelChange`, `pickerValue`/`defaultPickerValue`, `showTime`, `disabledDate`/`disabledTime`, `cellRender`/`panelRender`, `presets`, `renderExtraFooter`, `prevIcon`/`nextIcon`/`suffixIcon`/`superNextIcon`/`superPrevIcon`, `allowClear.clearIcon` + - Reference path: [DatePicker component:40-231](file://frontend/antd/date-picker/date-picker.tsx#L40-L231) + - **TimePicker**: Supports `value`, `onChange`/`onPanelChange`/`onCalendarChange`, `pickerValue`/`defaultPickerValue`, `disabledDate`/`disabledTime`, `cellRender`/`panelRender`, `renderExtraFooter`, `prevIcon`/`nextIcon`/`suffixIcon`/`superNextIcon`/`superPrevIcon`, `allowClear.clearIcon` + - Reference path: [TimePicker component:37-198](file://frontend/antd/time-picker/time-picker.tsx#L37-L198) + +- **Interaction and Rating** + - **Checkbox**: Supports `value`, `onValueChange`, `onChange` + - Reference path: [Checkbox component:4-19](file://frontend/antd/checkbox/checkbox.tsx#L4-L19) + - **Radio**: Supports `value`, `onValueChange`, `onChange`, theme token injection + - Reference path: [Radio component:6-29](file://frontend/antd/radio/radio.tsx#L6-L29) + - **Rate**: Supports `value`, `onValueChange`, `onChange`, `character` slot/function + - Reference path: [Rate component:6-42](file://frontend/antd/rate/rate.tsx#L6-L42) + - **Switch**: Supports `value`, `onChange`, `checkedChildren`/`unCheckedChildren` slots + - Reference path: [Switch component:6-39](file://frontend/antd/switch/switch.tsx#L6-L39) + - **Slider**: Supports `value`, `onChange`, `marks` (children rendering), `tooltip.formatter` slot + - Reference path: [Slider component:37-94](file://frontend/antd/slider/slider.tsx#L37-L94) + +- **Color and Form** + - **ColorPicker**: Supports `value`, `onValueChange`, `onChange`, `value_format` (rgb/hex/hsb), `presets`, `panelRender`, `showText` + - Reference path: [ColorPicker component:11-103](file://frontend/antd/color-picker/color-picker.tsx#L11-L103) + - **Form**: Supports `value`, `onValueChange`, `formAction` (reset/submit/validate), `requiredMark`, `feedbackIcons` + - Reference path: [Form component:8-76](file://frontend/antd/form/form.tsx#L8-L76) + +- **Transfer** + - **Transfer**: Supports `value` (targetKeys), `onChange`, `titles`/`selectAllLabels`/`actions` slots, `render`/`footer`/`locale.notFoundContent`, `selectionsIcon` + - Reference path: [Transfer component:9-110](file://frontend/antd/transfer/transfer.tsx#L9-L110) + +[This section provides a summary overview; no specific file analysis] diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Feedback Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Feedback Components API.md new file mode 100644 index 00000000..58608580 --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Feedback Components API.md @@ -0,0 +1,383 @@ +# Feedback Components API + + +**Files referenced in this document** +- [frontend/antd/alert/alert.tsx](file://frontend/antd/alert/alert.tsx) +- [frontend/antd/drawer/drawer.tsx](file://frontend/antd/drawer/drawer.tsx) +- [frontend/antd/message/message.tsx](file://frontend/antd/message/message.tsx) +- [frontend/antd/modal/modal.tsx](file://frontend/antd/modal/modal.tsx) +- [frontend/antd/notification/notification.tsx](file://frontend/antd/notification/notification.tsx) +- [frontend/antd/popconfirm/popconfirm.tsx](file://frontend/antd/popconfirm/popconfirm.tsx) +- [frontend/antd/progress/progress.tsx](file://frontend/antd/progress/progress.tsx) +- [frontend/antd/result/result.tsx](file://frontend/antd/result/result.tsx) +- [frontend/antd/skeleton/skeleton.tsx](file://frontend/antd/skeleton/skeleton.tsx) +- [frontend/antd/spin/spin.tsx](file://frontend/antd/spin/spin.tsx) +- [frontend/antd/watermark/watermark.tsx](file://frontend/antd/watermark/watermark.tsx) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [docs/components/antd/alert/README.md](file://docs/components/antd/alert/README.md) +- [docs/components/antd/drawer/README.md](file://docs/components/antd/drawer/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the API reference for Ant Design-based feedback components in ModelScope Studio, covering: Alert, Drawer, Message, Modal, Notification, Popconfirm, Progress, Result, Skeleton, Spin, and Watermark. It includes: + +- Property definitions and type constraints +- State management and lifecycle +- Animation and interaction logic +- Standard instantiation and configuration example paths +- Event callbacks and asynchronous handling +- Accessibility and user experience design principles + +## Project Structure + +Feedback components are implemented on the frontend as Svelte wrappers that bridge Ant Design React components, and are uniformly exported via backend Python modules for on-demand use in applications. + +```mermaid +graph TB +subgraph "Frontend" +A1["alert.tsx"] +A2["drawer.tsx"] +A3["message.tsx"] +A4["modal.tsx"] +A5["notification.tsx"] +A6["popconfirm.tsx"] +A7["progress.tsx"] +A8["result.tsx"] +A9["skeleton.tsx"] +A10["spin.tsx"] +A11["watermark.tsx"] +end +subgraph "Backend" +B1["__init__.py"] +B2["components.py"] +end +A1 --> B1 +A2 --> B1 +A3 --> B1 +A4 --> B1 +A5 --> B1 +A6 --> B1 +A7 --> B1 +A8 --> B1 +A9 --> B1 +A10 --> B1 +A11 --> B1 +B1 --> B2 +``` + +Diagram sources + +- [frontend/antd/alert/alert.tsx:1-46](file://frontend/antd/alert/alert.tsx#L1-L46) +- [frontend/antd/drawer/drawer.tsx:1-60](file://frontend/antd/drawer/drawer.tsx#L1-L60) +- [frontend/antd/message/message.tsx:1-79](file://frontend/antd/message/message.tsx#L1-L79) +- [frontend/antd/modal/modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) +- [frontend/antd/notification/notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [frontend/antd/popconfirm/popconfirm.tsx:1-65](file://frontend/antd/popconfirm/popconfirm.tsx#L1-L65) +- [frontend/antd/progress/progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [frontend/antd/result/result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- [frontend/antd/watermark/watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +Section sources + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +## Core Components + +- **Alert**: Displays warning information requiring user attention; supports slots for `description`, `icon`, `action`, `closable.closeIcon`, etc. +- **Drawer**: A drawer panel that slides in from the screen edge; supports `title`, `footer`, `extra`, `closeIcon`, and render hooks. +- **Message**: Global hint message; supports visibility control, custom content and icons, and destroy/open operations. +- **Modal**: Modal dialog; supports `title`, `footer`, button icons, render hooks, and container mounting. +- **Notification**: Global notification alert; supports position, actions, close icon, description, and message. +- **Popconfirm**: Bubble confirmation; supports confirm/cancel text and icons, and popup container. +- **Progress**: Progress bar; supports `format` and `rounding` function handling. +- **Result**: Result page; supports `title`, `subTitle`, `icon`, and `extra` slots. +- **Skeleton**: Skeleton screen placeholder. +- **Spin**: Loading indicator; supports `tip` text and `indicator` slots. +- **Watermark**: Watermark overlay. + +Section sources + +- [frontend/antd/alert/alert.tsx:1-46](file://frontend/antd/alert/alert.tsx#L1-L46) +- [frontend/antd/drawer/drawer.tsx:1-60](file://frontend/antd/drawer/drawer.tsx#L1-L60) +- [frontend/antd/message/message.tsx:1-79](file://frontend/antd/message/message.tsx#L1-L79) +- [frontend/antd/modal/modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) +- [frontend/antd/notification/notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [frontend/antd/popconfirm/popconfirm.tsx:1-65](file://frontend/antd/popconfirm/popconfirm.tsx#L1-L65) +- [frontend/antd/progress/progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [frontend/antd/result/result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- [frontend/antd/watermark/watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) + +## Architecture Overview + +Feedback components follow a layered architecture of "Svelte wrapper + Ant Design React component + unified backend export": + +- **Frontend layer**: Each component wraps an Ant Design component with `sveltify`, supporting `slots` and function callback conversion. +- **Interaction layer**: Bridges callbacks and child nodes via utilities like `useFunction`/`useTargets`. +- **Export layer**: Python modules centrally export each component for unified import and aliasing in applications. + +```mermaid +sequenceDiagram +participant App as "Application" +participant Wrapper as "Svelte Wrapper" +participant AD as "Ant Design Component" +participant Util as "Utility Hooks" +App->>Wrapper : Passes props and slots +Wrapper->>Util : useFunction()/useTargets() +Util-->>Wrapper : Converted callbacks/target nodes +Wrapper->>AD : Renders and passes props/slots +AD-->>App : Fires event callbacks/state changes +``` + +Diagram sources + +- [frontend/antd/alert/alert.tsx:12-43](file://frontend/antd/alert/alert.tsx#L12-L43) +- [frontend/antd/drawer/drawer.tsx:24-57](file://frontend/antd/drawer/drawer.tsx#L24-L57) +- [frontend/antd/message/message.tsx:18-76](file://frontend/antd/message/message.tsx#L18-L76) +- [frontend/antd/modal/modal.tsx:22-104](file://frontend/antd/modal/modal.tsx#L22-L104) +- [frontend/antd/notification/notification.tsx:17-103](file://frontend/antd/notification/notification.tsx#L17-L103) + +## Component Details + +### Alert + +- **Key Capabilities** + - Supports slots: `message`, `description`, `icon`, `action`, `closable.closeIcon` + - The `afterClose` callback is converted via `useFunction` +- **Lifecycle** + - Renders based on props after mounting; fires `afterClose` upon dismissal +- **Interaction and Animation** + - Controlled by Ant Design's built-in animation and transitions +- **Example path** + - [docs/components/antd/alert/README.md:1-8](file://docs/components/antd/alert/README.md#L1-L8) + +Section sources + +- [frontend/antd/alert/alert.tsx:7-43](file://frontend/antd/alert/alert.tsx#L7-L43) + +### Drawer + +- **Key Capabilities** + - Supports slots: `title`, `footer`, `extra`, `closeIcon`, `closable.closeIcon`, `drawerRender` + - `afterOpenChange`, `getContainer`, `drawerRender` are handled via `useFunction`/`renderParamsSlot` +- **Lifecycle** + - Fires `afterOpenChange` when open/close state changes +- **Interaction and Animation** + - Ant Design drawer slide-in/slide-out animation +- **Example path** + - [docs/components/antd/drawer/README.md:1-9](file://docs/components/antd/drawer/README.md#L1-L9) + +Section sources + +- [frontend/antd/drawer/drawer.tsx:8-57](file://frontend/antd/drawer/drawer.tsx#L8-L57) + +### Message + +- **Key Capabilities** + - Obtains the API via `message.useMessage` + - Supports `visible` to control show/hide, with `onVisible` callback + - `content` and `icon` slots support customization + - `getContainer` is handled functionally +- **Lifecycle** + - Opens when `visible=true`; destroys when `visible=false` or on unmount +- **Async and Events** + - `onClose` simultaneously triggers `onVisible(false)` and the original `onClose` +- **Example path** + - Refer to demo examples in each component's README + +Section sources + +- [frontend/antd/message/message.tsx:9-76](file://frontend/antd/message/message.tsx#L9-L76) + +### Modal + +- **Key Capabilities** + - Supports `okText`, `okButtonProps.icon`, `cancelText`, `cancelButtonProps.icon`, `footer`, `title`, `modalRender`, `closable.closeIcon`, `closeIcon`, etc. + - `afterOpenChange`, `afterClose`, `getContainer`, `footer`, `modalRender` are handled via `useFunction`/`renderParamsSlot` +- **Lifecycle** + - Fires `afterOpenChange`/`afterClose` when open/close state changes +- **Interaction and Animation** + - Ant Design dialog open/close animation and overlay behavior + +Section sources + +- [frontend/antd/modal/modal.tsx:8-104](file://frontend/antd/modal/modal.tsx#L8-L104) + +### Notification + +- **Key Capabilities** + - Obtains the API via `notification.useNotification` + - Supports `visible` to control show/hide, with `onVisible` callback + - Supports slots: `btn`, `actions`, `closeIcon`, `description`, `icon`, `message` + - Position parameters: `top`, `bottom`, `rtl`, `stack` +- **Lifecycle** + - Opens when `visible=true`; destroys when `visible=false` or on unmount +- **Async and Events** + - `onClose` simultaneously triggers `onVisible(false)` and the original `onClose` + +Section sources + +- [frontend/antd/notification/notification.tsx:8-103](file://frontend/antd/notification/notification.tsx#L8-L103) + +### Popconfirm + +- **Key Capabilities** + - Supports `okText`, `okButtonProps.icon`, `cancelText`, `cancelButtonProps.icon`, `title`, `description` + - `afterOpenChange`, `getPopupContainer` are handled via `useFunction` +- **Lifecycle** + - Fires `afterOpenChange` when the popup opens/closes +- **Interaction and Animation** + - Ant Design bubble confirmation popup behavior + +Section sources + +- [frontend/antd/popconfirm/popconfirm.tsx:7-62](file://frontend/antd/popconfirm/popconfirm.tsx#L7-L62) + +### Progress + +- **Key Capabilities** + - Supports `format` and `rounding` function handling +- **Performance and Complexity** + - Pure display component with no complex computation + +Section sources + +- [frontend/antd/progress/progress.tsx:5-21](file://frontend/antd/progress/progress.tsx#L5-L21) + +### Result + +- **Key Capabilities** + - Supports slots: `title`, `subTitle`, `icon`, `extra` + - Uses `useTargets` to manage child node rendering strategy +- **Lifecycle** + - Renders child nodes when slots are present; hides default children otherwise + +Section sources + +- [frontend/antd/result/result.tsx:7-30](file://frontend/antd/result/result.tsx#L7-L30) + +### Skeleton + +- **Key Capabilities** + - Directly wraps Ant Design Skeleton +- **Usage Recommendations** + - Use as a placeholder display before data loads + +Section sources + +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) + +### Spin + +- **Key Capabilities** + - Supports `tip` and `indicator` slots + - Uses `useTargets` to control child node visibility +- **Lifecycle** + - Shows children when no slots are present; hides children and delegates rendering to Spin when slots exist + +Section sources + +- [frontend/antd/spin/spin.tsx:7-35](file://frontend/antd/spin/spin.tsx#L7-L35) + +### Watermark + +- **Key Capabilities** + - Directly wraps Ant Design Watermark +- **Usage Recommendations** + - Use for content protection and copyright marking + +Section sources + +- [frontend/antd/watermark/watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) + +## Dependency Analysis + +- **Unified Export** + - Backend modules centrally export each component for unified import and alias management on the application side +- **Inter-component Coupling** + - Components are relatively independent; collaboration primarily occurs through the Ant Design ecosystem and common utility hooks + +```mermaid +graph LR +Init["__init__.py"] --> Comp["components.py"] +Init --> |exports| C1["Alert"] +Init --> |exports| C2["Drawer"] +Init --> |exports| C3["Message"] +Init --> |exports| C4["Modal"] +Init --> |exports| C5["Notification"] +Init --> |exports| C6["Popconfirm"] +Init --> |exports| C7["Progress"] +Init --> |exports| C8["Result"] +Init --> |exports| C9["Skeleton"] +Init --> |exports| C10["Spin"] +Init --> |exports| C11["Watermark"] +``` + +Diagram sources + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +Section sources + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +## Performance Considerations + +- **Slot and Function Conversion** + - Use `useFunction` to bridge callback functions to the React environment, avoiding re-renders caused by redundant function creation +- **Conditional Rendering** + - Result/Spin precisely control child node rendering via `useTargets`, reducing unnecessary DOM structures +- **Destroy and Cleanup** + - Message/Notification actively `destroy` on unmount or when `visible=false`, preventing memory leaks and duplicate notifications + +## Troubleshooting Guide + +- **Slot Not Working** + - Confirm that the slot name matches the component definition (e.g., `closable.closeIcon`, `okButtonProps.icon`, etc.) +- **Callback Not Firing** + - Check that callbacks are wrapped via `useFunction`; ensure the function signature matches what Ant Design expects +- **Container Mounting Issues** + - `getContainer` supports string selectors or functions; if a string is passed, it is internally converted to a function +- **Notification/Message Not Dismissing** + - Ensure `destroy` is triggered when `visible=false` or the component unmounts; inspect the `onClose` callback chain + +Section sources + +- [frontend/antd/alert/alert.tsx:12-43](file://frontend/antd/alert/alert.tsx#L12-L43) +- [frontend/antd/drawer/drawer.tsx:24-57](file://frontend/antd/drawer/drawer.tsx#L24-L57) +- [frontend/antd/message/message.tsx:35-68](file://frontend/antd/message/message.tsx#L35-L68) +- [frontend/antd/notification/notification.tsx:38-95](file://frontend/antd/notification/notification.tsx#L38-L95) + +## Conclusion + +ModelScope Studio's feedback components achieve flexible extension of Ant Design components and a consistent usage experience through unified Svelte wrappers and utility hooks. Developers can quickly customize interaction and visual presentation via slots and functional callbacks, while simplified module management is enabled by unified backend exports. It is recommended to make appropriate use of each feedback component in real-world scenarios, combining loading strategies, visibility control, and accessibility requirements to enhance the user experience. + +## Appendix + +- **Examples and Demos** + - Refer to the demo examples in each component's README for a quick start: + - [docs/components/antd/alert/README.md:1-8](file://docs/components/antd/alert/README.md#L1-L8) + - [docs/components/antd/drawer/README.md:1-9](file://docs/components/antd/drawer/README.md#L1-L9) diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/General Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/General Components API.md new file mode 100644 index 00000000..4a649ac1 --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/General Components API.md @@ -0,0 +1,442 @@ +# General Components API + + +**Files referenced in this document** +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/float-button/float-button.tsx](file://frontend/antd/float-button/float-button.tsx) +- [frontend/antd/float-button/Index.svelte](file://frontend/antd/float-button/Index.svelte) +- [frontend/antd/icon/icon.tsx](file://frontend/antd/icon/icon.tsx) +- [frontend/antd/icon/Index.svelte](file://frontend/antd/icon/Index.svelte) +- [frontend/antd/typography/typography.base.tsx](file://frontend/antd/typography/typography.base.tsx) +- [frontend/antd/typography/Base.svelte](file://frontend/antd/typography/Base.svelte) +- [frontend/antd/typography/title/Index.svelte](file://frontend/antd/typography/title/Index.svelte) +- [frontend/antd/typography/paragraph/Index.svelte](file://frontend/antd/typography/paragraph/Index.svelte) +- [frontend/antd/typography/text/Index.svelte](file://frontend/antd/typography/text/Index.svelte) +- [frontend/antd/typography/link/Index.svelte](file://frontend/antd/typography/link/Index.svelte) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the API reference for general Ant Design-based components in ModelScope Studio, covering Button, FloatButton, Icon, and Typography. It includes: + +- Property definitions and event handling +- Slots and style customization +- Use cases and best practices +- TypeScript types and their correspondence to native Ant Design +- Responsive design, accessibility, and performance optimization recommendations + +## Project Structure + +These components follow a unified "Svelte entry + React wrapper" pattern: the Svelte entry handles prop forwarding, class name composition, and visibility control; the React wrapper interfaces with Ant Design components to implement slot rendering and complex interactions. + +```mermaid +graph TB +subgraph "Button" +B_Index["button/Index.svelte"] +B_Impl["button/button.tsx"] +end +subgraph "FloatButton" +F_Index["float-button/Index.svelte"] +F_Impl["float-button/float-button.tsx"] +end +subgraph "Icon" +I_Index["icon/Index.svelte"] +I_Impl["icon/icon.tsx"] +end +subgraph "Typography" +T_Base["typography/Base.svelte"] +T_Impl["typography/typography.base.tsx"] +T_Title["typography/title/Index.svelte"] +T_Para["typography/paragraph/Index.svelte"] +T_Text["typography/text/Index.svelte"] +T_Link["typography/link/Index.svelte"] +end +B_Index --> B_Impl +F_Index --> F_Impl +I_Index --> I_Impl +T_Title --> T_Base --> T_Impl +T_Para --> T_Base +T_Text --> T_Base +T_Link --> T_Base +``` + +Diagram sources + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/float-button/Index.svelte:1-70](file://frontend/antd/float-button/Index.svelte#L1-L70) +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) +- [frontend/antd/icon/icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [frontend/antd/typography/Base.svelte:1-85](file://frontend/antd/typography/Base.svelte#L1-L85) +- [frontend/antd/typography/typography.base.tsx:1-170](file://frontend/antd/typography/typography.base.tsx#L1-L170) +- [frontend/antd/typography/title/Index.svelte:1-12](file://frontend/antd/typography/title/Index.svelte#L1-L12) +- [frontend/antd/typography/paragraph/Index.svelte:1-12](file://frontend/antd/typography/paragraph/Index.svelte#L1-L12) +- [frontend/antd/typography/text/Index.svelte:1-12](file://frontend/antd/typography/text/Index.svelte#L1-L12) +- [frontend/antd/typography/link/Index.svelte:1-12](file://frontend/antd/typography/link/Index.svelte#L1-L12) + +Section sources + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/float-button/Index.svelte:1-70](file://frontend/antd/float-button/Index.svelte#L1-L70) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) +- [frontend/antd/typography/Base.svelte:1-85](file://frontend/antd/typography/Base.svelte#L1-L85) + +## Core Components + +- **Button**: Aligned with Ant Design Button; supports `icon` and `loading.icon` slots, with priority logic between `value` and child nodes. +- **FloatButton**: Aligned with Ant Design FloatButton; supports `icon`, `description`, `tooltip`, `tooltip.title`, and `badge.count` slots, with function bridging for tooltip configuration. +- **Icon**: Supports built-in Ant Design icon name mapping and IconFont; supports a custom `component` slot. +- **Typography**: A unified typography base supporting `title`, `paragraph`, `text`, and `link` variants, with slot-based configuration for `copyable`, `editable`, and `ellipsis`. + +Section sources + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/icon/icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [frontend/antd/typography/typography.base.tsx:1-170](file://frontend/antd/typography/typography.base.tsx#L1-L170) + +## Architecture Overview + +All components are unified through the Svelte entry, which handles: + +- Prop forwarding and extra prop merging +- Visibility control and class name composition +- Slot context injection +- Lazy loading and async component rendering + +The React wrapper layer handles: + +- Interfacing with Ant Design components +- Mapping slots to ReactSlot +- Conditional rendering and function bridging for complex configuration objects (e.g., `tooltip`, `ellipsis`) + +```mermaid +sequenceDiagram +participant Svelte as "Svelte Entry (Index.svelte)" +participant Loader as "importComponent" +participant ReactImpl as "React Wrapper (button.tsx/float-button.tsx/icon.tsx/typography.base.tsx)" +participant AntD as "Ant Design Component" +Svelte->>Loader : Dynamically imports component module +Loader-->>Svelte : Returns renderable component +Svelte->>ReactImpl : Passes props + slots + value +ReactImpl->>AntD : Renders and injects slots/config +AntD-->>ReactImpl : Render result +ReactImpl-->>Svelte : Render result +``` + +Diagram sources + +- [frontend/antd/button/Index.svelte:10-73](file://frontend/antd/button/Index.svelte#L10-L73) +- [frontend/antd/button/button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) +- [frontend/antd/float-button/Index.svelte:10-69](file://frontend/antd/float-button/Index.svelte#L10-L69) +- [frontend/antd/float-button/float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) +- [frontend/antd/icon/Index.svelte:10-66](file://frontend/antd/icon/Index.svelte#L10-L66) +- [frontend/antd/icon/icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- [frontend/antd/typography/Base.svelte:11-83](file://frontend/antd/typography/Base.svelte#L11-L83) +- [frontend/antd/typography/typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) + +## Component Details + +### Button + +- **Capability Overview** + - Supports all Ant Design Button props and events + - Slots: `icon`, `loading.icon` + - Content priority: renders child nodes when present, otherwise falls back to `value` +- **Key Behaviors** + - Injects `slots.icon` into Ant Design Button's `icon` + - Injects `slots.loading.icon` into `loading.icon`, preserving `loading.delay` if `loading` is an object +- **Use Cases** + - Basic buttons, buttons with icons, loading buttons +- **Examples (paths)** + - Basic usage: [frontend/antd/button/Index.svelte:59-73](file://frontend/antd/button/Index.svelte#L59-L73) + - Slot icons: [frontend/antd/button/button.tsx:18-30](file://frontend/antd/button/button.tsx#L18-L30) +- **Types and Native Correspondence** + - Wraps Ant Design Button's `GetProps` type via `sveltify`, maintaining a consistent prop signature +- **Styles and Accessibility** + - Controlled via `elem_classes`/`elem_id`/`elem_style`; accessibility provided by Ant Design +- **Performance** + - Child node detection with conditional rendering avoids unnecessary DOM updates + +```mermaid +flowchart TD +Start(["Enter Button Render"]) --> HasChildren{"Does child node exist?"} +HasChildren --> |Yes| RenderChild["Render child node"] +HasChildren --> |No| RenderValue["Render value"] +RenderChild --> InjectIcon["Inject slots.icon into AntD Button"] +RenderValue --> InjectIcon +InjectIcon --> LoadingCfg{"Is loading.icon configured?"} +LoadingCfg --> |Yes| MergeLoading["Merge loading with loading.icon.delay"] +LoadingCfg --> |No| PassThrough["Pass through loading directly"] +MergeLoading --> End(["Done"]) +PassThrough --> End +``` + +Diagram sources + +- [frontend/antd/button/button.tsx:11-36](file://frontend/antd/button/button.tsx#L11-L36) + +Section sources + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +### FloatButton + +- **Capability Overview** + - Supports all Ant Design FloatButton props and events + - Slots: `icon`, `description`, `tooltip`, `tooltip.title`, `badge.count` + - `tooltip` supports object configuration; internally bridges `afterOpenChange`, `getPopupContainer`, and other functions via `useFunction` +- **Key Behaviors** + - Enables tooltip configuration when `slots.tooltip` exists or `tooltip` is an object + - Maps `slots.icon`/`description`/`badge.count` to their corresponding props +- **Use Cases** + - Back-to-top, floating action panels, floating entry points with description and badge +- **Examples (paths)** + - Basic usage: [frontend/antd/float-button/Index.svelte:56-69](file://frontend/antd/float-button/Index.svelte#L56-L69) + - Slots and tooltip configuration: [frontend/antd/float-button/float-button.tsx:19-72](file://frontend/antd/float-button/float-button.tsx#L19-L72) +- **Types and Native Correspondence** + - Wraps Ant Design FloatButton's `GetProps` type via `sveltify`, with an additional `id` field +- **Styles and Accessibility** + - Controlled via `elem_classes`/`elem_id`/`elem_style`; accessibility provided by Ant Design +- **Performance** + - Conditional rendering of tooltip and slots reduces unnecessary overhead + +```mermaid +sequenceDiagram +participant S as "Svelte Entry" +participant R as "React Wrapper" +participant T as "tooltip config" +participant A as "AntD FloatButton" +S->>R : Passes props + slots +R->>T : Checks if tooltip is an object or slots.tooltip.title exists +alt Tooltip enabled +T-->>R : Merges config and bridges functions +else Not enabled +T-->>R : Passes through tooltip directly +end +R->>A : Renders and injects icon/description/badge/count +A-->>R : Render result +``` + +Diagram sources + +- [frontend/antd/float-button/float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) +- [frontend/antd/float-button/Index.svelte:1-70](file://frontend/antd/float-button/Index.svelte#L1-L70) + +Section sources + +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/float-button/Index.svelte:1-70](file://frontend/antd/float-button/Index.svelte#L1-L70) + +### Icon + +- **Capability Overview** + - Supports Ant Design built-in icon name mapping + - Supports font icons provided by `IconFontProvider` + - Slot: `component` (for custom SVG components) +- **Key Behaviors** + - If `slots.component` is provided, renders the custom component with Ant Design `IconWrapper` + - Otherwise, looks up the built-in icon by `value` or uses `IconFont.type` +- **Use Cases** + - Inline text icons, button icons, custom vector icons +- **Examples (paths)** + - Basic usage: [frontend/antd/icon/Index.svelte:52-66](file://frontend/antd/icon/Index.svelte#L52-L66) + - Custom component and IconFont: [frontend/antd/icon/icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- **Types and Native Correspondence** + - Wraps Ant Design Icons' `GetProps` type via `sveltify`, with an additional `value` field +- **Styles and Accessibility** + - Controlled via `elem_classes`/`elem_id`/`elem_style`; accessibility provided by Ant Design +- **Performance** + - `useMemo` caches custom components to avoid redundant creation + +```mermaid +flowchart TD +Start(["Enter Icon Render"]) --> HasCustom{"Does slots.component exist?"} +HasCustom --> |Yes| WrapCustom["Wrap custom component with Ant Design IconWrapper"] +HasCustom --> |No| LookupIcon{"Is value a built-in icon name?"} +LookupIcon --> |Yes| RenderBuiltin["Render built-in icon"] +LookupIcon --> |No| UseIconFont{"Does IconFont context exist?"} +UseIconFont --> |Yes| RenderIconFont["Use IconFont(type=value)"] +UseIconFont --> |No| Noop["Not rendered"] +WrapCustom --> End(["Done"]) +RenderBuiltin --> End +RenderIconFont --> End +Noop --> End +``` + +Diagram sources + +- [frontend/antd/icon/icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) + +Section sources + +- [frontend/antd/icon/icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) + +### Typography + +- **Capability Overview** + - Unified base: four variants — `title`, `paragraph`, `text`, `link` + - Supports slot-based configuration for `copyable`, `editable`, and `ellipsis` + - Slots: `copyable.icon`, `copyable.tooltips`, `editable.icon`, `editable.tooltip`, `editable.enterIcon`, `ellipsis.symbol`, `ellipsis.tooltip`, `ellipsis.tooltip.title` +- **Key Behaviors** + - Selects the corresponding Ant Design Typography component based on `component` + - Conditionally injects `copyable`, `editable`, and `ellipsis` configuration + - `ellipsis` enablement conditions differ for the `link` component +- **Use Cases** + - Unified typography and interaction for headings, paragraphs, text, and links +- **Examples (paths)** + - Basic usage: [frontend/antd/typography/Base.svelte:65-84](file://frontend/antd/typography/Base.svelte#L65-L84) + - Sub-component aliases: [frontend/antd/typography/title/Index.svelte:9-11](file://frontend/antd/typography/title/Index.svelte#L9-L11) + - Slot and config merging: [frontend/antd/typography/typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) +- **Types and Native Correspondence** + - Wraps multiple Ant Design Typography types via `sveltify`, with additional `component` and `value` fields +- **Styles and Accessibility** + - Controlled via `elem_classes`/`elem_id`/`elem_style`; accessibility provided by Ant Design +- **Performance** + - Conditional rendering with slot target collection reduces unnecessary overhead + +```mermaid +sequenceDiagram +participant S as "Base.svelte" +participant R as "typography.base.tsx" +participant T as "Typography Component" +participant C as "copyable/editable/ellipsis" +S->>R : Passes component/value + slots +R->>R : Parses copyable/editable/ellipsis config +alt Capability supported +R->>C : Injects slots.icon/tooltip/symbol/... and merges config +else Not supported +R->>C : No injection, keeps undefined +end +R->>T : Renders corresponding Typography component +T-->>R : Render result +``` + +Diagram sources + +- [frontend/antd/typography/Base.svelte:11-83](file://frontend/antd/typography/Base.svelte#L11-L83) +- [frontend/antd/typography/typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) + +Section sources + +- [frontend/antd/typography/typography.base.tsx:1-170](file://frontend/antd/typography/typography.base.tsx#L1-L170) +- [frontend/antd/typography/Base.svelte:1-85](file://frontend/antd/typography/Base.svelte#L1-L85) +- [frontend/antd/typography/title/Index.svelte:1-12](file://frontend/antd/typography/title/Index.svelte#L1-L12) +- [frontend/antd/typography/paragraph/Index.svelte:1-12](file://frontend/antd/typography/paragraph/Index.svelte#L1-L12) +- [frontend/antd/typography/text/Index.svelte:1-12](file://frontend/antd/typography/text/Index.svelte#L1-L12) +- [frontend/antd/typography/link/Index.svelte:1-12](file://frontend/antd/typography/link/Index.svelte#L1-L12) + +## Dependency Analysis + +- **Inter-component Coupling** + - The four Typography sub-components are merely aliases for Base, reducing duplication and coupling + - Button/FloatButton/Icon separate entry from implementation for ease of maintenance and extension +- **External Dependencies** + - Ant Design component library (Button, FloatButton, Typography, Icon, etc.) + - `@svelte-preprocess-react` (sveltify, ReactSlot, useFunction, etc.) + - Utility functions: `useTargets`, `useSlotsChildren`, `omitUndefinedProps`, `renderParamsSlot`, etc. +- **Potential Circular Dependencies** + - No direct circular dependencies found; all components follow a unidirectional dependency: entry → implementation → Ant Design + +```mermaid +graph LR +S_Button["button/Index.svelte"] --> R_Button["button/button.tsx"] +S_Float["float-button/Index.svelte"] --> R_Float["float-button/float-button.tsx"] +S_Icon["icon/Index.svelte"] --> R_Icon["icon/icon.tsx"] +S_TBase["typography/Base.svelte"] --> R_TBase["typography/typography.base.tsx"] +R_TBase --> AntD["Ant Design Components"] +R_Button --> AntD +R_Float --> AntD +R_Icon --> AntD +``` + +Diagram sources + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/float-button/Index.svelte:1-70](file://frontend/antd/float-button/Index.svelte#L1-L70) +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) +- [frontend/antd/icon/icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [frontend/antd/typography/Base.svelte:1-85](file://frontend/antd/typography/Base.svelte#L1-L85) +- [frontend/antd/typography/typography.base.tsx:1-170](file://frontend/antd/typography/typography.base.tsx#L1-L170) + +Section sources + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/float-button/Index.svelte:1-70](file://frontend/antd/float-button/Index.svelte#L1-L70) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) +- [frontend/antd/typography/Base.svelte:1-85](file://frontend/antd/typography/Base.svelte#L1-L85) + +## Performance Considerations + +- **On-demand Rendering** + - Conditional checks and slot detection inject configuration and slots only when needed, reducing rendering cost +- **Function Bridging** + - Callbacks in configurations like `tooltip` are bridged via `useFunction`, avoiding new function creation on every render +- **Computed Caching** + - `Icon` uses `useMemo` to cache custom components, avoiding redundant creation +- **Async Loading** + - Lazy loading via `importComponent` reduces initial page load pressure + +## Troubleshooting Guide + +- **Slot Not Working** + - Verify that the slot name matches the component's supported list (e.g., Button: `icon`, `loading.icon`; FloatButton: `icon`/`description`/`tooltip`/`badge.count`; Typography: `copyable.*`, `editable.*`, `ellipsis.*`) +- **Tooltip Callback Not Working** + - When `tooltip` is an object, ensure related callbacks have been bridged via `useFunction` +- **Custom Icon Not Displayed** + - Ensure `value` is a valid icon name or that the IconFont context is available +- **`ellipsis` Not Working on `link`** + - Ensure `ellipsis` configuration is present or the slot has been provided +- **Visibility Issues** + - Ensure the `visible` prop is correctly passed to the entry component + +Section sources + +- [frontend/antd/button/button.tsx:11-36](file://frontend/antd/button/button.tsx#L11-L36) +- [frontend/antd/float-button/float-button.tsx:19-72](file://frontend/antd/float-button/float-button.tsx#L19-L72) +- [frontend/antd/icon/icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- [frontend/antd/typography/typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) +- [frontend/antd/button/Index.svelte:59-73](file://frontend/antd/button/Index.svelte#L59-L73) +- [frontend/antd/float-button/Index.svelte:56-69](file://frontend/antd/float-button/Index.svelte#L56-L69) +- [frontend/antd/icon/Index.svelte:52-66](file://frontend/antd/icon/Index.svelte#L52-L66) +- [frontend/antd/typography/Base.svelte:65-84](file://frontend/antd/typography/Base.svelte#L65-L84) + +## Conclusion + +The above components implement deep alignment with and flexible extension of Ant Design through a unified Svelte + React wrapper pattern. Using the slot system and utility functions, developers can achieve rich interaction and style customization while maintaining type safety. It is recommended to follow the prop and slot conventions documented here, combined with the performance and accessibility recommendations, to achieve a more stable and maintainable user experience. + +## Appendix + +- **Props and Slots Summary** + - **Button** + - Props: inherits all Ant Design Button props + - Slots: `icon`, `loading.icon` + - **FloatButton** + - Props: inherits all Ant Design FloatButton props + - Slots: `icon`, `description`, `tooltip`, `tooltip.title`, `badge.count` + - **Icon** + - Props: `value` (string), inherits all Ant Design Icon props + - Slots: `component` (custom SVG component) + - **Typography** + - Props: `component` (`'title'|'paragraph'|'text'|'link'`), `value` (string) + - Slots: `copyable.icon`, `copyable.tooltips`; `editable.icon`, `editable.tooltip`, `editable.enterIcon`; `ellipsis.symbol`, `ellipsis.tooltip`, `ellipsis.tooltip.title` diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Layout Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Layout Components API.md new file mode 100644 index 00000000..83606490 --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Layout Components API.md @@ -0,0 +1,398 @@ +# Layout Components API + + +**Files referenced in this document** +- [divider.tsx](file://frontend/antd/divider/divider.tsx) +- [flex.tsx](file://frontend/antd/flex/flex.tsx) +- [grid/context.ts](file://frontend/antd/grid/context.ts) +- [grid/row/row.tsx](file://frontend/antd/grid/row/row.tsx) +- [grid/col/col.tsx](file://frontend/antd/grid/col/col.tsx) +- [layout/layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) +- [layout/Base.svelte](file://frontend/antd/layout/Base.svelte) +- [layout.sider/layout.sider.tsx](file://frontend/antd/layout/sider/layout.sider.tsx) +- [space/space.tsx](file://frontend/antd/space/space.tsx) +- [splitter/splitter.tsx](file://frontend/antd/splitter/splitter.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the API reference for Ant Design-based layout components in ModelScope Studio, covering Divider, Flex, Grid (Row/Col), Layout (Header/Footer/Sider/Content), Space, and Splitter. It includes: + +- Property definitions and type sources for each component +- Layout algorithms and nesting rules +- Responsive behavior and key points of size calculation +- Correspondence with CSS Grid/Flexbox +- Standard usage paths and best practices +- Performance optimization and mobile adaptation recommendations + +## Project Structure + +These layout components expose Ant Design's React components as Svelte components through a unified Svelte preprocessing bridge. The core patterns are: + +- Using `sveltify` to wrap Ant Design components as Svelte components +- Collecting and rendering child items via context and Slot mechanisms +- Dynamically selecting specific Ant Design sub-components (e.g., Header/Footer/Content/Layout) via a Base component as needed + +```mermaid +graph TB +subgraph "Antd Wrapper Layer" +D["Divider
divider.tsx"] +F["Flex
flex.tsx"] +G["Grid.Row/Col
row.tsx / col.tsx"] +L["Layout.Base
layout.base.tsx"] +S["Space
space.tsx"] +SP["Splitter
splitter.tsx"] +end +subgraph "Context and Slots" +Ctx["Grid Context
grid/context.ts"] +Slots["ReactSlot / useTargets
Space Rendering"] +end +D --> |"sveltify"| AntD_D["antd.Divider"] +F --> |"sveltify"| AntD_F["antd.Flex"] +G --> |"useItems context"| Ctx +G --> |"ReactSlot"| Slots +L --> |"Dynamic component selection"| AntD_L["antd.Layout.*"] +S --> |"ReactSlot / useTargets"| Slots +SP --> |"withItemsContextProvider"| Ctx +SP --> |"ReactSlot"| Slots +``` + +Diagram sources + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) + +Section sources + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) + +## Core Components + +- **Divider**: A dividing line supporting child nodes as custom content or empty content. +- **Flex**: A flexbox layout container that forwards all Ant Design Flex props. +- **Grid**: A Row/Col combination implementing a grid system; Col registers itself to Row via context. +- **Layout**: The Base component dynamically maps to Header/Footer/Content/Layout based on the `component` prop. +- **Space**: Enhances slot rendering and separator slots on top of Ant Design Space. +- **Splitter**: A split-panel container that collects Panel children via context and renders them. + +Section sources + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) + +## Architecture Overview + +The following diagram shows how layout components organize child items through context and Slot mechanisms, ultimately rendering as an Ant Design component tree. + +```mermaid +sequenceDiagram +participant App as "Application" +participant Row as "Grid.Row
row.tsx" +participant Ctx as "Grid Context
context.ts" +participant Col as "Grid.Col
col.tsx" +participant Base as "Layout.Base
layout.base.tsx" +App->>Row : Renders Row and provides children +Row->>Ctx : withItemsContextProvider registers default list +Col->>Ctx : ItemHandler registers column item +Row->>Row : useItems retrieves default list +Row->>App : Renders ARow + ACol*ReactSlot rendering +App->>Base : Renders Base and specifies component +Base->>Base : Selects ALayout.Header/Footer/Content/Layout based on component +Base-->>App : Returns Ant Design component +``` + +Diagram sources + +- [grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) +- [layout/layout.base.tsx:13-37](file://frontend/antd/layout/layout.base.tsx#L13-L37) + +## Component Details + +### Divider + +- **Function**: Provides horizontal or vertical dividing lines, with optional custom child nodes (e.g., icons, text). +- **Key Points**: + - When child nodes are present, they are passed to Ant Design Divider; otherwise, an empty divider is rendered. + - Types come from Ant Design Divider Props. +- **Typical usage path** + - [divider.tsx:5-12](file://frontend/antd/divider/divider.tsx#L5-L12) + +Section sources + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) + +### Flex + +- **Function**: An Ant Design Flex container supporting main-axis/cross-axis alignment, wrapping, and other layout props. +- **Key Points**: + - Directly forwards all Ant Design Flex Props. + - Suitable for complex flexbox layout scenarios. +- **Typical usage path** + - [flex.tsx:4-8](file://frontend/antd/flex/flex.tsx#L4-L8) + +Section sources + +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) + +### Grid + +- **Row/Col Combination** + - **Row**: Collects Col children via context, renders as Ant Design Row, and renders Col content via Slot. + - **Col**: Registers itself into Row's context via `ItemHandler`. +- **Context** + - Provides `withItemsContextProvider`, `useItems`, and `ItemHandler` for collecting and distributing child items. +- **Responsive and Nesting** + - Supports responsive breakpoint props (controlled by Ant Design Row/Col Props); Col can be nested within Row. +- **Typical usage paths** + - [grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) + - [grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) + - [grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) + +```mermaid +classDiagram +class GridContext { ++withItemsContextProvider(slots) ++useItems() ++ItemHandler +} +class Row { ++props : RowProps ++children : Col* ++render() : ARow + ACol* +} +class Col { ++props : ColProps ++register() : ItemHandler +} +Row --> GridContext : "Registers/consumes default list" +Col --> GridContext : "Registers into default list" +``` + +Diagram sources + +- [grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) +- [grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) + +Section sources + +- [grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) + +### Layout + +- **Base Component** + - Dynamically maps to Header/Footer/Content/Layout based on the `component` prop. + - Supports extra class names and style forwarding. +- **Sider Sub-component** + - Exported via a separate file; used with Layout to implement sidebars. +- **Typical usage paths** + - [layout/layout.base.tsx:13-37](file://frontend/antd/layout/layout.base.tsx#L13-L37) + - [layout/Base.svelte:53-67](file://frontend/antd/layout/Base.svelte#L53-L67) + - [layout.sider/layout.sider.tsx](file://frontend/antd/layout/sider/layout.sider.tsx) + +```mermaid +sequenceDiagram +participant Svelte as "Base.svelte" +participant Base as "layout.base.tsx" +participant AD as "antd.Layout.*" +Svelte->>Base : Passes component and props +Base->>Base : Selects Header/Footer/Content/Layout based on component +Base->>AD : Renders corresponding component and forwards props +AD-->>Svelte : Returns DOM +``` + +Diagram sources + +- [layout/Base.svelte:53-67](file://frontend/antd/layout/Base.svelte#L53-L67) +- [layout/layout.base.tsx:13-37](file://frontend/antd/layout/layout.base.tsx#L13-L37) + +Section sources + +- [layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [layout.sider/layout.sider.tsx](file://frontend/antd/layout/sider/layout.sider.tsx) + +### Space + +- **Function**: Inserts spacing between elements, supporting a custom separator slot. +- **Key Points**: + - Uses `useTargets` to parse children, hides the real DOM, and renders via Ant Design Space. + - Supports a `split` slot for custom separators. +- **Typical usage path** + - [space/space.tsx:7-26](file://frontend/antd/space/space.tsx#L7-L26) + +```mermaid +flowchart TD +Start(["Start"]) --> Parse["Parse children into target list"] +Parse --> Hide["Hide real DOM"] +Hide --> Render["Render Ant Design Space"] +Render --> Split{"Is split slot provided?"} +Split --> |Yes| UseSplit["Use split slot"] +Split --> |No| UseProp["Use props.split"] +UseSplit --> Done(["Done"]) +UseProp --> Done +``` + +Diagram sources + +- [space/space.tsx:8-26](file://frontend/antd/space/space.tsx#L8-L26) + +Section sources + +- [space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) + +### Splitter + +- **Function**: Splits an area into multiple panels with draggable size adjustment. +- **Key Points**: + - Collects Panel children from the default slot via `withItemsContextProvider`. + - Uses `ReactSlot` to render each Panel's content. +- **Typical usage path** + - [splitter/splitter.tsx:7-35](file://frontend/antd/splitter/splitter.tsx#L7-L35) + +```mermaid +sequenceDiagram +participant App as "Application" +participant Splitter as "Splitter
splitter.tsx" +participant Ctx as "Context
context.ts" +participant Panel as "Panel" +App->>Splitter : Renders Splitter and provides children +Splitter->>Ctx : withItemsContextProvider registers default panel list +Splitter->>Splitter : useItems retrieves default panels +Splitter->>Panel : Renders each Panel and injects content +Panel-->>App : Returns draggable panel +``` + +Diagram sources + +- [splitter/splitter.tsx:7-35](file://frontend/antd/splitter/splitter.tsx#L7-L35) +- [grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) + +Section sources + +- [splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) + +## Dependency Analysis + +- **Inter-component Coupling** + - Grid.Row/Col depends on Grid context for child item collection and distribution. + - Space/Splitter depends on the common Slot mechanism and target resolution utilities. + - Layout.Base implements multi-form layouts through dynamic component selection. +- **External Dependencies** + - Ant Design component library (Divider, Flex, Grid, Layout, Space, Splitter). + - Svelte preprocessing toolchain (sveltify, ReactSlot, useTargets). + - Style utilities (classnames) for conditional class name composition. + +```mermaid +graph LR +Row["Grid.Row"] --> Ctx["Grid Context"] +Col["Grid.Col"] --> Ctx +Space["Space"] --> Slot["ReactSlot / useTargets"] +Splitter["Splitter"] --> Ctx +Splitter --> Slot +LayoutBase["Layout.Base"] --> AD["antd.Layout.*"] +``` + +Diagram sources + +- [grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) +- [grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) +- [space/space.tsx:8-26](file://frontend/antd/space/space.tsx#L8-L26) +- [splitter/splitter.tsx:7-35](file://frontend/antd/splitter/splitter.tsx#L7-L35) +- [layout/layout.base.tsx:13-37](file://frontend/antd/layout/layout.base.tsx#L13-L37) + +Section sources + +- [grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +## Performance Considerations + +- **Virtualization and Lazy Loading** + - For Grid/Space/Splitter with long lists or many children, prefer virtualization or pagination strategies to reduce upfront rendering overhead. +- **Slot Rendering Optimization** + - Space hides the real DOM and only renders Ant Design Space, avoiding redundant rendering and style jitter. +- **Conditional Rendering** + - Layout.Base dynamically selects components based on `component`, avoiding unnecessary DOM structure. +- **Responsive Breakpoints** + - Grid uses Ant Design breakpoint params; set responsive thresholds appropriately to avoid frequent reflows. +- **Mobile Adaptation** + - On small screens, prefer Flex or Space's compact mode to reduce overflow issues from fixed-width layouts. + - For Splitter on mobile, it is recommended to limit minimum panel size and disable dragging to improve interaction stability. + +## Troubleshooting Guide + +- **Grid Children Not Displayed** + - Check that Row correctly wraps Col and that Col has registered to the context via `ItemHandler`. + - Confirm that Row's children include Col and that Col's `el` is valid. +- **Space Separator Not Working** + - Confirm that the `split` slot or `props.split` has been provided, and that the slot content can be correctly rendered by ReactSlot. +- **Splitter Panel Empty** + - Confirm that Panel has been registered in the default slot and that Panel's `el` is valid. +- **Layout Style Abnormalities** + - Check that the `component` passed to the Base component matches expectations, and confirm that the class name composition logic has not been overridden. + +Section sources + +- [grid/row/row.tsx:12-29](file://frontend/antd/grid/row/row.tsx#L12-L29) +- [grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) +- [space/space.tsx:13-22](file://frontend/antd/space/space.tsx#L13-L22) +- [splitter/splitter.tsx:9-31](file://frontend/antd/splitter/splitter.tsx#L9-L31) +- [layout/layout.base.tsx:31-35](file://frontend/antd/layout/layout.base.tsx#L31-L35) + +## Conclusion + +ModelScope Studio's layout components present Ant Design's layout capabilities in a more ergonomic way through a unified Svelte preprocessing bridge. Grid, Layout, Space, Splitter, and other components maintain consistency with the Ant Design API while enhancing slot and context capabilities, making them suitable for composing and reusing complex layout scenarios. Following the property definitions, nesting rules, and performance recommendations in this document will deliver a stable and efficient layout experience on both desktop and mobile. + +## Appendix + +- **Correspondence with CSS Grid/Flexbox** + - Grid.Row/Col corresponds to row/column division in CSS Grid; Flex corresponds to CSS Flexbox. + - Space corresponds to flex gap distribution; Splitter corresponds to draggable area partitioning. +- **Common Layout Scenarios** + - **Grid system**: Row + Col combination, controlling column width and wrapping by breakpoint. + - **Flexbox layout**: Flex container with multiple children, controlling main-axis and cross-axis alignment. + - **Split panels**: Splitter with multiple Panels, supporting draggable size adjustment. + - **Page layout**: Layout.Base selecting Header/Footer/Content/Sider combinations as needed. diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Navigation Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Navigation Components API.md new file mode 100644 index 00000000..b66562ca --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Navigation Components API.md @@ -0,0 +1,462 @@ +# Navigation Components API + + +**Files referenced in this document** +- [frontend/antd/anchor/Index.svelte](file://frontend/antd/anchor/Index.svelte) +- [frontend/antd/anchor/anchor.tsx](file://frontend/antd/anchor/anchor.tsx) +- [frontend/antd/anchor/context.ts](file://frontend/antd/anchor/context.ts) +- [frontend/antd/breadcrumb/Index.svelte](file://frontend/antd/breadcrumb/Index.svelte) +- [frontend/antd/breadcrumb/breadcrumb.tsx](file://frontend/antd/breadcrumb/breadcrumb.tsx) +- [frontend/antd/breadcrumb/context.ts](file://frontend/antd/breadcrumb/context.ts) +- [frontend/antd/breadcrumb/item/Index.svelte](file://frontend/antd/breadcrumb/item/Index.svelte) +- [frontend/antd/dropdown/Index.svelte](file://frontend/antd/dropdown/Index.svelte) +- [frontend/antd/dropdown/dropdown.tsx](file://frontend/antd/dropdown/dropdown.tsx) +- [frontend/antd/menu/Index.svelte](file://frontend/antd/menu/Index.svelte) +- [frontend/antd/menu/menu.tsx](file://frontend/antd/menu/menu.tsx) +- [frontend/antd/menu/context.ts](file://frontend/antd/menu/context.ts) +- [frontend/antd/menu/item/Index.svelte](file://frontend/antd/menu/item/Index.svelte) +- [frontend/antd/pagination/Index.svelte](file://frontend/antd/pagination/Index.svelte) +- [frontend/antd/pagination/pagination.tsx](file://frontend/antd/pagination/pagination.tsx) +- [frontend/antd/steps/Index.svelte](file://frontend/antd/steps/Index.svelte) +- [frontend/antd/steps/steps.tsx](file://frontend/antd/steps/steps.tsx) +- [frontend/antd/steps/context.ts](file://frontend/antd/steps/context.ts) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the API reference for Ant Design-based navigation components in ModelScope Studio, covering: Anchor, Breadcrumb, Dropdown, Menu, Pagination, and Steps. It provides a systematic overview of architecture design, data flow, processing logic, type definitions, event binding, routing integration, permission control, and dynamic loading, along with reusable usage patterns and best practices. + +## Project Structure + +Navigation components use a unified "Svelte wrapper layer + React component bridge" pattern on the frontend: + +- The Svelte layer handles prop forwarding, visibility control, style injection, slot rendering, and lazy loading. +- The React layer bridges native Ant Design components into the Svelte ecosystem via `sveltify`, while providing slot rendering, function hooks, and context injection capabilities. + +```mermaid +graph TB +subgraph "Svelte Wrapper Layer" +A_Index["anchor/Index.svelte"] +B_Index["breadcrumb/Index.svelte"] +C_Index["dropdown/Index.svelte"] +D_Index["menu/Index.svelte"] +E_Index["pagination/Index.svelte"] +F_Index["steps/Index.svelte"] +end +subgraph "React Bridge Layer" +A_Core["anchor.tsx"] +B_Core["breadcrumb.tsx"] +C_Core["dropdown.tsx"] +D_Core["menu.tsx"] +E_Core["pagination.tsx"] +F_Core["steps.tsx"] +end +A_Index --> A_Core +B_Index --> B_Core +C_Index --> C_Core +D_Index --> D_Core +E_Index --> E_Core +F_Index --> F_Core +``` + +Diagram sources + +- [frontend/antd/anchor/Index.svelte:1-66](file://frontend/antd/anchor/Index.svelte#L1-L66) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/dropdown/Index.svelte:1-70](file://frontend/antd/dropdown/Index.svelte#L1-L70) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/Index.svelte:1-75](file://frontend/antd/menu/Index.svelte#L1-L75) +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/pagination/Index.svelte:1-68](file://frontend/antd/pagination/Index.svelte#L1-L68) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [frontend/antd/steps/Index.svelte:1-63](file://frontend/antd/steps/Index.svelte#L1-L63) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) + +Section sources + +- [frontend/antd/anchor/Index.svelte:1-66](file://frontend/antd/anchor/Index.svelte#L1-L66) +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/dropdown/Index.svelte:1-70](file://frontend/antd/dropdown/Index.svelte#L1-L70) +- [frontend/antd/menu/Index.svelte:1-75](file://frontend/antd/menu/Index.svelte#L1-L75) +- [frontend/antd/pagination/Index.svelte:1-68](file://frontend/antd/pagination/Index.svelte#L1-L68) +- [frontend/antd/steps/Index.svelte:1-63](file://frontend/antd/steps/Index.svelte#L1-L63) + +## Core Components + +This section provides an overview of the responsibilities and common characteristics of the six navigation components: + +- **Anchor**: In-page anchor navigation supporting container selection and current anchor callbacks. +- **Breadcrumb**: Displays the current page's position in the hierarchy; supports custom separators, item rendering, and dropdown icons. +- **Dropdown**: Wraps a trigger element and renders a dropdown menu; supports custom popup rendering and menu item injection. +- **Menu**: Side or top navigation menu; supports themes, expand icons, overflow indicators, and select/expand events. +- **Pagination**: Data pagination control; supports quick-jump buttons and custom page item rendering. +- **Steps**: Step flow indicator; supports step item lists and custom progress dot rendering. + +Section sources + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) + +## Architecture Overview + +Component bridging follows a unified pattern of "lazy loading + slot rendering + function hooks": + +- **Prop forwarding**: The wrapper layer forwards common props such as `visible`, `elem_id`, `elem_classes`, `elem_style`, `_internal`, and `as_item` to the React component. +- **Slot rendering**: Slot name mapping and parameterized rendering are supported via `ReactSlot` and `renderParamsSlot`. +- **Dynamic injection**: `items` lists are injected via `withItemsContextProvider`, supporting both default slots and explicit `items` params. +- **Event binding**: Events such as `onOpenChange`, `onSelect`, `onDeselect`, and `onChange` are ensured to be reactive through the `useFunction` hook. + +```mermaid +sequenceDiagram +participant S as "Svelte Wrapper Layer (Index.svelte)" +participant P as "Prop Processor (processProps)" +participant R as "React Component (sveltify)" +participant C as "Context/Slots (Items/Slots)" +S->>P : Parses component props and extra props +P-->>S : Returns normalized prop set +S->>R : Renders Antd component and passes props +R->>C : Reads items context and slots +C-->>R : Provides items list and slot functions +R-->>S : Fires event callbacks (onChange/onSelect, etc.) +S-->>S : Processes result via Gradio/routing callback +``` + +Diagram sources + +- [frontend/antd/anchor/Index.svelte:22-44](file://frontend/antd/anchor/Index.svelte#L22-L44) +- [frontend/antd/anchor/anchor.tsx:10-43](file://frontend/antd/anchor/anchor.tsx#L10-L43) +- [frontend/antd/breadcrumb/breadcrumb.tsx:15-63](file://frontend/antd/breadcrumb/breadcrumb.tsx#L15-L63) +- [frontend/antd/dropdown/dropdown.tsx:26-108](file://frontend/antd/dropdown/dropdown.tsx#L26-L108) +- [frontend/antd/menu/menu.tsx:18-92](file://frontend/antd/menu/menu.tsx#L18-L92) +- [frontend/antd/pagination/pagination.tsx:14-52](file://frontend/antd/pagination/pagination.tsx#L14-L52) +- [frontend/antd/steps/steps.tsx:16-49](file://frontend/antd/steps/steps.tsx#L16-L49) + +## Component Details + +### Anchor + +- **Responsibility**: Provides in-page anchor navigation; supports container selection and current anchor callbacks. +- **Key Props and Behaviors** + - Container selection: `getContainer` specifies the scroll container. + - Current anchor: `getCurrentAnchor` retrieves the currently active anchor. + - Items injection: `items` are injected via context, supporting default slot and explicit `items`. +- **Events and State** + - No explicit event callbacks; scroll positioning and highlight sync are achieved via callback functions. +- **Usage Notes** + - Use with anchor items on long pages; ensure the container is set correctly. + - Use slots to render custom anchor titles. + +```mermaid +flowchart TD +Start(["Enter Anchor"]) --> Items["Parse items context"] +Items --> Render["Render Antd Anchor"] +Render --> Events{"Scroll/Click event"} +Events --> |Positioning| SetActive["Set current anchor"] +Events --> |Switch| Callback["Execute callback function"] +SetActive --> End(["Done"]) +Callback --> End +``` + +Diagram sources + +- [frontend/antd/anchor/anchor.tsx:10-43](file://frontend/antd/anchor/anchor.tsx#L10-L43) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) + +Section sources + +- [frontend/antd/anchor/Index.svelte:1-66](file://frontend/antd/anchor/Index.svelte#L1-L66) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) + +### Breadcrumb + +- **Responsibility**: Displays the current page's path in the hierarchy; supports custom separators, item rendering, and dropdown icons. +- **Key Props and Behaviors** + - Separator: `separator` supports slots and functions. + - Item rendering: `itemRender` supports slots and functions. + - Dropdown icon: `dropdownIcon` supports slots. + - Items injection: supports `default` and `items` slots. +- **Events and State** + - Rendering is controlled via props and slots; no direct event callbacks. +- **Usage Notes** + - Generate a hierarchical structure in combination with a routing system; use `itemRender` to customize link styles when necessary. + +```mermaid +sequenceDiagram +participant B as "Breadcrumb" +participant S as "Slots" +participant I as "Items Context" +B->>I : Reads items/default +B->>S : Renders separator/itemRender/dropdownIcon +B-->>B : Renders Antd Breadcrumb +``` + +Diagram sources + +- [frontend/antd/breadcrumb/breadcrumb.tsx:15-63](file://frontend/antd/breadcrumb/breadcrumb.tsx#L15-L63) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) + +Section sources + +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) +- [frontend/antd/breadcrumb/item/Index.svelte:1-72](file://frontend/antd/breadcrumb/item/Index.svelte#L1-L72) + +### Dropdown + +- **Responsibility**: Wraps a trigger element and renders a dropdown menu; supports custom popup rendering and menu item injection. +- **Key Props and Behaviors** + - Popup container: `getPopupContainer`. + - Dropdown rendering: `dropdownRender`, `popupRender` support slots and functions. + - Menu expand icon: `menu.expandIcon` supports slots. + - Overflow indicator: `menu.overflowedIndicator` supports slots. + - Menu item injection: items are injected via the menu context. +- **Events and State** + - Rendering is controlled via props and slots; no direct event callbacks. +- **Usage Notes** + - Place the trigger element inside the component to avoid style occlusion. + - Use slots to implement complex dropdown panel layouts. + +```mermaid +classDiagram +class Dropdown { ++props : GetProps ++slots : dropdownRender,popupRender,menu.expandIcon,menu.overflowedIndicator ++getPopupContainer() ++render() +} +class MenuItems { ++items : ItemType[] ++expandIcon() ++overflowedIndicator() +} +Dropdown --> MenuItems : "Injects menu items" +``` + +Diagram sources + +- [frontend/antd/dropdown/dropdown.tsx:15-108](file://frontend/antd/dropdown/dropdown.tsx#L15-L108) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) + +Section sources + +- [frontend/antd/dropdown/Index.svelte:1-70](file://frontend/antd/dropdown/Index.svelte#L1-L70) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) + +### Menu + +- **Responsibility**: Side or top navigation menu; supports themes, expand icons, overflow indicators, and select/expand events. +- **Key Props and Behaviors** + - Theme: `theme` supports external injection. + - Expand icon: `expandIcon` supports slots. + - Overflow indicator: `overflowedIndicator` supports slots. + - Popup rendering: `popupRender` supports slots. + - Events: `onOpenChange`, `onSelect`, `onDeselect`. + - Items injection: supports `default` and `items` slots. +- **Events and State** + - State management and routing integration are achieved via `onOpenChange`, `onSelect`, and `onDeselect`. +- **Usage Notes** + - When integrating with a routing library, handle routing navigation and selection state sync inside `onSelect`. + +```mermaid +sequenceDiagram +participant M as "Menu" +participant E as "Event Callbacks" +participant R as "Router/Gradio" +M->>E : onSelect/onDeselect/onOpenChange +E->>R : Update route/state +R-->>M : Sync selected/expanded state +``` + +Diagram sources + +- [frontend/antd/menu/menu.tsx:18-92](file://frontend/antd/menu/menu.tsx#L18-L92) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) + +Section sources + +- [frontend/antd/menu/Index.svelte:1-75](file://frontend/antd/menu/Index.svelte#L1-L75) +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [frontend/antd/menu/item/Index.svelte:1-84](file://frontend/antd/menu/item/Index.svelte#L1-L84) + +### Pagination + +- **Responsibility**: Data pagination control; supports quick-jump buttons and custom page item rendering. +- **Key Props and Behaviors** + - Quick jump: `showQuickJumper` supports the `goButton` slot. + - Total display: `showTotal` supports functions. + - Page item rendering: `itemRender` supports slots and functions. + - Events: `onChange(page, pageSize)`. +- **Events and State** + - Handle pagination logic and data refresh inside `onChange`. +- **Usage Notes** + - When interfacing with backend pagination APIs, pay attention to `page`/`pageSize` conversion and boundary handling. + +```mermaid +flowchart TD +Start(["User action"]) --> Jump["Click page number / quick jump"] +Jump --> Call["Call onChange(page,pageSize)"] +Call --> Fetch["Request new page data"] +Fetch --> Update["Update list and total count"] +Update --> End(["Done"]) +``` + +Diagram sources + +- [frontend/antd/pagination/pagination.tsx:14-52](file://frontend/antd/pagination/pagination.tsx#L14-L52) + +Section sources + +- [frontend/antd/pagination/Index.svelte:1-68](file://frontend/antd/pagination/Index.svelte#L1-L68) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) + +### Steps + +- **Responsibility**: Step flow indicator; supports step item lists and custom progress dot rendering. +- **Key Props and Behaviors** + - Step items: `items` injection, supporting `default` and `items` slots. + - Progress dot: `progressDot` supports slots and functions. + - Events: step switching is implemented via callback functions. +- **Events and State** + - No direct event callbacks; step state management is achieved via function hooks. +- **Usage Notes** + - When combined with form wizards, control the availability of the next step based on the current step. + +```mermaid +sequenceDiagram +participant S as "Steps" +participant P as "progressDot slot" +participant I as "items context" +S->>I : Reads items/default +S->>P : Renders progress dot +S-->>S : Renders Antd Steps +``` + +Diagram sources + +- [frontend/antd/steps/steps.tsx:16-49](file://frontend/antd/steps/steps.tsx#L16-L49) +- [frontend/antd/steps/context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) + +Section sources + +- [frontend/antd/steps/Index.svelte:1-63](file://frontend/antd/steps/Index.svelte#L1-L63) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/steps/context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) + +## Dependency Analysis + +- **Inter-component Coupling** + - Dropdown depends on Menu's context injection for unified menu item management. + - All components with `items` depend on the context and rendering utilities provided by `createItemsContext`. +- **External Dependencies** + - Native Ant Design components as the rendering foundation. + - `@svelte-preprocess-react` provides tools such as `sveltify`, `ReactSlot`, `renderItems`, and `renderParamsSlot`. +- **Potential Circular Dependencies** + - Direct circular imports are avoided via context injection; each component independently maintains its own context. + +```mermaid +graph LR +Ctx["createItemsContext"] --> A["Anchor Items"] +Ctx --> B["Breadcrumb Items"] +Ctx --> M["Menu Items"] +Ctx --> S["Steps Items"] +D["Dropdown"] --> M +A --> Antd["Antd Anchor"] +B --> Antd2["Antd Breadcrumb"] +D --> Antd3["Antd Dropdown"] +M --> Antd4["Antd Menu"] +P["Pagination"] --> Antd5["Antd Pagination"] +S --> Antd6["Antd Steps"] +``` + +Diagram sources + +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [frontend/antd/steps/context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) +- [frontend/antd/dropdown/dropdown.tsx:10-13](file://frontend/antd/dropdown/dropdown.tsx#L10-L13) + +Section sources + +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [frontend/antd/steps/context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) +- [frontend/antd/dropdown/dropdown.tsx:10-13](file://frontend/antd/dropdown/dropdown.tsx#L10-L13) + +## Performance Considerations + +- **Lazy Loading**: The Svelte wrapper layer lazy-loads React components to reduce the initial page load burden. +- **Computed Caching**: The React layer uses `useMemo` to stabilize `items`, avoiding unnecessary re-renders. +- **Slot Cloning**: Slot rendering enables cloning by default to ensure independence, but be mindful of cloning overhead. +- **Event Hooks**: The `useFunction` hook ensures stable callback references, preventing re-renders caused by function reference changes. + +## Troubleshooting Guide + +- **Event Not Triggered** + - Check that `onOpenChange`/`onSelect`/`onDeselect`/`onChange` callbacks have been correctly passed. + - Confirm that the callback functions are wrapped with the `useFunction` hook. +- **Slot Not Working** + - Confirm that the slot name matches the mapping (e.g., `menu.expandIcon`, `itemRender`, etc.). + - Check that the slot has cloning enabled (`clone: true`). +- **Items Not Displayed** + - Confirm that `items` have been injected via context or passed explicitly. + - Check the priority and naming of the default slot vs. the `items` slot. +- **Style Conflicts** + - Check whether `elem_id`/`elem_classes` conflict with global styles. + - Ensure the component style class prefix `ms-gr-antd-*` has not been overridden. + +Section sources + +- [frontend/antd/anchor/anchor.tsx:10-43](file://frontend/antd/anchor/anchor.tsx#L10-L43) +- [frontend/antd/breadcrumb/breadcrumb.tsx:15-63](file://frontend/antd/breadcrumb/breadcrumb.tsx#L15-L63) +- [frontend/antd/dropdown/dropdown.tsx:26-108](file://frontend/antd/dropdown/dropdown.tsx#L26-L108) +- [frontend/antd/menu/menu.tsx:18-92](file://frontend/antd/menu/menu.tsx#L18-L92) +- [frontend/antd/pagination/pagination.tsx:14-52](file://frontend/antd/pagination/pagination.tsx#L14-L52) +- [frontend/antd/steps/steps.tsx:16-49](file://frontend/antd/steps/steps.tsx#L16-L49) + +## Conclusion + +ModelScope Studio's navigation components achieve seamless integration of Ant Design components in the frontend ecosystem through a unified Svelte wrapper layer and React bridge layer. The design emphasizes: + +- **Ease of use**: Unified prop forwarding and slot mapping. +- **Extensibility**: Context injection and function hooks for greater flexibility. +- **Maintainability**: Clear separation of responsibilities and dependencies. + +It is recommended to normalize event callbacks and state management in combination with routing systems and permission frameworks in real-world projects to achieve a better user experience and development efficiency. + +## Appendix + +- **Routing Integration Recommendations** + - Handle routing navigation and state sync uniformly in Menu/Pagination/Steps callbacks. + - Handle scroll positioning and highlight sync uniformly in Anchor and Steps callbacks. +- **Permission Control Recommendations** + - Filter invisible items at the items injection stage, or hide them based on permission conditions at the rendering layer. +- **Dynamic Loading Recommendations** + - Use lazy loading and `useMemo` caching strategies to avoid frequent re-renders. +- **Accessibility Recommendations** + - Provide keyboard accessibility and screen-reader-friendly labels for clickable items. + - Provide clear ARIA attributes and state hints for step indicators and pagination controls. diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Other Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Other Components API.md new file mode 100644 index 00000000..4162672a --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design Components API/Other Components API.md @@ -0,0 +1,278 @@ +# Other Components API + + +**Files referenced in this document** +- [frontend/antd/affix/Index.svelte](file://frontend/antd/affix/Index.svelte) +- [frontend/antd/affix/affix.tsx](file://frontend/antd/affix/affix.tsx) +- [frontend/antd/affix/package.json](file://frontend/antd/affix/package.json) +- [frontend/antd/config-provider/Index.svelte](file://frontend/antd/config-provider/Index.svelte) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) +- [frontend/antd/config-provider/package.json](file://frontend/antd/config-provider/package.json) +- [docs/components/antd/affix/README.md](file://docs/components/antd/affix/README.md) +- [docs/components/antd/config_provider/README.md](file://docs/components/antd/config_provider/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document provides a systematic overview of special-function Ant Design components in ModelScope Studio: Affix (sticky positioning) and ConfigProvider (global configuration). It covers their APIs, type definitions, context provision, theme and internationalization mechanisms, and how they integrate into the component system. The document also presents standard usage workflows, typical scenarios, and best practices to help developers quickly understand and correctly use these components. + +## Project Structure + +- Components are organized as Svelte packages; each component directory contains: + - `Index.svelte`: The Gradio/Svelte wrapper layer, responsible for prop forwarding, slot rendering, visibility control, and lazy loading. + - Component implementation files (e.g., `affix.tsx`, `config-provider.tsx`): Bridge React components into a Svelte-usable form via `@svelte-preprocess-react`, extending necessary types and behaviors. + - `package.json`: The export entry, supporting both Gradio and default modes. +- Documentation is located under `docs/components/antd`, providing examples and explanations. + +```mermaid +graph TB +subgraph "Ant Design Components" +A["affix/Index.svelte"] +B["affix/affix.tsx"] +C["config-provider/Index.svelte"] +D["config-provider/config-provider.tsx"] +E["config-provider/locales.ts"] +end +A --> B +C --> D +D --> E +``` + +Diagram sources + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) + +Section sources + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/antd/affix/package.json:1-15](file://frontend/antd/affix/package.json#L1-L15) +- [frontend/antd/config-provider/package.json:1-15](file://frontend/antd/config-provider/package.json#L1-L15) +- [docs/components/antd/affix/README.md:1-9](file://docs/components/antd/affix/README.md#L1-L9) +- [docs/components/antd/config_provider/README.md:1-8](file://docs/components/antd/config_provider/README.md#L1-L8) + +## Core Components + +- **Affix** + - **Responsibility**: Fixes child elements to the viewport or container boundaries; commonly used for sidebars, back-to-top buttons, etc. + - **Key Points**: Dynamically determines the scroll container via the `target` function; supports `visible` to control rendering; supports extra prop forwarding and slot rendering. +- **ConfigProvider** + - **Responsibility**: Provides unified global configuration for Ant Design components, including themes, locales, popup containers, and empty state rendering. + - **Key Points**: Supports theme algorithm toggles (dark/compact), internationalization locale switching, style injection, and container function callbacks; can be used as the context root node. + +Section sources + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) + +## Architecture Overview + +The following diagram illustrates the call chain from the Svelte wrapper layer to React components, as well as the theme and internationalization processing flow for ConfigProvider. + +```mermaid +sequenceDiagram +participant UI as "Page/Application" +participant Wrap as "Svelte Wrapper Layer (Index.svelte)" +participant Impl as "Component Implementation (.tsx)" +participant AD as "Ant Design Component Library" +participant CSS as "Style Injection (StyleProvider)" +UI->>Wrap : Renders component and passes props/slots +Wrap->>Impl : Lazy-imports and forwards props +Impl->>AD : Instantiates target component (e.g., Affix/ConfigProvider) +Impl->>CSS : Injects style prefix and hash strategy +AD-->>UI : Render result +``` + +Diagram sources + +- [frontend/antd/affix/Index.svelte:55-68](file://frontend/antd/affix/Index.svelte#L55-L68) +- [frontend/antd/affix/affix.tsx:6-11](file://frontend/antd/affix/affix.tsx#L6-L11) +- [frontend/antd/config-provider/Index.svelte:54-71](file://frontend/antd/config-provider/Index.svelte#L54-L71) +- [frontend/antd/config-provider/config-provider.tsx:108-149](file://frontend/antd/config-provider/config-provider.tsx#L108-L149) + +## Component Details + +### Affix + +- **Responsibility** + - Fixes child content to the viewport or a specified container boundary, showing/hiding as the user scrolls. +- **Props and Behaviors** + - Supports a `target` container function for dynamically selecting the scroll container. + - Supports `visible` to control whether to render. + - Supports extra prop forwarding and slot rendering. +- **Use Cases** + - Sidebar toolbars, back-to-top buttons, floating action areas, etc. +- **Types and Implementation Notes** + - Bridges Ant Design's `Affix` as a Svelte component via `sveltify` from `@svelte-preprocess-react`. + - `target` is wrapped via `useFunction` to ensure reactive updates. +- **Examples and Documentation** + - Documentation provides two examples: "Basic" and "Container scroll" for quick onboarding. + +```mermaid +sequenceDiagram +participant P as "Parent Component" +participant W as "affix/Index.svelte" +participant T as "affix.tsx (Antd Affix)" +participant R as "React/Antd" +P->>W : Passes props (including target/visible/slots) +W->>T : Forwards after processProps +T->>R : Wraps target via useFunction and renders +R-->>P : DOM result with sticky positioning applied +``` + +Diagram sources + +- [frontend/antd/affix/Index.svelte:23-49](file://frontend/antd/affix/Index.svelte#L23-L49) +- [frontend/antd/affix/affix.tsx:6-11](file://frontend/antd/affix/affix.tsx#L6-L11) + +Section sources + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [docs/components/antd/affix/README.md:1-9](file://docs/components/antd/affix/README.md#L1-L9) + +### ConfigProvider + +- **Responsibility** + - Provides unified global configuration covering theme, locale, popup container, empty state rendering, and more. +- **Theme and Algorithms** + - `theme.algorithm` supports automatic detection: dark/compact algorithms can be enabled based on `themeMode` or explicit configuration. +- **Internationalization** + - `locale` supports multi-language mapping, switching based on browser language or explicit input; also synchronizes `dayjs` locale settings. +- **Slots and Prop Composition** + - Supports converting slots into a prop tree for declarative passing of complex configuration items. +- **Context and Containers** + - Marks the context as `antd` type via `setConfigType`, affecting behaviors like shared theming. + - Supports `getPopupContainer`/`getTargetContainer` for customizing popup and mount containers. + +```mermaid +flowchart TD +Start(["Enter ConfigProvider"]) --> Locale["Parse locale
Load corresponding Antd and dayjs language pack"] +Locale --> Theme["Merge theme.algorithm
Generate final algorithm array based on themeMode and props"] +Theme --> Slots["Convert slots to prop tree
Functionalize slots like renderEmpty"] +Slots --> Style["Inject style prefix and hash strategy"] +Style --> Render["Render subtree"] +Render --> End(["Done"]) +``` + +Diagram sources + +- [frontend/antd/config-provider/config-provider.tsx:85-105](file://frontend/antd/config-provider/config-provider.tsx#L85-L105) +- [frontend/antd/config-provider/config-provider.tsx:127-143](file://frontend/antd/config-provider/config-provider.tsx#L127-L143) +- [frontend/antd/config-provider/config-provider.tsx:29-49](file://frontend/antd/config-provider/config-provider.tsx#L29-L49) +- [frontend/antd/config-provider/locales.ts:15-27](file://frontend/antd/config-provider/locales.ts#L15-L27) + +Section sources + +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [docs/components/antd/config_provider/README.md:1-8](file://docs/components/antd/config_provider/README.md#L1-L8) + +## Dependency Analysis + +- **Component Export** + - Both components provide Gradio and default entry points via the `exports` field in `package.json`, making them usable across different runtime environments. +- **Runtime Dependencies** + - ConfigProvider depends on Ant Design's `ConfigProvider`, theme algorithms, and style injection; it also depends on `dayjs` and the locales mapping. + - Affix depends on Ant Design's `Affix` and the `useFunction` utility to wrap callback functions. +- **Wrapper Layer Coupling** + - Both components use lazy imports and prop forwarding to reduce initial load pressure and improve rendering controllability. + +```mermaid +graph LR +PkgA["@modelscope-studio/antd-affix/package.json"] --> IA["affix/Index.svelte"] +PkgB["@modelscope-studio/antd-config-provider/package.json"] --> IC["config-provider/Index.svelte"] +IA --> TA["affix.tsx"] +IC --> TC["config-provider.tsx"] +TC --> L["locales.ts"] +``` + +Diagram sources + +- [frontend/antd/affix/package.json:1-15](file://frontend/antd/affix/package.json#L1-L15) +- [frontend/antd/config-provider/package.json:1-15](file://frontend/antd/config-provider/package.json#L1-L15) +- [frontend/antd/affix/Index.svelte:10-13](file://frontend/antd/affix/Index.svelte#L10-L13) +- [frontend/antd/config-provider/Index.svelte:11-13](file://frontend/antd/config-provider/Index.svelte#L11-L13) + +Section sources + +- [frontend/antd/affix/package.json:1-15](file://frontend/antd/affix/package.json#L1-L15) +- [frontend/antd/config-provider/package.json:1-15](file://frontend/antd/config-provider/package.json#L1-L15) + +## Performance Considerations + +- **Lazy Loading** + - Components are loaded on demand via `importComponent` and the `{#await}` pattern, avoiding initial page blocking. +- **Prop Forwarding and Derived Computation** + - Using `processProps` and `$derived` avoids unnecessary re-renders, only updating when essential props change. +- **Style Injection Strategy** + - Using `StyleProvider` with a high-priority hash reduces style conflicts and repaint costs. +- **Callback Function Wrapping** + - Using `useFunction` to wrap callbacks like `target`/`getPopupContainer` ensures stable function references, reducing unnecessary updates. + +## Troubleshooting Guide + +- **Sticky Positioning Not Working** + - Check that `target` returns the correct scroll container; confirm that `visible` is `true` and the container has a scrollbar. + - Reference paths: [frontend/antd/affix/Index.svelte:47-49](file://frontend/antd/affix/Index.svelte#L47-L49), [frontend/antd/affix/affix.tsx:7-10](file://frontend/antd/affix/affix.tsx#L7-L10) +- **Popup/Float Position Abnormal** + - Check that `getPopupContainer` returns the correct container; confirm the `getTargetContainer` setting in ConfigProvider. + - Reference path: [frontend/antd/config-provider/config-provider.tsx:93-95](file://frontend/antd/config-provider/config-provider.tsx#L93-L95) +- **Theme Not Switching or Algorithm Not Taking Effect** + - Confirm the combination of `themeMode` and `theme.algorithm`; note that the algorithm array is composed of multiple algorithm functions. + - Reference paths: [frontend/antd/config-provider/config-provider.tsx:88-91](file://frontend/antd/config-provider/config-provider.tsx#L88-L91), [frontend/antd/config-provider/config-provider.tsx:127-143](file://frontend/antd/config-provider/config-provider.tsx#L127-L143) +- **Locale Not Taking Effect** + - Check the `locale` parameter format and the locales mapping; confirm that the `dayjs` locale has been synchronized. + - Reference paths: [frontend/antd/config-provider/config-provider.tsx:85-105](file://frontend/antd/config-provider/config-provider.tsx#L85-L105), [frontend/antd/config-provider/locales.ts:15-27](file://frontend/antd/config-provider/locales.ts#L15-L27) + +Section sources + +- [frontend/antd/affix/Index.svelte:47-49](file://frontend/antd/affix/Index.svelte#L47-L49) +- [frontend/antd/affix/affix.tsx:7-10](file://frontend/antd/affix/affix.tsx#L7-L10) +- [frontend/antd/config-provider/config-provider.tsx:85-105](file://frontend/antd/config-provider/config-provider.tsx#L85-L105) +- [frontend/antd/config-provider/config-provider.tsx:88-91](file://frontend/antd/config-provider/config-provider.tsx#L88-L91) +- [frontend/antd/config-provider/config-provider.tsx:127-143](file://frontend/antd/config-provider/config-provider.tsx#L127-L143) +- [frontend/antd/config-provider/locales.ts:15-27](file://frontend/antd/config-provider/locales.ts#L15-L27) + +## Conclusion + +- Affix and ConfigProvider in ModelScope Studio are seamlessly integrated with the Ant Design component library through a unified Svelte wrapper layer and `@svelte-preprocess-react` bridging. +- ConfigProvider provides powerful global configuration capabilities covering themes, internationalization, and container strategies; Affix focuses on sticky positioning scenarios with good configurability and performance. +- It is recommended to place ConfigProvider at the application root to unify style and locale; use Affix for areas requiring sticky positioning, and set `target` and `visible` appropriately. + +## Appendix + +- **Examples and Demos** + - Affix examples: Basic, Container scroll + - ConfigProvider examples: Basic +- **Reference Documentation** + - Ant Design official Affix and ConfigProvider documentation links are in each component's README. + +Section sources + +- [docs/components/antd/affix/README.md:1-9](file://docs/components/antd/affix/README.md#L1-L9) +- [docs/components/antd/config_provider/README.md:1-8](file://docs/components/antd/config_provider/README.md#L1-L8) diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Ant Design X Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Ant Design X Components API.md new file mode 100644 index 00000000..84e46c54 --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Ant Design X Components API.md @@ -0,0 +1,436 @@ +# Ant Design X Components API + + +**Files referenced in this document** +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/components/pro/__init__.py](file://backend/modelscope_studio/components/pro/__init__.py) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [frontend/antdx/conversations/conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [frontend/antdx/sender/sender.tsx](file://frontend/antdx/sender/sender.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the API reference for Ant Design X-based Svelte components in ModelScope Studio, covering the following component families: + +- **General Components**: Common UI component wrappers from Ant Design (antd) +- **Awakening Components**: Components for guiding user interaction, hints, or triggering flows +- **Expression Components**: Components for content display, rich text, chat bubbles, and other expressive uses +- **Confirmation Components**: Interaction components for secondary confirmation and popup confirmation +- **Feedback Components**: Feedback components for messages, notifications, progress, and results +- **Tool Components**: Auxiliary capabilities including forms, layouts, toolbars, and contexts + +The document focuses on property definitions, event handlers, slot systems, state management, message passing, conversation flow control mechanisms, and provides usage patterns and best practices for AI/ML scenarios. + +## Project Structure + +ModelScope Studio's frontend uses a combination of Svelte + Ant Design X, bridging React components into the Svelte ecosystem through a unified adapter layer. The backend Python layer is responsible for exporting component collections for on-demand use in applications. + +```mermaid +graph TB +subgraph "Backend Component Export" +A_init["backend/modelscope_studio/components/__init__.py"] +A_antd_init["backend/modelscope_studio/components/antd/__init__.py"] +A_antdx_init["backend/modelscope_studio/components/antdx/__init__.py"] +A_base_init["backend/modelscope_studio/components/base/__init__.py"] +A_pro_init["backend/modelscope_studio/components/pro/__init__.py"] +end +subgraph "Frontend Adapter Layer" +F_button["frontend/antd/button/button.tsx"] +F_form["frontend/antd/form/form.tsx"] +F_actions["frontend/antdx/actions/actions.tsx"] +F_bubble["frontend/antdx/bubble/bubble.tsx"] +F_conversations["frontend/antdx/conversations/conversations.tsx"] +F_sender["frontend/antdx/sender/sender.tsx"] +end +A_init --> A_antd_init +A_init --> A_antdx_init +A_init --> A_base_init +A_init --> A_pro_init +A_antd_init --> F_button +A_antd_init --> F_form +A_antdx_init --> F_actions +A_antdx_init --> F_bubble +A_antdx_init --> F_conversations +A_antdx_init --> F_sender +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +**Section sources** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) + +## Core Components + +This section provides a quick overview of each component family's key responsibilities and typical use cases for rapid identification and selection. + +- **General Components (Antd)** + - Responsibility: Provide basic UI capabilities such as buttons, inputs, forms, layouts, messages, notifications, etc. + - Typical components: Button, Form, Input, Modal, Message, Notification, etc. + - Feature: Bridges Ant Design's React components as Svelte components via an adapter; supports slots and functional props. + +- **Awakening Components (AntdX)** + - Responsibility: Guide users to their next action, such as action menus, hints, skill toggles, etc. + - Typical components: Actions, Sender, Suggestion, Welcome, etc. + - Feature: Supports complex slots, context injection, event forwarding, and value change integration. + +- **Expression Components (AntdX)** + - Responsibility: For content expression and conversational display, such as bubbles, thought chains, file cards, attachments, etc. + - Typical components: Bubble, ThoughtChain, FileCard, Attachments, Prompts, etc. + - Feature: Supports render functions, editable configuration, header/footer, and extra area slots. + +- **Confirmation Components (AntdX)** + - Responsibility: For secondary confirmation, popup confirmation, and similar interactions. + - Typical components: Popconfirm, Modal (static), Tour, etc. + - Feature: Consistent interaction semantics with AntdX, maintaining a uniform slot and event model. + +- **Feedback Components (AntdX)** + - Responsibility: Messages, notifications, progress, results, and other feedback. + - Typical components: Message, Notification, Progress, Result, etc. + - Feature: Supports slot-based rendering, functional callbacks, and state-driven updates. + +- **Tool Components (AntdX)** + - Responsibility: Auxiliary capabilities for forms, layouts, contexts, and application containers. + - Typical components: Form, Layout, XProvider, Markdown, Slot, etc. + - Feature: Provides contexts, rendering utility functions, and the slot system. + +**Section sources** + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +## Architecture Overview + +The following diagram shows the mapping from backend component exports to the frontend adapter layer to specific components, as well as the processing paths for slots and functional props. + +```mermaid +graph TB +subgraph "Backend Export" +B1["antd/__init__.py
Exports Button/Form etc."] +B2["antdx/__init__.py
Exports Actions/Bubble etc."] +B3["base/__init__.py
Exports Application/Slot etc."] +B4["pro/__init__.py
Exports Chatbot/Monaco etc."] +end +subgraph "Frontend Adapter" +F1["sveltify
Bridges React components"] +F2["Slot System
ReactSlot/renderParamsSlot"] +F3["Functional Props
useFunction/createFunction"] +F4["Context and Menu Items
withItemsContextProvider/useItems"] +end +subgraph "Component Instances" +C1["Button"] +C2["Form"] +C3["Actions"] +C4["Bubble"] +C5["Conversations"] +C6["Sender"] +end +B1 --> F1 --> C1 +B1 --> F1 --> C2 +B2 --> F1 --> C3 +B2 --> F1 --> C4 +B2 --> F1 --> C5 +B2 --> F1 --> C6 +F1 --> F2 +F1 --> F3 +F1 --> F4 +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +## Component Details + +### General Components API (Antd) + +#### Button + +- **Purpose**: Bridges Ant Design's Button as a Svelte component; supports slots and loading icon slots. +- **Key Points** + - Slots: `icon`, `loading.icon` + - Value binding: Intelligent selection between `value` and `children` + - Loading state: `loading` supports object input with configurable delay +- **Usage Notes** + - When slots exist, slot rendering takes priority; otherwise falls back to prop values. + - Uses `useTargets` to handle target nodes in `children`. + +**Section sources** + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) + +#### Form + +- **Purpose**: Bridges Ant Design's Form as a Svelte component; provides controlled value and action sync. +- **Key Points** + - Controlled value: `value` and `onValueChange` + - Action sync: `formAction` (reset/submit/validate) and `onResetFormAction` + - Slots: `requiredMark` + - Callbacks: `onValuesChange` +- **Usage Notes** + - Uses `useEffect` to execute reset/submit/validate based on `formAction`. + - Syncs external `value` to the internal form instance. + +**Section sources** + +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) + +### Awakening Components API (AntdX) + +#### Actions + +- **Purpose**: Bridges AntdX's Actions as a Svelte component; supports menu items and dropdown render slots. +- **Key Points** + - Slots: `dropdownProps.menu.items`, `dropdownProps.menu.expandIcon`, `dropdownProps.menu.overflowedIndicator`, `dropdownProps.dropdownRender`, `dropdownProps.popupRender` + - Context: Integrates with menu item context, supporting `items`/`default` slots + - Rendering: `renderItems`, `renderParamsSlot`, `createFunction` +- **Usage Notes** + - Prioritizes `items` from slots; falls back to prop `items` if absent. + - Conditionally replaces dropdown render and menu items. + +**Section sources** + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) + +#### Sender + +- **Purpose**: Svelte adapter for AntdX Sender; supports file upload, paste, suggestion context, and slotted header/footer. +- **Key Points** + - Slots: `suffix`, `header`, `prefix`, `footer`, `skill.*` series + - Events: `onSubmit` (fires when suggestion is not open), `onChange`, `onPasteFile` + - Value change: `onValueChange` and `useValueChange` + - Upload: The `upload` function returns an array of file data +- **Usage Notes** + - Calls `upload` when pasting files and returns the path. + - Formats results and customizes rendering via `slotConfig`. + +**Section sources** + +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +### Expression Components API (AntdX) + +#### Bubble + +- **Purpose**: Svelte adapter for AntdX Bubble; supports header/body/footer/extra areas and editable configuration. +- **Key Points** + - Slots: `avatar`, `editable.okText`, `editable.cancelText`, `content`, `footer`, `header`, `extra`, `loadingRender`, `contentRender` + - Functions: `typing`, `contentRender`, `header`/`footer`/`avatar`/`extra`, `editable` +- **Usage Notes** + - Supports boolean `editable` or object configuration; slot content takes priority when slots exist. + - Converts props to functional rendering via `useFunction`. + +**Section sources** + +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) + +#### Conversations + +- **Purpose**: Svelte adapter for AntdX Conversations; supports grouping, menus, and slotted labels. +- **Key Points** + - Slots: `menu.trigger`, `menu.expandIcon`, `menu.overflowedIndicator`, `groupable.label` + - Context: Menu item context and conversation item context + - Rendering: `renderItems`, `patchMenuEvents` (event forwarding) +- **Usage Notes** + - Supports string or object form for `menu` configuration; auto-falls back when no `items`. + - Injects style class names via `classNames`. + +**Section sources** + +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) + +### Confirmation Components API (AntdX) + +- **Popconfirm**: Secondary confirmation popup; supports slotted title and description. +- **Modal (static)**: Static modal dialog; suitable for fixed content display. +- **Tour**: Guided tour; supports steps and slotted rendering. + +[This section is conceptual; no specific file analysis] + +### Feedback Components API (AntdX) + +- **Message**: Message hint; supports slotted content and functional rendering. +- **Notification**: Notification alert; supports slotted rendering and close callbacks. +- **Progress**: Progress bar; supports slotted formatting. +- **Result**: Result page; supports slotted action areas. + +[This section is conceptual; no specific file analysis] + +### Tool Components API (AntdX) + +- **Form**: See "General Components" section. +- **Layout**: Layout container supporting Content/Footer/Header/Sider. +- **XProvider**: Context provider supplying global configuration for AntdX components. +- **Markdown**: Markdown rendering component. +- **Slot**: Slot container for dynamic content mounting. + +**Section sources** + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +## Dependency Analysis + +```mermaid +graph TB +subgraph "Backend Export" +A["components/__init__.py"] +A_antd["antd/__init__.py"] +A_antdx["antdx/__init__.py"] +A_base["base/__init__.py"] +A_pro["pro/__init__.py"] +end +subgraph "Frontend Adapter" +U_render["renderItems/renderParamsSlot"] +U_func["useFunction/createFunction"] +U_slot["ReactSlot"] +U_ctx["withItemsContextProvider/useItems"] +end +subgraph "Components" +C_btn["Button"] +C_form["Form"] +C_act["Actions"] +C_bub["Bubble"] +C_conv["Conversations"] +C_snd["Sender"] +end +A --> A_antd --> C_btn +A --> A_antd --> C_form +A --> A_antdx --> C_act +A --> A_antdx --> C_bub +A --> A_antdx --> C_conv +A --> A_antdx --> C_snd +C_btn -.-> U_render +C_form -.-> U_func +C_act -.-> U_render +C_act -.-> U_ctx +C_bub -.-> U_func +C_bub -.-> U_slot +C_conv -.-> U_render +C_conv -.-> U_ctx +C_snd -.-> U_func +C_snd -.-> U_slot +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +**Section sources** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +## Performance Considerations + +- **Lazy Rendering of Slots and Functional Props** + - Corresponding content is only rendered when slots exist, avoiding unnecessary computation. + - `useMemo` wraps menu and rendering logic to reduce repeated renders. +- **Controlled Value and Action Sync** + - Uses `useEffect` to trigger reset/submit/validate based on `formAction`, avoiding frequent redraws. + - Uses `useValueChange` to manage input value changes, reducing upstream jitter. +- **Event Forwarding and Debouncing** + - Stops DOM event bubbling on `onClick` in menu events to avoid unexpected triggers. + - Uses `useMemoizedFn` to cache callbacks for functional props. + +[This section provides general guidance; no specific file analysis] + +## Troubleshooting Guide + +- **Slot Not Working** + - Check that slot key names match the component's convention (e.g., `menu.items`, `dropdownRender`, etc.). + - Confirm that the slot is not hidden by `children` or not passed correctly. +- **Value Not Synced** + - For Form: Confirm that `value` is correctly passed in and `onValueChange` is being fired. + - For Sender: Confirm the binding of `onValueChange` and `useValueChange`. +- **Dropdown Menu Not Showing** + - Check that `dropdownProps` and `menu.items` are correctly configured. + - Confirm that `withItemsContextProvider` wraps the component. +- **Upload Failing** + - Confirm that the return value of the `upload` function contains a `path` field. + - Check that the path returned by `onPasteFile` is correct. + +**Section sources** + +- [frontend/antd/form/form.tsx:32-53](file://frontend/antd/form/form.tsx#L32-L53) +- [frontend/antdx/sender/sender.tsx:135-138](file://frontend/antdx/sender/sender.tsx#L135-L138) +- [frontend/antdx/actions/actions.tsx:39-96](file://frontend/antdx/actions/actions.tsx#L39-L96) + +## Conclusion + +This document covers the APIs and usage patterns of Ant Design X Svelte components in ModelScope Studio, focusing on key mechanisms such as the slot system, functional props, context and menu item integration, value change and action sync. For AI/ML scenarios, it is recommended to prioritize Sender, Bubble, Conversations, and Actions for building conversation and expression flows, using slots and functional props to achieve highly customized content rendering and interaction behaviors. + +## Appendix + +### Component Instantiation and Configuration (AI/ML Scenario Recommendations) + +- **Conversation Flow** + - Use Sender as the input entry; configure `upload` to support multimodal input. + - Use Bubble to render response content; enable `editable` when secondary editing is needed. + - Use Conversations to manage the conversation list; combine `menu` and `groupable` for grouping and operations. +- **Form and Validation** + - Use Form for controlled value and action sync; combine reset/submit/validate for flow control. +- **Actions and Guidance** + - Use Actions for context menus and guidance items; combine slots for custom rendering. + +[This section is conceptual; no specific file analysis] diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Awakening Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Awakening Components API.md new file mode 100644 index 00000000..1c62f5ae --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Awakening Components API.md @@ -0,0 +1,348 @@ +# Awakening Components API + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/antdx/welcome/__init__.py](file://backend/modelscope_studio/components/antdx/welcome/__init__.py) +- [backend/modelscope_studio/components/antdx/prompts/__init__.py](file://backend/modelscope_studio/components/antdx/prompts/__init__.py) +- [frontend/antdx/welcome/Index.svelte](file://frontend/antdx/welcome/Index.svelte) +- [frontend/antdx/welcome/welcome.tsx](file://frontend/antdx/welcome/welcome.tsx) +- [frontend/antdx/prompts/Index.svelte](file://frontend/antdx/prompts/Index.svelte) +- [frontend/antdx/prompts/prompts.tsx](file://frontend/antdx/prompts/prompts.tsx) +- [frontend/antdx/prompts/context.ts](file://frontend/antdx/prompts/context.ts) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the Ant Design X Awakening Components API reference for ModelScope Studio, focusing on the following two components: + +- Welcome Component (AntdXWelcome): Used to display welcome messages on the first load or in specific scenarios, supporting slot-based configuration for title, description, icon, and extra content. +- Prompts Component (AntdXPrompts): Used to display a set of clickable prompt cards, supporting configuration for title, vertical layout, fade-in animation, line wrapping, etc., and providing an item click event callback. + +This document provides an in-depth analysis of system architecture, component relationships, data flow, processing logic, integration points, error handling, and performance characteristics, as well as lifecycle hooks, event handling, state management mechanisms, TypeScript type definitions, and interface specifications, helping developers build smooth first-time experiences and prompt guidance in AI applications. + +## Project Structure + +ModelScope Studio's frontend adopts the Svelte + Ant Design X component system, with the backend bridging frontend components via Python components. The Welcome and Prompts components are located in the `antdx` module; backend components handle property passing and event binding, while frontend components handle rendering and interaction. + +```mermaid +graph TB +subgraph "Backend" +B_Welcome["AntdXWelcome
Python Component"] +B_Prompts["AntdXPrompts
Python Component"] +end +subgraph "Frontend" +F_Welcome["welcome/Index.svelte
Renderer"] +F_Welcome_TSX["welcome/welcome.tsx
Component Implementation"] +F_Prompts["prompts/Index.svelte
Renderer"] +F_Prompts_TSX["prompts/prompts.tsx
Component Implementation"] +F_Prompts_Context["prompts/context.ts
Context"] +end +B_Welcome --> F_Welcome +F_Welcome --> F_Welcome_TSX +B_Prompts --> F_Prompts +F_Prompts --> F_Prompts_TSX +F_Prompts_TSX --> F_Prompts_Context +``` + +**Chart Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) +- [frontend/antdx/welcome/Index.svelte:1-72](file://frontend/antdx/welcome/Index.svelte#L1-L72) +- [frontend/antdx/welcome/welcome.tsx](file://frontend/antdx/welcome/welcome.tsx) +- [frontend/antdx/prompts/Index.svelte:1-71](file://frontend/antdx/prompts/Index.svelte#L1-L71) +- [frontend/antdx/prompts/prompts.tsx](file://frontend/antdx/prompts/prompts.tsx) +- [frontend/antdx/prompts/context.ts](file://frontend/antdx/prompts/context.ts) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:1-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:1-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L1-L88) +- [frontend/antdx/welcome/Index.svelte:1-72](file://frontend/antdx/welcome/Index.svelte#L1-L72) +- [frontend/antdx/prompts/Index.svelte:1-71](file://frontend/antdx/prompts/Index.svelte#L1-L71) + +## Core Components + +This section provides an overview of the key responsibilities and capability boundaries of the two components: + +- Welcome Component (AntdXWelcome) + - Responsibility: Display welcome messages, supporting multiple slots (title, description, icon, extra content) with optional styles and variants. + - Key Points: Does not expose standard API (`skip_api` is true); implemented via slots and static resource path injection. +- Prompts Component (AntdXPrompts) + - Responsibility: Display a set of prompt cards, supporting title, vertical layout, fade-in animation, line wrapping, etc.; provides an item click event callback. + - Key Points: Internally nested item components; event binding is configured via `EventListener`. + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) + +## Architecture Overview + +The diagram below shows the call chain from backend components to frontend renderers to specific component implementations, as well as the event binding and slot passing mechanism. + +```mermaid +sequenceDiagram +participant Py as "Python Backend Component" +participant Svelte as "Svelte Renderer" +participant TSX as "TSX Component Implementation" +Py->>Py : "Initialize component properties and events" +Py->>Svelte : "Pass props and visibility control" +Svelte->>TSX : "Dynamically import and render component" +TSX-->>Svelte : "Render complete, await slot content" +Svelte-->>Py : "Event callback binding (e.g., item_click)" +``` + +**Chart Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:55-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L55-L73) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:70-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L70-L88) +- [frontend/antdx/welcome/Index.svelte:10-72](file://frontend/antdx/welcome/Index.svelte#L10-L72) +- [frontend/antdx/prompts/Index.svelte:10-71](file://frontend/antdx/prompts/Index.svelte#L10-L71) + +## Detailed Component Analysis + +### Welcome Component (AntdXWelcome) + +- Component Purpose: Used for first-time experience or onboarding scenarios, carrying title, description, icon, and extra content. +- Slot Support: `extra`, `icon`, `description`, `title`. +- Properties and Behavior: + - Supports additional properties `additional_props`, styles `styles`/`class_names`, and root class name `root_class_name`. + - The `icon` parameter is processed through static asset service (`serve_static_file`). + - Does not expose standard API (`skip_api` is true); suitable for use through slot and static resource combinations. +- Lifecycle and Hooks: + - `preprocess`/`postprocess`/`example_payload`/`example_value` all return null, indicating this component does not participate in regular data flow transformation. +- Typical Use Cases: + - Welcome pages after app startup, new user onboarding, feature entry hints, etc. + +```mermaid +classDiagram +class AntdXWelcome { ++EVENTS : list ++SLOTS : list ++additional_props : dict|None ++extra : str|None ++icon : str|None ++styles : dict|str|None ++class_names : dict|str|None ++description : str|None ++variant : "filled"| "borderless"| None ++title : str|None ++root_class_name : str|None ++skip_api() : bool ++preprocess(payload) : None ++postprocess(value) : None ++example_payload() : None ++example_value() : None +} +``` + +**Chart Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) +- [frontend/antdx/welcome/Index.svelte:1-72](file://frontend/antdx/welcome/Index.svelte#L1-L72) +- [frontend/antdx/welcome/welcome.tsx](file://frontend/antdx/welcome/welcome.tsx) + +### Prompts Component (AntdXPrompts) + +- Component Purpose: Display a set of prompt cards, supporting title, vertical layout, fade-in animation, line wrapping, etc. +- Internal Structure: + - Nested item component: `AntdXPrompts.Item`. + - Events: `item_click` (triggered when a prompt item is clicked). +- Properties and Behavior: + - `items`: List of prompt items (array of dicts). + - Styles and layout: `prefix_cls`, `vertical`, `fade_in`, `fade_in_left`, `wrap`. + - Supports `additional_props`, `styles`, `class_names`, `root_class_name`. + - Does not expose standard API (`skip_api` is true). +- Event Handling: + - Maps click events to internal state updates (`bind_itemClick_event`) via `EventListener("item_click")`. + +```mermaid +classDiagram +class AntdXPrompts { ++Item : AntdXPromptsItem ++EVENTS : list ++SLOTS : list ++items : list[dict]|None ++prefix_cls : str|None ++title : str|None ++vertical : bool|None ++fade_in : bool|None ++fade_in_left : bool|None ++wrap : bool|None ++styles : dict|str|None ++class_names : dict|str|None ++root_class_name : str|None ++skip_api() : bool ++preprocess(payload) : None ++postprocess(value) : None ++example_payload() : Any ++example_value() : Any +} +class AntdXPromptsItem { ++... item-level properties and behavior ... +} +AntdXPrompts --> AntdXPromptsItem : "contains" +``` + +**Chart Sources** + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) +- [frontend/antdx/prompts/Index.svelte:1-71](file://frontend/antdx/prompts/Index.svelte#L1-L71) +- [frontend/antdx/prompts/prompts.tsx](file://frontend/antdx/prompts/prompts.tsx) +- [frontend/antdx/prompts/context.ts](file://frontend/antdx/prompts/context.ts) + +### Component Rendering and Event Binding Flow + +The following sequence diagram shows how backend components bind events and render components through frontend renderers. + +```mermaid +sequenceDiagram +participant Backend as "Backend Component" +participant Renderer as "Svelte Renderer" +participant Frontend as "TSX Component" +Backend->>Renderer : "Pass component properties and event configuration" +Renderer->>Frontend : "Dynamically import and render" +Frontend-->>Renderer : "Register event listeners (e.g., item_click)" +Renderer-->>Backend : "Event callbacks take effect" +``` + +**Chart Sources** + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-23](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L23) +- [frontend/antdx/prompts/Index.svelte:10-71](file://frontend/antdx/prompts/Index.svelte#L10-L71) + +## Dependency Analysis + +- Component Base Class and Utilities: + - All components inherit from `ModelScopeLayoutComponent`, uniformly handling visibility, element ID/classes, styles, and render switches. + - Frontend directory resolution is done via `resolve_frontend_dir`, ensuring correct mapping between Python backend and Svelte frontend. +- Inter-component Coupling: + - The Welcome and Prompts components are independent UI components with no direct dependency on each other. + - The Prompts component's internal item component interacts with the context, but is still exposed externally as a whole component. + +```mermaid +graph LR +Base["ModelScopeLayoutComponent
Component Base Class"] --> Welcome["AntdXWelcome"] +Base --> Prompts["AntdXPrompts"] +Resolve["resolve_frontend_dir
Frontend Directory Resolution"] --> Welcome +Resolve --> Prompts +``` + +**Chart Sources** + +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:55-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L55-L55) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:70-70](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L70-L70) + +**Section Sources** + +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:55-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L55-L55) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:70-70](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L70-L70) + +## Performance Considerations + +- Rendering Strategy + - Components are rendered via dynamic import, avoiding first-screen blocking and improving initial load performance. +- Event Binding + - Events are only bound when needed, and unnecessary re-renders are reduced through internal state updates. +- Resource Handling + - Static resources such as icons are handled via `serve_static_file`; caching and preloading are recommended for optimizing user experience. + +[This section provides general guidance and requires no specific file sources] + +## Troubleshooting Guide + +- Component Not Displaying + - Check whether `visible`, `elem_id`, `elem_classes`, `elem_style` are correctly set. + - Confirm the render switch `render` is true. +- Slot Content Not Taking Effect + - Confirm slot names match the component's supported `SLOTS` list (Welcome: `extra`, `icon`, `description`, `title`; Prompts: `title`, `items`). +- Event Not Firing + - Confirm event listeners are correctly configured (Prompts component's `item_click`). +- Icon or Static Resources Cannot Load + - Confirm the `icon` path is valid and `serve_static_file` is working properly. + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:14-15](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L14-L15) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:25-26](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L25-L26) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-23](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L23) + +## Conclusion + +AntdXWelcome and AntdXPrompts serve as the core components for "welcome onboarding" and "prompt guidance" respectively in ModelScope Studio. The former achieves flexible welcome page display through slots and static resources; the latter provides efficient prompt word guidance through item click events and layout configuration. Both use dynamic rendering and event binding mechanisms, with good extensibility and maintainability. Combined with the type definitions, interface specifications, and best practices provided in this document, developers can quickly build consistent and smooth first-time experience and prompt guidance flows in AI applications. + +[This section is a summary and requires no specific file sources] + +## Appendix + +### TypeScript Type Definitions and Interface Specifications + +- Welcome Component (AntdXWelcome) + - Supported Properties: `additional_props`, `extra`, `icon`, `styles`, `class_names`, `description`, `variant`, `title`, `root_class_name`, `as_item`, `visible`, `elem_id`, `elem_classes`, `elem_style`, `render`. + - Slots: `extra`, `icon`, `description`, `title`. + - Events: None. + - Lifecycle Hooks: `preprocess`/`postprocess`/`example_payload`/`example_value` return null. +- Prompts Component (AntdXPrompts) + - Supported Properties: `items`, `prefix_cls`, `title`, `vertical`, `fade_in`, `fade_in_left`, `wrap`, `styles`, `class_names`, `root_class_name`, `additional_props`, `as_item`, `visible`, `elem_id`, `elem_classes`, `elem_style`, `render`. + - Slots: `title`, `items`. + - Events: `item_click` (triggered when a prompt item is clicked). + - Lifecycle Hooks: `preprocess`/`postprocess`/`example_payload`/`example_value` return null. + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:17-54](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L17-L54) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:14-15](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L14-L15) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:61-69](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L61-L69) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:28-68](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L28-L68) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:25-26](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L25-L26) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:76-87](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L76-L87) + +### Integration with Conversation Systems + +- The Prompts component can serve as a guidance layer before conversation input; after the user clicks a prompt item, the upper-level business logic injects the prompt content into the conversation input field or directly initiates a conversation request. +- The Welcome component can serve as the entry point hint for a conversation session, deciding whether to display it based on context state. + +[This section is a conceptual explanation and requires no specific file sources] + +### Best Practices + +- Welcome Component + - Use slots to organize title, description, and icon for clear visual hierarchy. + - For multilingual scenarios, pass `title` and `description` through an external copy management module. +- Prompts Component + - Set `vertical`, `fade_in`, `fade_in_left`, `wrap` appropriately to adapt to different screen sizes and interaction paces. + - Provide clear semantic labels for each prompt item to facilitate accessibility and SEO. +- Event Handling + - Perform the minimum necessary operations in the `item_click` callback (such as writing the prompt content to the input field) to avoid blocking the UI. +- State Management + - Decouple the visibility of the Prompts collection from the current conversation state, allowing reuse across different pages or views. + +[This section provides general guidance and requires no specific file sources] diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Confirmation Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Confirmation Components API.md new file mode 100644 index 00000000..2fb63a41 --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Confirmation Components API.md @@ -0,0 +1,331 @@ +# Confirmation Components API + + +**Files Referenced in This Document** +- [thought_chain/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py) +- [think/__init__.py](file://backend/modelscope_studio/components/antdx/think/__init__.py) +- [thought-chain.tsx](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [think.tsx](file://frontend/antdx/think/think.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the Ant Design X Confirmation Components API reference for ModelScope Studio, focusing on the complete interface and behavioral specifications of the ThoughtChain component and the Think component. Content includes: + +- Component property, event, and slot definitions +- Visualization and node management mechanisms for the thinking process +- Confirmation flow control and state management +- Integration recommendations for AI reasoning processes and decision display scenarios +- TypeScript type and interface specifications +- Best practices and common issue troubleshooting + +## Project Structure + +Ant Design X components are wrapped by Python component packages on the backend and bridged to the native `@ant-design/x` implementation on the frontend via Svelte/React hybrid bridging. Core file organization: + +- Backend Python wrapper: Located under `backend/modelscope_studio/components/antdx`, providing Python component classes for ThoughtChain and Think respectively +- Frontend implementation: Located under `frontend/antdx`, providing TSX implementations for `thought-chain` and `think` respectively + +```mermaid +graph TB +subgraph "Backend" +PY_TC["AntdXThoughtChain
Python Component"] +PY_TH["AntdXThink
Python Component"] +end +subgraph "Frontend" +FE_TC["ThoughtChain
TSX Implementation"] +FE_TH["Think
TSX Implementation"] +end +subgraph "Third-Party Libraries" +ADX["@ant-design/x
Native Component Library"] +end +PY_TC --> FE_TC +PY_TH --> FE_TH +FE_TC --> ADX +FE_TH --> ADX +``` + +Chart Sources + +- [thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +Section Sources + +- [thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +## Core Components + +This section provides an overview of the responsibilities and capability boundaries of the two core components: + +- ThoughtChain: Used to visually display a sequence of reasoning or decision-making nodes in tree/list form, supporting expand/collapse, connector styles, and node collection management +- Think: Used to encapsulate a single thought unit, supporting title, icon, loading state, and expandable state, with slot extension points + +Section Sources + +- [thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) + +## Architecture Overview + +The diagram below shows the call chain from backend Python components to frontend TSX implementations to `@ant-design/x` native components. + +```mermaid +sequenceDiagram +participant PyTC as "Backend : AntdXThoughtChain" +participant PyTH as "Backend : AntdXThink" +participant FETC as "Frontend : ThoughtChain" +participant FETH as "Frontend : Think" +participant ADX as "@ant-design/x" +PyTC->>FETC : Render ThoughtChain component +FETC->>ADX : Render using XThoughtChain +PyTH->>FETH : Render Think component +FETH->>ADX : Render using XThink +``` + +Chart Sources + +- [thought_chain/**init**.py:68-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L68-L86) +- [think/**init**.py:61-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L61-L79) +- [thought-chain.tsx:11-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L43) +- [think.tsx:6-24](file://frontend/antdx/think/think.tsx#L6-L24) + +## Detailed Component Analysis + +### ThoughtChain Component + +- Component Purpose: Used to present "thought chain"-style data flows or decision sequences, supporting node collections (`items`), expanded keys (`expanded_keys`), default expanded keys (`default_expanded_keys`), connector styles (`line`), etc. +- Slots: Supports `items` slot for injecting node collections +- Events: `expand` event, triggered when expanded keys change +- Property Notes: + - `expanded_keys` / `default_expanded_keys`: Control node expand state + - `items`: Node data collection, can be passed via slot or property + - `line`: Connector style, supports boolean values and specific string enumerations + - `prefix_cls` / `styles` / `class_names` / `root_class_name`: Style and class name customization + - Other general properties: `visible`, `elem_id`, `elem_classes`, `elem_style`, `render`, etc. + +```mermaid +classDiagram +class AntdXThoughtChain { ++expanded_keys : list[str] | None ++default_expanded_keys : list[str] | None ++items : list[dict] | None ++line : bool | "solid" | "dashed" | "dotted" | None ++prefix_cls : str | None ++additional_props : dict | None ++styles : dict | str | None ++class_names : dict | str | None ++root_class_name : str | None ++EVENTS : ["expand"] ++SLOTS : ["items"] ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +``` + +Chart Sources + +- [thought_chain/**init**.py:30-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L30-L86) + +Section Sources + +- [thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [thought-chain.tsx:11-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L43) + +### Think Component + +- Component Purpose: Used to encapsulate a single thought unit, supporting title (`title`), icon (`icon`), loading state (`loading`), default expanded (`default_expanded`), current expanded (`expanded`), and blink (`blink`), etc. +- Slots: Supports `loading`, `icon`, and `title` slots for custom rendering +- Events: `expand` event, for expanded state change notifications +- Property Notes: + - `icon` / `title` / `loading`: Basic display properties + - `default_expanded` / `expanded`: Expand state control + - `blink`: Visual indicator + - Other general properties: `visible`, `elem_id`, `elem_classes`, `elem_style`, `render`, etc. + +```mermaid +classDiagram +class AntdXThink { ++additional_props : dict | None ++icon : str | None ++styles : dict | str | None ++class_names : dict | str | None ++loading : str | bool | None ++title : str | None ++root_class_name : str | None ++default_expanded : bool | None ++expanded : bool | None ++blink : bool | None ++EVENTS : ["expand"] ++SLOTS : ["loading","icon","title"] ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +``` + +Chart Sources + +- [think/**init**.py:21-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L21-L79) + +Section Sources + +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [think.tsx:6-24](file://frontend/antdx/think/think.tsx#L6-L24) + +### Frontend Implementation and Slot Mechanism + +- The ThoughtChain frontend implementation reads slot `items`/`default` via context and clones nodes when necessary to avoid side effects; finally passes the parsed `items` to `@ant-design/x`'s `XThoughtChain` +- The Think frontend implementation injects `slots.loading`/`icon`/`title` into `@ant-design/x`'s `XThink` via `ReactSlot`; falls back to property values if no slot is provided + +```mermaid +flowchart TD +Start(["Enter ThoughtChain Render"]) --> ReadSlot["Read slots items/default"] +ReadSlot --> HasItems{"Does slot items exist and is non-empty?"} +HasItems -- Yes --> UseItems["Use slot items"] +HasItems -- No --> UseDefault["Use slot default"] +UseItems --> Clone["Optional: clone nodes"] +UseDefault --> Clone +Clone --> RenderADX["Render XThoughtChain with items"] +RenderADX --> End(["Done"]) +``` + +Chart Sources + +- [thought-chain.tsx:14-39](file://frontend/antdx/thought-chain/thought-chain.tsx#L14-L39) + +Section Sources + +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [think.tsx:6-24](file://frontend/antdx/think/think.tsx#L6-L24) + +## Dependency Analysis + +- Backend Python components are only responsible for declaring properties, events, slots, and frontend directory mappings; they do not directly handle business logic +- Frontend TSX components are responsible for: + - Parsing slots and properties, merging them into the props required by `@ant-design/x` + - Bridging to the React ecosystem via `sveltify` +- Third-party library `@ant-design/x` provides the actual UI behavior and styles + +```mermaid +graph LR +PY["Backend Python Component"] --> FE["Frontend TSX Component"] +FE --> ADX["@ant-design/x"] +``` + +Chart Sources + +- [thought_chain/**init**.py:68-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L68-L86) +- [think/**init**.py:61-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L61-L79) +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +Section Sources + +- [thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +## Performance Considerations + +- Node Cloning: The frontend clones slot nodes when necessary to avoid side effects from shared references, but this increases memory and computation overhead. Use with caution when the number of nodes is large +- Slot Parsing: Prioritize using the `items` slot, falling back to the `default` slot, to reduce unnecessary property passing +- Expand State: Set `expanded_keys`/`default_expanded_keys` appropriately to avoid expanding too many nodes at once, which causes rendering pressure +- Loading State: The Think component's `loading` slot/property should be enabled on demand to avoid redundant animations and DOM structure + +## Troubleshooting Guide + +- Slot Not Taking Effect + - Check whether the `items`/`default` slot is used correctly; confirm slot name casing and ordering + - If using the `items` property, ensure the type matches `@ant-design/x`'s expectations +- Expand Event Not Working + - Confirm the `expand` event is bound; check whether `bind_expand_event` or related state is updated in the callback +- Loading State and Slot Conflict + - When a `loading` slot is provided, the slot takes priority over the property; if no slot is provided, it falls back to the property value +- Styles and Class Names + - To override styles, prefer using `styles`/`class_names`/`root_class_name`; watch for conflicts with the third-party library's default styles + +Section Sources + +- [thought-chain.tsx:14-39](file://frontend/antdx/thought-chain/thought-chain.tsx#L14-L39) +- [think.tsx:10-17](file://frontend/antdx/think/think.tsx#L10-L17) +- [thought_chain/**init**.py:20-25](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L20-L25) +- [think/**init**.py:12-16](file://backend/modelscope_studio/components/antdx/think/__init__.py#L12-L16) + +## Conclusion + +- ThoughtChain and Think components provide a stable foundation for visualizing AI reasoning and decision-making processes through their clear property, event, and slot design +- For large-scale node scenarios, it is recommended to optimize slot usage and expand strategies, combining loading states and style customization to enhance the user experience +- Through `expand` events and expand state control, interactive confirmation flows and step-by-step displays can be implemented + +## Appendix + +### API Specifications and Type Definitions (Based on Source Code) + +- AntdXThoughtChain + - Properties + - `expanded_keys`: List, node expand keys + - `default_expanded_keys`: List, initial expand keys + - `items`: List, node data + - `line`: Boolean or specific string, connector style + - `prefix_cls`: String, prefix class name + - `additional_props`/`styles`/`class_names`/`root_class_name`: Style and class name customization + - `visible`/`elem_id`/`elem_classes`/`elem_style`/`render`: General properties + - Events + - `expand`: Expand key change callback + - Slots + - `items`: Node collection +- AntdXThink + - Properties + - `icon`/`title`/`loading`: Icon, title, loading state + - `default_expanded`/`expanded`: Default/current expand state + - `blink`: Blink effect + - `styles`/`class_names`/`root_class_name`: Style and class name customization + - `visible`/`elem_id`/`elem_classes`/`elem_style`/`render`: General properties + - Events + - `expand`: Expand state change callback + - Slots + - `loading`/`icon`/`title`: Slot alternatives to the corresponding properties + +Section Sources + +- [thought_chain/**init**.py:30-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L30-L86) +- [think/**init**.py:21-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L21-L79) + +### Integration and Best Practices + +- Reasoning Process Visualization + - Use ThoughtChain to display multi-step reasoning/decision sequences; each Think represents a single thought unit + - Control step-by-step display via `expand`, combined with the `loading` slot to indicate thinking in progress +- User Understanding Optimization + - Use the `line` connector style and `prefix_cls` appropriately to enhance hierarchical sense + - Use `icon`/`title` in Think to clarify roles and intent; use `blink` when attention is needed +- State Management and Flow Control + - Manage node expansion via `expanded_keys`/`default_expanded_keys`; drive subsequent steps via `expand` events + - For long chains, consider pagination/segmented loading to avoid rendering too many nodes at once diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Expression Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Expression Components API.md new file mode 100644 index 00000000..0c2f2b76 --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Expression Components API.md @@ -0,0 +1,344 @@ +# Expression Components API + + +**Files Referenced in This Document** +- [frontend/antdx/attachments/Index.svelte](file://frontend/antdx/attachments/Index.svelte) +- [frontend/antdx/attachments/attachments.tsx](file://frontend/antdx/attachments/attachments.tsx) +- [frontend/antdx/sender/Index.svelte](file://frontend/antdx/sender/Index.svelte) +- [frontend/antdx/sender/sender.tsx](file://frontend/antdx/sender/sender.tsx) +- [frontend/antdx/suggestion/Index.svelte](file://frontend/antdx/suggestion/Index.svelte) +- [frontend/antdx/suggestion/suggestion.tsx](file://frontend/antdx/suggestion/suggestion.tsx) +- [frontend/antdx/suggestion/context.ts](file://frontend/antdx/suggestion/context.ts) +- [frontend/antdx/file-card/base.tsx](file://frontend/antdx/file-card/base.tsx) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/utils/hooks/useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [docs/components/antdx/attachments/README.md](file://docs/components/antdx/attachments/README.md) +- [docs/components/antdx/sender/README.md](file://docs/components/antdx/sender/README.md) +- [docs/components/antdx/suggestion/README.md](file://docs/components/antdx/suggestion/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the API reference for Ant Design X Expression Components in ModelScope Studio, focusing on the following three components: + +- Attachments Component: For displaying and uploading files/images and other attachments in multimodal input +- Sender Component: For chat message input, quick command triggering, and paste upload +- Suggestion Component: For providing selectable suggestion items within an input field + +The document covers component property interfaces, event callbacks, data binding, state synchronization, TypeScript type definitions, integration with the chat system, and best practices for multimodal data processing and user input optimization. + +## Project Structure + +- Components are organized with a Svelte wrapper layer (`Index.svelte`) + React implementation layer (`*.tsx`), bridging Ant Design X React components as Svelte components via `svelte-preprocess-react`. +- The Attachments component supports custom placeholder images, preview containers, icon rendering, list item rendering, and other slot extensions; the Sender component supports prefix/suffix/header/footer slots, skill panels, and paste upload; the Suggestion component supports dynamic item rendering and keyboard trigger control. + +```mermaid +graph TB +subgraph "Svelte Wrapper Layer" +A_Index["attachments/Index.svelte"] +B_Index["sender/Index.svelte"] +C_Index["suggestion/Index.svelte"] +end +subgraph "React Implementation Layer" +A_Impl["attachments.tsx"] +B_Impl["sender.tsx"] +C_Impl["suggestion.tsx"] +end +A_Index --> A_Impl +B_Index --> B_Impl +C_Index --> C_Impl +``` + +Chart Sources + +- [frontend/antdx/attachments/Index.svelte:1-98](file://frontend/antdx/attachments/Index.svelte#L1-L98) +- [frontend/antdx/sender/Index.svelte:1-102](file://frontend/antdx/sender/Index.svelte#L1-L102) +- [frontend/antdx/suggestion/Index.svelte:1-75](file://frontend/antdx/suggestion/Index.svelte#L1-L75) +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) +- [frontend/antdx/suggestion/suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) + +Section Sources + +- [frontend/antdx/attachments/Index.svelte:1-98](file://frontend/antdx/attachments/Index.svelte#L1-L98) +- [frontend/antdx/sender/Index.svelte:1-102](file://frontend/antdx/sender/Index.svelte#L1-L102) +- [frontend/antdx/suggestion/Index.svelte:1-75](file://frontend/antdx/suggestion/Index.svelte#L1-L75) + +## Core Components + +- Attachments Component + - Responsibility: Display and manage attachment lists, supporting drag-and-drop/click upload, count limits, placeholder images, preview configuration, custom rendering, and icon slots. + - Key Properties: `items`, `maxCount`, `placeholder`, `imageProps`, `showUploadList`, `beforeUpload`, `customRequest`, `isImageUrl`, `itemRender`, `iconRender`, `getDropContainer`, `progress`, `onChange`/`onValueChange`, `upload`. + - Data Flow: Receives `items` and maintains a local `fileList`; `onChange`/`onValueChange` syncs external values; the `upload` callback handles file uploading and backfills `uid`. +- Sender Component + - Responsibility: Chat input field supporting text input, paste upload, quick command panel, prefix/suffix and header/footer slots, submission interception, and coordination. + - Key Properties: `value`, `onValueChange`, `onChange`, `onSubmit`, `suffix`/`header`/`prefix`/`footer`, `skill`, `slotConfig`, `onPasteFile`, `upload`. + - Data Flow: Uses `useValueChange` to sync external `value`; when the quick command panel is open, `onSubmit` is not triggered; when pasting files, file path arrays are obtained via `upload`. +- Suggestion Component + - Responsibility: Provides selectable suggestion items within an input field, supporting dynamic `items` rendering, slot extensions, keyboard trigger control, and popup container configuration. + - Key Properties: `items`, `open`, `onOpenChange`, `getPopupContainer`, `shouldTrigger`, `children` slot. + - Data Flow: Maintains `open` state internally; merges `items` from slots and props; shares state with subtree via `SuggestionOpenContext`. + +Section Sources + +- [frontend/antdx/attachments/attachments.tsx:36-410](file://frontend/antdx/attachments/attachments.tsx#L36-L410) +- [frontend/antdx/sender/sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) +- [frontend/antdx/suggestion/suggestion.tsx:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) + +## Architecture Overview + +The diagram below shows the bridging relationship and data flow between the three components across Svelte and React layers. + +```mermaid +sequenceDiagram +participant Svelte as "Svelte Wrapper Layer" +participant ReactImpl as "React Implementation Layer" +participant Gradio as "Gradio Client" +Svelte->>ReactImpl : Pass props/slots/callbacks +ReactImpl->>ReactImpl : useFunction/useValueChange handles function and value sync +ReactImpl->>Gradio : upload callback for file upload +Gradio-->>ReactImpl : Returns FileData list +ReactImpl-->>Svelte : Triggers onValueChange/onChange +Svelte-->>Svelte : updateProps updates value +``` + +Chart Sources + +- [frontend/antdx/attachments/Index.svelte:77-92](file://frontend/antdx/attachments/Index.svelte#L77-L92) +- [frontend/antdx/sender/Index.svelte:71-78](file://frontend/antdx/sender/Index.svelte#L71-L78) +- [frontend/antdx/attachments/attachments.tsx:329-348](file://frontend/antdx/attachments/attachments.tsx#L329-L348) +- [frontend/antdx/sender/sender.tsx:135-138](file://frontend/antdx/sender/sender.tsx#L135-L138) + +## Detailed Component Analysis + +### Attachments Component + +- Types and Interfaces + - Exported types: Based on `@ant-design/x`'s `AttachmentsProps`, with additional declarations for `onValueChange`, `onChange`, `upload`, `items`, etc. + - Supported slot keys: `showUploadList.extra`, `showUploadList.previewIcon`, `showUploadList.removeIcon`, `showUploadList.downloadIcon`, `iconRender`, `itemRender`, `placeholder`, `placeholder.title`, `placeholder.description`, `placeholder.icon`, `imageProps.placeholder`, `imageProps.preview.mask`, `imageProps.preview.closeIcon`, `imageProps.preview.toolbarRender`, `imageProps.preview.imageRender`. +- Upload Flow + - In `onChange`, distinguishes between add/remove operations: on add, executes `beforeUpload` first, then calls `upload` to get `FileData`, merges into `fileList`, and finally triggers `onValueChange`. + - On remove, if not currently uploading, triggers `onRemove` and updates the value. +- Configuration Notes + - `maxCount` controls single/multi-file upload strategy. + - `imageProps.preview` supports custom `mask`/`closeIcon`/`toolbarRender`/`imageRender`, or completely disables preview. + - `placeholder` supports object-based configuration combined with slots. + - `showUploadList` supports object-based configuration combined with slots, injecting `downloadIcon`/`removeIcon`/`previewIcon`/`extra` separately. +- Events and State + - `onValueChange`: Returns `FileData[]`, for external value binding. + - `onChange`: Returns string path arrays, for downstream processing by path. + - `upload`: `Promise<(FileData|null)[]>`, must preserve the original file `uid` for subsequent matching. + +```mermaid +flowchart TD +Start(["Start"]) --> Change["Listen to onChange event"] +Change --> IsRemove{"Is this a remove operation?"} +IsRemove --> |Yes| RemoveLogic["Trigger onRemove
Update fileList
Trigger onValueChange/onChange"] +IsRemove --> |No| AddLogic["Execute beforeUpload
Check maxCount and upload status
Call upload to get FileData
Merge into fileList
Trigger onValueChange/onChange"] +RemoveLogic --> End(["End"]) +AddLogic --> End +``` + +Chart Sources + +- [frontend/antdx/attachments/attachments.tsx:275-354](file://frontend/antdx/attachments/attachments.tsx#L275-L354) + +Section Sources + +- [frontend/antdx/attachments/attachments.tsx:36-410](file://frontend/antdx/attachments/attachments.tsx#L36-L410) +- [frontend/antdx/attachments/Index.svelte:72-92](file://frontend/antdx/attachments/Index.svelte#L72-L92) + +### Sender Component + +- Types and Interfaces + - Exported types: Based on `@ant-design/x`'s `SenderProps`, with additional declarations for `onValueChange`, `upload`, `onPasteFile`, etc. + - Slot keys: `suffix`, `header`, `prefix`, `footer`, `skill.title`, `skill.toolTip.title`, `skill.closable.closeIcon`. + - `slotConfig`: Supports `formatResult`/`customRender` function wrapping. +- Submission Flow + - `onSubmit` is intercepted: when the quick command panel is open, submission is blocked to avoid accidental triggers. + - `onChange` syncs the internal `value` and triggers the external `onChange`. +- Paste Upload + - `onPasteFile`: Reads clipboard files, calls `upload` to get a `FileData` array, and passes the path array back to `onPasteFile`. +- Events and State + - `onValueChange`: When the external `value` changes, `useValueChange` syncs the internal state. + - `onChange`: Real-time change notification. + - `upload`: `Promise
useFunction/useValueChange"] +Svelte --> Impl["React Implementation Layer"] +Impl --> ADX["@ant-design/x Components"] +Impl --> Utils["BaseFileCard/Upload Utilities"] +Hooks --> Impl +``` + +Chart Sources + +- [frontend/antdx/attachments/Index.svelte:28-56](file://frontend/antdx/attachments/Index.svelte#L28-L56) +- [frontend/antdx/sender/Index.svelte:35-66](file://frontend/antdx/sender/Index.svelte#L35-L66) +- [frontend/antdx/suggestion/Index.svelte:26-54](file://frontend/antdx/suggestion/Index.svelte#L26-L54) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/hooks/useValueChange.ts:9-29](file://frontend/utils/hooks/useValueChange.ts#L9-L29) +- [frontend/antdx/file-card/base.tsx:15-41](file://frontend/antdx/file-card/base.tsx#L15-L41) + +Section Sources + +- [frontend/antdx/attachments/Index.svelte:28-56](file://frontend/antdx/attachments/Index.svelte#L28-L56) +- [frontend/antdx/sender/Index.svelte:35-66](file://frontend/antdx/sender/Index.svelte#L35-L66) +- [frontend/antdx/suggestion/Index.svelte:26-54](file://frontend/antdx/suggestion/Index.svelte#L26-L54) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/hooks/useValueChange.ts:9-29](file://frontend/utils/hooks/useValueChange.ts#L9-L29) +- [frontend/antdx/file-card/base.tsx:15-41](file://frontend/antdx/file-card/base.tsx#L15-L41) + +## Performance Considerations + +- Slot and Functionalization + - Use `useFunction` to wrap props and slots, reducing unnecessary re-renders. + - Use `useMemo` and `useMemoizedEqualValue` to cache results for complex computations (such as `items` rendering). +- Upload State + - The Attachments component sets the `uploading` state during upload to prevent concurrent uploads and accidental deletions. + - Use `maxCount` and a temporary `fileList` to avoid excess uploads and UI jitter. +- Value Synchronization + - `useValueChange` only updates internal state when the external `value` changes, preventing circular updates. + +Section Sources + +- [frontend/antdx/attachments/attachments.tsx:122-132](file://frontend/antdx/attachments/attachments.tsx#L122-L132) +- [frontend/antdx/attachments/attachments.tsx:304-312](file://frontend/antdx/attachments/attachments.tsx#L304-L312) +- [frontend/antdx/sender/sender.tsx:68-72](file://frontend/antdx/sender/sender.tsx#L68-L72) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/hooks/useValueChange.ts:9-29](file://frontend/utils/hooks/useValueChange.ts#L9-L29) + +## Troubleshooting Guide + +- Attachment Upload Failure + - Check whether the `upload` callback correctly returns `FileData[]` with `uid` matching the original files. + - Confirm the Gradio client upload path is consistent with the `rootUrl`/`apiPrefix` configuration. +- Quick Command Not Triggering + - Confirm `shouldTrigger` is set and works in coordination with the input field's `onKeyDown`/`onTrigger`. + - Check whether the `open` state is being overridden externally, or whether `SuggestionOpenContext` is being correctly passed. +- Sender Submission Intercepted + - If the quick command panel is open, `onSubmit` will be intercepted; close the panel or wait for it to close before submitting. +- Preview and Icons Not Displaying + - Check whether the slot keys for `imageProps.preview` and `showUploadList` are correctly configured. + - Ensure slot content is correctly rendered; use `ReactSlot` wrapping if necessary. + +Section Sources + +- [frontend/antdx/attachments/attachments.tsx:329-348](file://frontend/antdx/attachments/attachments.tsx#L329-L348) +- [frontend/antdx/suggestion/suggestion.tsx:135-140](file://frontend/antdx/suggestion/suggestion.tsx#L135-L140) +- [frontend/antdx/sender/sender.tsx:126-130](file://frontend/antdx/sender/sender.tsx#L126-L130) + +## Conclusion + +- The Attachments component provides comprehensive multimodal upload capabilities and flexible slot extensions, suitable for handling image/file multimedia input in chat scenarios. +- The Sender component integrates input, paste upload, and the quick command panel, offering good interaction consistency and controllability. +- The Suggestion component achieves a highly customizable suggestion experience through the context and slot system, adapting to various triggering and rendering requirements. +- It is recommended to use the Gradio client and `BaseFileCard` together in real applications to uniformly handle file paths, ensuring cross-module consistency and maintainability. + +## Appendix + +- Example and Documentation Entry Points + - Attachments component examples: see demo tab in the documentation directory + - Sender component examples: see demo tab in the documentation directory + - Suggestion component examples: see demo tab in the documentation directory + +Section Sources + +- [docs/components/antdx/attachments/README.md:1-9](file://docs/components/antdx/attachments/README.md#L1-L9) +- [docs/components/antdx/sender/README.md:1-10](file://docs/components/antdx/sender/README.md#L1-L10) +- [docs/components/antdx/suggestion/README.md:1-10](file://docs/components/antdx/suggestion/README.md#L1-L10) diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Feedback Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Feedback Components API.md new file mode 100644 index 00000000..eec901af --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Feedback Components API.md @@ -0,0 +1,395 @@ +# Feedback Components API + + +**Files Referenced in This Document** +- [frontend/antd/notification/notification.tsx](file://frontend/antd/notification/notification.tsx) +- [frontend/antd/notification/Index.svelte](file://frontend/antd/notification/Index.svelte) +- [frontend/antdx/notification/notification.tsx](file://frontend/antdx/notification/notification.tsx) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [frontend/antdx/actions/feedback/actions.feedback.tsx](file://frontend/antdx/actions/feedback/actions.feedback.tsx) +- [frontend/antdx/actions/action-item/actions.action-item.tsx](file://frontend/antdx/actions/action-item/actions.action-item.tsx) +- [frontend/antdx/actions/item/actions.item.tsx](file://frontend/antdx/actions/item/actions.item.tsx) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the Ant Design X Feedback Components API reference for ModelScope Studio, focusing on two types of feedback capabilities: + +- Actions Component: Provides a set of clickable action items in conversations or workflows, supporting dropdown menus, sub-items, icons, and other extensions. +- Notification Component: For global notification messages and browser native notification permission management, covering both Ant Design and Ant Design X implementations. + +This document systematically covers interface definitions, data structures, event and state management, user interaction mechanisms, type specifications and best practices, and provides typical use cases and configuration recommendations for AI applications. + +## Project Structure + +Feedback components are primarily distributed in the following paths: + +- Frontend Ant Design implementation: `frontend/antd/notification` +- Frontend Ant Design X implementation: `frontend/antdx/notification` and `frontend/antdx/actions` +- Common utilities: `frontend/utils` — items context and rendering utilities + +```mermaid +graph TB +subgraph "Ant Design Implementation" +A1["antd/notification/notification.tsx"] +A2["antd/notification/Index.svelte"] +end +subgraph "Ant Design X Implementation" +B1["antdx/notification/notification.tsx"] +B2["antdx/actions/actions.tsx"] +B3["antdx/actions/context.ts"] +B4["antdx/actions/feedback/actions.feedback.tsx"] +B5["antdx/actions/action-item/actions.action-item.tsx"] +B6["antdx/actions/item/actions.item.tsx"] +end +subgraph "Common Utilities" +C1["utils/createItemsContext.tsx"] +C2["utils/renderItems.tsx"] +C3["utils/renderParamsSlot.tsx"] +C4["utils/renderSlot.tsx"] +end +A2 --> A1 +B2 --> B3 +B2 --> C1 +B2 --> C2 +B2 --> C3 +B2 --> C4 +B4 --> B2 +B5 --> B3 +B6 --> B2 +``` + +Chart Sources + +- [frontend/antd/notification/notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [frontend/antd/notification/Index.svelte:56-79](file://frontend/antd/notification/Index.svelte#L56-L79) +- [frontend/antdx/notification/notification.tsx:1-51](file://frontend/antdx/notification/notification.tsx#L1-L51) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:1-16](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L1-L16) +- [frontend/antdx/actions/action-item/actions.action-item.tsx:1-23](file://frontend/antdx/actions/action-item/actions.action-item.tsx#L1-L23) +- [frontend/antdx/actions/item/actions.item.tsx:1-34](file://frontend/antdx/actions/item/actions.item.tsx#L1-L34) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) + +Section Sources + +- [frontend/antd/notification/notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [frontend/antd/notification/Index.svelte:56-79](file://frontend/antd/notification/Index.svelte#L56-L79) +- [frontend/antdx/notification/notification.tsx:1-51](file://frontend/antdx/notification/notification.tsx#L1-L51) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:1-16](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L1-L16) +- [frontend/antdx/actions/action-item/actions.action-item.tsx:1-23](file://frontend/antdx/actions/action-item/actions.action-item.tsx#L1-L23) +- [frontend/antdx/actions/item/actions.item.tsx:1-34](file://frontend/antdx/actions/item/actions.item.tsx#L1-L34) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) + +## Core Components + +- Actions Component + - Responsible for rendering a set of interactive action items, supporting dropdown menus, sub-items, icon slots, and menu item context injection. + - Provides the `Actions.Feedback` sub-component to adapt to specific feedback scenarios. +- Notification Component + - Ant Design version: Based on `antd.notification.useNotification`, supports visibility control and slot rendering. + - Ant Design X version: Based on `@ant-design/x/notification`, with built-in browser notification permission requests and the ability to close by tag. + +Section Sources + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:1-16](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L1-L16) +- [frontend/antd/notification/notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [frontend/antdx/notification/notification.tsx:1-51](file://frontend/antdx/notification/notification.tsx#L1-L51) + +## Architecture Overview + +The runtime architecture of feedback components consists of a "component bridge layer + notification/action library + rendering pipeline": + +- Component Bridge Layer: Wraps Svelte components as React components via `sveltify`, uniformly exposing properties and slots externally. +- Notification/Action Library: Connects to notification and action capabilities from both `antd` and `@ant-design/x`. +- Rendering Pipeline: Uses utilities such as `createItemsContext` and `renderItems` to convert DOM nodes from slots into a React component tree, supporting parameterized slots and cloning strategies. + +```mermaid +sequenceDiagram +participant UI as "Caller" +participant Actions as "Actions Component" +participant ItemsCtx as "ItemsContext" +participant Renderer as "Rendering Pipeline" +participant XActions as "@ant-design/x Actions" +UI->>Actions : Pass items/dropdownProps/slots +Actions->>ItemsCtx : Inject context and collect slot items +Actions->>Renderer : Parse slots into React components +Renderer-->>Actions : Return renderable items +Actions->>XActions : Render as Ant Design X action list +XActions-->>UI : User interaction callbacks (onClick, etc.) +``` + +Chart Sources + +- [frontend/antdx/actions/actions.tsx:17-120](file://frontend/antdx/actions/actions.tsx#L17-L120) +- [frontend/utils/createItemsContext.tsx:97-274](file://frontend/utils/createItemsContext.tsx#L97-L274) +- [frontend/utils/renderItems.tsx:8-114](file://frontend/utils/renderItems.tsx#L8-L114) + +## Detailed Component Analysis + +### Actions Component API + +- Component Name: Actions +- Appearance: Ant Design X Actions component, supporting dropdown menus and multi-level sub-items. +- Key Properties (partial): + - `items`: Action item array, supporting default slot and sub-item slots. + - `dropdownProps`: Configuration passed through to the dropdown menu, including `dropdownRender`, `popupRender`, `menu`, etc. + - `slots`: Slot mapping, supporting `menu.expandIcon`, `menu.overflowedIndicator`, `menu.items`, etc. +- Slots and Context: + - Uses `createItemsContext` to maintain `default` and `items` slot item collections. + - Writes child nodes to the context via `ItemHandler`, supporting dynamic calculation of `itemProps`, `itemChildren`, etc. +- Rendering Flow: + - Merges external `items` with slot parsing results to generate the final menu items. + - Performs parameterized slot rendering for `dropdownRender`/`popupRender` and menu items. +- Typical Sub-components: + - `Actions.Feedback`: Directly forwards `@ant-design/x`'s `Actions.Feedback`. + - `Actions.Item`: Encapsulates slots for default icon and running icon. + - `ActionsActionItem`: A convenience wrapper for `ItemHandler`, restricting allowed slot keys. + +```mermaid +classDiagram +class Actions { ++props : ActionsProps ++slots : Record ++dropdownProps ++items +} +class ActionsItem { ++props : ActionsItemProps ++slots : defaultIcon, runningIcon +} +class ActionsFeedback { ++props : ActionsFeedbackProps +} +class ItemsContext { ++items : Record ++setItem() ++useItems() +} +class ItemHandler { ++itemIndex ++itemSlotKey ++allowedSlots ++itemChildrenKey +} +Actions --> ItemsContext : "collect/read" +Actions --> ItemHandler : "sub-item injection" +ActionsItem --> Actions : "as sub-item" +ActionsFeedback --> Actions : "sub-component" +``` + +Chart Sources + +- [frontend/antdx/actions/actions.tsx:17-120](file://frontend/antdx/actions/actions.tsx#L17-L120) +- [frontend/antdx/actions/item/actions.item.tsx:6-34](file://frontend/antdx/actions/item/actions.item.tsx#L6-L34) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:5-16](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L5-L16) +- [frontend/antdx/actions/context.ts:3-4](file://frontend/antdx/actions/context.ts#L3-L4) +- [frontend/antdx/actions/action-item/actions.action-item.tsx:7-20](file://frontend/antdx/actions/action-item/actions.action-item.tsx#L7-L20) + +Section Sources + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:1-16](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L1-L16) +- [frontend/antdx/actions/action-item/actions.action-item.tsx:1-23](file://frontend/antdx/actions/action-item/actions.action-item.tsx#L1-L23) +- [frontend/antdx/actions/item/actions.item.tsx:1-34](file://frontend/antdx/actions/item/actions.item.tsx#L1-L34) +- [frontend/utils/createItemsContext.tsx:20-95](file://frontend/utils/createItemsContext.tsx#L20-L95) +- [frontend/utils/renderItems.tsx:8-114](file://frontend/utils/renderItems.tsx#L8-L114) +- [frontend/utils/renderParamsSlot.tsx:5-51](file://frontend/utils/renderParamsSlot.tsx#L5-L51) +- [frontend/utils/renderSlot.tsx:13-29](file://frontend/utils/renderSlot.tsx#L13-L29) + +### Notification Component API + +- Ant Design Version (antd/notification) + - Property Notes: + - `visible`: Whether to show the notification. + - `onVisible`: Callback when closed, used to sync `visible` state. + - `notificationKey`: Unique identifier, used for `destroy`/`open`. + - Supported slots: `btn`, `actions`, `closeIcon`, `description`, `icon`, `message`. + - Behavior Mechanism: + - When `visible` is true, calls `open`; otherwise, `destroy`. + - In the `onClose` callback, triggers `onVisible(false)` first, then executes the user's custom `onClose`. +- Ant Design X Version (@ant-design/x/notification) + - Property Notes: + - `visible`: Whether to show the notification. + - `onVisible`: Callback when closed. + - `onPermission`: Browser notification permission change callback. + - `tag`: Notification tag, used for closing by tag. + - Behavior Mechanism: + - If not yet authorized before the first display, requests permission; only `open` when `granted`. + - When `visible` is true, `open`; otherwise, `close(tag)`. + - Automatically closes notifications with the corresponding `tag` when the component unmounts. + +```mermaid +sequenceDiagram +participant Caller as "Caller" +participant ANTD as "antd Notification" +participant XNOTI as "X Notification" +Caller->>ANTD : Set visible=true, pass message/description etc. +ANTD->>ANTD : useNotification initialization +ANTD->>ANTD : open({ key, message, description, ... }) +ANTD-->>Caller : onClose callback triggers onVisible(false) +Caller->>XNOTI : Set visible=true, pass tag/message +XNOTI->>XNOTI : useNotification gets permission +alt Not authorized +XNOTI->>XNOTI : requestPermission() +end +XNOTI->>XNOTI : open({ tag, message, onClose }) +XNOTI-->>Caller : onClose callback triggers onVisible(false) +``` + +Chart Sources + +- [frontend/antd/notification/notification.tsx:38-95](file://frontend/antd/notification/notification.tsx#L38-L95) +- [frontend/antdx/notification/notification.tsx:17-46](file://frontend/antdx/notification/notification.tsx#L17-L46) + +Section Sources + +- [frontend/antd/notification/notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [frontend/antd/notification/Index.svelte:56-79](file://frontend/antd/notification/Index.svelte#L56-L79) +- [frontend/antdx/notification/notification.tsx:1-51](file://frontend/antdx/notification/notification.tsx#L1-L51) + +## Dependency Analysis + +- Actions and Rendering Toolchain + - Actions depends on `createItemsContext` to maintain the slot item collection. + - Uses `renderItems` to convert slot items into a React component tree, supporting the `children` key and `itemPropsTransformer`. + - `renderParamsSlot` and `renderSlot` support parameterized slots and cloning strategies. +- Actions and Menu Context + - Works with the `antd/menu` context; prioritizes `dropdownProps.menu.items` provided by the menu context. +- Notification and Permissions + - The X version has built-in permission requests and callbacks, avoiding duplicate requests. + - The ANTD version does not involve browser permissions; local notifications only. + +```mermaid +graph LR +Actions["Actions"] --> Ctx["createItemsContext"] +Actions --> RItems["renderItems"] +Actions --> RPSlot["renderParamsSlot"] +Actions --> RSlot["renderSlot"] +Actions --> MenuCtx["antd/menu context"] +XNoti["X Notification"] --> Perm["requestPermission/onPermission"] +ANoti["antd Notification"] --> Local["Local Notifications"] +``` + +Chart Sources + +- [frontend/antdx/actions/actions.tsx:10-15](file://frontend/antdx/actions/actions.tsx#L10-L15) +- [frontend/utils/createItemsContext.tsx:97-274](file://frontend/utils/createItemsContext.tsx#L97-L274) +- [frontend/utils/renderItems.tsx:8-114](file://frontend/utils/renderItems.tsx#L8-L114) +- [frontend/utils/renderParamsSlot.tsx:5-51](file://frontend/utils/renderParamsSlot.tsx#L5-L51) +- [frontend/utils/renderSlot.tsx:13-29](file://frontend/utils/renderSlot.tsx#L13-L29) +- [frontend/antdx/notification/notification.tsx:13-19](file://frontend/antdx/notification/notification.tsx#L13-L19) + +Section Sources + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/antdx/notification/notification.tsx:1-51](file://frontend/antdx/notification/notification.tsx#L1-L51) + +## Performance Considerations + +- Slot Rendering Optimization + - Use `useMemo` to wrap `dropdownProps` modifications, reducing unnecessary re-renders. + - `renderItems` supports `clone`/`forceClone` controls to avoid unnecessary React node rebuilding. +- Notification Lifecycle + - ANTD: Destroys the corresponding key when `visible` toggles, and also destroys on unmount to avoid memory leaks. + - X: Closes by tag when `visible=false` or on unmount, ensuring resource cleanup. +- Permission Request Debouncing + - The X version checks permissions before first open, avoiding duplicate requests. + +Section Sources + +- [frontend/antdx/actions/actions.tsx:39-96](file://frontend/antdx/actions/actions.tsx#L39-L96) +- [frontend/antd/notification/notification.tsx:74-95](file://frontend/antd/notification/notification.tsx#L74-L95) +- [frontend/antdx/notification/notification.tsx:17-46](file://frontend/antdx/notification/notification.tsx#L17-L46) + +## Troubleshooting Guide + +- Actions Sub-items Not Displaying + - Check slot keys: verify `default` and `subItems` match the `ItemHandler`'s `itemChildrenKey`. + - Confirm the return value logic of `allowedSlots` and `itemChildren` is consistent. +- Slot Not Taking Effect + - Confirm elements in `slots` have been correctly passed to `ItemHandler` or Actions's `slots`. + - For parameterized slots, confirm `renderParamsSlot`'s `targets` and `withParams` configuration. +- Notification Not Displaying + - ANTD: Confirm `visible` is true and `notificationKey` is unique; check whether `onVisible(false)` is called in `onClose`. + - X: Confirm browser notification permission is `granted`; check whether `tag` is correctly passed; check whether `onVisible(false)` is called in `onClose`. +- Performance Issues + - Check whether `dropdownProps` changes frequently; reuse object references or use `useMemo` as much as possible. + - Reduce unnecessary cloning; only enable `forceClone` when necessary. + +Section Sources + +- [frontend/antdx/actions/action-item/actions.action-item.tsx:11-19](file://frontend/antdx/actions/action-item/actions.action-item.tsx#L11-L19) +- [frontend/antdx/actions/context.ts:3-4](file://frontend/antdx/actions/context.ts#L3-L4) +- [frontend/utils/renderParamsSlot.tsx:23-49](file://frontend/utils/renderParamsSlot.tsx#L23-L49) +- [frontend/antd/notification/notification.tsx:38-95](file://frontend/antd/notification/notification.tsx#L38-L95) +- [frontend/antdx/notification/notification.tsx:17-46](file://frontend/antdx/notification/notification.tsx#L17-L46) + +## Conclusion + +- Actions transforms complex UI structures into composable and extensible action lists through slot and context mechanisms, suitable for carrying multi-step task and multi-turn conversation action feedback in AI applications. +- Notification provides unified visibility and lifecycle management on both the ANTD and X sides; the X version additionally supports browser notification permissions, meeting richer user feedback needs. +- It is recommended to choose the appropriate implementation version based on business semantics in real applications, and to follow slot and context best practices for stable and high-performance feedback experiences. + +## Appendix + +### Type and Interface Summary + +- Actions + - `ActionsProps`: From `@ant-design/x`, includes `items`, `dropdownProps`, etc. + - `ActionsItemProps`: Property collection for `Actions.Item`. + - `ActionsFeedbackProps`: Property collection for `Actions.Feedback`. +- Notification + - ANTD: `ArgsProps` and `NotificationConfig`, supporting `visible`, `onVisible`, slots, etc. + - X: `XNotificationOpenArgs`, supporting `visible`, `onVisible`, `onPermission`, `tag`, etc. + +Section Sources + +- [frontend/antdx/actions/actions.tsx:3-8](file://frontend/antdx/actions/actions.tsx#L3-L8) +- [frontend/antd/notification/notification.tsx:8-16](file://frontend/antd/notification/notification.tsx#L8-L16) +- [frontend/antdx/notification/notification.tsx:6-11](file://frontend/antdx/notification/notification.tsx#L6-L11) + +### Usage Scenarios and Best Practices + +- Action Feedback in AI Applications + - Use `Actions.Feedback` to quickly mount feedback-type actions. + - Use `Actions.Item` to customize icons and text, combined with slots for dynamic text and status indicators. + - For multi-level menus, use `subItems` and `allowedSlots` to manage hierarchy. +- Notification Timing Control + - ANTD: Use `visible` for precise show/hide control; use brief notifications for critical errors or success states. + - X: Enable for system-level alerts; note that permission requests only trigger on the first use, avoiding frequent interruptions. +- State Synchronization + - Uniformly set `onVisible(false)` in `onClose` to ensure UI and state consistency. + - For batch closures, use `tag` or `key` for precise targeting. diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/General Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/General Components API.md new file mode 100644 index 00000000..4ee600b7 --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/General Components API.md @@ -0,0 +1,518 @@ +# General Components API + + +**Files Referenced in This Document** +- [bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [prompts.tsx](file://frontend/antdx/prompts/prompts.tsx) +- [suggestion.tsx](file://frontend/antdx/suggestion/suggestion.tsx) +- [sender.tsx](file://frontend/antdx/sender/sender.tsx) +- [context.ts (suggestion item context)](file://frontend/antdx/suggestion/context.ts) +- [context.ts (conversation item context)](file://frontend/antdx/conversations/context.ts) +- [context.ts (prompt item context)](file://frontend/antdx/prompts/context.ts) +- [renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [createFunction.ts](file://frontend/utils/createFunction.ts) +- [patchSlots.ts](file://frontend/utils/patchSlots.ts) +- [useMemoizedEqualValue.ts](file://frontend/utils/hooks/useMemoizedEqualValue.ts) +- [react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) +- [react-contexts.ts](file://frontend/svelte-preprocess-react/react-contexts.ts) +- [sveltify.svelte.ts](file://frontend/svelte-preprocess-react/sveltify.svelte.ts) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the Ant Design X General Components API reference for ModelScope Studio. It focuses on the complete interface specifications and usage guides for the following core general components: + +- Bubble: Conversation bubble component, supports avatar, content, footer, extra actions, and other slots and render functions +- Conversations: Conversation list/group management, supports menus, group labels, overflow indicators, and other extensions +- Prompts: Prompt card collection, supports title slots and dynamic item rendering +- Suggestion: Quick commands/suggestion input, supports popup containers, trigger strategies, and sub-item slot patching +- Sender: Sender component, supports paste upload, skill panel, prefix/suffix/header/footer slots + +This document covers property definitions, event handling, slot systems, state management, message passing, and conversation flow control mechanisms. It also provides instantiation and configuration example paths for AI chat and conversation scenarios, TypeScript types and integration with Ant Design components, as well as performance optimization and best practices. + +## Project Structure + +Ant Design X general components are located in the `antdx` submodule of the frontend directory. They adopt a "Svelte wrapper + React component bridge" architecture: using `svelte-preprocess-react` to use `@ant-design/x` React components in a Svelte-compatible way, while providing a unified slot system and context injection capability. + +```mermaid +graph TB +subgraph "Ant Design X General Components" +B["Bubble
Bubble Component"] +C["Conversations
Conversation List/Groups"] +P["Prompts
Prompt Cards"] +S["Suggestion
Quick Commands/Suggestions"] +SD["Sender
Sender"] +end +subgraph "Utilities and Context" +U1["renderItems.tsx
Render Items Utility"] +U2["renderParamsSlot.tsx
Parameterized Slot Renderer"] +U3["useFunction.ts
Function Wrapper Hook"] +U4["useValueChange.ts
Value Change Hook"] +U5["createFunction.ts
Function Factory"] +U6["patchSlots.ts
Slot Patching"] +U7["react-slot.tsx
React Slot"] +U8["react-contexts.ts
React Contexts"] +U9["sveltify.svelte.ts
Svelte Wrapper"] +end +B --> U1 +B --> U2 +B --> U3 +B --> U7 +C --> U1 +C --> U2 +C --> U3 +C --> U8 +P --> U1 +P --> U2 +S --> U1 +S --> U2 +S --> U3 +S --> U6 +SD --> U1 +SD --> U2 +SD --> U3 +SD --> U4 +SD --> U5 +SD --> U7 +SD --> U8 +``` + +Chart Sources + +- [bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) +- [sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) +- [renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [createFunction.ts](file://frontend/utils/createFunction.ts) +- [patchSlots.ts](file://frontend/utils/patchSlots.ts) +- [react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) +- [react-contexts.ts](file://frontend/svelte-preprocess-react/react-contexts.ts) +- [sveltify.svelte.ts](file://frontend/svelte-preprocess-react/sveltify.svelte.ts) + +Section Sources + +- [bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) +- [sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +## Core Components + +This section provides an overview of the five core general components, their responsibilities and typical use cases, to help quickly locate specific implementations and example paths. + +- Bubble (Conversation Bubble) + - Supports avatar, content, header, footer, extra actions, editable text, loading state, and custom content rendering + - Slot keys: `avatar`, `content`, `header`, `footer`, `extra`, `editable.okText`, `editable.cancelText`, `loadingRender`, `contentRender` + - Typical use cases: User/system message display, editable replies, async loading states + +- Conversations (Conversation Management) + - Supports conversation item lists, grouping, menus, overflow indicators, expand icons, and triggers + - Slot keys: `menu.items`, `menu.trigger`, `menu.expandIcon`, `menu.overflowedIndicator`, `groupable.label` + - Typical use cases: Historical conversation browsing, group collapsing, right-click menu operations + +- Prompts (Prompt Collection) + - Supports prompt card title slots and dynamic item rendering + - Slot keys: `title` + - Typical use cases: Chat guidance, quick prompts, templated input + +- Suggestion (Quick Commands) + - Supports suggestion item lists, sub-item slot patching, popup containers, open state, and keyboard trigger strategies + - Slot keys: `children` + - Typical use cases: @mentions, /commands, quick suggestions + +- Sender (Sender) + - Supports paste upload, skill panel, prefix/suffix/header/footer slots, value change, and submission interception + - Slot keys: `suffix`, `header`, `prefix`, `footer`, `skill.title`, `skill.toolTip.title`, `skill.closable.closeIcon` + - Typical use cases: Text input, file paste upload, skill toggles + +Section Sources + +- [bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) +- [conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) +- [prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) +- [suggestion.tsx:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) +- [sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) + +## Architecture Overview + +The diagram below shows the call relationships and data flow between general components and the utility library, reflecting the overall flow of "slot parsing → function wrapping → render item generation → React component bridging". + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Comp as "Svelte Wrapper Component" +participant Utils as "Utility Library" +participant X as "@ant-design/x Component" +Dev->>Comp : Pass props and slots +Comp->>Utils : Parse slots / wrap functions / handle value changes +Utils-->>Comp : Return render results / function handles +Comp->>X : Pass through props and bridge React component +X-->>Dev : Render UI and trigger callbacks +``` + +Chart Sources + +- [bubble.tsx:27-115](file://frontend/antdx/bubble/bubble.tsx#L27-L115) +- [conversations.tsx:72-171](file://frontend/antdx/conversations/conversations.tsx#L72-L171) +- [prompts.tsx:16-37](file://frontend/antdx/prompts/prompts.tsx#L16-L37) +- [suggestion.tsx:77-159](file://frontend/antdx/suggestion/suggestion.tsx#L77-L159) +- [sender.tsx:35-169](file://frontend/antdx/sender/sender.tsx#L35-L169) +- [renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [createFunction.ts](file://frontend/utils/createFunction.ts) +- [patchSlots.ts](file://frontend/utils/patchSlots.ts) +- [react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) + +## Detailed Component Analysis + +### Bubble Component API + +- Component Responsibilities + - Wraps `@ant-design/x`'s Bubble in Svelte form, providing slot and function wrapping capabilities + - Supports editable text, loading state, custom content rendering, and avatar/header/footer/extra action slots +- Key Properties and Slots + - Props: Inherits from `BubbleProps`, supports `editable`, `typing`, `content`, `avatar`, `extra`, `footer`, `header`, `loadingRender`, `contentRender`, etc. + - Slots: `avatar`, `content`, `header`, `footer`, `extra`, `editable.okText`, `editable.cancelText`, `loadingRender`, `contentRender` +- Events and State + - Callbacks are wrapped via `useFunction` to ensure reactive updates; `editable` supports boolean or config objects +- Usage Notes + - Edit mode is enabled when `editable` config exists or slots are present; `loadingRender`/`contentRender` support parameterized slots +- Example Path + - [Bubble Implementation:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) + +```mermaid +classDiagram +class Bubble { ++props : BubbleProps ++slots : slot collection ++useFunction() ++ReactSlot ++renderParamsSlot() +} +class XBubble { ++Inherits from @ant-design/x +} +Bubble --> XBubble : "bridge" +``` + +Chart Sources + +- [bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) + +Section Sources + +- [bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) + +### Conversations Component API + +- Component Responsibilities + - Wraps `@ant-design/x`'s Conversations in Svelte form, providing menu and grouping capabilities +- Key Properties and Slots + - Props: Inherits from `ConversationsProps`, supports `items`, `menu`, `groupable`, `classNames`, etc. + - Slots: `menu.items`, `menu.trigger`, `menu.expandIcon`, `menu.overflowedIndicator`, `groupable.label` +- Events and State + - Menu callbacks are wrapped via `useFunction`; menu events are wrapped to pass the current conversation context + - Group labels support both slot and function configuration +- Usage Notes + - `menu` supports strings or objects; when `items` is not provided, they can be injected from context + - `classNames.item` injects style class names for improved consistency +- Example Path + - [Conversations Implementation:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Conv as "Conversations" +participant Ctx as "Context/Slots" +participant XConv as "X Conversations" +Dev->>Conv : Pass items/menu/groupable +Conv->>Ctx : Read slots/context items +Conv->>Conv : Wrap menu callbacks via useFunction +Conv->>XConv : Pass through props and render +XConv-->>Dev : Render conversation list/groups +``` + +Chart Sources + +- [conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) +- [context.ts (conversation item context):1-7](file://frontend/antdx/conversations/context.ts#L1-L7) + +Section Sources + +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [context.ts (conversation item context):1-7](file://frontend/antdx/conversations/context.ts#L1-L7) + +### Prompts Component API + +- Component Responsibilities + - Wraps `@ant-design/x`'s Prompts in Svelte form, providing title slots and dynamic item rendering +- Key Properties and Slots + - Props: Inherits from `PromptsProps`, supports `items`, `title`, etc. + - Slots: `title` +- Events and State + - Item lists are dynamically generated via `renderItems`; slot `items`/`default` takes priority +- Usage Notes + - Suitable for "quick prompts", "templated input", and similar scenarios +- Example Path + - [Prompts Implementation:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) + +```mermaid +flowchart TD +Start(["Start"]) --> Read["Read slot items/default"] +Read --> HasItems{"Has items?"} +HasItems --> |Yes| Render["renderItems render"] +HasItems --> |No| UseProps["Use props.items"] +Render --> SetTitle["Set title slot"] +UseProps --> SetTitle +SetTitle --> End(["End"]) +``` + +Chart Sources + +- [prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) +- [context.ts (prompt item context):1-7](file://frontend/antdx/prompts/context.ts#L1-L7) + +Section Sources + +- [prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [context.ts (prompt item context):1-7](file://frontend/antdx/prompts/context.ts#L1-L7) + +### Suggestion Component API + +- Component Responsibilities + - Wraps `@ant-design/x`'s Suggestion in Svelte form, providing suggestion item slot patching, popup containers, open state, and keyboard trigger strategies +- Key Properties and Slots + - Props: Inherits from `SuggestionProps`, adds `children` slot and `shouldTrigger` callback + - Slots: `children` +- Events and State + - `SuggestionOpenContext` and `useSuggestionOpenContext` control and observe the open state + - `patchSlots` patches suggestion item `icon`/`label`/`extra`/`children` slots + - `useMemoizedEqualValue` optimizes rendering overhead +- Usage Notes + - Supports injecting context into `children` render function to customize `onTrigger`/`onKeyDown` + - Supports controlled/uncontrolled `open` state switching +- Example Path + - [Suggestion Implementation:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Sug as "Suggestion" +participant Ctx as "SuggestionContext/SuggestionOpenContext" +participant Patch as "patchSlots" +participant XSug as "X Suggestion" +Dev->>Sug : Pass items/children/shouldTrigger +Sug->>Patch : Patch suggestion item slots +Sug->>Ctx : Provider injects context +Sug->>XSug : Pass through props and render +XSug-->>Dev : Popup and suggestion items +``` + +Chart Sources + +- [suggestion.tsx:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) +- [context.ts (suggestion item context):1-7](file://frontend/antdx/suggestion/context.ts#L1-L7) +- [react-contexts.ts](file://frontend/svelte-preprocess-react/react-contexts.ts) + +Section Sources + +- [suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) +- [context.ts (suggestion item context):1-7](file://frontend/antdx/suggestion/context.ts#L1-L7) + +### Sender Component API + +- Component Responsibilities + - Wraps `@ant-design/x`'s Sender in Svelte form, providing paste upload, skill panel, slots, and value change hooks +- Key Properties and Slots + - Props: Inherits from `SenderProps`, adds `upload`, `onPasteFile`, `onValueChange`, etc. + - Slots: `suffix`, `header`, `prefix`, `footer`, `skill.title`, `skill.toolTip.title`, `skill.closable.closeIcon` +- Events and State + - `useValueChange` manages controlled/uncontrolled `value` + - `useSuggestionOpenContext` intercepts submission when Suggestion is open + - `createFunction`/`formatResult`/`customRender` customize `slotConfig` +- Usage Notes + - When pasting files, calls `upload` and backfills the path array + - Skill panel supports combinations of slots and configuration for tooltip/closable +- Example Path + - [Sender Implementation:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) + +```mermaid +flowchart TD +A["onPasteFile triggered"] --> B["Call upload(files)"] +B --> C["Backfill path array to onPasteFile"] +D["onSubmit triggered"] --> E{"Is Suggestion open?"} +E --> |Yes| F["Intercept submission"] +E --> |No| G["Normal submission"] +H["onChange triggered"] --> I["useValueChange updates value"] +``` + +Chart Sources + +- [sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) + +Section Sources + +- [sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +## Dependency Analysis + +There is a clear dependency relationship between general components and the utility library: components consume utility library capabilities through the context and slot systems, ultimately bridging to `@ant-design/x` React components. + +```mermaid +graph LR +subgraph "Components" +B["Bubble"] +C["Conversations"] +P["Prompts"] +S["Suggestion"] +SD["Sender"] +end +subgraph "Utilities" +R1["renderItems"] +R2["renderParamsSlot"] +H1["useFunction"] +H2["useValueChange"] +H3["useMemoizedEqualValue"] +F1["createFunction"] +F2["patchSlots"] +RS["ReactSlot"] +RC["ReactContexts"] +end +B --> R1 +B --> R2 +B --> H1 +B --> RS +C --> R1 +C --> R2 +C --> H1 +C --> RC +P --> R1 +P --> R2 +S --> R1 +S --> R2 +S --> H1 +S --> F2 +S --> H3 +SD --> R1 +SD --> R2 +SD --> H1 +SD --> H2 +SD --> F1 +SD --> RS +SD --> RC +``` + +Chart Sources + +- [bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) +- [sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) +- [renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [createFunction.ts](file://frontend/utils/createFunction.ts) +- [patchSlots.ts](file://frontend/utils/patchSlots.ts) +- [react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) +- [react-contexts.ts](file://frontend/svelte-preprocess-react/react-contexts.ts) + +Section Sources + +- [bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) +- [sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +## Performance Considerations + +- Slot and Function Wrapping + - Use `useMemoizedEqualValue` and `useMemo` to reduce render jitter and redundant computation + - Wrap callbacks via `useFunction` to prevent child component re-renders caused by new function instances on every render +- Render Items and Slots + - `renderItems` and `renderParamsSlot` execute only when necessary, reducing unnecessary cloning and rendering + - `patchSlots` patches suggestion items on demand, avoiding full replacement +- Value Change and Event Interception + - `useValueChange` unifies value management to prevent external state inconsistencies + - Sender intercepts submission when Suggestion is open, reducing invalid requests +- Best Practices + - Properly split slots and functions, avoid heavy logic inside slots + - Use stable references for high-frequency update data, combined with `useMemo`/`useCallback` + - Reuse already-parsed `items` in Conversations/Prompts as much as possible to reduce duplicate rendering + +[This section provides general performance guidance and requires no specific file sources] + +## Troubleshooting Guide + +- Slot Not Taking Effect + - Check if slot key names match the component declarations (e.g., `bubble`'s `editable.okText`, `conversations`'s `menu.items`, etc.) + - Confirm that slot content is properly wrapped in `ReactSlot` or `renderParamsSlot` +- Event Not Firing + - Confirm that the callback wrapped by `useFunction` is correctly passed to the underlying component + - For Conversations menu events, check if `patchMenuEvents` correctly wraps the original event +- Suggestion Item Slot Not Displaying + - Confirm that `patchSlots` has patched `icon`/`label`/`extra`/`children` + - Check if the Suggestion `children` render function returns the correct nodes +- Sender Submission Intercepted + - Confirm whether `SuggestionOpenContext` state is `true` + - Check if `shouldTrigger` correctly fires on keyboard events +- Value Not Updating + - Confirm that `useValueChange`'s `onValueChange` is being called + - Check the synchronization logic between `props.value` and internal state + +Section Sources + +- [bubble.tsx:27-115](file://frontend/antdx/bubble/bubble.tsx#L27-L115) +- [conversations.tsx:35-122](file://frontend/antdx/conversations/conversations.tsx#L35-L122) +- [suggestion.tsx:100-159](file://frontend/antdx/suggestion/suggestion.tsx#L100-L159) +- [sender.tsx:126-138](file://frontend/antdx/sender/sender.tsx#L126-L138) + +## Conclusion + +ModelScope Studio's Ant Design X general components achieve seamless bridging with `@ant-design/x` components through a unified slot system and function wrapping mechanism. Bubble, Conversations, Prompts, Suggestion, and Sender provide powerful extensibility and ease of use for AI chat and conversation scenarios. Following this document's property definitions, event handling, slot system, and state management recommendations, you can efficiently build high-quality conversational interfaces and interaction flows. + +[This section is a summary and requires no specific file sources] + +## Appendix + +- TypeScript Types and Interfaces + - All components extend or trim the corresponding `Props` types from `@ant-design/x` to ensure type safety + - Slots and function wrapping leverage generics and utility functions to guarantee type inference +- Integration with Ant Design Components + - Svelte-to-React bridging is achieved via `sveltify` and `ReactSlot` from `svelte-preprocess-react` + - Property and callback functionalization is achieved via utility tools such as `createFunction`/`useFunction` +- Example Path Index + - Bubble: [bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) + - Conversations: [conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) + - Prompts: [prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) + - Suggestion: [suggestion.tsx:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) + - Sender: [sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) + +[This section is supplementary information and requires no specific file sources] diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Tool Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Tool Components API.md new file mode 100644 index 00000000..652751cf --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Ant Design X Components API/Tool Components API.md @@ -0,0 +1,377 @@ +# Tool Components API + + +**Files Referenced in This Document** +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antdx/code-highlighter/code-highlighter.tsx](file://frontend/antdx/code-highlighter/code-highlighter.tsx) +- [frontend/antdx/file-card/file-card.tsx](file://frontend/antdx/file-card/file-card.tsx) +- [frontend/antdx/file-card/base.tsx](file://frontend/antdx/file-card/base.tsx) +- [frontend/antdx/folder/folder.tsx](file://frontend/antdx/folder/folder.tsx) +- [frontend/antdx/folder/context.ts](file://frontend/antdx/folder/context.ts) +- [frontend/antdx/mermaid/mermaid.tsx](file://frontend/antdx/mermaid/mermaid.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [docs/components/antdx/x_provider/README.md](file://docs/components/antdx/x_provider/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document covers the Ant Design X Tool Components API for ModelScope Studio, focusing on the complete interface and usage of the following components: + +- XProvider Global Configuration Component (based on antd's ConfigProvider extension) +- CodeHighlighter Code Highlighting Component +- FileCard File Card Component +- Folder Directory Component +- Mermaid Flowchart Component + +The document covers global configuration approaches, code highlighting language and theme support, file management interactions, flowchart drawing and action integration, and integration with the Gradio ecosystem. It also provides key type definition notes, context provision and state management mechanisms, performance optimization, and best extension practices. + +## Project Structure + +Key directories and files around tool components: + +- Frontend component implementations are in `frontend/antdx` and `frontend/antd`, corresponding to Ant Design X components and the antd configuration layer respectively +- Each component is wrapped via `sveltify` as a React component usable in Svelte, bridged through slots and parameters +- Shared context between components is provided via `createItemsContext`, used for tree nodes, directory icons, and action items, etc. + +```mermaid +graph TB +subgraph "Antd Configuration Layer" +CP["ConfigProvider
frontend/antd/config-provider/config-provider.tsx"] +end +subgraph "Ant Design X Tool Components" +CH["CodeHighlighter
frontend/antdx/code-highlighter/code-highlighter.tsx"] +FC["FileCard
frontend/antdx/file-card/file-card.tsx"] +FCB["BaseFileCard
frontend/antdx/file-card/base.tsx"] +FD["Folder
frontend/antdx/folder/folder.tsx"] +FDCtx["Folder Context
frontend/antdx/folder/context.ts"] +MM["Mermaid
frontend/antdx/mermaid/mermaid.tsx"] +ActCtx["Actions Context
frontend/antdx/actions/context.ts"] +end +CP --> CH +CP --> FC +FC --> FCB +CP --> FD +FD --> FDCtx +CP --> MM +MM --> ActCtx +``` + +Chart Sources + +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:1-54](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L1-L54) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) +- [frontend/antdx/folder/folder.tsx:1-123](file://frontend/antdx/folder/folder.tsx#L1-L123) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) + +Section Sources + +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:1-54](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L1-L54) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) +- [frontend/antdx/folder/folder.tsx:1-123](file://frontend/antdx/folder/folder.tsx#L1-L123) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) + +## Core Components + +This section provides an overview of each component's responsibilities and key capabilities: + +- XProvider: Replaces antd's ConfigProvider in Gradio Blocks scenarios, uniformly providing global configuration for Ant Design X components (theme, localization, popup containers, etc.), and compatible with slot injection +- CodeHighlighter: Encapsulates `@ant-design/x`'s code highlighting component, supporting custom `header` slots and syntax highlighting styles in light/dark themes +- FileCard: File card component, supporting slot-based configuration for image placeholders, preview masks, close icons, toolbar rendering, indicators, and description text +- Folder: Directory tree component, supporting slot injection for tree node data, directory icon mapping, empty state rendering, and title/preview rendering, and can connect to file content services +- Mermaid: Flowchart component, supporting theme switching, highlight styles, action item context injection, and custom actions + +Section Sources + +- [docs/components/antdx/x_provider/README.md:1-19](file://docs/components/antdx/x_provider/README.md#L1-L19) +- [frontend/antd/config-provider/config-provider.tsx:51-151](file://frontend/antd/config-provider/config-provider.tsx#L51-L151) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:29-51](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L29-L51) +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/folder/folder.tsx:16-120](file://frontend/antdx/folder/folder.tsx#L16-L120) +- [frontend/antdx/mermaid/mermaid.tsx:33-84](file://frontend/antdx/mermaid/mermaid.tsx#L33-L84) + +## Architecture Overview + +XProvider serves as the top-level configuration container, providing unified theme, localization, and popup container strategies to tool components below; tool components use slot and parameter bridging, combined with context providers for flexible slot-based and dynamic rendering. + +```mermaid +sequenceDiagram +participant App as "Application" +participant XProv as "XProvider (ConfigProvider)" +participant Comp as "Tool Component" +participant Slots as "Slot System" +App->>XProv : "Wrap application and pass configuration" +XProv->>Comp : "Provide theme/localization/container strategy" +Comp->>Slots : "Read slots (e.g., header, mask, previewRender)" +Slots-->>Comp : "Return React nodes" +Comp-->>App : "Render final UI" +``` + +Chart Sources + +- [frontend/antd/config-provider/config-provider.tsx:108-149](file://frontend/antd/config-provider/config-provider.tsx#L108-L149) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:35-49](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L35-L49) +- [frontend/antdx/file-card/file-card.tsx:46-123](file://frontend/antdx/file-card/file-card.tsx#L46-L123) +- [frontend/antdx/folder/folder.tsx:48-116](file://frontend/antdx/folder/folder.tsx#L48-L116) +- [frontend/antdx/mermaid/mermaid.tsx:47-81](file://frontend/antdx/mermaid/mermaid.tsx#L47-L81) + +## Component Details + +### XProvider Global Configuration Component + +- Role: Replaces antd's ConfigProvider, providing unified global configuration for `@ant-design/x` components +- Key Capabilities + - Theme Mode: Supports `themeMode` to control dark/compact algorithms + - Localization: Automatically parses and loads the corresponding `antd`/`dayjs` locale resources based on the browser language + - Popup Containers: Supports `getPopupContainer`/`getTargetContainer` function injection + - Slot-based: Injects slots into component properties via `combinePropsAndSlots` + - Custom Rendering: `renderEmpty` supports both slot and function forms +- Usage Recommendations + - Use `antdx.XProvider` instead of `antd.ConfigProvider` in Gradio Blocks + - Switch light/dark themes via `themeMode`, avoiding re-render issues caused by duplicate keys + - Set `getPopupContainer` appropriately to ensure floating layers render in the correct container + +Section Sources + +- [docs/components/antdx/x_provider/README.md:1-19](file://docs/components/antdx/x_provider/README.md#L1-L19) +- [frontend/antd/config-provider/config-provider.tsx:51-151](file://frontend/antd/config-provider/config-provider.tsx#L51-L151) + +### CodeHighlighter Code Highlighting Component + +- Role: Renders code with syntax highlighting, supporting `header` slots and light/dark theme styles +- Key Capabilities + - Language Support: Relies on `react-syntax-highlighter`'s Prism style, can directly render multiple languages + - Light/Dark Theme: Switches `materialDark`/`materialLight` styles based on `themeMode`, uniformly removing the code block outer margin + - Slot-based: Supports `header` slot for custom header injection + - Value Binding: Both the `value` property and child node content can serve as code input +- Usage Recommendations + - In AI applications, prefer consistent light/dark theme styles for a better reading experience + - Add copy, download, and other action buttons via the `header` slot + +Section Sources + +- [frontend/antdx/code-highlighter/code-highlighter.tsx:29-51](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L29-L51) + +### FileCard File Card Component + +- Role: Displays file information, supporting slot-based configuration for image placeholders, preview masks, toolbars, indicators, and description text +- Key Capabilities + - Image Processing: Supports slot-based placeholders, preview containers, close icons, toolbars, and image rendering + - Loading State: `spinProps` supports `size`, `icon`, `description`, `indicator` slots + - Description and Icons: `description` and `icon` slots allow custom display content + - Resource Resolution: Resolves relative paths and `FileData` via `BaseFileCard`'s `resolveFileSrc` +- Usage Recommendations + - For remote images, ensure `rootUrl` and `apiPrefix` are correctly concatenated for an accessible URL + - Enable preview functionality on demand to avoid unnecessary DOM rendering + +```mermaid +flowchart TD +Start(["Enter FileCard"]) --> CheckImg["Check if imageProps.preview is enabled"] +CheckImg --> |Enabled| BuildPreview["Build preview config (with slots)"] +CheckImg --> |Disabled| NoPreview["Disable preview"] +BuildPreview --> ResolveSrc["Resolve src to accessible URL"] +NoPreview --> ResolveSrc +ResolveSrc --> Render["Render BaseFileCard"] +Render --> End(["Done"]) +``` + +Chart Sources + +- [frontend/antdx/file-card/file-card.tsx:34-123](file://frontend/antdx/file-card/file-card.tsx#L34-L123) +- [frontend/antdx/file-card/base.tsx:15-41](file://frontend/antdx/file-card/base.tsx#L15-L41) + +Section Sources + +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/file-card/base.tsx:9-41](file://frontend/antdx/file-card/base.tsx#L9-L41) + +### Folder Directory Component + +- Role: Directory tree component, supporting tree node data, directory icon mapping, empty state and title rendering, preview rendering, and file content services +- Key Capabilities + - Tree Node Context: Provides two data sources `treeData`/`default` via `withTreeNodeItemsContextProvider` + - Directory Icon Context: Provides extension-to-icon mapping via `withDirectoryIconItemsContextProvider` + - Preview Service: `fileContentService` can inject a callback for loading file content + - Slot-based: `emptyRender`, `directoryTitle`, `previewTitle`, `previewRender` all support slots +- Usage Recommendations + - When `treeData` is empty, fall back to the default node list to ensure stable initial rendering + - Directory icon mappings are collected via slots and then converted to a dictionary for fast lookup + +```mermaid +sequenceDiagram +participant FD as "Folder" +participant Ctx as "Context Provider" +participant XFD as "@ant-design/x Folder" +participant FS as "File Content Service" +FD->>Ctx : "Read tree nodes and directory icons" +FD->>FD : "Merge treeData/default" +FD->>FD : "Build directory icon mapping" +FD->>XFD : "Pass treeData, directoryIcons, emptyRender..." +alt fileContentService exists +FD->>FS : "Call onLoadFileContent(filePath)" +FS-->>FD : "Return file content" +end +XFD-->>FD : "Render tree and preview" +``` + +Chart Sources + +- [frontend/antdx/folder/folder.tsx:24-120](file://frontend/antdx/folder/folder.tsx#L24-L120) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) + +Section Sources + +- [frontend/antdx/folder/folder.tsx:16-120](file://frontend/antdx/folder/folder.tsx#L16-L120) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) + +### Mermaid Flowchart Component + +- Role: Flowchart drawing component, supporting theme switching, highlight styles, and action item context +- Key Capabilities + - Theme and Highlight: Switches `dark`/`base` theme based on `themeMode`, and applies Prism-style highlighting + - Actions Context: Injects custom action items via `withActionItemsContextProvider` + - Slot-based: `header` and `actions.customActions` support slots + - Config Merging: `theme` in `config` will be overridden by `themeMode` +- Usage Recommendations + - In AI applications, inject copy, download, full-screen, and other actions via `actions.customActions` + - Maintain theme consistency to avoid visual breaks caused by light/dark switching + +Section Sources + +- [frontend/antdx/mermaid/mermaid.tsx:33-84](file://frontend/antdx/mermaid/mermaid.tsx#L33-L84) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) + +## Dependency Analysis + +- Component Coupling + - FileCard depends on BaseFileCard for resource resolution, reducing duplicate logic + - Folder injects tree nodes and directory icons via context providers, decoupling external data sources + - Mermaid injects custom actions via the actions context provider, enhancing extensibility +- External Dependencies + - `react-syntax-highlighter`: Provides Prism-style highlighting + - `@ant-design/x`: Provides underlying component capabilities (CodeHighlighter, Folder, Mermaid, FileCard, etc.) + - `antd`: ConfigProvider extension and theme algorithms +- Circular Dependencies + - No circular dependencies detected in the current structure; context providers are abstracted via `createItemsContext`, avoiding direct mutual references + +```mermaid +graph LR +CH["CodeHighlighter"] --> XCH["@ant-design/x CodeHighlighter"] +FC["FileCard"] --> FCB["BaseFileCard"] +FCB --> XFC["@ant-design/x FileCard"] +FD["Folder"] --> XFD["@ant-design/x Folder"] +FD --> FDCtx["Folder Context"] +MM["Mermaid"] --> XMM["@ant-design/x Mermaid"] +MM --> ActCtx["Actions Context"] +CP["ConfigProvider (XProvider)"] --> CH +CP --> FC +CP --> FD +CP --> MM +``` + +Chart Sources + +- [frontend/antdx/code-highlighter/code-highlighter.tsx:1-54](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L1-L54) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) +- [frontend/antdx/folder/folder.tsx:1-123](file://frontend/antdx/folder/folder.tsx#L1-L123) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) + +Section Sources + +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/folder/folder.tsx:16-120](file://frontend/antdx/folder/folder.tsx#L16-L120) +- [frontend/antdx/mermaid/mermaid.tsx:33-84](file://frontend/antdx/mermaid/mermaid.tsx#L33-L84) +- [frontend/antd/config-provider/config-provider.tsx:51-151](file://frontend/antd/config-provider/config-provider.tsx#L51-L151) + +## Performance Considerations + +- Rendering Strategy + - Use `useMemo` to cache computed results like `treeData`, `directoryIcons`, `actions.customActions`, etc., to avoid duplicate renders + - Enable preview containers and toolbars only when needed to reduce DOM structure complexity +- Theme Switching + - When `themeMode` changes, combine light/dark algorithms and reuse style objects to avoid frequent style rebuilding +- Slot Rendering + - When using `renderParamsSlot` and `renderItems`, pass `clone: true` as much as possible to ensure independent slot node updates +- Resource Resolution + - `BaseFileCard`'s `resolveFileSrc` only recalculates when `src`/`rootUrl`/`apiPrefix` changes, avoiding unnecessary URL concatenation + +[This section provides general guidance and requires no specific file sources] + +## Troubleshooting Guide + +- Localization Not Taking Effect + - Check whether the `locale` parameter format is as expected; confirm the `locales` map has the corresponding language pack + - Confirm `dayjs.locale` has been correctly set +- Popup Layer Position Anomaly + - Check whether the container returned by `getPopupContainer`/`getTargetContainer` is visible and at the correct z-index level +- Preview Not Available + - Confirm `imageProps.preview` has not been explicitly set to `false`, and at least one of the `mask`/`closeIcon`/`toolbarRender`/`imageRender` slots is available +- Files Inaccessible + - Confirm `resolveFileSrc`'s `rootUrl` and `apiPrefix` are correctly concatenated; use `FileData.url` field if necessary +- Action Items Not Displaying + - Confirm that action items injected via `withActionItemsContextProvider` have been correctly collected and passed to `actions.customActions` + +Section Sources + +- [frontend/antd/config-provider/config-provider.tsx:96-105](file://frontend/antd/config-provider/config-provider.tsx#L96-L105) +- [frontend/antdx/file-card/file-card.tsx:34-123](file://frontend/antdx/file-card/file-card.tsx#L34-L123) +- [frontend/antdx/file-card/base.tsx:15-41](file://frontend/antdx/file-card/base.tsx#L15-L41) +- [frontend/antdx/mermaid/mermaid.tsx:40-84](file://frontend/antdx/mermaid/mermaid.tsx#L40-L84) + +## Conclusion + +This document systematically covers the API and usage of Ant Design X Tool Components in ModelScope Studio, with a focus on the interface highlights and best practices of XProvider global configuration, CodeHighlighter, FileCard, Folder, and Mermaid. Through slot-based design and context providers, the components achieve highly customizable and extensible capabilities within the Gradio ecosystem, suitable for tool integration and content display scenarios in AI applications. + +[This section is a summary and requires no specific file sources] + +## Appendix + +### Component API Quick Reference + +- XProvider + - Main Properties: `themeMode`, `locale`, `getPopupContainer`, `getTargetContainer`, `renderEmpty`, `component`, `className`, `style`, `id` + - Slots: None (injected via parameters and functions) +- CodeHighlighter + - Main Properties: `value`, `themeMode`, `highlightProps`, `header` + - Slots: `header` +- FileCard + - Main Properties: `rootUrl`, `apiPrefix`, `src`, `imageProps`, `spinProps`, `description`, `icon`, `mask` + - Slots: `imageProps.placeholder`, `imageProps.preview.mask`, `imageProps.preview.closeIcon`, `imageProps.preview.toolbarRender`, `imageProps.preview.imageRender`, `description`, `icon`, `mask`, `spinProps.icon`, `spinProps.description`, `spinProps.indicator` +- Folder + - Main Properties: `treeData`, `directoryIcons`, `emptyRender`, `directoryTitle`, `previewTitle`, `previewRender`, `fileContentService` + - Slots: `emptyRender`, `previewRender`, `directoryTitle`, `previewTitle` +- Mermaid + - Main Properties: `value`, `themeMode`, `config`, `actions`, `header` + - Slots: `header`, `actions.customActions` + +Section Sources + +- [frontend/antd/config-provider/config-provider.tsx:51-151](file://frontend/antd/config-provider/config-provider.tsx#L51-L151) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:29-51](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L29-L51) +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/folder/folder.tsx:16-120](file://frontend/antdx/folder/folder.tsx#L16-L120) +- [frontend/antdx/mermaid/mermaid.tsx:33-84](file://frontend/antdx/mermaid/mermaid.tsx#L33-L84) diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Basic Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Basic Components API.md new file mode 100644 index 00000000..17bbd1ec --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Basic Components API.md @@ -0,0 +1,570 @@ +# Basic Components API + + +**Files referenced in this document** +- [frontend/base/application/Index.svelte](file://frontend/base/application/Index.svelte) +- [frontend/base/auto-loading/Index.svelte](file://frontend/base/auto-loading/Index.svelte) +- [frontend/base/slot/Index.svelte](file://frontend/base/slot/Index.svelte) +- [frontend/base/fragment/Index.svelte](file://frontend/base/fragment/Index.svelte) +- [frontend/base/div/Index.svelte](file://frontend/base/div/Index.svelte) +- [frontend/base/span/Index.svelte](file://frontend/base/span/Index.svelte) +- [frontend/base/text/Index.svelte](file://frontend/base/text/Index.svelte) +- [frontend/base/markdown/Index.svelte](file://frontend/base/markdown/Index.svelte) +- [frontend/base/each/Index.svelte](file://frontend/base/each/Index.svelte) +- [frontend/base/filter/Index.svelte](file://frontend/base/filter/Index.svelte) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the authoritative reference for ModelScope Studio's basic Svelte components, covering the complete API specifications and usage instructions for the following components: Application, AutoLoading, Slot, Fragment, Div, Span, Text, Markdown, Each, and Filter. Content includes: + +- Property definitions and default values +- Event and callback conventions +- Slot system and parameter mapping +- Lifecycle and rendering control (visibility, lazy loading) +- Inter-component communication mechanisms (contexts, slot keys, loading states) +- TypeScript type constraints and interface specifications +- Instantiation and configuration example paths +- Performance optimization and best practices + +## Project Structure + +Base components are located in the `base` directory of the frontend workspace, organized with a "one directory per component" structure. Each component contains an entry `Index.svelte` and corresponding implementation files (`.tsx` or `.svelte`). Components use a unified preprocessing toolchain for property extraction, additional property injection, and lazy loading. + +```mermaid +graph TB +subgraph "Base Components" +APP["application/Index.svelte"] +AL["auto-loading/Index.svelte"] +SLOT["slot/Index.svelte"] +FRAG["fragment/Index.svelte"] +DIV["div/Index.svelte"] +SPAN["span/Index.svelte"] +TEXT["text/Index.svelte"] +MD["markdown/Index.svelte"] +EACH["each/Index.svelte"] +FILT["filter/Index.svelte"] +end +subgraph "Common Utilities" +PREACT["@svelte-preprocess-react/*"] +CLS["classnames"] +end +APP --> PREACT +AL --> PREACT +SLOT --> PREACT +FRAG --> PREACT +DIV --> PREACT +SPAN --> PREACT +TEXT --> PREACT +MD --> PREACT +EACH --> PREACT +FILT --> PREACT +DIV --> CLS +SPAN --> CLS +MD --> CLS +AL --> CLS +``` + +Diagram sources + +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) +- [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [frontend/base/filter/Index.svelte:1-52](file://frontend/base/filter/Index.svelte#L1-L52) + +Section sources + +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) +- [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [frontend/base/filter/Index.svelte:1-52](file://frontend/base/filter/Index.svelte#L1-L52) + +## Core Components + +This section systematically covers the key properties, events, slots, and lifecycle of each component, along with type constraints and usage notes. + +- **Application** + - Purpose: Dynamically imports and renders application-level components, with support for lazy loading and `children` rendering. + - Key properties + - `children`: Optional render function for passing child nodes. + - Other properties are extracted by `getProps` and passed through to internal components. + - Lifecycle + - Uses `{#await}` for async rendering, ensuring the component mounts only after the import completes. + - Example path + - [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) + +- **AutoLoading** + - Purpose: Wraps any component, providing visibility, generating state, error state, and style passthrough capabilities. + - Key properties + - `visible`: Controls whether to render. + - `generating`: Indicates the generating state, affecting the loading status. + - `showError`: Whether to display the error state. + - `elem_id`/`elem_classes`/`elem_style`: DOM attribute passthrough. + - `as_item`/`_internal`: Internal flags and container identifiers. + - Other properties are passed through after processing by `getComponentProps`/`processProps`. + - Context + - Reads config type, slot collection, and loading status. + - Example path + - [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) + +- **Slot** + - Purpose: Registers and updates named slots, supporting parameter mapping and visibility control. + - Key properties + - `value`: Slot key value. + - `params_mapping`: Parameter mapping expression string, converted to a function at runtime. + - `visible`/`as_item`/`_internal`: Controls visibility and containerization. + - Behavior + - Detects `value` changes in `effect` and calls `setSlot` to update the context. + - Sets the current slot key and parameter mapping. + - Example path + - [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) + +- **Fragment** + - Purpose: Lightweight container that wraps multiple child nodes without introducing extra DOM. + - Key properties + - `visible`/`_internal`/`as_item`: Controls visibility and containerization. + - Other properties are passed through to the internal Fragment. + - Note + - `shouldResetSlotKey`: Slot key reset is disabled in the configuration. + - Example path + - [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + +- **Div** + - Purpose: Block-level container supporting styles, class names, IDs, and internal layout flags. + - Key properties + - `value`: Text or content value. + - `elem_style`: Inline style object. + - `additional_props`: Additional properties object. + - `_internal.layout`: Marks whether this is a layout-related internal element. + - `visible`/`as_item`/`elem_id`/`elem_classes`: Controls visibility and DOM attributes. + - Example path + - [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) + +- **Span** + - Purpose: Inline container; behaves similarly to Div but with inline semantics. + - Key properties + - `value`: Text or content value. + - `additional_props`: Additional properties object. + - `_internal.layout`: Marks whether this is a layout-related internal element. + - `visible`/`as_item`/`elem_id`/`elem_classes`/`elem_style`: Controls visibility and DOM attributes. + - Example path + - [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) + +- **Text** + - Purpose: Text display component with value and common property passthrough. + - Key properties + - `value`: Text value. + - `visible`/`as_item`/`_internal`: Controls visibility and containerization. + - Example path + - [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) + +- **Markdown** + - Purpose: Markdown rendering component with support for themes, root paths, and slots. + - Key properties + - `value`: Markdown text. + - `elem_id`/`elem_classes`/`elem_style`: DOM attribute passthrough. + - `visible`/`as_item`/`_internal`: Controls visibility and containerization. + - Context + - Reads `root` and `theme` from the shared configuration. + - Reads the slot collection for custom component embedding. + - Example path + - [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) + +- **Each** + - Purpose: List rendering component supporting context merging, index calculation, and placeholders. + - Key properties + - `value`: Array to be rendered. + - `context_value`: Context object. + - `_internal.index`: Internal start index. + - `visible`/`as_item`/`elem_id`/`elem_classes`/`elem_style`: Controls visibility and DOM attributes. + - Behavior + - Uses `EachPlaceholder` to merge external changes and determines whether to force-clone rendering. + - Supports nested Each, calculating sub-indices and slot keys via `getSubIndex` and `getSlotKey`. + - Example path + - [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +- **Filter** + - Purpose: Conditional filter component that wraps `children` into a fragment filterable by parameter mapping. + - Key properties + - `params_mapping`: Parameter mapping expression string. + - `visible`/`as_item`/`_internal`: Controls visibility and containerization. + - Example path + - [frontend/base/filter/Index.svelte:1-52](file://frontend/base/filter/Index.svelte#L1-L52) + +Section sources + +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) +- [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [frontend/base/filter/Index.svelte:1-52](file://frontend/base/filter/Index.svelte#L1-L52) + +## Architecture Overview + +Base components complete property resolution, additional property injection, and lazy loading through a unified preprocessing pipeline, while leveraging the context system for slot registration, loading state, and config type management. Components collaborate through props and contexts, forming clear responsibility boundaries and composability. + +```mermaid +sequenceDiagram +participant U as "User Code" +participant IDX as "Index.svelte" +participant PRE as "@svelte-preprocess-react/*" +participant CMP as "Internal Component" +participant CTX as "Context (slots/config/loading)" +U->>IDX : Pass props and children +IDX->>PRE : getProps()/processProps() +PRE-->>IDX : Normalized props and additional properties +IDX->>CTX : Read/set slots/config/loading state +IDX->>CMP : Async import and render component +CMP-->>U : Render result +``` + +Diagram sources + +- [frontend/base/auto-loading/Index.svelte:15-52](file://frontend/base/auto-loading/Index.svelte#L15-L52) +- [frontend/base/slot/Index.svelte:16-54](file://frontend/base/slot/Index.svelte#L16-L54) +- [frontend/base/markdown/Index.svelte:19-44](file://frontend/base/markdown/Index.svelte#L19-L44) + +## Detailed Component Analysis + +### Application Component + +- Design highlights + - Uses `importComponent` to dynamically import internal `Application.svelte`. + - Renders `children` as slot content. +- API summary + - Properties + - `children`: Optional render function + - Other properties are extracted by `getProps` and passed through + - Slots + - Default slot: `children()` + - Lifecycle + - `{#await}` async rendering prevents mounting before import completes + +Example path + +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) + +Section sources + +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) + +### AutoLoading Component + +- Design highlights + - Wraps any component, providing visibility, generating state, error state, and style passthrough. + - Integrates with `getLoadingStatus` and config type linkage. +- API summary + - Properties + - `visible`/`generating`/`showError` + - `elem_id`/`elem_classes`/`elem_style` + - `as_item`/`_internal` + - Other properties processed by `processProps` + - Context + - Reads config type, slot collection, and loading status + - Slots + - Default slot: `children()` + +Example path + +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) + +Section sources + +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) + +### Slot Component + +- Design highlights + - Registers named slots with support for parameter mapping and visibility control. + - Detects `value` changes in `effect` and updates the context. +- API summary + - Properties + - `value`: Slot key + - `params_mapping`: Parameter mapping expression + - `visible`/`as_item`/`_internal` + - Behavior + - `setSlotKey`/`setSlotParamsMapping` + - Obtains the host element via `svelte-slot bind:this` + +Example path + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) + +Section sources + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) + +### Fragment Component + +- Design highlights + - Lightweight container that does not introduce extra DOM. + - Slot key reset is disabled to maintain context stability. +- API summary + - Properties + - `visible`/`_internal`/`as_item` + - Other properties are passed through + - Slots + - Default slot: `children()` + +Example path + +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + +Section sources + +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + +### Div Component + +- Design highlights + - Block-level container supporting styles, class names, IDs, and internal layout flags. +- API summary + - Properties + - `value`/`additional_props`/`_internal.layout` + - `elem_id`/`elem_classes`/`elem_style` + - `visible`/`as_item`/`_internal` + - Slots + - Default slot: `children()` + +Example path + +- [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) + +Section sources + +- [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) + +### Span Component + +- Design highlights + - Inline container; behaves similarly to Div. +- API summary + - Properties + - `value`/`additional_props`/`_internal.layout` + - `elem_id`/`elem_classes`/`elem_style` + - `visible`/`as_item`/`_internal` + - Slots + - Default slot: `children()` + +Example path + +- [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) + +Section sources + +- [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) + +### Text Component + +- Design highlights + - Text display component with minimal overhead. +- API summary + - Properties + - `value` + - `visible`/`as_item`/`_internal` + +Example path + +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) + +Section sources + +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) + +### Markdown Component + +- Design highlights + - Supports themes and root paths, combining with slots for extensible rendering. +- API summary + - Properties + - `value` + - `elem_id`/`elem_classes`/`elem_style` + - `visible`/`as_item`/`_internal` + - Context + - Reads `shared.root` and `theme` + - Reads the slot collection + +Example path + +- [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) + +Section sources + +- [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) + +### Each Component + +- Design highlights + - List rendering with support for context merging, index calculation, and placeholders. + - Nested Each calculates sub-indices and slot keys via `getSubIndex` and `getSlotKey`. +- API summary + - Properties + - `value`/`context_value`/`_internal.index` + - `elem_id`/`elem_classes`/`elem_style` + - `visible`/`as_item`/`_internal` + - Slots + - Default slot: `children()` + - Events + - `EachPlaceholder.onChange`: Receives merged `value` and `contextValue` + +Example path + +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +Section sources + +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +### Filter Component + +- Design highlights + - Conditional filter container that wraps `children` into a fragment filterable by parameter mapping. +- API summary + - Properties + - `params_mapping` + - `visible`/`as_item`/`_internal` + - Slots + - Default slot: `children()` + +Example path + +- [frontend/base/filter/Index.svelte:1-52](file://frontend/base/filter/Index.svelte#L1-L52) + +Section sources + +- [frontend/base/filter/Index.svelte:1-52](file://frontend/base/filter/Index.svelte#L1-L52) + +## Dependency Analysis + +Base components generally depend on the `@svelte-preprocess-react` toolkit and styling libraries, forming a unified property processing and lazy loading mechanism. Some components also depend on the context system for slot registration and loading state management. + +```mermaid +graph LR +subgraph "Utilities" +PRE["@svelte-preprocess-react/*"] +CLS["classnames"] +end +subgraph "Components" +AL["AutoLoading"] +SLOT["Slot"] +MD["Markdown"] +DIV["Div"] +SPAN["Span"] +FRAG["Fragment"] +EACH["Each"] +FILT["Filter"] +end +AL --> PRE +SLOT --> PRE +MD --> PRE +DIV --> PRE +SPAN --> PRE +FRAG --> PRE +EACH --> PRE +FILT --> PRE +DIV -.-> CLS +SPAN -.-> CLS +MD -.-> CLS +AL -.-> CLS +``` + +Diagram sources + +- [frontend/base/auto-loading/Index.svelte:1-10](file://frontend/base/auto-loading/Index.svelte#L1-L10) +- [frontend/base/slot/Index.svelte:1-8](file://frontend/base/slot/Index.svelte#L1-L8) +- [frontend/base/markdown/Index.svelte:1-8](file://frontend/base/markdown/Index.svelte#L1-L8) +- [frontend/base/div/Index.svelte:1-8](file://frontend/base/div/Index.svelte#L1-L8) +- [frontend/base/span/Index.svelte:1-7](file://frontend/base/span/Index.svelte#L1-L7) + +Section sources + +- [frontend/base/auto-loading/Index.svelte:1-10](file://frontend/base/auto-loading/Index.svelte#L1-L10) +- [frontend/base/slot/Index.svelte:1-8](file://frontend/base/slot/Index.svelte#L1-L8) +- [frontend/base/markdown/Index.svelte:1-8](file://frontend/base/markdown/Index.svelte#L1-L8) +- [frontend/base/div/Index.svelte:1-8](file://frontend/base/div/Index.svelte#L1-L8) +- [frontend/base/span/Index.svelte:1-7](file://frontend/base/span/Index.svelte#L1-L7) + +## Performance Considerations + +- Lazy loading + - Use `importComponent` and `{#await}` to load components only when needed, reducing the initial load. +- Visibility control + - Use the `visible` property to quickly show/hide without triggering unnecessary rendering and context updates. +- Slot keys and contexts + - Set slot keys and parameter mappings appropriately to avoid duplicate registration and invalid updates. +- Style passthrough + - Prefer `elem_classes` and `elem_style` to reduce frequent inline style changes. +- List rendering + - The Each component supports placeholder and force-clone strategies; choose as needed to balance performance and consistency. +- Loading state + - AutoLoading combines `generating` and `showError` states to avoid duplicate requests and flickering. + +## Troubleshooting Guide + +- Component not rendering + - Check if the `visible` property is `true`. + - Confirm that the `{#await}` import flow succeeded. +- Slot not taking effect + - Confirm that `Slot`'s `value` and `params_mapping` are correctly set. + - Check that the parent component has correctly registered the slot key. +- Each rendering abnormalities + - Check that `value` is an array and `context_value` is an object. + - For nested Each, confirm the index and slot key calculation logic. +- Markdown theme or resource path issues + - Confirm that `shared.root` and `theme` configurations are correct. +- AutoLoading state out of sync + - Check that `generating` and `showError` are consistent with the business state. + +Section sources + +- [frontend/base/each/Index.svelte:66-104](file://frontend/base/each/Index.svelte#L66-L104) +- [frontend/base/markdown/Index.svelte:47-63](file://frontend/base/markdown/Index.svelte#L47-L63) +- [frontend/base/auto-loading/Index.svelte:65-80](file://frontend/base/auto-loading/Index.svelte#L65-L80) +- [frontend/base/slot/Index.svelte:57-61](file://frontend/base/slot/Index.svelte#L57-L61) + +## Conclusion + +ModelScope Studio's base components achieve a highly cohesive, loosely coupled, and easily composable UI infrastructure through a unified preprocessing pipeline and context system. By following the property specifications, slot conventions, and performance recommendations in this document, stable runtime performance can be achieved while maintaining development efficiency. + +## Appendix + +- TypeScript type constraints and interface specifications + - `getProps
Package Info"] +C["@modelscope-studio/pro-chatbot
Package Info"] +M["@modelscope-studio/pro-monaco-editor
Package Info"] +U["@modelscope-studio/pro-multimodal-input
Package Info"] +W["@modelscope-studio/pro-web-sandbox
Package Info"] +end +subgraph "Svelte Bridge Layer" +CI["chatbot/Index.svelte"] +MI["monaco-editor/Index.svelte"] +UI["multimodal-input/Index.svelte"] +WI["web-sandbox/Index.svelte"] +end +subgraph "Runtime Shared Context" +G["gradio.shared.*
root/api_prefix/theme"] +end +P --> CI +P --> MI +P --> UI +P --> WI +C --> CI +M --> MI +U --> UI +W --> WI +CI --> G +MI --> G +UI --> G +WI --> G +``` + +Diagram sources + +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) +- [frontend/pro/chatbot/package.json:1-15](file://frontend/pro/chatbot/package.json#L1-L15) +- [frontend/pro/monaco-editor/package.json:1-15](file://frontend/pro/monaco-editor/package.json#L1-L15) +- [frontend/pro/multimodal-input/package.json:1-15](file://frontend/pro/multimodal-input/package.json#L1-L15) +- [frontend/pro/web-sandbox/package.json:1-15](file://frontend/pro/web-sandbox/package.json#L1-L15) +- [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) +- [frontend/pro/monaco-editor/Index.svelte:1-101](file://frontend/pro/monaco-editor/Index.svelte#L1-L101) +- [frontend/pro/multimodal-input/Index.svelte:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) +- [frontend/pro/web-sandbox/Index.svelte:1-76](file://frontend/pro/web-sandbox/Index.svelte#L1-L76) + +Section sources + +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) +- [frontend/pro/chatbot/package.json:1-15](file://frontend/pro/chatbot/package.json#L1-L15) +- [frontend/pro/monaco-editor/package.json:1-15](file://frontend/pro/monaco-editor/package.json#L1-L15) +- [frontend/pro/multimodal-input/package.json:1-15](file://frontend/pro/multimodal-input/package.json#L1-L15) +- [frontend/pro/web-sandbox/package.json:1-15](file://frontend/pro/web-sandbox/package.json#L1-L15) + +## Core Components + +This section provides an overview of the responsibilities and common capabilities of the four professional components: + +- **Chatbot**: Displays and interacts with conversational message streams. Supports composite content including text, tool calls, files, welcome messages, and suggested prompts. Features user/assistant actions (copy, edit, delete, like/dislike, retry) and theme adaptation. +- **MultimodalInput**: Multimodal input entry supporting text and file uploads, with upload hooks and event callbacks for easy integration with Gradio clients. +- **WebSandbox**: A compilable and renderable web sandbox providing compile error/success and render error events, with support for theme mode and slot extensions. +- **MonacoEditor**: A code editor based on Monaco, supporting initialization with local or CDN loaders, with value change events and theme mode. + +Section sources + +- [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) +- [frontend/pro/multimodal-input/Index.svelte:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) +- [frontend/pro/web-sandbox/Index.svelte:1-76](file://frontend/pro/web-sandbox/Index.svelte#L1-L76) +- [frontend/pro/monaco-editor/Index.svelte:1-101](file://frontend/pro/monaco-editor/Index.svelte#L1-L101) + +## Architecture Overview + +All four components adopt a unified bridging pattern: the Svelte layer handles property resolution, event writeback, dynamic imports, and slot rendering; the underlying TSX components carry the specific UI logic; the runtime shared context (`gradio.shared`) provides global configurations such as `root`, `api_prefix`, and `theme`. + +```mermaid +sequenceDiagram +participant App as "Application" +participant S as "Svelte Bridge Layer" +participant R as "React/TSX Component" +participant G as "Gradio Shared Context" +App->>S : Pass properties and slots +S->>G : Read root/api_prefix/theme +S->>R : Dynamic import and pass properties/events +R-->>S : Value change callback +S->>App : updateProps writes back value +S-->>App : Render slot content +``` + +Diagram sources + +- [frontend/pro/chatbot/Index.svelte:14-64](file://frontend/pro/chatbot/Index.svelte#L14-L64) +- [frontend/pro/monaco-editor/Index.svelte:14-89](file://frontend/pro/monaco-editor/Index.svelte#L14-L89) +- [frontend/pro/multimodal-input/Index.svelte:17-66](file://frontend/pro/multimodal-input/Index.svelte#L17-L66) +- [frontend/pro/web-sandbox/Index.svelte:14-57](file://frontend/pro/web-sandbox/Index.svelte#L14-L57) + +## Detailed Component Analysis + +### Chatbot Component API + +- Package exports and entry point + - Package name and export mapping follow the standard; the main entry points to `Index.svelte`. +- Property definitions + - `additional_props`: Additional property passthrough + - `as_item`: Element identifier + - `_internal`: Internal layout flag + - `value`: Message array, type see `ChatbotMessages` + - `suggestion_select` / `welcome_prompt_select`: Event callback alias mappings + - Visibility and style: `visible`, `elem_id`, `elem_classes`, `elem_style` + - Runtime shared: `gradio.shared.root`, `gradio.shared.api_prefix`, `gradio.shared.theme` +- Events and callbacks + - `onValueChange`: Value change writeback to parent component +- Slot system + - Supports `children` slot and `slots` mapping +- Data model and types + - `ChatbotMessages`, `ChatbotMessage`, `ChatbotMessageContentObject`, action types (`like`/`dislike`/`retry`/`copy`/`edit`/`delete`), etc. +- Advanced features + - Theme mode inherited from `gradio.shared.theme` + - Built-in composite display of welcome messages, suggested prompts, files/tools/text content +- Usage examples (paths) + - Basic usage and value binding: [frontend/pro/chatbot/Index.svelte:76-84](file://frontend/pro/chatbot/Index.svelte#L76-L84) + - Event writeback: [frontend/pro/chatbot/Index.svelte:76-80](file://frontend/pro/chatbot/Index.svelte#L76-L80) + - Type definition reference: [frontend/pro/chatbot/type.ts:160-197](file://frontend/pro/chatbot/type.ts#L160-L197) + +```mermaid +classDiagram +class ChatbotMessage { ++role ++content ++status ++meta ++key +} +class ChatbotMessages { +} +class ChatbotMessageContentObject { ++type ++content ++options +} +ChatbotMessages --> ChatbotMessage +ChatbotMessage --> ChatbotMessageContentObject +``` + +Diagram sources + +- [frontend/pro/chatbot/type.ts:137-158](file://frontend/pro/chatbot/type.ts#L137-L158) +- [frontend/pro/chatbot/type.ts:121-135](file://frontend/pro/chatbot/type.ts#L121-L135) + +Section sources + +- [frontend/pro/chatbot/package.json:1-15](file://frontend/pro/chatbot/package.json#L1-L15) +- [frontend/pro/chatbot/Index.svelte:14-64](file://frontend/pro/chatbot/Index.svelte#L14-L64) +- [frontend/pro/chatbot/Index.svelte:76-84](file://frontend/pro/chatbot/Index.svelte#L76-L84) +- [frontend/pro/chatbot/type.ts:160-197](file://frontend/pro/chatbot/type.ts#L160-L197) + +### MultimodalInput Component API + +- Package exports and entry point + - Package name and export mapping follow the standard; the main entry points to `Index.svelte`. +- Property definitions + - `additional_props`: Additional property passthrough + - `_internal`: Internal flag + - `value`: Multimodal input value, type from the underlying component + - `key_press` / `paste_file` / `key_down`: Event callback alias mappings + - Visibility and style: `visible`, `elem_id`, `elem_classes`, `elem_style` + - Runtime shared: `gradio.shared.theme` +- Events and callbacks + - `onValueChange`: Value change writeback +- Slot system + - Supports `children` slot and `slots` mapping +- File upload + - Upload hook: Uploads files via `gradio.shared.client.upload`, returns `FileData[]` +- Usage examples (paths) + - Value binding and event writeback: [frontend/pro/multimodal-input/Index.svelte:88-92](file://frontend/pro/multimodal-input/Index.svelte#L88-L92) + - Upload flow: [frontend/pro/multimodal-input/Index.svelte:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) + +```mermaid +sequenceDiagram +participant UI as "MultimodalInput" +participant GR as "Gradio Client" +participant SV as "Svelte Bridge Layer" +UI->>GR : upload(prepare_files(files)) +GR-->>UI : FileData[] +UI->>SV : updateProps({ value }) +``` + +Diagram sources + +- [frontend/pro/multimodal-input/Index.svelte:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) +- [frontend/pro/multimodal-input/Index.svelte:88-92](file://frontend/pro/multimodal-input/Index.svelte#L88-L92) + +Section sources + +- [frontend/pro/multimodal-input/package.json:1-15](file://frontend/pro/multimodal-input/package.json#L1-L15) +- [frontend/pro/multimodal-input/Index.svelte:17-66](file://frontend/pro/multimodal-input/Index.svelte#L17-L66) +- [frontend/pro/multimodal-input/Index.svelte:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) + +### WebSandbox Component API + +- Package exports and entry point + - Package name and export mapping follow the standard; the main entry points to `Index.svelte`. +- Property definitions + - `additional_props`: Additional property passthrough + - `_internal`: Internal flag + - `value`: Sandbox value, type from the underlying component + - `compile_error` / `compile_success` / `render_error`: Event callback alias mappings + - Visibility and style: `visible`, `elem_id`, `elem_classes`, `elem_style` + - Runtime shared: `gradio.shared.theme` +- Slot system + - Supports `children` slot and `slots` mapping +- Usage examples (paths) + - Value binding and theme: [frontend/pro/web-sandbox/Index.svelte:62-70](file://frontend/pro/web-sandbox/Index.svelte#L62-L70) + +```mermaid +flowchart TD +Start(["Start"]) --> CheckVisible["Check visible"] +CheckVisible --> |No| End(["End"]) +CheckVisible --> |Yes| Load["Dynamically load WebSandbox"] +Load --> Render["Render and pass value/slots/theme"] +Render --> End +``` + +Diagram sources + +- [frontend/pro/web-sandbox/Index.svelte:60-75](file://frontend/pro/web-sandbox/Index.svelte#L60-L75) + +Section sources + +- [frontend/pro/web-sandbox/package.json:1-15](file://frontend/pro/web-sandbox/package.json#L1-L15) +- [frontend/pro/web-sandbox/Index.svelte:14-57](file://frontend/pro/web-sandbox/Index.svelte#L14-L57) +- [frontend/pro/web-sandbox/Index.svelte:62-70](file://frontend/pro/web-sandbox/Index.svelte#L62-L70) + +### MonacoEditor Component API + +- Package exports and entry point + - Package name and export mapping follow the standard; the main entry points to `Index.svelte`. +- Property definitions + - `additional_props`: Additional property passthrough + - `_internal`: Internal flag + - `value`: Editor initial value + - `_loader`: Loader configuration + - `mode`: `'cdn'` | `'local'` + - `cdn_url`: CDN path + - Visibility and style: `visible`, `elem_id`, `elem_classes`, `elem_style` + - Runtime shared: `gradio.shared.theme` +- Events and callbacks + - `onValueChange`: Value change writeback +- Slot system + - Supports `children` slot and `slots` mapping +- Loader mechanism + - Local loading: Initializes Monaco and registers Workers by language + - CDN loading: Sets the `vs` path +- Usage examples (paths) + - Value binding and theme: [frontend/pro/monaco-editor/Index.svelte:79-89](file://frontend/pro/monaco-editor/Index.svelte#L79-L89) + - Loader selection and initialization: [frontend/pro/monaco-editor/Index.svelte:61-70](file://frontend/pro/monaco-editor/Index.svelte#L61-L70) + - Loader implementation: [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +```mermaid +flowchart TD +A["Select Loader"] --> B{"mode=local?"} +B --> |Yes| C["initLocalLoader()
Register Monaco and Workers"] +B --> |No| D{"cdn_url present?"} +D --> |Yes| E["initCDNLoader(cdn_url)
Set vs path"] +D --> |No| F["Use default configuration"] +C --> G["Done"] +E --> G +F --> G +``` + +Diagram sources + +- [frontend/pro/monaco-editor/Index.svelte:61-70](file://frontend/pro/monaco-editor/Index.svelte#L61-L70) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +Section sources + +- [frontend/pro/monaco-editor/package.json:1-15](file://frontend/pro/monaco-editor/package.json#L1-L15) +- [frontend/pro/monaco-editor/Index.svelte:14-89](file://frontend/pro/monaco-editor/Index.svelte#L14-L89) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +## Dependency Analysis + +- Unified dependency chain + - The Svelte bridge layer depends on `getProps`/`processProps`/`importComponent` and slot utilities from `@svelte-preprocess-react` + - Each component obtains shared configuration (`root`, `api_prefix`, `theme`) through `gradio.shared` + - File upload capability comes from `prepare_files` and `client.upload` of `@gradio/client` +- Inter-component coupling + - Low coupling: Each component independently maintains its own properties and events + - High cohesion: The bridge layer handles property processing and dynamic loading; underlying components focus on UI logic + +```mermaid +graph LR +SP["@svelte-preprocess-react/*"] --> BR["Svelte Bridge Layer"] +BR --> CH["Chatbot"] +BR --> ME["MonacoEditor"] +BR --> MU["MultimodalInput"] +BR --> WS["WebSandbox"] +GC["@gradio/client"] --> MU +GS["gradio.shared.*"] --> BR +``` + +Diagram sources + +- [frontend/pro/chatbot/Index.svelte:1-12](file://frontend/pro/chatbot/Index.svelte#L1-L12) +- [frontend/pro/monaco-editor/Index.svelte:1-12](file://frontend/pro/monaco-editor/Index.svelte#L1-L12) +- [frontend/pro/multimodal-input/Index.svelte:1-9](file://frontend/pro/multimodal-input/Index.svelte#L1-L9) +- [frontend/pro/web-sandbox/Index.svelte:1-8](file://frontend/pro/web-sandbox/Index.svelte#L1-L8) + +Section sources + +- [frontend/pro/chatbot/Index.svelte:1-12](file://frontend/pro/chatbot/Index.svelte#L1-L12) +- [frontend/pro/monaco-editor/Index.svelte:1-12](file://frontend/pro/monaco-editor/Index.svelte#L1-L12) +- [frontend/pro/multimodal-input/Index.svelte:1-9](file://frontend/pro/multimodal-input/Index.svelte#L1-L9) +- [frontend/pro/web-sandbox/Index.svelte:1-8](file://frontend/pro/web-sandbox/Index.svelte#L1-L8) + +## Performance Considerations + +- Dynamic imports and lazy loading + - Use `importComponent` to dynamically import underlying components to avoid blocking the initial render +- Computed properties and derived values + - Use `$derived` to reuse derived computations and reduce unnecessary re-renders +- Loader strategy + - MonacoEditor supports both local and CDN loaders; choose as needed to balance bundle size and network overhead +- Event writeback + - Trigger `updateProps` only when values change to avoid frequent writebacks +- File upload + - Use `prepare_files` and the Gradio client for uploads to reduce manual serialization costs + +## Troubleshooting Guide + +- Editor not loading + - Check that `_loader.mode` and `cdn_url` configurations are correct + - Confirm that `initCDNLoader`/`initLocalLoader` has completed initialization + - Reference: [frontend/pro/monaco-editor/Index.svelte:61-70](file://frontend/pro/monaco-editor/Index.svelte#L61-L70), [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- Upload failing + - Confirm that `gradio.shared.client` is available and `root` is correct + - Check `prepare_files` and the returned `FileData[]` + - Reference: [frontend/pro/multimodal-input/Index.svelte:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) +- Theme not applied + - Confirm that `gradio.shared.theme` is set to `light`/`dark` + - Reference: [frontend/pro/chatbot/Index.svelte:83](file://frontend/pro/chatbot/Index.svelte#L83), [frontend/pro/web-sandbox/Index.svelte:70](file://frontend/pro/web-sandbox/Index.svelte#L70), [frontend/pro/monaco-editor/Index.svelte:88](file://frontend/pro/monaco-editor/Index.svelte#L88) + +Section sources + +- [frontend/pro/monaco-editor/Index.svelte:61-70](file://frontend/pro/monaco-editor/Index.svelte#L61-L70) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/multimodal-input/Index.svelte:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) +- [frontend/pro/chatbot/Index.svelte:83](file://frontend/pro/chatbot/Index.svelte#L83) +- [frontend/pro/web-sandbox/Index.svelte:70](file://frontend/pro/web-sandbox/Index.svelte#L70) +- [frontend/pro/monaco-editor/Index.svelte:88](file://frontend/pro/monaco-editor/Index.svelte#L88) + +## Conclusion + +This reference document systematically covers the API and implementation details of ModelScope Studio's Pro Svelte components, emphasizing the unified pattern of the bridge layer, the use of the runtime shared context, and deep integration with the Gradio ecosystem. Through well-designed properties, event writeback, and dynamic loading strategies, these components efficiently support core AI application scenarios such as conversation, code editing, multimodal input, and sandbox rendering. + +## Appendix + +- TypeScript types and interfaces + - Chatbot types: [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- Package exports and entry points + - Chatbot: [frontend/pro/chatbot/package.json:1-15](file://frontend/pro/chatbot/package.json#L1-L15) + - MonacoEditor: [frontend/pro/monaco-editor/package.json:1-15](file://frontend/pro/monaco-editor/package.json#L1-L15) + - MultimodalInput: [frontend/pro/multimodal-input/package.json:1-15](file://frontend/pro/multimodal-input/package.json#L1-L15) + - WebSandbox: [frontend/pro/web-sandbox/package.json:1-15](file://frontend/pro/web-sandbox/package.json#L1-L15) +- Component bridge implementations + - Chatbot: [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) + - MonacoEditor: [frontend/pro/monaco-editor/Index.svelte:1-101](file://frontend/pro/monaco-editor/Index.svelte#L1-L101) + - MultimodalInput: [frontend/pro/multimodal-input/Index.svelte:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) + - WebSandbox: [frontend/pro/web-sandbox/Index.svelte:1-76](file://frontend/pro/web-sandbox/Index.svelte#L1-L76) diff --git a/.wiki/en/API Reference/JavaScript API/Svelte Component API/Svelte Components API.md b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Svelte Components API.md new file mode 100644 index 00000000..9784d1f0 --- /dev/null +++ b/.wiki/en/API Reference/JavaScript API/Svelte Component API/Svelte Components API.md @@ -0,0 +1,415 @@ +# Svelte Components API + + +**Files referenced in this document** +- [frontend/package.json](file://frontend/package.json) +- [frontend/tsconfig.json](file://frontend/tsconfig.json) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/form/Index.svelte](file://frontend/antd/form/Index.svelte) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/layout/Index.svelte](file://frontend/antd/layout/Index.svelte) +- [frontend/antd/modal/Index.svelte](file://frontend/antd/modal/Index.svelte) +- [frontend/antd/table/Index.svelte](file://frontend/antd/table/Index.svelte) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/createFunction.ts](file://frontend/utils/createFunction.ts) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance and Best Practices](#performance-and-best-practices) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the API reference for ModelScope Studio frontend Svelte components, focusing on the Svelte component encapsulation system based on the Ant Design (Antd) ecosystem. The document covers: + +- Component property definitions: props interfaces, default values, and type constraints +- Event system: user interaction events, state change events, and custom events +- Slot system: usage of default slots, named slots, and scoped slots +- Lifecycle and rendering: component instantiation, async loading, and conditional rendering +- Inter-component communication: parent-child, sibling, and cross-level communication patterns +- Style customization: CSS class names, theme variables, and inline styles +- TypeScript types: interface specifications, generic usage, and type inference +- Performance optimization: on-demand loading, derived computation, and event throttling recommendations + +## Project Structure + +The frontend uses a multi-package organization, with core components in `frontend/antd` and `frontend/antdx`, implementing Antd components in Svelte through the Svelte 5 and React component bridging solution. + +```mermaid +graph TB +subgraph "Frontend Packages" +A["frontend/package.json"] +B["frontend/tsconfig.json"] +end +subgraph "Antd Component Layer" +BTN["antd/button/Index.svelte"] +BTN_TS["antd/button/button.tsx"] +FORM["antd/form/Index.svelte"] +FORM_TS["antd/form/form.tsx"] +LYT["antd/layout/Index.svelte"] +MODAL["antd/modal/Index.svelte"] +TAB["antd/table/Index.svelte"] +end +subgraph "Common Utilities" +RS["utils/renderSlot.tsx"] +CF["utils/createFunction.ts"] +end +A --> BTN +A --> FORM +A --> LYT +A --> MODAL +A --> TAB +BTN --> BTN_TS +FORM --> FORM_TS +BTN_TS --> RS +FORM_TS --> RS +BTN_TS --> CF +FORM_TS --> CF +``` + +**Diagram sources** + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/modal/Index.svelte:1-63](file://frontend/antd/modal/Index.svelte#L1-L63) +- [frontend/antd/table/Index.svelte:1-61](file://frontend/antd/table/Index.svelte#L1-L61) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) + +**Section sources** + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) + +## Core Components + +This section provides an overview of the responsibilities and common characteristics of the main components: + +- **Button**: Wraps Antd Button, supports icon and loading state slots, with visibility control and class name concatenation. +- **Form**: Wraps Antd Form, provides value synchronization, action triggers (reset/submit/validate), required mark, and feedback icon slots. +- **Layout**: Basic layout container that passes through children and component identifiers. +- **Modal**: Wraps Antd Modal, supports visibility control and slots. +- **Table**: Wraps Antd Table, supports visibility control and slots. + +**Section sources** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/modal/Index.svelte:1-63](file://frontend/antd/modal/Index.svelte#L1-L63) +- [frontend/antd/table/Index.svelte:1-61](file://frontend/antd/table/Index.svelte#L1-L61) + +## Architecture Overview + +Components adopt a three-layer architecture of "Svelte layer + React wrapping layer + utility functions": + +- Svelte layer: Responsible for property collection, slot resolution, conditional rendering, and async loading. +- React wrapping layer: Uses `sveltify` to bridge Antd components for use in Svelte, handling slots and callbacks. +- Utility functions: Provides slot rendering, function-string-to-function conversion, and other capabilities. + +```mermaid +sequenceDiagram +participant Svelte as "Svelte Component Layer (Index.svelte)" +participant Utils as "Utilities (renderSlot.tsx/createFunction.ts)" +participant ReactComp as "React Wrapping Layer (button.tsx/form.tsx)" +participant Antd as "Antd Component" +Svelte->>Svelte : Collect props and slots +Svelte->>ReactComp : Async import and pass props +ReactComp->>Utils : Render slots / wrap functions +ReactComp->>Antd : Render Antd component +Antd-->>ReactComp : Callback events +ReactComp-->>Svelte : Trigger update/action +``` + +**Diagram sources** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) + +## Component Details + +### Button + +- Responsibility: Exposes Antd Button as a Svelte component, supports icon and loading state slots; conditionally renders based on visibility; concatenates style class names. +- Key props + - `additional_props?: Record
omitUndefinedProps"] +P2["patchProps/applyPatchToProps"] +P3["renderSlot/renderItems/patchSlots"] +P4["style.ts computation"] +P5["upload.ts resolution"] +P6["walkHtmlNodes traversal"] +P7["createFunction / function factory"] +end +subgraph "Output Layer" +OUT1["React Component Tree"] +OUT2["Inline Style String / Object"] +OUT3["Accessible File URL"] +end +IN1 --> P1 --> P2 --> P3 --> OUT1 +IN2 --> P3 --> OUT1 +IN2 --> P6 --> OUT1 +IN3 --> P5 --> OUT3 +IN1 --> P4 --> OUT2 +IN1 --> P7 --> P3 +``` + +Diagram sources + +- [convertToCamelCase.ts:1-22](file://frontend/utils/convertToCamelCase.ts#L1-L22) +- [patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [omitUndefinedProps.ts:1-17](file://frontend/utils/omitUndefinedProps.ts#L1-L17) +- [renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [style.ts:1-77](file://frontend/utils/style.ts#L1-L77) +- [upload.ts:1-45](file://frontend/utils/upload.ts#L1-L45) +- [walkHtmlNodes.ts:1-19](file://frontend/utils/walkHtmlNodes.ts#L1-L19) +- [createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) + +## Detailed Component Analysis + +### Property Handling Functions + +#### convertToCamelCase and convertObjectKeyToCamelCase + +- Functionality: Converts underscore-style naming to camelCase; batch converts object key names +- Parameters and return values: + - `convertToCamelCase(str: string): string` + - `convertObjectKeyToCamelCase
ModelScopeLayoutComponent
ModelScopeDataLayoutComponent"] +B["AntdButton"] +C["AntdForm / AntdFormItem"] +D["AntdTable / AntdTableColumn"] +E["AntdInput / AntdSelect"] +F["AntdLayout / AntdMenu / AntdModal"] +G["AntdMessage / AntdNotification"] +H["AntdCard / AntdBreadcrumb"] +end +subgraph "Frontend Layer (Svelte)" +P["button/*"] +Q["form/*"] +R["table/*"] +S["input/*"] +T["select/*"] +U["layout/*"] +V["menu/*"] +W["modal/*"] +X["message/*"] +Y["notification/*"] +Z["card/*"] +AA["breadcrumb/*"] +end +A --> B +A --> C +A --> D +A --> E +A --> F +A --> G +A --> H +B --> P +C --> Q +D --> R +E --> S +E --> T +F --> U +F --> V +F --> W +G --> X +G --> Y +H --> Z +H --> AA +``` + +Diagram sources + +- [backend/modelscope_studio/utils/dev/component.py:54-169](file://backend/modelscope_studio/utils/dev/component.py#L54-L169) +- [backend/modelscope_studio/components/antd/button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) +- [backend/modelscope_studio/components/antd/table/**init**.py:16-153](file://backend/modelscope_studio/components/antd/table/__init__.py#L16-L153) +- [backend/modelscope_studio/components/antd/input/**init**.py:16-127](file://backend/modelscope_studio/components/antd/input/__init__.py#L16-L127) +- [backend/modelscope_studio/components/antd/select/**init**.py:12-231](file://backend/modelscope_studio/components/antd/select/__init__.py#L12-L231) +- [backend/modelscope_studio/components/antd/layout/**init**.py:14-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L14-L91) +- [backend/modelscope_studio/components/antd/menu/**init**.py:12-123](file://backend/modelscope_studio/components/antd/menu/__init__.py#L12-L123) +- [backend/modelscope_studio/components/antd/modal/**init**.py:11-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L11-L136) +- [backend/modelscope_studio/components/antd/message/**init**.py:10-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L10-L91) +- [backend/modelscope_studio/components/antd/notification/**init**.py:10-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L10-L109) +- [backend/modelscope_studio/components/antd/card/**init**.py:12-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L12-L149) +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:9-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L9-L73) + +Section sources + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) + +## Core Components + +- Base component classes + - `ModelScopeComponent`: General component base class; supports Gradio properties such as `value`, `visible`, `elem_*`, `key`, `inputs`, `load_fn`, `render`; provides `skip_api` to control API exposure. + - `ModelScopeLayoutComponent`: Layout component base class; supports `__enter__`/`__exit__` context management for nested layouts. + - `ModelScopeDataLayoutComponent`: Data-layout component base class; combines data component capabilities with layout capabilities. +- Events and slots + - `EVENTS`: List of events supported by the component; binds callbacks via `EventListener`. + - `SLOTS`: Set of slot names supported by the component; used for rendering child content or custom nodes. +- Frontend directory resolution + - `FRONTEND_DIR`: Points to the corresponding Svelte component directory via `resolve_frontend_dir(...)`. + +Section sources + +- [backend/modelscope_studio/utils/dev/component.py:54-169](file://backend/modelscope_studio/utils/dev/component.py#L54-L169) +- [backend/modelscope_studio/components/antd/button/**init**.py:41-49](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L49) +- [backend/modelscope_studio/components/antd/table/**init**.py:32-53](file://backend/modelscope_studio/components/antd/table/__init__.py#L32-L53) +- [backend/modelscope_studio/components/antd/input/**init**.py:25-41](file://backend/modelscope_studio/components/antd/input/__init__.py#L25-L41) + +## Architecture Overview + +The following sequence diagram shows a typical component's call chain from construction to event binding: + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Py as "Antd Component Class" +participant Base as "ModelScopeComponent/ModelScopeLayoutComponent" +participant FE as "Svelte Frontend Component" +Dev->>Py : Instantiate component (pass parameters) +Py->>Base : Call parent __init__(visible, elem_*, render, ...) +Base->>Base : Initialize internal state (_internal, as_item, elem_style) +Py->>FE : Set FRONTEND_DIR and pass props +Py->>Py : Configure EVENTS/SLOTS +Dev->>Py : Bind event listeners (EventListener) +Py->>FE : Bind frontend event callbacks via internal markers +FE-->>Py : Trigger event callbacks +Py-->>Dev : Return processed value/payload +``` + +Diagram sources + +- [backend/modelscope_studio/utils/dev/component.py:54-99](file://backend/modelscope_studio/utils/dev/component.py#L54-L99) +- [backend/modelscope_studio/components/antd/button/**init**.py:51-87](file://backend/modelscope_studio/components/antd/button/__init__.py#L51-L87) +- [backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) + +## Detailed Component Analysis + +### Button + +- Import path: `modelscope_studio.components.antd.AntdButton` or `modelscope_studio.components.antd.Button` +- Sub-components: `Group` +- Events: `click` +- Slots: `icon`, `loading.icon` +- Key parameters (selected): `value`, `block`, `danger`, `ghost`, `disabled`, `href`, `html_type`, `icon`, `icon_position`, `loading`, `shape`, `size`, `type`, `variant`, `color`, `root_class_name` +- Methods: `preprocess`/`postprocess`/`example_payload`/`example_value` +- Code snippet path (example) + - [basic usage:51-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L51-L157) +- Event binding flow + - Maps callbacks to frontend events via `EventListener("click", ...)` in `EVENTS`. +- Data binding + - When used as input/output, `value` type is string; `preprocess`/`postprocess` returns string. +- Parameter validation and exceptions + - Most parameters are nullable scalars or literal enums; no explicit validation logic seen — validation is recommended at the application layer. +- Inter-component communication + - Interacts with forms or other components via Gradio's `inputs`/`outputs` mechanism. + +Section sources + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) + +### Form and Form.Item + +- Import path: `modelscope_studio.components.antd.AntdForm` / `AntdFormItem` +- Sub-components: `Item`, `Provider` +- Events: `fields_change`, `finish`, `finish_failed`, `values_change` +- Slots: `requiredMark` +- Form key parameters (selected): `colon`, `disabled`, `component`, `feedback_icons`, `initial_values`, `label_align`, `label_col`, `label_wrap`, `layout`, `preserve`, `required_mark`, `scroll_to_first_error`, `size`, `validate_messages`, `validate_trigger`, `variant`, `wrapper_col`, `clear_on_destroy`, `root_class_name`, `class_names`, `styles` +- FormItem key parameters (selected): `label`, `form_name`, `colon`, `dependencies`, `extra`, `help`, `hidden`, `initial_value`, `label_align`, `label_col`, `message_variants`, `normalize`, `no_style`, `preserve`, `required`, `rules`, `should_update`, `tooltip`, `trigger`, `validate_debounce`, `validate_first`, `validate_status`, `validate_trigger`, `value_prop_name`, `wrapper_col`, `layout`, `root_class_name` +- Methods: `preprocess`/`postprocess`/`example_payload`/`example_value` +- Code snippet paths (example) + - [form:43-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L43-L133) + - [form item:21-126](file://backend/modelscope_studio/components/antd/form/item/__init__.py#L21-L126) + +Section sources + +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) +- [backend/modelscope_studio/components/antd/form/item/**init**.py:9-126](file://backend/modelscope_studio/components/antd/form/item/__init__.py#L9-L126) + +### Table and Table.Column + +- Import path: `modelscope_studio.components.antd.AntdTable` / `AntdTableColumn` +- Sub-components: `Column`, `ColumnGroup`, `Expandable`, `RowSelection` +- Events: `change`, `scroll` +- Slots: `footer`, `title`, `summary`, `expandable`, `rowSelection`, `loading.tip`, `loading.indicator`, `pagination.showQuickJumper.goButton`, `pagination.itemRender`, `showSorterTooltip.title` +- Table key parameters (selected): `data_source`, `columns`, `bordered`, `components`, `expandable`, `footer`, `get_popup_container`, `loading`, `locale`, `pagination`, `row_class_name`, `row_key`, `row_selection`, `row_hoverable`, `scroll`, `show_header`, `show_sorter_tooltip`, `size`, `sort_directions`, `sticky`, `summary`, `table_layout`, `title`, `virtual`, `on_row`, `on_header_row`, `root_class_name`, `class_names`, `styles` +- Table.Column key parameters (selected): `built_in_column`, `align`, `col_span`, `data_index`, `default_filtered_value`, `filter_reset_to_default_filtered_value`, `default_sort_order`, `ellipsis`, `filter_dropdown`, `filter_dropdown_open`, `filtered`, `filtered_value`, `filter_icon`, `filter_on_close`, `filter_multiple`, `filter_mode`, `filter_search`, `filters`, `filter_dropdown_props`, `fixed`, `key`, `column_render`, `responsive`, `row_scope`, `should_cell_update`, `show_sorter_tooltip`, `sorter`, `sort_order`, `sort_icon`, `title`, `width`, `min_width`, `hidden`, `on_cell`, `on_header_cell`, `class_names`, `styles` +- Methods: `preprocess`/`postprocess`/`example_payload`/`example_value` +- Code snippet paths (example) + - [table:55-153](file://backend/modelscope_studio/components/antd/table/__init__.py#L55-L153) + - [table.column:33-150](file://backend/modelscope_studio/components/antd/table/column/__init__.py#L33-L150) + +Section sources + +- [backend/modelscope_studio/components/antd/table/**init**.py:16-153](file://backend/modelscope_studio/components/antd/table/__init__.py#L16-L153) +- [backend/modelscope_studio/components/antd/table/column/**init**.py:10-150](file://backend/modelscope_studio/components/antd/table/column/__init__.py#L10-L150) + +### Input and Select + +- Import path: `modelscope_studio.components.antd.AntdInput` / `AntdSelect` +- Sub-components: `Textarea`, `Password`, `OTP`, `Search` (Input); `Option` (Select) +- Input events: `change`, `press_enter`, `clear` +- Select events: `change`, `blur`, `focus`, `search`, `select`, `clear`, `popup_scroll`, `dropdown_visible_change`, `popup_visible_change`, `active` +- Slots (Input): `addonAfter`, `addonBefore`, `allowClear.clearIcon`, `prefix`, `suffix`, `showCount.formatter` +- Slots (Select): `allowClear.clearIcon`, `maxTagPlaceholder`, `menuItemSelectedIcon`, `dropdownRender`, `popupRender`, `optionRender`, `tagRender`, `labelRender`, `notFoundContent`, `removeIcon`, `suffixIcon`, `prefix`, `options` +- Input key parameters (selected): `addon_after`, `addon_before`, `allow_clear`, `count`, `default_value`, `read_only`, `disabled`, `max_length`, `prefix`, `show_count`, `size`, `status`, `suffix`, `type`, `placeholder`, `variant`, `root_class_name`, `class_names`, `styles` +- Select key parameters (selected): `allow_clear`, `auto_clear_search_value`, `auto_focus`, `default_active_first_option`, `default_open`, `default_value`, `disabled`, `popup_class_name`, `popup_match_select_width`, `dropdown_render`, `popup_render`, `dropdown_style`, `field_names`, `filter_option`, `filter_sort`, `get_popup_container`, `label_in_value`, `list_height`, `loading`, `max_count`, `max_tag_count`, `max_tag_placeholder`, `max_tag_text_length`, `menu_item_selected_icon`, `mode`, `not_found_content`, `open`, `option_filter_prop`, `option_label_prop`, `options`, `option_render`, `placeholder`, `placement`, `remove_icon`, `search_value`, `show_search`, `size`, `status`, `suffix_icon`, `prefix`, `tag_render`, `label_render`, `token_separators`, `variant`, `virtual`, `class_names`, `styles`, `root_class_name` +- Methods: `preprocess`/`postprocess`/`example_payload`/`example_value` +- Code snippet paths (example) + - [input:43-127](file://backend/modelscope_studio/components/antd/input/__init__.py#L43-L127) + - [select:59-231](file://backend/modelscope_studio/components/antd/select/__init__.py#L59-L231) + +Section sources + +- [backend/modelscope_studio/components/antd/input/**init**.py:16-127](file://backend/modelscope_studio/components/antd/input/__init__.py#L16-L127) +- [backend/modelscope_studio/components/antd/select/**init**.py:12-231](file://backend/modelscope_studio/components/antd/select/__init__.py#L12-L231) + +### Layout, Menu, and Modal + +- Import path: `modelscope_studio.components.antd.AntdLayout` / `AntdMenu` / `AntdModal` +- Sub-components: `Layout.Content`/`Footer`/`Header`/`Sider` (Layout); `Menu.Item` (Menu); `Modal.Static` (Modal) +- Events (Layout/Menu/Modal): `click`, `deselect`, `open_change`, `select`, `ok`, `cancel`, etc. +- Slots (Layout/Menu/Modal): See individual component definitions +- Code snippet paths (example) + - [layout:39-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L39-L91) + - [menu:36-123](file://backend/modelscope_studio/components/antd/menu/__init__.py#L36-L123) + - [modal:34-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L34-L136) + +Section sources + +- [backend/modelscope_studio/components/antd/layout/**init**.py:14-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L14-L91) +- [backend/modelscope_studio/components/antd/menu/**init**.py:12-123](file://backend/modelscope_studio/components/antd/menu/__init__.py#L12-L123) +- [backend/modelscope_studio/components/antd/modal/**init**.py:11-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L11-L136) + +### Message, Notification, Card, and Breadcrumb + +- Import path: `modelscope_studio.components.antd.AntdMessage` / `AntdNotification` / `AntdCard` / `AntdBreadcrumb` +- Events: `click`, `close` (some components) +- Slots: `icon`/`content` (Message); `actions`/`closeIcon`/`description`/`icon`/`message`/`title` (Notification); `title`/`tabList`/`tabProps.*` (Card); `separator`/`itemRender`/`items`/`dropdownIcon` (Breadcrumb) +- Code snippet paths (example) + - [message:26-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L26-L91) + - [notification:26-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L26-L109) + - [card:56-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L56-L149) + - [breadcrumb:20-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L20-L73) + +Section sources + +- [backend/modelscope_studio/components/antd/message/**init**.py:10-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L10-L91) +- [backend/modelscope_studio/components/antd/notification/**init**.py:10-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L10-L109) +- [backend/modelscope_studio/components/antd/card/**init**.py:12-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L12-L149) +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:9-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L9-L73) + +## Dependency Analysis + +- Component exports + - `modelscope_studio.components.antd.__init__` and `components.py` synchronize exports of all Antd component classes for unified imports. +- Base class dependencies + - All components depend on base component classes in `modelscope_studio.utils.dev.component`, ensuring a unified lifecycle, event, and slot mechanism. +- Frontend dependencies + - Each component points to its corresponding Svelte component directory via `FRONTEND_DIR`, maintaining consistent directory structures between frontend and backend. + +```mermaid +graph LR +A["antd/__init__.py"] --> B["Button/Form/Table/Input/Select/Layout/..."] +C["antd/components.py"] --> B +D["utils/dev/component.py"] --> B +B --> E["Svelte Frontend Components"] +``` + +Diagram sources + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [backend/modelscope_studio/utils/dev/component.py:54-169](file://backend/modelscope_studio/utils/dev/component.py#L54-L169) + +Section sources + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [backend/modelscope_studio/utils/dev/component.py:54-169](file://backend/modelscope_studio/utils/dev/component.py#L54-L169) + +## Performance Considerations + +- Event binding + - Maps Python callbacks to frontend events via `EVENTS`, avoiding unnecessary re-renders; set event trigger frequency and debouncing appropriately. +- Slots and virtualization + - Components such as Table support `virtual`, `sticky`, `scroll`, and similar parameters; it is recommended to enable virtual scrolling and fixed headers in large data scenarios to improve performance. +- Render control + - Use `render` and `visible` to control component initial rendering and visibility, reducing first-screen pressure. +- Data flow + - Input components (e.g., Input, Select) are recommended to work with Form for batch validation and debouncing, reducing overhead from frequent updates. + +## Troubleshooting Guide + +- Events not triggering + - Check that `EVENTS` is correctly declared; confirm that `EventListener` names match frontend events. + - Confirm that the component has `FRONTEND_DIR` set correctly and frontend event callbacks are bound. +- Slots not working + - Verify that the corresponding slot name exists in the `SLOTS` list; ensure the slot content passed matches the expected format. +- Data type mismatch + - The return types of `preprocess`/`postprocess` for input components must match component definitions; if type errors occur, check `value` and the return type from `api_info`. +- Form validation failure + - Check FormItem's `rules`, `validate_trigger`, `validate_status`, and other configurations; adjust `validate_first` and `validate_debounce` as needed. +- Layout flickering or style anomalies + - Layout components (e.g., Layout, Menu) can optimize SSR-scenario style flickering via parameters such as `has_sider`, `inline_collapsed`, and `theme_value`. + +Section sources + +- [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) +- [backend/modelscope_studio/components/antd/form/item/**init**.py:13-19](file://backend/modelscope_studio/components/antd/form/item/__init__.py#L13-L19) +- [backend/modelscope_studio/components/antd/table/**init**.py:32-53](file://backend/modelscope_studio/components/antd/table/__init__.py#L32-L53) +- [backend/modelscope_studio/components/antd/menu/**init**.py:96-103](file://backend/modelscope_studio/components/antd/menu/__init__.py#L96-L103) +- [backend/modelscope_studio/components/antd/layout/**init**.py:33-37](file://backend/modelscope_studio/components/antd/layout/__init__.py#L33-L37) + +## Conclusion + +This reference document systematically covers the Python API of the Antd component library, clearly defining import paths, constructor parameters, events and slots, data binding, and state management interfaces for component classes. It is recommended to use example paths to quickly locate implementation details in actual development, and to optimize component usage experience according to the performance and troubleshooting guidelines. + +## Appendix: API Index by Category + +- General Components + - `Button`, `Message`, `Notification`, `Card`, `Breadcrumb` + - Example paths: [button:51-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L51-L157), [message:26-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L26-L91), [notification:26-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L26-L109), [card:56-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L56-L149), [breadcrumb:20-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L20-L73) +- Layout Components + - `Layout` (including `Content`/`Footer`/`Header`/`Sider`), `Menu` (including `Item`) + - Example paths: [layout:39-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L39-L91), [menu:36-123](file://backend/modelscope_studio/components/antd/menu/__init__.py#L36-L123) +- Navigation Components + - `Breadcrumb` (including `Item`) + - Example paths: [breadcrumb:20-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L20-L73) +- Data Entry Components + - `Input` (including `Textarea`/`Password`/`OTP`/`Search`), `Select` (including `Option`) + - Example paths: [input:43-127](file://backend/modelscope_studio/components/antd/input/__init__.py#L43-L127), [select:59-231](file://backend/modelscope_studio/components/antd/select/__init__.py#L59-L231) +- Data Display Components + - `Table` (including `Column`/`ColumnGroup`/`Expandable`/`RowSelection`) + - Example paths: [table:55-153](file://backend/modelscope_studio/components/antd/table/__init__.py#L55-L153), [table.column:33-150](file://backend/modelscope_studio/components/antd/table/column/__init__.py#L33-L150) +- Feedback Components + - `Modal` (including `Static`), `Message`, `Notification` + - Example paths: [modal:34-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L34-L136), [message:26-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L26-L91), [notification:26-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L26-L109) +- Form Components + - `Form` (including `Item`/`Provider`) + - Example paths: [form:43-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L43-L133), [form.item:21-126](file://backend/modelscope_studio/components/antd/form/item/__init__.py#L21-L126) diff --git a/.wiki/en/API Reference/Python API/Antd Components API/Data Display Components API.md b/.wiki/en/API Reference/Python API/Antd Components API/Data Display Components API.md new file mode 100644 index 00000000..7a2033ee --- /dev/null +++ b/.wiki/en/API Reference/Python API/Antd Components API/Data Display Components API.md @@ -0,0 +1,661 @@ +# Data Display Components API + + +**Files referenced in this document** +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antd/avatar/__init__.py](file://backend/modelscope_studio/components/antd/avatar/__init__.py) +- [backend/modelscope_studio/components/antd/badge/__init__.py](file://backend/modelscope_studio/components/antd/badge/__init__.py) +- [backend/modelscope_studio/components/antd/calendar/__init__.py](file://backend/modelscope_studio/components/antd/calendar/__init__.py) +- [backend/modelscope_studio/components/antd/card/__init__.py](file://backend/modelscope_studio/components/antd/card/__init__.py) +- [backend/modelscope_studio/components/antd/carousel/__init__.py](file://backend/modelscope_studio/components/antd/carousel/__init__.py) +- [backend/modelscope_studio/components/antd/collapse/__init__.py](file://backend/modelscope_studio/components/antd/collapse/__init__.py) +- [backend/modelscope_studio/components/antd/descriptions/__init__.py](file://backend/modelscope_studio/components/antd/descriptions/__init__.py) +- [backend/modelscope_studio/components/antd/empty/__init__.py](file://backend/modelscope_studio/components/antd/empty/__init__.py) +- [backend/modelscope_studio/components/antd/image/__init__.py](file://backend/modelscope_studio/components/antd/image/__init__.py) +- [backend/modelscope_studio/components/antd/list/__init__.py](file://backend/modelscope_studio/components/antd/list/__init__.py) +- [backend/modelscope_studio/components/antd/popover/__init__.py](file://backend/modelscope_studio/components/antd/popover/__init__.py) +- [backend/modelscope_studio/components/antd/qr_code/__init__.py](file://backend/modelscope_studio/components/antd/qr_code/__init__.py) +- [backend/modelscope_studio/components/antd/segmented/__init__.py](file://backend/modelscope_studio/components/antd/segmented/__init__.py) +- [backend/modelscope_studio/components/antd/statistic/__init__.py](file://backend/modelscope_studio/components/antd/statistic/__init__.py) +- [backend/modelscope_studio/components/antd/table/__init__.py](file://backend/modelscope_studio/components/antd/table/__init__.py) +- [backend/modelscope_studio/components/antd/tabs/__init__.py](file://backend/modelscope_studio/components/antd/tabs/__init__.py) +- [backend/modelscope_studio/components/antd/tag/__init__.py](file://backend/modelscope_studio/components/antd/tag/__init__.py) +- [backend/modelscope_studio/components/antd/tag/checkable_tag/__init__.py](file://backend/modelscope_studio/components/antd/tag/checkable_tag/__init__.py) +- [backend/modelscope_studio/components/antd/tag/checkable_tag_group/__init__.py](file://backend/modelscope_studio/components/antd/tag/checkable_tag_group/__init__.py) +- [backend/modelscope_studio/components/antd/timeline/__init__.py](file://backend/modelscope_studio/components/antd/timeline/__init__.py) +- [backend/modelscope_studio/components/antd/tooltip/__init__.py](file://backend/modelscope_studio/components/antd/tooltip/__init__.py) +- [backend/modelscope_studio/components/antd/tour/__init__.py](file://backend/modelscope_studio/components/antd/tour/__init__.py) +- [backend/modelscope_studio/components/antd/tree/__init__.py](file://backend/modelscope_studio/components/antd/tree/__init__.py) +- [frontend/antd/timeline/timeline.tsx](file://frontend/antd/timeline/timeline.tsx) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx) +- [frontend/antd/tag/checkable-tag/Index.svelte](file://frontend/antd/tag/checkable-tag/Index.svelte) +- [frontend/antd/tag/tag.tsx](file://frontend/antd/tag/tag.tsx) + + +## Update Summary + +**Changes Made** + +- Added complete API documentation for the Timeline component, including the latest feature specifications +- Added detailed documentation for the checkable tag group component, covering both CheckableTag and CheckableTagGroup +- Updated Tag component documentation, supplementing checkable tag-related functionality +- Improved documentation of inter-component relationships and usage scenarios + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is a Python API reference and practical guide for Antd data display components, covering Avatar, Badge, Calendar, Card, Carousel, Collapse, Descriptions, Empty, Image, List, Popover, QRCode, Segmented, Statistic, Table, Tabs, Tag, Timeline, Tooltip, Tour, Tree, and other components. Content includes: + +- Constructor parameters, event binding, slots and rendering behavior +- Preprocessing and postprocessing (preprocess/postprocess) workflows +- Usage example paths and common scenarios +- Rendering optimization, lazy loading, and responsive design recommendations +- Data formatting, internationalization, and theme customization approaches +- User experience and accessibility best practices + +## Project Structure + +Antd components are encapsulated as Python classes in the backend, all inheriting from a common component base class, and mapped to corresponding Svelte implementations through frontend directory mappings. Component export entries are centralized in antd/**init**.py and antd/components.py. + +```mermaid +graph TB +A["Python Component Module
backend/modelscope_studio/components/antd"] --> B["Component Export Entry
antd/__init__.py"] +A --> C["Common Component Base Class
utils.dev.ModelScope*Component"] +D["Frontend Component Directory
frontend/antd/
*.tsx / Index.svelte"] +B --> F["Concrete Component Classes
AntdXxx(...)"] +F --> E +``` + +**Chart sources** + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +**Section sources** + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +## Core Components + +The following is a list of data display components and their common characteristics covered in this document: + +- Unified inheritance: most components inherit from ModelScopeLayoutComponent or ModelScopeComponent; some data-type components inherit from ModelScopeDataLayoutComponent (e.g., Avatar, Image) +- Event system: register frontend event callbacks via EVENTS list, bound to \_internal.update +- Slot system: define available slot names via SLOTS, used for passing template fragments or render functions +- Frontend directory: point to frontend component directory via resolve_frontend_dir("component-name") +- Preprocessing/postprocessing: implement preprocess and postprocess based on component type, handling strings, file paths, Gradio FileData, and other inputs/outputs + +**Section sources** + +- [backend/modelscope_studio/components/antd/avatar/**init**.py:18-114](file://backend/modelscope_studio/components/antd/avatar/__init__.py#L18-L114) +- [backend/modelscope_studio/components/antd/image/**init**.py:18-120](file://backend/modelscope_studio/components/antd/image/__init__.py#L18-L120) +- [backend/modelscope_studio/components/antd/calendar/**init**.py:11-102](file://backend/modelscope_studio/components/antd/calendar/__init__.py#L11-L102) +- [backend/modelscope_studio/components/antd/card/**init**.py:12-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L12-L149) +- [backend/modelscope_studio/components/antd/carousel/**init**.py:8-95](file://backend/modelscope_studio/components/antd/carousel/__init__.py#L8-L95) +- [backend/modelscope_studio/components/antd/collapse/**init**.py:11-99](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L11-L99) +- [backend/modelscope_studio/components/antd/descriptions/**init**.py:9-86](file://backend/modelscope_studio/components/antd/descriptions/__init__.py#L9-L86) +- [backend/modelscope_studio/components/antd/empty/**init**.py:8-71](file://backend/modelscope_studio/components/antd/empty/__init__.py#L8-L71) +- [backend/modelscope_studio/components/antd/list/**init**.py:11-101](file://backend/modelscope_studio/components/antd/list/__init__.py#L11-L101) +- [backend/modelscope_studio/components/antd/popover/**init**.py:10-124](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L124) +- [backend/modelscope_studio/components/antd/qr_code/**init**.py:10-96](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L10-L96) +- [backend/modelscope_studio/components/antd/tabs/**init**.py:1-145](file://backend/modelscope_studio/components/antd/tabs/__init__.py#L1-L145) +- [backend/modelscope_studio/components/antd/timeline/**init**.py:1-81](file://backend/modelscope_studio/components/antd/timeline/__init__.py#L1-L81) +- [backend/modelscope_studio/components/antd/tooltip/**init**.py:1-145](file://backend/modelscope_studio/components/antd/tooltip/__init__.py#L1-L145) +- [backend/modelscope_studio/components/antd/tour/**init**.py:1-145](file://backend/modelscope_studio/components/antd/tour/__init__.py#L1-L145) +- [backend/modelscope_studio/components/antd/tree/**init**.py:1-145](file://backend/modelscope_studio/components/antd/tree/__init__.py#L1-L145) + +## Architecture Overview + +The following diagram shows the class relationships and event binding patterns of data display components in the Python layer: + +```mermaid +classDiagram +class ModelScopeLayoutComponent +class ModelScopeComponent +class ModelScopeDataLayoutComponent +class AntdAvatar { ++EVENTS ++SLOTS ++FRONTEND_DIR ++preprocess() ++postprocess() +} +class AntdImage { ++EVENTS ++SLOTS ++FRONTEND_DIR ++preprocess() ++postprocess() +} +class AntdCalendar { ++EVENTS ++SLOTS ++FRONTEND_DIR ++api_info() +} +class AntdCard { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdCarousel { ++EVENTS ++FRONTEND_DIR +} +class AntdCollapse { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdDescriptions { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdEmpty { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdList { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdPopover { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdQRCode { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdTag { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdTagCheckableTag { ++EVENTS ++SLOTS ++FRONTEND_DIR ++api_info() +} +class AntdTagCheckableTagGroup { ++EVENTS ++SLOTS ++FRONTEND_DIR ++api_info() +} +class AntdTimeline { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +ModelScopeDataLayoutComponent <|-- AntdAvatar +ModelScopeDataLayoutComponent <|-- AntdImage +ModelScopeLayoutComponent <|-- AntdCard +ModelScopeLayoutComponent <|-- AntdCarousel +ModelScopeLayoutComponent <|-- AntdCollapse +ModelScopeLayoutComponent <|-- AntdDescriptions +ModelScopeLayoutComponent <|-- AntdEmpty +ModelScopeLayoutComponent <|-- AntdList +ModelScopeLayoutComponent <|-- AntdPopover +ModelScopeComponent <|-- AntdCalendar +ModelScopeComponent <|-- AntdQRCode +ModelScopeLayoutComponent <|-- AntdTag +ModelScopeDataLayoutComponent <|-- AntdTagCheckableTag +ModelScopeDataLayoutComponent <|-- AntdTagCheckableTagGroup +ModelScopeLayoutComponent <|-- AntdTimeline +``` + +**Chart sources** + +- [backend/modelscope_studio/components/antd/avatar/**init**.py:18-114](file://backend/modelscope_studio/components/antd/avatar/__init__.py#L18-L114) +- [backend/modelscope_studio/components/antd/image/**init**.py:18-120](file://backend/modelscope_studio/components/antd/image/__init__.py#L18-L120) +- [backend/modelscope_studio/components/antd/calendar/**init**.py:11-102](file://backend/modelscope_studio/components/antd/calendar/__init__.py#L11-L102) +- [backend/modelscope_studio/components/antd/card/**init**.py:12-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L12-L149) +- [backend/modelscope_studio/components/antd/carousel/**init**.py:8-95](file://backend/modelscope_studio/components/antd/carousel/__init__.py#L8-L95) +- [backend/modelscope_studio/components/antd/collapse/**init**.py:11-99](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L11-L99) +- [backend/modelscope_studio/components/antd/descriptions/**init**.py:9-86](file://backend/modelscope_studio/components/antd/descriptions/__init__.py#L9-L86) +- [backend/modelscope_studio/components/antd/empty/**init**.py:8-71](file://backend/modelscope_studio/components/antd/empty/__init__.py#L8-L71) +- [backend/modelscope_studio/components/antd/list/**init**.py:11-101](file://backend/modelscope_studio/components/antd/list/__init__.py#L11-L101) +- [backend/modelscope_studio/components/antd/popover/**init**.py:10-124](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L124) +- [backend/modelscope_studio/components/antd/qr_code/**init**.py:10-96](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L10-L96) +- [backend/modelscope_studio/components/antd/tag/**init**.py:12-88](file://backend/modelscope_studio/components/antd/tag/__init__.py#L12-L88) +- [backend/modelscope_studio/components/antd/tag/checkable_tag/**init**.py:11-85](file://backend/modelscope_studio/components/antd/tag/checkable_tag/__init__.py#L11-L85) +- [backend/modelscope_studio/components/antd/tag/checkable_tag_group/**init**.py:12-102](file://backend/modelscope_studio/components/antd/tag/checkable_tag_group/__init__.py#L12-L102) +- [backend/modelscope_studio/components/antd/timeline/**init**.py:9-81](file://backend/modelscope_studio/components/antd/timeline/__init__.py#L9-L81) + +## Detailed Component Analysis + +### Avatar + +- Functional purpose: Avatar display, supports icon, placeholder, and error handling events +- Key points + - Supports slots: icon, src + - Events: error + - Data model: AntdAvatarData (root supports FileData or str) + - Preprocessing/postprocessing: converts FileData to path or wraps as FileData +- Key parameters (selected) + - value, alt, gap, icon, shape, size, src_set, draggable, cross_origin, class_names, styles, root_class_name +- Usage example path + - [Example: Avatar with error handling:18-114](file://backend/modelscope_studio/components/antd/avatar/__init__.py#L18-L114) + +**Section sources** + +- [backend/modelscope_studio/components/antd/avatar/**init**.py:18-114](file://backend/modelscope_studio/components/antd/avatar/__init__.py#L18-L114) + +### Badge + +- Functional purpose: Information marking, supports dot, count, status, etc. +- Key points + - Slots: count, text + - Parameters: count, dot, overflow_count, show_zero, size, status, text, title, color, etc. +- Usage example path + - [Example: Badge with status:9-87](file://backend/modelscope_studio/components/antd/badge/__init__.py#L9-87) + +**Section sources** + +- [backend/modelscope_studio/components/antd/badge/**init**.py:9-87](file://backend/modelscope_studio/components/antd/badge/__init__.py#L9-L87) + +### Calendar + +- Functional purpose: Date selection and panel switching +- Key points + - Events: change, panel_change, select + - Slots: cellRender, fullCellRender, headerRender + - API: api_info returns a union type of number|string +- Usage example path + - [Example: Calendar events and render hooks:11-102](file://backend/modelscope_studio/components/antd/calendar/__init__.py#L11-L102) + +**Section sources** + +- [backend/modelscope_studio/components/antd/calendar/**init**.py:11-102](file://backend/modelscope_studio/components/antd/calendar/__init__.py#L11-L102) + +### Card + +- Functional purpose: Information container, supports title, extra content, cover, action area, tabs, etc. +- Key points + - Sub-components: Grid, Meta + - Events: click, tab_change + - Slots: actions, cover, extra, tabBarExtraContent, title, tabList, tabProps.\*, etc. + - Lifecycle: checks for Grid in **exit** +- Usage example path + - [Example: Card layout with tabs:12-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L12-L149) + +**Section sources** + +- [backend/modelscope_studio/components/antd/card/**init**.py:12-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L12-L149) + +### Carousel + +- Functional purpose: Carousel/slideshow container +- Key points + - Parameters: arrows, autoplay, autoplay_speed, adaptive_height, dot_position, dots, draggable, fade, infinite, speed, effect, after_change, before_change, wait_for_animate +- Usage example path + - [Example: Carousel configuration:8-95](file://backend/modelscope_studio/components/antd/carousel/__init__.py#L8-L95) + +**Section sources** + +- [backend/modelscope_studio/components/antd/carousel/**init**.py:8-95](file://backend/modelscope_studio/components/antd/carousel/__init__.py#L8-L95) + +### Collapse + +- Functional purpose: Content folding/expanding +- Key points + - Sub-components: Item + - Events: change + - Slots: expandIcon, items + - Parameters: accordion, active_key, bordered, collapsible, default_active_key, destroy_on_hidden, destroy_inactive_panel, expand_icon, ghost, items, size +- Usage example path + - [Example: Collapse panel with items:11-99](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L11-L99) + +**Section sources** + +- [backend/modelscope_studio/components/antd/collapse/**init**.py:11-99](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L11-L99) + +### Descriptions + +- Functional purpose: Key-value pair description display +- Key points + - Sub-components: Item + - Slots: extra, title, items + - Parameters: bordered, colon, column, content_style, layout, size, title, items, label_style +- Usage example path + - [Example: Descriptions list with items:9-86](file://backend/modelscope_studio/components/antd/descriptions/__init__.py#L9-86) + +**Section sources** + +- [backend/modelscope_studio/components/antd/descriptions/**init**.py:9-86](file://backend/modelscope_studio/components/antd/descriptions/__init__.py#L9-L86) + +### Empty + +- Functional purpose: Empty state placeholder +- Key points + - Slots: description, image + - Parameters: description, image (including constant enums), image_style +- Usage example path + - [Example: Empty state with image:8-71](file://backend/modelscope_studio/components/antd/empty/__init__.py#L8-71) + +**Section sources** + +- [backend/modelscope_studio/components/antd/empty/**init**.py:8-71](file://backend/modelscope_studio/components/antd/empty/__init__.py#L8-L71) + +### Image + +- Functional purpose: Image display and preview +- Key points + - Sub-components: PreviewGroup + - Events: error, preview_transform, preview_visible_change + - Slots: placeholder, preview.mask, preview.closeIcon, preview.toolbarRender, preview.imageRender + - Data model: AntdImageData (root supports FileData or str) + - Preprocessing/postprocessing: similar to Avatar, handles FileData and local paths +- Usage example path + - [Example: Image with preview group:18-120](file://backend/modelscope_studio/components/antd/image/__init__.py#L18-120) + +**Section sources** + +- [backend/modelscope_studio/components/antd/image/**init**.py:18-120](file://backend/modelscope_studio/components/antd/image/__init__.py#L18-L120) + +### List + +- Functional purpose: List rendering and pagination +- Key points + - Sub-components: Item, Item.Meta + - Events: pagination_change, pagination_show_size_change + - Slots: footer, header, loadMore, renderItem + - Parameters: bordered, data_source, footer, grid, header, item_layout, loading, load_more, locale, pagination, render_item, row_key, size, split +- Usage example path + - [Example: List with pagination:11-101](file://backend/modelscope_studio/components/antd/list/__init__.py#L11-L101) + +**Section sources** + +- [backend/modelscope_studio/components/antd/list/**init**.py:11-101](file://backend/modelscope_studio/components/antd/list/__init__.py#L11-L101) + +### Popover + +- Functional purpose: Bubble card with trigger +- Key points + - Events: open_change + - Slots: title, content + - Parameters: align, arrow, auto_adjust_overflow, color, default_open, destroy_tooltip_on_hide, destroy_on_hidden, fresh, get_popup_container, mouse_enter_delay, mouse_leave_delay, overlay_class_name, overlay_style, overlay_inner_style, placement, trigger, open, z_index +- Usage example path + - [Example: Popover with trigger:10-124](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L124) + +**Section sources** + +- [backend/modelscope_studio/components/antd/popover/**init**.py:10-124](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L124) + +### QRCode + +- Functional purpose: Dynamic QR code generation and status management +- Key points + - Events: refresh + - Slots: statusRender + - Parameters: type, bordered, color, bg_color, boost_level, error_level, icon, icon_size, margin_size, size, status, status_render +- Usage example path + - [Example: QR code with status rendering:10-96](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L10-96) + +**Section sources** + +- [backend/modelscope_studio/components/antd/qr_code/**init**.py:10-96](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L10-L96) + +### Segmented + +- Functional purpose: Segmented selector (data display type) +- Key points + - Sub-components: Option + - Parameters: options, block, size, disabled, onChange, etc. (per frontend definition) +- Usage example path + - [Example: Segmented with options](file://backend/modelscope_studio/components/antd/segmented/__init__.py) + +**Section sources** + +- [backend/modelscope_studio/components/antd/segmented/__init__.py] + +### Statistic + +- Functional purpose: Numeric display and countdown +- Key points + - Sub-components: Countdown, Timer + - Parameters: value, precision, prefix, suffix, formatter, groupSeparator, format, onFinish, etc. +- Usage example path + - [Example: Statistic and countdown](file://backend/modelscope_studio/components/antd/statistic/__init__.py) + +**Section sources** + +- [backend/modelscope_studio/components/antd/statistic/__init__.py] + +### Table + +- Functional purpose: Data table rendering and interaction +- Key points + - Sub-components: Column, ColumnGroup, Expandable, RowSelection, RowSelection.Selection + - Parameters: dataSource, columns, pagination, scroll, size, loading, onChange, onHeaderRow, onRow, etc. +- Usage example path + - [Example: Table with column configuration](file://backend/modelscope_studio/components/antd/table/__init__.py) + +**Section sources** + +- [backend/modelscope_studio/components/antd/table/__init__.py] + +### Tabs + +- Functional purpose: Tab container and switching +- Key points + - Sub-components: Item + - Parameters: activeKey, defaultActiveKey, type, tabPosition, size, hideAdd, addIcon, removeIcon, renderTabBar, onEdit, onChange, etc. +- Usage example path + - [Example: Tabs with items](file://backend/modelscope_studio/components/antd/tabs/__init__.py) + +**Section sources** + +- [backend/modelscope_studio/components/antd/tabs/__init__.py] + +### Tag + +- Functional purpose: Tag display and checkable tags +- Key points + - Sub-components: CheckableTag, CheckableTagGroup + - Events: close, change, click + - Slots: icon, closeIcon + - Parameters: value, disabled, href, bordered, close_icon, color, icon +- Usage example path + - [Example: Tag with checkable tags](file://backend/modelscope_studio/components/antd/tag/__init__.py) + +**Update** Added checkable tag group component support, including individual checkable tags and checkable tag groups + +**Section sources** + +- [backend/modelscope_studio/components/antd/tag/**init**.py:12-88](file://backend/modelscope_studio/components/antd/tag/__init__.py#L12-L88) + +### Timeline + +- Functional purpose: Timeline display +- Key points + - Sub-components: Item + - Events: none + - Slots: pending, pendingDot + - Parameters: mode, reverse, orientation, title_span, variant, pending, pending_dot, items +- Usage example path + - [Example: Timeline with items](file://backend/modelscope_studio/components/antd/timeline/__init__.py) + +**Update** Added complete API documentation for the Timeline component, including the latest feature specifications + +**Section sources** + +- [backend/modelscope_studio/components/antd/timeline/**init**.py:9-81](file://backend/modelscope_studio/components/antd/timeline/__init__.py#L9-L81) + +### Tooltip + +- Functional purpose: Text tooltip +- Key points + - Parameters: title, color, placement, trigger, mouseEnterDelay, mouseLeaveDelay, overlayClassName, overlayStyle, overlayInnerStyle, destroyTooltipOnHide, etc. +- Usage example path + - [Example: Text tooltip](file://backend/modelscope_studio/components/antd/tooltip/__init__.py) + +**Section sources** + +- [backend/modelscope_studio/components/antd/tooltip/__init__.py] + +### Tour + +- Functional purpose: Guided navigation +- Key points + - Sub-components: Step + - Parameters: steps, current, scrollIntoViewOptions, mask, gap, indicator, prefixCls, onClose, onChange, etc. +- Usage example path + - [Example: Tour with steps](file://backend/modelscope_studio/components/antd/tour/__init__.py) + +**Section sources** + +- [backend/modelscope_studio/components/antd/tour/__init__.py] + +### Tree + +- Functional purpose: Tree structure display and interaction +- Key points + - Sub-components: TreeNode, DirectoryTree + - Parameters: treeData, defaultExpandAll, defaultExpandedKeys, expandedKeys, selectedKeys, checkable, checkStrictly, multiple, fieldNames, onChange, onCheck, onSelect, etc. +- Usage example path + - [Example: Tree with nodes](file://backend/modelscope_studio/components/antd/tree/__init__.py) + +**Section sources** + +- [backend/modelscope_studio/components/antd/tree/__init__.py] + +### Checkable Tag Group Components + +#### AntdTagCheckableTag + +- Functional purpose: Tag component that supports checked state +- Key points + - Events: change, click + - Slots: icon + - Parameters: label, value, icon + - Data type: boolean, representing the checked state +- Usage example path + - [Example: Checkable tag](file://backend/modelscope_studio/components/antd/tag/checkable_tag/__init__.py) + +#### AntdTagCheckableTagGroup + +- Functional purpose: Container combining multiple checkable tags +- Key points + - Events: change + - Slots: options + - Parameters: options, disabled, multiple, default_value + - Data type: string, number, or string/number array, representing the selected tag values +- Usage example path + - [Example: Checkable tag group](file://backend/modelscope_studio/components/antd/tag/checkable_tag_group/__init__.py) + +**Added** Complete documentation for the checkable tag group component, covering both individual tag and tag group usage patterns + +**Section sources** + +- [backend/modelscope_studio/components/antd/tag/checkable_tag/**init**.py:11-85](file://backend/modelscope_studio/components/antd/tag/checkable_tag/__init__.py#L11-L85) +- [backend/modelscope_studio/components/antd/tag/checkable_tag_group/**init**.py:12-102](file://backend/modelscope_studio/components/antd/tag/checkable_tag_group/__init__.py#L12-L102) + +## Dependency Analysis + +- Component exports: all Antd components are centrally exported in antd/**init**.py and antd/components.py, enabling unified imports and alias usage +- Base class dependency: each component depends on the ModelScope\*Component hierarchy in utils.dev for unified event binding and frontend directory resolution +- Frontend mapping: maps Python components to frontend/antd/
backend/modelscope_studio/components/antd/__init__.py"] --> B["AutoComplete
auto_complete/__init__.py"] +A --> C["Cascader
cascader/__init__.py"] +A --> D["Checkbox
checkbox/__init__.py"] +A --> E["ColorPicker
color_picker/__init__.py"] +A --> F["DatePicker
date_picker/__init__.py"] +A --> G["Form
form/__init__.py"] +A --> H["Input
input/__init__.py"] +A --> I["InputNumber
input_number/__init__.py"] +J["Frontend Directory
frontend/antd/*"]:::ext +B --> J +C --> J +D --> J +E --> J +F --> J +G --> J +H --> J +I --> J +classDef ext fill:#fff,stroke:#333,stroke-width:1px; +``` + +Chart sources + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/auto_complete/**init**.py:1-146](file://backend/modelscope_studio/components/antd/auto_complete/__init__.py#L1-L146) +- [backend/modelscope_studio/components/antd/cascader/**init**.py:1-191](file://backend/modelscope_studio/components/antd/cascader/__init__.py#L1-L191) +- [backend/modelscope_studio/components/antd/checkbox/**init**.py:1-83](file://backend/modelscope_studio/components/antd/checkbox/__init__.py#L1-L83) +- [backend/modelscope_studio/components/antd/color_picker/**init**.py:1-148](file://backend/modelscope_studio/components/antd/color_picker/__init__.py#L1-L148) +- [backend/modelscope_studio/components/antd/date_picker/**init**.py:1-208](file://backend/modelscope_studio/components/antd/date_picker/__init__.py#L1-L208) +- [backend/modelscope_studio/components/antd/form/**init**.py:1-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L1-L133) +- [backend/modelscope_studio/components/antd/input/**init**.py:1-127](file://backend/modelscope_studio/components/antd/input/__init__.py#L1-L127) +- [backend/modelscope_studio/components/antd/input_number/**init**.py:1-147](file://backend/modelscope_studio/components/antd/input_number/__init__.py#L1-L147) + +Section sources + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +## Core Components + +This section provides an overview of the general capabilities and differences of data entry components: + +- All components inherit from a unified data layout component base class, providing consistent lifecycle and event binding mechanisms. +- Each component provides: + - Constructor parameters: supports common properties (e.g., size, status, style, class names, etc.) and component-specific properties. + - Event list: binds frontend callbacks via event listeners. + - Slot list: used for custom rendering (e.g., dropdown panel, prefix/suffix, placeholder content, etc.). + - Data type specifications: declares input/output types through API specs. + - Preprocessing/postprocessing: type conversion or formatting of payload/value. + - Example values and example payloads: facilitates quick integration and testing. + +Section sources + +- [backend/modelscope_studio/components/antd/auto_complete/**init**.py:11-146](file://backend/modelscope_studio/components/antd/auto_complete/__init__.py#L11-L146) +- [backend/modelscope_studio/components/antd/cascader/**init**.py:13-191](file://backend/modelscope_studio/components/antd/cascader/__init__.py#L13-L191) +- [backend/modelscope_studio/components/antd/checkbox/**init**.py:12-83](file://backend/modelscope_studio/components/antd/checkbox/__init__.py#L12-L83) +- [backend/modelscope_studio/components/antd/color_picker/**init**.py:12-148](file://backend/modelscope_studio/components/antd/color_picker/__init__.py#L12-L148) +- [backend/modelscope_studio/components/antd/date_picker/**init**.py:13-208](file://backend/modelscope_studio/components/antd/date_picker/__init__.py#L13-L208) +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) +- [backend/modelscope_studio/components/antd/input/**init**.py:16-127](file://backend/modelscope_studio/components/antd/input/__init__.py#L16-L127) +- [backend/modelscope_studio/components/antd/input_number/**init**.py:11-147](file://backend/modelscope_studio/components/antd/input_number/__init__.py#L11-L147) + +## Architecture Overview + +Backend components connect to frontend directory mappings through a unified base class. The frontend components handle UI rendering and interaction, while the backend manages data type constraints, event binding, and serialization. + +```mermaid +sequenceDiagram +participant U as "User" +participant FE as "Frontend Component (Svelte)" +participant BE as "Backend Component (Python)" +participant API as "Gradio/Server" +U->>FE : Input/Select/Click +FE-->>BE : Trigger event (e.g., change/search/select) +BE->>BE : Bind event callbacks
Update internal state +BE->>API : Serialize payload and submit +API-->>BE : Return processed value +BE-->>FE : Post-process result and update UI +``` + +Chart sources + +- [backend/modelscope_studio/components/antd/auto_complete/**init**.py:18-43](file://backend/modelscope_studio/components/antd/auto_complete/__init__.py#L18-L43) +- [backend/modelscope_studio/components/antd/cascader/**init**.py:20-36](file://backend/modelscope_studio/components/antd/cascader/__init__.py#L20-L36) +- [backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) + +## Detailed Component Analysis + +### AutoComplete + +- Type and purpose: Auto-complete component for string input, supporting option lists and search events. +- Key properties + - Common: size, status, variant, placeholder, disabled, class_names, styles, root_class_name, as_item, etc. + - Specific: allow_clear, auto_focus, backfill, default_active_first_option, default_open, dropdown_render, popup_render, popup_class_name, popup_match_select_width, filter_option, get_popup_container, not_found_content, open, options, placement, options, etc. +- Events: change, blur, focus, search, select, clear, dropdown_visible_change, popup_visible_change. +- Slots: allowClear.clearIcon, dropdownRender, popupRender, children, notFoundContent, options. +- Data types + - Input/Output: string. + - API spec: string type. +- Preprocessing/postprocessing: pass-through. +- Usage examples + - Use as a single input in a form, combined with validation rules. + - Use `options` to provide candidate lists, combined with `search` event for remote search. +- Error handling + - Customize the prompt via `not_found_content` when no match is found. +- Real-time validation + - Trigger remote validation via `search` event, used with Form's validation trigger strategy. + +Section sources + +- [backend/modelscope_studio/components/antd/auto_complete/**init**.py:12-146](file://backend/modelscope_studio/components/antd/auto_complete/__init__.py#L12-L146) + +### Cascader + +- Type and purpose: Multi-level cascading selection, supports async loading and search. +- Key properties + - Common: size, status, variant, placeholder, disabled, class_names, styles, root_class_name, as_item, etc. + - Specific: allow_clear, auto_clear_search_value, auto_focus, change_on_select, display_render, tag_render, popup_class_name, dropdown_render, popup_render, expand_icon, prefix, expand_trigger, filed_names, get_popup_container, max_tag_count, max_tag_placeholder, max_tag_text_length, not_found_content, open, options, placement, show_search, multiple, show_checked_strategy, remove_icon, search_value, dropdown_menu_column_style, option_render, etc. +- Events: change, search, dropdown_visible_change, popup_visible_change, load_data. +- Slots: allowClear.clearIcon, suffixIcon, maxTagPlaceholder, notFoundContent, expandIcon, removeIcon, prefix, displayRender, tagRender, dropdownRender, popupRender, showSearch.render. +- Data types + - Input/Output: string array or number array (path keys). + - API spec: string array or string. +- Preprocessing/postprocessing: pass-through. +- Usage examples + - Commonly used for province/city/district selection, category filtering, and similar scenarios. + - Use `load_data` to implement lazy loading. +- Error handling + - Customize empty state via `not_found_content`. +- Real-time validation + - Combine `search` and `change` events with Form validation. + +Section sources + +- [backend/modelscope_studio/components/antd/cascader/**init**.py:13-191](file://backend/modelscope_studio/components/antd/cascader/__init__.py#L13-L191) + +### Checkbox + +- Type and purpose: Boolean value selection. +- Key properties + - Common: class_names, styles, additional_props, root_class_name, as_item, etc. + - Specific: auto_focus, default_checked, disabled, indeterminate. +- Events: change. +- Data types + - Input/Output: boolean. + - API spec: boolean type. +- Preprocessing/postprocessing: pass-through. +- Usage examples + - Use standalone or combined into a Group. +- Error handling + - No special error handling logic; follows boolean constraints. +- Real-time validation + - Can participate directly in Form validation. + +Section sources + +- [backend/modelscope_studio/components/antd/checkbox/**init**.py:12-83](file://backend/modelscope_studio/components/antd/checkbox/__init__.py#L12-L83) + +### ColorPicker + +- Type and purpose: Color value selection, supports solid color and gradient modes. +- Key properties + - Common: class_names, styles, additional_props, root_class_name, as_item, etc. + - Specific: value_format, allow_clear, arrow, presets, disabled, disabled_alpha, disabled_format, destroy_tooltip_on_hide, destroy_on_hidden, format, mode, open, default_value, default_format, show_text, placement, trigger, panel_render, size. +- Events: change, change_complete, clear, open_change, format_change. +- Slots: presets, panelRender, showText. +- Data types + - Input/Output: hex string or gradient color array object. + - API spec: string or color array object. +- Preprocessing/postprocessing: pass-through. +- Usage examples + - Used for theme color, brand color, and similar configurations. +- Error handling + - Invalid formats are intercepted by frontend validation. +- Real-time validation + - Combine `change` and `change_complete` events with validation. + +Section sources + +- [backend/modelscope_studio/components/antd/color_picker/**init**.py:12-148](file://backend/modelscope_studio/components/antd/color_picker/__init__.py#L12-L148) + +### DatePicker + +- Type and purpose: Date/time selection, supports multiple modes and range selection. +- Key properties + - Common: class_names, styles, additional_props, root_class_name, as_item, etc. + - Specific: allow_clear, auto_focus, cell_render, components, disabled, disabled_date, format, order, preserve_invalid_on_blur, input_read_only, locale, mode, need_confirm, next_icon, open, panel_render, picker, placement, placeholder, popup_class_name, popup_style, get_popup_container, min_date, max_date, prefix, prev_icon, size, presets, status, suffix_icon, super_next_icon, super_prev_icon, variant, default_picker_value, default_value, disabled_time, multiple, picker_value, render_extra_footer, show_now, show_time, show_week, preview_value. +- Events: change, ok, panel_change, open_change. +- Slots: allowClear.clearIcon, prefix, prevIcon, nextIcon, suffixIcon, superNextIcon, superPrevIcon, renderExtraFooter, cellRender, panelRender. +- Data types + - Input/Output: string, number, or array (range). + - API spec: string, number, or array. +- Preprocessing/postprocessing: pass-through. +- Usage examples + - Supports date, week, month, quarter, year, and other modes; can enable time selection and confirmation button. +- Error handling + - Restrict ranges via `disabled_date`, `min_date`, `max_date`. +- Real-time validation + - Combine `panel_change` and `change` events with validation. + +Section sources + +- [backend/modelscope_studio/components/antd/date_picker/**init**.py:13-208](file://backend/modelscope_studio/components/antd/date_picker/__init__.py#L13-L208) + +### Form + +- Type and purpose: Data collection and validation container, supports field change, submit, reset, and validation. +- Key properties + - Common: class_names, styles, additional_props, root_class_name, as_item, etc. + - Specific: form_action, colon, disabled, component, feedback_icons, initial_values, label_align, label_col, label_wrap, layout, form_name, preserve, required_mark, scroll_to_first_error, size, validate_messages, validate_trigger, variant, wrapper_col, clear_on_destroy. +- Events: fields_change, finish, finish_failed, values_change. +- Slots: requiredMark. +- Data types + - Input/Output: dict or wrapped model. + - Preprocessing: extract wrapped model into dict. +- Preprocessing/postprocessing: unpack AntdFormData to dict. +- Usage examples + - Place each data entry component as a child item in Form to manage validation and submission uniformly. +- Error handling + - Control error display and positioning via `validate_messages`, `scroll_to_first_error`. +- Real-time validation + - Control trigger timing via `validate_trigger` (e.g., onChange). + +Section sources + +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) + +### Input + +- Type and purpose: Basic text input, supports password, search, multi-line text, OTP and other variants. +- Key properties + - Common: class_names, styles, additional_props, root_class_name, as_item, etc. + - Specific: addon_after, addon_before, allow_clear, count, default_value, read_only, disabled, max_length, prefix, show_count, size, status, suffix, type, placeholder, variant. +- Events: change, press_enter, clear. +- Slots: addonAfter, addonBefore, allowClear.clearIcon, prefix, suffix, showCount.formatter. +- Data types + - Input/Output: string. + - API spec: string. +- Preprocessing/postprocessing: pass-through. +- Usage examples + - Extend to different forms via Password, Search, Textarea, OTP subclasses. +- Error handling + - Provide feedback via `status` and validation rules. +- Real-time validation + - Combine `change` and `press_enter` events with validation. + +Section sources + +- [backend/modelscope_studio/components/antd/input/**init**.py:16-127](file://backend/modelscope_studio/components/antd/input/__init__.py#L16-L127) + +### InputNumber + +- Type and purpose: Numeric input, supports stepping, precision, up/down controls, etc. +- Key properties + - Common: class_names, styles, additional_props, root_class_name, as_item, etc. + - Specific: addon_after, addon_before, auto_focus, change_on_blur, change_on_wheel, controls, decimal_separator, placeholder, default_value, disabled, formatter, keyboard, max, min, mode, parser, precision, prefix, read_only, size, status, step, string_mode, suffix, variant. +- Events: change, press_enter, step. +- Slots: addonAfter, addonBefore, controls.upIcon, controls.downIcon, prefix, suffix. +- Data types + - Input/Output: integer or float. + - API spec: number. +- Preprocessing/postprocessing: parse string to integer or float. +- Usage examples + - Suitable for price, quantity, rating, and other numeric inputs. +- Error handling + - Constrain range and granularity via `min`/`max`, `precision`, `step`. +- Real-time validation + - Combine `change` and `step` events with validation. + +Section sources + +- [backend/modelscope_studio/components/antd/input_number/**init**.py:11-147](file://backend/modelscope_studio/components/antd/input_number/__init__.py#L11-L147) + +### Mentions (not found in backend) + +- Status: No backend implementation file found in the current repository. +- Recommendation: If needed, refer to the Antd official documentation and frontend implementation, and add the backend adapter layer. + +### Radio (not found in backend) + +- Status: No backend implementation file found in the current repository. +- Recommendation: If needed, refer to the Antd official documentation and frontend implementation, and add the backend adapter layer. + +### Rate (not found in backend) + +- Status: No backend implementation file found in the current repository. +- Recommendation: If needed, refer to the Antd official documentation and frontend implementation, and add the backend adapter layer. + +### Select (not found in backend) + +- Status: No backend implementation file found in the current repository. +- Recommendation: If needed, refer to the Antd official documentation and frontend implementation, and add the backend adapter layer. + +### Slider (not found in backend) + +- Status: No backend implementation file found in the current repository. +- Recommendation: If needed, refer to the Antd official documentation and frontend implementation, and add the backend adapter layer. + +### Switch (not found in backend) + +- Status: No backend implementation file found in the current repository. +- Recommendation: If needed, refer to the Antd official documentation and frontend implementation, and add the backend adapter layer. + +### TimePicker (not found in backend) + +- Status: No backend implementation file found in the current repository. +- Recommendation: If needed, refer to the Antd official documentation and frontend implementation, and add the backend adapter layer. + +### Transfer (not found in backend) + +- Status: No backend implementation file found in the current repository. +- Recommendation: If needed, refer to the Antd official documentation and frontend implementation, and add the backend adapter layer. + +### TreeSelect (not found in backend) + +- Status: No backend implementation file found in the current repository. +- Recommendation: If needed, refer to the Antd official documentation and frontend implementation, and add the backend adapter layer. + +### Upload (not found in backend) + +- Status: No backend implementation file found in the current repository. +- Recommendation: If needed, refer to the Antd official documentation and frontend implementation, and add the backend adapter layer. + +## Dependency Analysis + +- Inter-component coupling + - All components share the same base class and event system, with low coupling and high cohesion. + - Form acts as a container, aggregating data entry components to form a loosely-coupled form ecosystem. +- External dependencies + - The event system is based on Gradio's event listeners. + - Frontend directory mappings are resolved via utility functions, ensuring frontend-backend consistency. +- Circular dependencies + - No circular dependencies detected. + +```mermaid +graph LR +Base["Unified Base Class"] --> AC["AutoComplete"] +Base --> CS["Cascader"] +Base --> CB["Checkbox"] +Base --> CP["ColorPicker"] +Base --> DP["DatePicker"] +Base --> FM["Form"] +Base --> IN["Input"] +Base --> INN["InputNumber"] +FM --> AC +FM --> CS +FM --> CB +FM --> CP +FM --> DP +FM --> IN +FM --> INN +``` + +Chart sources + +- [backend/modelscope_studio/components/antd/auto_complete/**init**.py:12](file://backend/modelscope_studio/components/antd/auto_complete/__init__.py#L12) +- [backend/modelscope_studio/components/antd/cascader/**init**.py:13](file://backend/modelscope_studio/components/antd/cascader/__init__.py#L13) +- [backend/modelscope_studio/components/antd/checkbox/**init**.py:12](file://backend/modelscope_studio/components/antd/checkbox/__init__.py#L12) +- [backend/modelscope_studio/components/antd/color_picker/**init**.py:12](file://backend/modelscope_studio/components/antd/color_picker/__init__.py#L12) +- [backend/modelscope_studio/components/antd/date_picker/**init**.py:13](file://backend/modelscope_studio/components/antd/date_picker/__init__.py#L13) +- [backend/modelscope_studio/components/antd/form/**init**.py:17](file://backend/modelscope_studio/components/antd/form/__init__.py#L17) +- [backend/modelscope_studio/components/antd/input/**init**.py:16](file://backend/modelscope_studio/components/antd/input/__init__.py#L16) +- [backend/modelscope_studio/components/antd/input_number/**init**.py:11](file://backend/modelscope_studio/components/antd/input_number/__init__.py#L11) + +Section sources + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) + +## Performance Considerations + +- Event binding and callbacks + - Set event bindings judiciously (e.g., only enable search/visibility change events when necessary) to avoid excessive triggering. +- Data types and serialization + - Numeric input components perform string-to-number conversion during preprocessing, reducing overhead from frontend type inconsistencies. +- Dropdowns and popups + - For complex dropdowns (e.g., Cascader), use lazy loading and virtual scrolling (if supported by the frontend) to reduce rendering costs. +- Styles and class names + - Use `class_names` and `styles` to streamline styles, avoiding repeated computation and repaints. +- Form validation + - Set `validate_trigger` appropriately to avoid performance issues from high-frequency validation. + +## Troubleshooting Guide + +- Event not triggered + - Check that event listeners are correctly bound and confirm that the frontend callback is enabled. +- Data type mismatch + - For numeric input components, preprocessing may fail when non-numeric strings are entered; ensure input format is correct. +- Validation not working + - Confirm that Form's `validate_trigger` settings are consistent with component events; check `required_mark` and `scroll_to_first_error` configuration. +- Dropdown/popup issues + - Check `get_popup_container` and `placement` configuration, ensuring the container is visible and the position is reasonable. +- Cascading load failure + - Confirm that `load_data` callback logic is consistent with the `options` structure. + +Section sources + +- [backend/modelscope_studio/components/antd/input_number/**init**.py:128-140](file://backend/modelscope_studio/components/antd/input_number/__init__.py#L128-L140) +- [backend/modelscope_studio/components/antd/form/**init**.py:48-68](file://backend/modelscope_studio/components/antd/form/__init__.py#L48-L68) +- [backend/modelscope_studio/components/antd/cascader/**init**.py:33-36](file://backend/modelscope_studio/components/antd/cascader/__init__.py#L33-L36) + +## Conclusion + +This project provides a unified Antd data entry component backend adapter layer, covering core components such as AutoComplete, Cascader, Checkbox, ColorPicker, DatePicker, Form, Input, and InputNumber. Through a consistent event system, data type specifications, and preprocessing/postprocessing mechanisms, developers can efficiently build forms and data entry interfaces. For missing components (such as Mentions, Radio, Rate, Select, Slider, Switch, TimePicker, Transfer, TreeSelect, Upload), it is recommended to refer to the Antd official documentation and frontend implementations to add backend adapter layers and maintain ecosystem consistency. + +## Appendix + +- Usage recommendations + - Place data entry components inside a Form container to manage initial values, validation, and submission uniformly. + - For complex inputs (e.g., Cascader, DatePicker), prefer controlled mode with explicit API specs. + - Use slots and variants (`variant`) to improve accessibility and consistency. +- Best practices + - Set reasonable default values and placeholders for each input to improve user experience. + - For wide-range inputs (e.g., numbers), set `min`/`max` and `step` to avoid invalid input. + - For date inputs, specify `format` and `picker` mode explicitly to reduce ambiguity. diff --git a/.wiki/en/API Reference/Python API/Antd Components API/Feedback Components API.md b/.wiki/en/API Reference/Python API/Antd Components API/Feedback Components API.md new file mode 100644 index 00000000..c3aea9f1 --- /dev/null +++ b/.wiki/en/API Reference/Python API/Antd Components API/Feedback Components API.md @@ -0,0 +1,611 @@ +# Feedback Components API + + +**Files referenced in this document** +- [backend/modelscope_studio/components/antd/alert/__init__.py](file://backend/modelscope_studio/components/antd/alert/__init__.py) +- [backend/modelscope_studio/components/antd/drawer/__init__.py](file://backend/modelscope_studio/components/antd/drawer/__init__.py) +- [backend/modelscope_studio/components/antd/message/__init__.py](file://backend/modelscope_studio/components/antd/message/__init__.py) +- [backend/modelscope_studio/components/antd/modal/__init__.py](file://backend/modelscope_studio/components/antd/modal/__init__.py) +- [backend/modelscope_studio/components/antd/notification/__init__.py](file://backend/modelscope_studio/components/antd/notification/__init__.py) +- [backend/modelscope_studio/components/antd/popconfirm/__init__.py](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py) +- [backend/modelscope_studio/components/antd/progress/__init__.py](file://backend/modelscope_studio/components/antd/progress/__init__.py) +- [backend/modelscope_studio/components/antd/result/__init__.py](file://backend/modelscope_studio/components/antd/result/__init__.py) +- [backend/modelscope_studio/components/antd/skeleton/__init__.py](file://backend/modelscope_studio/components/antd/skeleton/__init__.py) +- [backend/modelscope_studio/components/antd/spin/__init__.py](file://backend/modelscope_studio/components/antd/spin/__init__.py) +- [backend/modelscope_studio/components/antd/watermark/__init__.py](file://backend/modelscope_studio/components/antd/watermark/__init__.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/components/antd/modal/static/__init__.py](file://backend/modelscope_studio/components/antd/modal/static/__init__.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) +- [frontend/antd/message/message.tsx](file://frontend/antd/message/message.tsx) +- [frontend/antd/drawer/drawer.tsx](file://frontend/antd/drawer/drawer.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the Python API reference for Antd feedback components, covering Alert, Drawer, Message, Modal, Notification, Popconfirm, Progress, Result, Skeleton, Spin, Watermark, and other feedback-related components. Content includes: + +- Constructor parameters and property definitions +- Method signatures and return types +- Usage examples (provided as "example paths") +- Timing control, animation, and interaction response +- Global configuration, themes, and internationalization +- UX design principles and notification strategy best practices + +## Project Structure + +Feedback components are located in the antd sub-module of the backend Python package. Each component inherits from a unified component base class, with the frontend implemented by corresponding Svelte components interfaced with the Gradio event system. + +```mermaid +graph TB +subgraph "Python Backend" +A["ModelScopeLayoutComponent
ModelScopeComponent
ModelScopeDataLayoutComponent"] +B["antd/__init__.py
exports component aliases"] +C["alert/__init__.py"] +D["drawer/__init__.py"] +E["message/__init__.py"] +F["modal/__init__.py"] +G["notification/__init__.py"] +H["popconfirm/__init__.py"] +I["progress/__init__.py"] +J["result/__init__.py"] +K["skeleton/__init__.py"] +L["spin/__init__.py"] +M["watermark/__init__.py"] +end +subgraph "Frontend Svelte" +P["config-provider/config-provider.tsx"] +Q["message/message.tsx"] +R["drawer/drawer.tsx"] +end +A --> C +A --> D +A --> E +A --> F +A --> G +A --> H +A --> I +A --> J +A --> K +A --> L +A --> M +B --> C +B --> D +B --> E +B --> F +B --> G +B --> H +B --> I +B --> J +B --> K +B --> L +B --> M +P --> E +P --> G +Q --> E +R --> D +``` + +Chart sources + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [frontend/antd/config-provider/config-provider.tsx:51-106](file://frontend/antd/config-provider/config-provider.tsx#L51-L106) +- [frontend/antd/message/message.tsx:55-78](file://frontend/antd/message/message.tsx#L55-L78) +- [frontend/antd/drawer/drawer.tsx:14-60](file://frontend/antd/drawer/drawer.tsx#L14-L60) + +Section sources + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +## Core Components + +The following is an overview of common constructor parameters and properties for feedback components (grouped by component): + +- Common parameters + - visible: boolean, whether to render + - elem_id: string, element ID + - elem_classes: list or string, CSS classes + - elem_style: dict, inline styles + - render: boolean, whether to render + - as_item: string, layout item identifier + - class_names: dict or string, additional class name mapping + - styles: dict or string, additional style mapping + - root_class_name: string, root node class name + - additional_props: dict, extra properties passed through to frontend components + - \_internal: internal parameter, reserved by the framework + +- Event binding (registered via EVENTS list) + - Event callbacks are bound to frontend components via internal updates at construction time + +Section sources + +- [backend/modelscope_studio/utils/dev/component.py:28-98](file://backend/modelscope_studio/utils/dev/component.py#L28-L98) +- [backend/modelscope_studio/components/antd/alert/**init**.py:16-20](file://backend/modelscope_studio/components/antd/alert/__init__.py#L16-L20) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:14-18](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L14-L18) +- [backend/modelscope_studio/components/antd/message/**init**.py:14-21](file://backend/modelscope_studio/components/antd/message/__init__.py#L14-L21) +- [backend/modelscope_studio/components/antd/modal/**init**.py:18-25](file://backend/modelscope_studio/components/antd/modal/__init__.py#L18-L25) +- [backend/modelscope_studio/components/antd/notification/**init**.py:14-21](file://backend/modelscope_studio/components/antd/notification/__init__.py#L14-L21) +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:14-27](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L14-L27) +- [backend/modelscope_studio/components/antd/watermark/**init**.py:12-16](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L12-L16) + +## Architecture Overview + +The feedback component call chain is as follows: the Python layer constructs component instances, sets properties and events; the frontend Svelte component receives props and interfaces with Ant Design components; the global ConfigProvider provides themes and internationalization; Message/Notification display globally through frontend context. + +```mermaid +sequenceDiagram +participant Py as "Python Component Instance" +participant FE as "Svelte Frontend Component" +participant CFG as "ConfigProvider" +participant MSG as "Message Context" +participant NOTI as "Notification Context" +Py->>FE : Set properties and events +FE->>CFG : Apply theme/language configuration +CFG-->>FE : Return localization and theme +FE->>MSG : Register message display +FE->>NOTI : Register notification display +MSG-->>Py : Event callbacks e.g. click/close +NOTI-->>Py : Event callbacks e.g. click/close +``` + +Chart sources + +- [frontend/antd/config-provider/config-provider.tsx:51-106](file://frontend/antd/config-provider/config-provider.tsx#L51-L106) +- [frontend/antd/message/message.tsx:55-78](file://frontend/antd/message/message.tsx#L55-L78) +- [backend/modelscope_studio/components/antd/message/**init**.py:14-21](file://backend/modelscope_studio/components/antd/message/__init__.py#L14-L21) +- [backend/modelscope_studio/components/antd/notification/**init**.py:14-21](file://backend/modelscope_studio/components/antd/notification/__init__.py#L14-L21) + +## Detailed Component Analysis + +### Alert + +- Constructor parameters and properties + - action: string, action button content + - after_close: string, callback after closing + - banner: boolean, banner mode + - closable: boolean or dict, closable configuration + - description: string, description text + - icon: string, icon + - message: string, title + - show_icon: boolean, whether to show icon + - type: text enum (success/info/warning/error), type + - slots: supports action, closable.closeIcon, description, icon, message +- Methods + - preprocess(payload): input preprocessing + - postprocess(value): output postprocessing + - example_payload()/example_value(): example data +- Events + - close: close event binding + +Section sources + +- [backend/modelscope_studio/components/antd/alert/**init**.py:25-89](file://backend/modelscope_studio/components/antd/alert/__init__.py#L25-L89) + +### Drawer + +- Constructor parameters and properties + - after_open_change: string, callback on open state change + - auto_focus: boolean, auto focus + - body_style: dict, body style + - close_icon: string, close icon + - closable: boolean or dict, closable + - destroy_on_close/destroy_on_hidden: boolean, destroy on close/hide + - draggable: boolean, draggable + - extra: string, extra content + - footer: string, footer + - force_render: boolean, force render + - get_container: string, container selector + - height/width: number or string, size + - keyboard: boolean, keyboard support + - mask/mask_closable: boolean, mask and click-to-close mask + - placement: text enum (left/right/top/bottom), position + - push: boolean or dict, push + - resizable: boolean, resizable + - size: text enum (default/large), size + - title: string, title + - loading: boolean, loading + - open: boolean, whether open + - z_index: integer, z-index + - drawer_render: string, render function + - slots: supports closeIcon, closable.closeIcon, extra, footer, title, drawerRender +- Methods + - preprocess()/postprocess(): preprocessing/postprocessing + - example_payload()/example_value(): example data +- Events + - close: close event binding + - resizable_resize_start: resize start event binding + - resizable_resize: resize event binding + - resizable_resize_end: resize end event binding + +**Update** Drawer component added three resize-related event handlers: + +- resizable_resize_start: triggered when the user starts dragging to resize the drawer +- resizable_resize: continuously triggered during the resize process +- resizable_resize_end: triggered when the resize operation is complete + +These events allow developers to monitor the dynamic adjustment process of the drawer for more fine-grained interaction control. + +Section sources + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:14-27](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L14-L27) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:26-126](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L26-L126) +- [frontend/antd/drawer/drawer.tsx:14-60](file://frontend/antd/drawer/drawer.tsx#L14-L60) + +### Message + +- Constructor parameters and properties + - content: string, message content + - type: text enum (success/info/warning/error/loading), type + - duration: number, duration + - icon: string, icon + - key: string/number/float, unique key + - pause_on_hover: boolean, pause on hover + - get_container: string, container selector + - rtl: boolean, right-to-left + - top: number, top offset + - slots: supports icon, content +- Methods + - preprocess(payload: str|None): str|None + - postprocess(value: str|None): str|None + - example_payload()/example_value(): example data +- Events + - click/close: click and close event binding + +Section sources + +- [backend/modelscope_studio/components/antd/message/**init**.py:26-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L26-L91) +- [frontend/antd/message/message.tsx:55-78](file://frontend/antd/message/message.tsx#L55-L78) + +### Modal + +- Constructor parameters and properties + - after_close: string, callback after closing + - cancel_button_props/cancel_text: dict/string, cancel button properties and text + - centered: boolean, centered + - closable/close_icon: boolean/dict/string, closable and close icon + - confirm_loading: boolean, confirming + - destroy_on_close/destroy_on_hidden: boolean, destroy on close/hide + - focus_trigger_after_close: boolean, focus trigger after close + - focusable: boolean/dict, focusable + - footer: string or default constant, footer + - force_render: boolean, force render + - get_container: string, container selector + - keyboard: boolean, keyboard support + - mask/mask_closable: boolean, mask and click-to-close mask + - modal_render: string, render function + - ok_text/ok_type/ok_button_props: string/dict, OK button properties + - loading: boolean, loading + - title: string, title + - open: boolean, whether open + - width: number/string, width + - wrap_class_name: string, wrapper class name + - z_index: integer, z-index + - after_open_change: string, callback on open state change + - slots: supports closeIcon, cancelButtonProps.icon, cancelText, closable.closeIcon, closeIcon, footer, title, okButtonProps.icon, okText, modalRender +- Methods + - preprocess()/postprocess(): preprocessing/postprocessing + - example_payload()/example_value(): example data +- Events + - ok/cancel: confirm and cancel event binding +- Static sub-components + - Static: static modal component (for static scenarios) + +Section sources + +- [backend/modelscope_studio/components/antd/modal/**init**.py:34-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L34-L136) +- [backend/modelscope_studio/components/antd/modal/static/**init**.py:30-61](file://backend/modelscope_studio/components/antd/modal/static/__init__.py#L30-L61) + +### Notification + +- Constructor parameters and properties + - message/description/title: string, message, description, title + - type: text enum (success/info/warning/error), type + - btn: string, button + - close_icon: string/boolean, close icon + - duration: number, duration + - show_progress/pause_on_hover: boolean, progress bar and pause on hover + - icon: string, icon + - key: string, unique key + - placement: text enum (top/topLeft/topRight/bottom/bottomLeft/bottomRight), position + - role: text enum (alert/status), role + - bottom/top: number, margins + - rtl: boolean, right-to-left + - get_container: string, container selector + - stack: boolean/dict, stack configuration + - slots: supports actions, closeIcon, description, icon, message, title +- Methods + - preprocess()/postprocess(): preprocessing/postprocessing + - example_payload()/example_value(): example data +- Events + - click/close: click and close event binding + +Section sources + +- [backend/modelscope_studio/components/antd/notification/**init**.py:26-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L26-L109) + +### Popconfirm + +- Constructor parameters and properties + - title/description: string, title and description + - cancel_button_props/cancel_text: dict/string, cancel button + - disabled: boolean, disabled + - icon: string, icon + - ok_button_props/ok_text/ok_type: dict/string/enum, OK button + - show_cancel: boolean, show cancel + - align/arrow/auto_adjust_overflow: dict/boolean, positioning and auto-fit + - color: string, color + - default_open: boolean, initially open + - destroy_tooltip_on_hide/destroy_on_hidden: boolean, destroy strategy + - fresh: boolean, refresh + - get_popup_container: string, popup container + - mouse_enter_delay/mouse_leave_delay: number, delay + - overlay_class_name/overlay_style/overlay_inner_style: string/dict, overlay styles + - placement: text enum (multiple directions), position + - trigger: text enum or list (hover/focus/click/contextMenu), trigger method + - open: boolean, whether open + - z_index: integer, z-index + - slots: supports title, description, cancelButtonProps.icon, cancelText, okButtonProps.icon, okText +- Methods + - preprocess()/postprocess(): preprocessing/postprocessing + - example_payload()/example_value(): example data +- Events + - open_change/cancel/confirm/popup_click: open change, cancel, confirm, popup click event binding + +Section sources + +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:39-156](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L39-L156) + +### Progress + +- Constructor parameters and properties + - percent: integer, default 0, percentage + - format: string, format function + - show_info: boolean, show info + - status: text enum (success/exception/normal/active), status + - rounding: string, rounding + - stroke_color: string/list/dict, stroke color + - stroke_linecap: text enum (round/butt/square), line cap + - success: dict, success area + - trail_color: string, trail color + - type: text enum (line/circle/dashboard), type + - size: number/list/dict/enum (small/default), size + - steps: integer/dict, steps + - percent_position: dict, percent position + - stroke_width: number/float, stroke width + - gap_degree/gap_position/gap_placement: number/enum, gap degree and position +- Methods + - preprocess()/postprocess(): preprocessing/postprocessing + - example_payload()/example_value(): example data + +Section sources + +- [backend/modelscope_studio/components/antd/progress/**init**.py:15-100](file://backend/modelscope_studio/components/antd/progress/__init__.py#L15-L100) + +### Result + +- Constructor parameters and properties + - extra: string, extra content + - icon: string, icon + - status: text enum (success/error/info/warning/404/403/500), status + - sub_title: string, subtitle + - title: string, title + - slots: supports extra, icon, subTitle, title +- Methods + - preprocess()/postprocess(): preprocessing/postprocessing + - example_payload()/example_value(): example data + +Section sources + +- [backend/modelscope_studio/components/antd/result/**init**.py:17-75](file://backend/modelscope_studio/components/antd/result/__init__.py#L17-L75) + +### Skeleton + +- Constructor parameters and properties + - active: boolean, animation + - avatar: boolean/dict, avatar skeleton + - loading: boolean, loading + - paragraph: boolean/dict, paragraph skeleton + - round: boolean, rounded + - title: boolean/dict, title skeleton +- Sub-components + - Node/Avatar/Button/Image/Input: skeleton nodes and elements +- Methods + - preprocess()/postprocess(): preprocessing/postprocessing + - example_payload()/example_value(): example data + +Section sources + +- [backend/modelscope_studio/components/antd/skeleton/**init**.py:22-80](file://backend/modelscope_studio/components/antd/skeleton/__init__.py#L22-L80) + +### Spin + +- Constructor parameters and properties + - spinning: boolean, whether spinning + - delay: number, delay + - fullscreen: boolean, fullscreen + - indicator: string, indicator + - percent: number/float/enum ('auto'), percentage + - size: text enum (small/default/large), size + - tip: string, tip text + - wrapper_class_name: string, wrapper class name + - slots: supports tip, indicator +- Methods + - preprocess()/postprocess(): preprocessing/postprocessing + - example_payload()/example_value(): example data + +Section sources + +- [backend/modelscope_studio/components/antd/spin/**init**.py:17-79](file://backend/modelscope_studio/components/antd/spin/__init__.py#L17-L79) + +### Watermark + +- Constructor parameters and properties + - content: string/list, content (text or array) + - width/height: number/float, size + - inherit: boolean, inherit + - rotate: number/float, rotation angle + - z_index: integer, z-index + - image: string, image watermark + - font: dict, font configuration + - gap: list, gap + - offset: list, offset +- Methods + - preprocess()/postprocess(): preprocessing/postprocessing + - example_payload()/example_value(): example data +- Events + - remove: remove event binding + +Section sources + +- [backend/modelscope_studio/components/antd/watermark/**init**.py:18-84](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L18-L84) + +## Dependency Analysis + +- Component base classes + - ModelScopeLayoutComponent: layout-type component base class, supports events and slots + - ModelScopeComponent: data-type component base class, supports values and loading + - ModelScopeDataLayoutComponent: data+layout combined base class +- Exports and aliases + - Components are exported as public aliases via antd/**init**.py for direct import usage + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +class ModelScopeComponent { ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +class ModelScopeDataLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +class AntdAlert +class AntdDrawer +class AntdMessage +class AntdModal +class AntdNotification +class AntdPopconfirm +class AntdProgress +class AntdResult +class AntdSkeleton +class AntdSpin +class AntdWatermark +ModelScopeLayoutComponent <|-- AntdAlert +ModelScopeLayoutComponent <|-- AntdDrawer +ModelScopeLayoutComponent <|-- AntdMessage +ModelScopeLayoutComponent <|-- AntdModal +ModelScopeLayoutComponent <|-- AntdNotification +ModelScopeLayoutComponent <|-- AntdPopconfirm +ModelScopeLayoutComponent <|-- AntdResult +ModelScopeLayoutComponent <|-- AntdSkeleton +ModelScopeLayoutComponent <|-- AntdSpin +ModelScopeLayoutComponent <|-- AntdWatermark +ModelScopeComponent <|-- AntdProgress +ModelScopeDataLayoutComponent <|-- AntdSkeleton +``` + +Chart sources + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/antd/alert/**init**.py:11-15](file://backend/modelscope_studio/components/antd/alert/__init__.py#L11-L15) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:10-13](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L10-L13) +- [backend/modelscope_studio/components/antd/message/**init**.py:10-13](file://backend/modelscope_studio/components/antd/message/__init__.py#L10-L13) +- [backend/modelscope_studio/components/antd/modal/**init**.py:11-16](file://backend/modelscope_studio/components/antd/modal/__init__.py#L11-L16) +- [backend/modelscope_studio/components/antd/notification/**init**.py:10-13](file://backend/modelscope_studio/components/antd/notification/__init__.py#L10-L13) +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:10-13](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L10-L13) +- [backend/modelscope_studio/components/antd/progress/**init**.py:8-11](file://backend/modelscope_studio/components/antd/progress/__init__.py#L8-L11) +- [backend/modelscope_studio/components/antd/result/**init**.py:8-11](file://backend/modelscope_studio/components/antd/result/__init__.py#L8-L11) +- [backend/modelscope_studio/components/antd/skeleton/**init**.py:11-14](file://backend/modelscope_studio/components/antd/skeleton/__init__.py#L11-L14) +- [backend/modelscope_studio/components/antd/spin/**init**.py:8-11](file://backend/modelscope_studio/components/antd/spin/__init__.py#L8-L11) +- [backend/modelscope_studio/components/antd/watermark/**init**.py:8-11](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L8-L11) + +Section sources + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) + +## Performance Considerations + +- Event binding and callbacks + - Bind callbacks at construction time via the EVENTS list to avoid the overhead of repeated binding at runtime +- Rendering strategy + - destroy_on_close/destroy_on_hidden: destroy on close or hide to reduce memory usage + - force_render: force render on demand to avoid unnecessary re-renders +- Animation and transitions + - Control visual feedback and performance balance through frontend component animation configurations (e.g., Spin's delay, Progress's active) +- Global components + - Message/Notification use context management to avoid frequent creation and destruction of instances + +## Troubleshooting Guide + +- Events not triggered + - Check that the EVENTS list and callback bindings are correct + - Confirm that the frontend component has correctly received and forwarded events +- Display issues + - Check state parameters such as visible, render, open + - For global components (Message/Notification), confirm container selectors and mount targets +- Theme and internationalization not taking effect + - Confirm ConfigProvider's locale and themeMode settings + - Check that the language pack in locales.ts is available + +Section sources + +- [backend/modelscope_studio/components/antd/alert/**init**.py:16-20](file://backend/modelscope_studio/components/antd/alert/__init__.py#L16-L20) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:14-18](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L14-L18) +- [backend/modelscope_studio/components/antd/message/**init**.py:14-21](file://backend/modelscope_studio/components/antd/message/__init__.py#L14-L21) +- [backend/modelscope_studio/components/antd/modal/**init**.py:18-25](file://backend/modelscope_studio/components/antd/modal/__init__.py#L18-L25) +- [backend/modelscope_studio/components/antd/notification/**init**.py:14-21](file://backend/modelscope_studio/components/antd/notification/__init__.py#L14-L21) +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:14-27](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L14-L27) +- [backend/modelscope_studio/components/antd/watermark/**init**.py:12-16](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L12-L16) +- [frontend/antd/config-provider/config-provider.tsx:51-106](file://frontend/antd/config-provider/config-provider.tsx#L51-L106) +- [frontend/antd/config-provider/locales.ts:159-806](file://frontend/antd/config-provider/locales.ts#L159-L806) + +## Conclusion + +This reference document covers the Python API, frontend integration, and global configuration essentials for feedback components. In practice, it is recommended to: + +- Clarify component responsibilities and applicable scenarios (alerts, dialogs, progress, skeleton, loading, watermark) +- Set event and lifecycle parameters appropriately to ensure smooth interactions +- Use ConfigProvider for unified theme and internationalization management +- Follow notification strategies and UX design principles to avoid excessive interruptions + +## Appendix + +- Usage examples (provided as "example paths") + - Message: see [docs/components/antd/message/README-zh_CN.md:1-8](file://docs/components/antd/message/README-zh_CN.md#L1-L8) + - Notification: see [docs/components/antd/notification/README-zh_CN.md:1-8](file://docs/components/antd/notification/README-zh_CN.md#L1-L8) +- Global configuration and internationalization + - ConfigProvider: see [frontend/antd/config-provider/config-provider.tsx:51-106](file://frontend/antd/config-provider/config-provider.tsx#L51-L106) + - Language packs: see [frontend/antd/config-provider/locales.ts:159-806](file://frontend/antd/config-provider/locales.ts#L159-L806) diff --git a/.wiki/en/API Reference/Python API/Antd Components API/General Components API.md b/.wiki/en/API Reference/Python API/Antd Components API/General Components API.md new file mode 100644 index 00000000..6afa4888 --- /dev/null +++ b/.wiki/en/API Reference/Python API/Antd Components API/General Components API.md @@ -0,0 +1,370 @@ +# General Components API + + +**Files Referenced in This Document** +- [button/__init__.py](file://backend/modelscope_studio/components/antd/button/__init__.py) +- [float_button/__init__.py](file://backend/modelscope_studio/components/antd/float_button/__init__.py) +- [icon/__init__.py](file://backend/modelscope_studio/components/antd/icon/__init__.py) +- [typography/__init__.py](file://backend/modelscope_studio/components/antd/typography/__init__.py) +- [affix/__init__.py](file://backend/modelscope_studio/components/antd/affix/__init__.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the Python API reference for Antd general components, covering Button, FloatButton, Icon, Typography, and Affix. Contents include: + +- Constructor parameters, property definitions, method signatures, and return types for each component class +- Standard instantiation examples (basic usage and advanced configuration) +- Event handling mechanisms, style customization approaches, and responsive behavior +- Parameter validation rules, exception handling strategies, and best practices +- API index organized by function for quick reference + +## Project Structure + +These components all reside in the backend Python package, wrapped through a unified layout component base class, pointing to corresponding frontend directories for UI rendering. + +```mermaid +graph TB +subgraph "Python Backend" +A["AntdButton
Constructor Parameters/Properties/Methods"] +B["AntdFloatButton
Constructor Parameters/Properties/Methods"] +C["AntdIcon
Constructor Parameters/Properties/Methods"] +D["AntdTypography
Aggregator: Text/Title/Paragraph/Link"] +E["AntdAffix
Constructor Parameters/Properties/Methods"] +end +subgraph "Frontend Directories" +F["button frontend directory"] +G["float-button frontend directory"] +H["icon frontend directory"] +I["typography frontend directory"] +J["affix frontend directory"] +end +A --> F +B --> G +C --> H +D --> I +E --> J +``` + +Diagram sources + +- [button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) +- [float_button/**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) +- [typography/**init**.py:1-12](file://backend/modelscope_studio/components/antd/typography/__init__.py#L1-L12) +- [affix/**init**.py:10-86](file://backend/modelscope_studio/components/antd/affix/__init__.py#L10-L86) + +Section sources + +- [button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) +- [float_button/**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) +- [typography/**init**.py:1-12](file://backend/modelscope_studio/components/antd/typography/__init__.py#L1-L12) +- [affix/**init**.py:10-86](file://backend/modelscope_studio/components/antd/affix/__init__.py#L10-L86) + +## Core Components + +This section provides an overview of the five general components' responsibilities and typical use cases: + +- **Button**: Triggers actions; supports multiple types, variants, sizes, shapes, and states (disabled, danger, ghost, loading). +- **FloatButton**: Floating global function button; can include description, tooltip, badge, and link. +- **Icon**: Semantic vector icon; supports rotation, spin animation, and dual-tone icon color settings. +- **Typography**: Text typography collection; contains Text, Title, Paragraph, and Link sub-components. +- **Affix**: Fixed position container; used to stick child elements to the top or bottom of the viewport. + +Section sources + +- [button/**init**.py:15-38](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L38) +- [float_button/**init**.py:12-21](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L21) +- [icon/**init**.py:9-14](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L14) +- [typography/**init**.py:7-12](file://backend/modelscope_studio/components/antd/typography/__init__.py#L7-L12) +- [affix/**init**.py:10-20](file://backend/modelscope_studio/components/antd/affix/__init__.py#L10-L20) + +## Architecture Overview + +Components follow the "Python wrapper + frontend rendering" pattern, injecting common properties (visibility, DOM ID, class names, inline styles, render toggle, etc.) through the unified layout component base class, and pointing to the corresponding frontend directory via `resolve_frontend_dir`. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Py as "AntdButton/AntdFloatButton/AntdIcon/AntdAffix" +participant Base as "ModelScopeLayoutComponent/ModelScopeDataLayoutComponent" +participant FE as "Frontend Component Directory" +Dev->>Py : Instantiate component with parameters +Py->>Base : Call parent constructor, inject common properties +Py->>FE : Set FRONTEND_DIR pointing to corresponding frontend directory +Base-->>Dev : Return renderable component object +``` + +Diagram sources + +- [button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) +- [float_button/**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) +- [affix/**init**.py:10-86](file://backend/modelscope_studio/components/antd/affix/__init__.py#L10-L86) + +## Detailed Component Analysis + +### Button Component API + +- Type and inheritance + - Class name: `AntdButton` + - Base class: `ModelScopeLayoutComponent` + - Nested sub-component: `Group` (button group) +- Events + - `click`: Click event; binds internal callback to enable event listening +- Slots + - `icon`, `loading.icon` +- Key properties and meanings + - `auto_insert_space`: Whether to automatically insert a space between Chinese characters + - `block`: Whether to span the full width of the parent container + - `class_names`: Semantic DOM class names + - `danger`/`disabled`/`ghost`/`loading`: Danger/disabled/ghost/loading states + - `href`/`html_type`: Link navigation and native HTML type + - `icon`/`icon_position`: Icon and icon position + - `shape`/`size`/`type`/`variant`/`color`: Shape, size, type, variant, color + - `styles`/`root_class_name`: Semantic styles and root class name + - Other Gradio common properties: `visible`, `elem_id`, `elem_classes`, `elem_style`, `render` +- Methods + - `preprocess(payload)`: Accepts string or None, returns string or None + - `postprocess(value)`: Accepts string or None, returns string or None + - `example_payload`/`example_value`: Example payload and example value +- Instantiation notes + - Use `type`/`variant`/`color`/`shape`/`size` to control appearance and semantics + - `loading` can be boolean or dict (if custom loading icon is needed) + - `href` works with `html_type='button'` or `'submit'`/`'reset'` +- Best practices + - Use `primary` type for main actions; use `danger` for destructive actions + - Set `loading` to prevent duplicate submissions + - For icon buttons, use `icon_position='start'`/`'end'` + +Section sources + +- [button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) + +### FloatButton Component API + +- Type and inheritance + - Class name: `AntdFloatButton` + - Base class: `ModelScopeLayoutComponent` + - Nested sub-components: `BackTop` (back to top), `Group` (button group) +- Events + - `click`: Click event; binds internal callback to enable event listening +- Slots + - `icon`, `description`, `tooltip`, `tooltip.title`, `badge.count` +- Key properties and meanings + - `icon`/`description`: Icon and description text + - `tooltip`: Tooltip text or configuration object + - `type`/`shape`: Type (default/primary), shape (circle/square) + - `href`/`href_target`/`html_type`: Hyperlink target and native HTML type + - `badge`: Badge configuration (some state-related properties not supported) + - `class_names`/`styles`/`root_class_name`: Styles and class names + - Other Gradio common properties: `visible`, `elem_id`, `elem_classes`, `elem_style`, `render` +- Methods + - `preprocess(payload)`: Accepts None, returns None + - `postprocess(value)`: Accepts None, returns None + - `example_payload`/`example_value`: Example payload and example value +- Instantiation notes + - Commonly used for global function entry points (e.g., back to top, quick actions) + - `tooltip` supports strings or objects to extend title, etc. +- Best practices + - Use `circle` shape to improve discoverability + - Combine with `BackTop` for "back to top" experience + +Section sources + +- [float_button/**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) + +### Icon Component API + +- Type and inheritance + - Class name: `AntdIcon` + - Base class: `ModelScopeDataLayoutComponent` + - Nested sub-component: `IconfontProvider` (IconFont provider) +- Events + - `click`: Click event; binds internal callback to enable event listening +- Slots + - `component`: Custom root node component +- Key properties and meanings + - `value`: Default icon name (e.g., `"GithubOutlined"`) + - `spin`: Whether to apply spin animation + - `rotate`: Rotation angle (degrees) + - `two_tone_color`: Primary color for dual-tone icons + - `component`: Root node component replacement + - `class_names`/`styles`: Styles and class names + - Other Gradio common properties: `visible`, `elem_id`, `elem_classes`, `elem_style`, `render` +- Methods + - `preprocess(payload)`: Accepts string or None, returns string or None + - `postprocess(value)`: Accepts string or None, returns string or None + - `example_payload`/`example_value`: Example payload and example value +- Instantiation notes + - When used as decorative elements, prefer semantic icon names + - `spin` and `rotate` can be used in combination +- Best practices + - Use in buttons or navigation with `icon_position` + - Explicitly specify the primary color for dual-tone icon scenarios + +Section sources + +- [icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) + +### Typography Component API + +- Type and inheritance + - Class name: `AntdTypography` + - Aggregator: Contains four sub-components: `Text`, `Title`, `Paragraph`, `Link` +- Notes + - This aggregator class only exports sub-components; specific sub-component definitions are in their respective modules +- Instantiation notes + - Access sub-components via `AntdTypography.Text`/`Title`/`Paragraph`/`Link` +- Best practices + - Use `Title` for documents and page headings + - Use `Paragraph` for body text + - Use `Link` for clickable links + +Section sources + +- [typography/**init**.py:1-12](file://backend/modelscope_studio/components/antd/typography/__init__.py#L1-L12) + +### Affix Component API + +- Type and inheritance + - Class name: `AntdAffix` + - Base class: `ModelScopeLayoutComponent` +- Events + - `change`: State change event (attached/detached); binds internal callback to enable event listening +- Key properties and meanings + - `offset_bottom`: Offset from the bottom of the viewport (pixels) + - `offset_top`: Offset from the top of the viewport (pixels) + - `get_target`: Specifies the scroll area DOM node selector + - `class_names`/`styles`/`root_class_name`: Styles and class names + - Other Gradio common properties: `visible`, `elem_id`, `elem_classes`, `elem_style`, `render` +- Methods + - `preprocess(payload)`: Accepts None, returns None + - `postprocess(value)`: Accepts None, returns None + - `example_payload`/`example_value`: Example payload and example value +- Instantiation notes + - Be careful not to block other page content, especially on small-screen devices + - `get_target` can restrict the scroll container to avoid global scroll interference +- Best practices + - Use for menus, toolbars, and other elements that need to remain in the visible area + - Combine with interaction feedback (e.g., `change` event) to update state + +Section sources + +- [affix/**init**.py:10-86](file://backend/modelscope_studio/components/antd/affix/__init__.py#L10-L86) + +## Dependency Analysis + +- Common dependencies + - Base class: `ModelScopeLayoutComponent` or `ModelScopeDataLayoutComponent` + - Event system: `gradio.events.EventListener` + - Frontend directory resolution: `resolve_frontend_dir` +- Inter-component relationships + - Button: Contains `ButtonGroup` + - FloatButton: Contains `BackTop` and `FloatButtonGroup` + - Icon: Contains `IconfontProvider` + - Typography: Aggregates `Text`/`Title`/`Paragraph`/`Link` +- Dependency visualization + +```mermaid +graph LR +subgraph "Events and Base Classes" +EL["EventListener"] +LCB["ModelScopeLayoutComponent"] +DLCB["ModelScopeDataLayoutComponent"] +end +BTN["AntdButton"] --> LCB +BTN --> EL +BTN --> |"resolve_frontend_dir('button')"| FE_BTN["button frontend directory"] +FLT["AntdFloatButton"] --> LCB +FLT --> EL +FLT --> |"resolve_frontend_dir('float-button')"| FE_FLT["float-button frontend directory"] +ICO["AntdIcon"] --> DLCB +ICO --> EL +ICO --> |"resolve_frontend_dir('icon')"| FE_ICO["icon frontend directory"] +TYP["AntdTypography"] --> |"exports Text/Title/Paragraph/Link"| SUB["Sub-components"] +AFF["AntdAffix"] --> LCB +AFF --> EL +AFF --> |"resolve_frontend_dir('affix')"| FE_AFF["affix frontend directory"] +``` + +Diagram sources + +- [button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) +- [float_button/**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) +- [typography/**init**.py:1-12](file://backend/modelscope_studio/components/antd/typography/__init__.py#L1-L12) +- [affix/**init**.py:10-86](file://backend/modelscope_studio/components/antd/affix/__init__.py#L10-L86) + +## Performance Considerations + +- Rendering and events + - Control rendering timing and visibility via Gradio common properties to reduce unnecessary redraws + - Enable event binding only when needed (e.g., `click`/`change`) to avoid excessive monitoring +- Icons and loading + - Use `spin`/`rotate` judiciously to avoid extra overhead on low-end devices + - Button's `loading` state prevents duplicate submissions, indirectly reducing server load +- Containers and scrolling + - Affix's `get_target` should be as precise as possible to avoid frequent calculations on large scroll containers +- Recommendations + - Use heavy components (e.g., Tooltip/Popover) sparingly in large lists; use lazy loading if necessary + - Maintain consistency when using appearance properties like `shape`/`size`/`type` to reduce style switching costs + +## Troubleshooting Guide + +- Events not triggering + - Confirm `EVENTS` is correctly configured and components are in an interactive state (not `disabled`/`loading`) + - For FloatButton/Affix, check that `click`/`change` events are bound +- Styles not taking effect + - Check whether `class_names`/`styles` conflicts with theme variables + - Confirm `root_class_name` is not overridden by external styles +- Icon display anomalies + - Confirm `value` is a supported icon name + - If using a custom `component`, ensure the component is renderable and has no circular dependencies +- Floating button blocking content + - Adjust `offset_top`/`offset_bottom` or use `get_target` to precisely control the scroll area +- Loading state not working + - When Button's `loading` is boolean or dict, confirm the parameter format is correct + +Section sources + +- [button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) +- [float_button/**init**.py:24-29](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L24-L29) +- [affix/**init**.py:21-26](file://backend/modelscope_studio/components/antd/affix/__init__.py#L21-L26) + +## Conclusion + +The above covers the Python API reference and best practice summary for Antd general components. Through a unified base class and event system, these components provide rich appearance and interaction capabilities while remaining simple and easy to use. It is recommended to choose component types and configuration options appropriate for the business scenario in real projects, paying attention to performance and maintainability. + +## Appendix + +- API index by category + - Button components: `AntdButton` (with `Group`), `AntdFloatButton` (with `BackTop`/`Group`) + - Icon components: `AntdIcon` (with `IconfontProvider`) + - Text typography: `AntdTypography` (`Text`/`Title`/`Paragraph`/`Link`) + - Positioning containers: `AntdAffix` +- Quick parameter reference + - Appearance: `type`, `variant`, `color`, `shape`, `size` + - State: `disabled`, `danger`, `ghost`, `loading` + - Behavior: `href`, `html_type`, `icon`, `icon_position`, `tooltip`, `badge` + - Style: `class_names`, `styles`, `root_class_name` + - Events: `click`, `change` +- Example path guide (no code content) + - Button basic usage and loading state: [button/**init**.py:88-108](file://backend/modelscope_studio/components/antd/button/__init__.py#L88-L108) + - FloatButton floating entry with back-to-top combination: [float_button/**init**.py:59-70](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L59-L70) + - Icon animation and dual-tone: [icon/**init**.py:47-53](file://backend/modelscope_studio/components/antd/icon/__init__.py#L47-L53) + - Affix positioning and scroll area: [affix/**init**.py:47-52](file://backend/modelscope_studio/components/antd/affix/__init__.py#L47-L52) diff --git a/.wiki/en/API Reference/Python API/Antd Components API/Layout Components API.md b/.wiki/en/API Reference/Python API/Antd Components API/Layout Components API.md new file mode 100644 index 00000000..4f76af5a --- /dev/null +++ b/.wiki/en/API Reference/Python API/Antd Components API/Layout Components API.md @@ -0,0 +1,439 @@ +# Layout Components API + + +**Files Referenced in This Document** +- [divider/__init__.py](file://backend/modelscope_studio/components/antd/divider/__init__.py) +- [flex/__init__.py](file://backend/modelscope_studio/components/antd/flex/__init__.py) +- [grid/row/__init__.py](file://backend/modelscope_studio/components/antd/grid/row/__init__.py) +- [grid/col/__init__.py](file://backend/modelscope_studio/components/antd/grid/col/__init__.py) +- [layout/__init__.py](file://backend/modelscope_studio/components/antd/layout/__init__.py) +- [layout/content/__init__.py](file://backend/modelscope_studio/components/antd/layout/content/__init__.py) +- [layout/footer/__init__.py](file://backend/modelscope_studio/components/antd/layout/footer/__init__.py) +- [layout/header/__init__.py](file://backend/modelscope_studio/components/antd/layout/header/__init__.py) +- [layout/sider/__init__.py](file://backend/modelscope_studio/components/antd/layout/sider/__init__.py) +- [space/__init__.py](file://backend/modelscope_studio/components/antd/space/__init__.py) +- [space/compact/__init__.py](file://backend/modelscope_studio/components/antd/space/compact/__init__.py) +- [splitter/__init__.py](file://backend/modelscope_studio/components/antd/splitter/__init__.py) +- [splitter/panel/__init__.py](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the Python API reference for Antd layout components, covering Divider, Flex, Grid (Row/Col), Layout (Layout/Header/Sider/Content/Footer), Space, and Splitter (Splitter/Panel). Contents include: + +- Constructor parameters, property definitions, method signatures, and return types for each component class +- Standard layout combination usage examples (responsive layout, grid system, flex layout) +- Nesting rules, spacing control, and alignment +- Layout breakpoint configuration, media query integration, and mobile adaptation +- Component collaboration patterns and performance optimization recommendations + +## Project Structure + +These layout components all reside in the backend Python package, using a unified base class and frontend directory resolution mechanism, allowing them to map to the corresponding frontend implementations at runtime. + +```mermaid +graph TB +subgraph "Antd Layout Components" +D["Divider"] +F["Flex"] +G["Grid
Row/Col"] +L["Layout
Layout/Header/Sider/Content/Footer"] +S["Space
Space/Compact"] +SP["Splitter
Splitter/Panel"] +end +D --> |"uses"| D +F --> |"uses"| F +G --> |"uses"| G +L --> |"contains"| L +S --> |"uses"| S +SP --> |"contains"| SP +``` + +**Diagram sources** + +- [divider/**init**.py:1-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L1-L95) +- [flex/**init**.py:1-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L1-L98) +- [grid/row/**init**.py:1-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L1-L94) +- [grid/col/**init**.py:1-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L1-L114) +- [layout/**init**.py:1-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L1-L91) +- [layout/content/**init**.py:1-75](file://backend/modelscope_studio/components/antd/layout/content/__init__.py#L1-L75) +- [layout/footer/**init**.py:1-75](file://backend/modelscope_studio/components/antd/layout/footer/__init__.py#L1-L75) +- [layout/header/**init**.py:1-75](file://backend/modelscope_studio/components/antd/layout/header/__init__.py#L1-L75) +- [layout/sider/**init**.py:1-128](file://backend/modelscope_studio/components/antd/layout/sider/__init__.py#L1-L128) +- [space/**init**.py:1-104](file://backend/modelscope_studio/components/antd/space/__init__.py#L1-L104) +- [space/compact/**init**.py:1-81](file://backend/modelscope_studio/components/antd/space/compact/__init__.py#L1-L81) +- [splitter/**init**.py:1-97](file://backend/modelscope_studio/components/antd/splitter/__init__.py#L1-L97) +- [splitter/panel/**init**.py:1-86](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L1-L86) + +**Section sources** + +- [divider/**init**.py:1-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L1-L95) +- [flex/**init**.py:1-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L1-L98) +- [grid/row/**init**.py:1-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L1-L94) +- [grid/col/**init**.py:1-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L1-L114) +- [layout/**init**.py:1-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L1-L91) +- [space/**init**.py:1-104](file://backend/modelscope_studio/components/antd/space/__init__.py#L1-L104) +- [splitter/**init**.py:1-97](file://backend/modelscope_studio/components/antd/splitter/__init__.py#L1-L97) + +## Core Components + +- **Divider**: A dividing line for separating content areas; supports horizontal/vertical, title position, dashed/solid style, plain text style, etc. +- **Flex**: A flex layout container; supports main-axis/cross-axis alignment, wrapping, spacing, direction, etc. +- **Grid**: Grid system; Row provides row-level alignment, spacing, and wrapping; Col provides column span, offset, order, responsive breakpoints, etc. +- **Layout**: Overall page layout; contains Header, Sider, Content, Footer sub-components; supports responsive collapse and breakpoint events. +- **Space**: Sets spacing between child elements; supports direction, alignment, auto-wrap, separator; `Space.Compact` is used for compact form arrangements. +- **Splitter**: Draggable split panel; supports horizontal/vertical layout, panel size range, collapse, and drag events. + +**Section sources** + +- [divider/**init**.py:8-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L8-L95) +- [flex/**init**.py:8-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L8-L98) +- [grid/row/**init**.py:8-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L8-L94) +- [grid/col/**init**.py:8-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L8-L114) +- [layout/**init**.py:14-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L14-L91) +- [space/**init**.py:9-104](file://backend/modelscope_studio/components/antd/space/__init__.py#L9-L104) +- [splitter/**init**.py:11-97](file://backend/modelscope_studio/components/antd/splitter/__init__.py#L11-L97) + +## Architecture Overview + +The following class diagram shows the inheritance and composition relationships of layout components, as well as key properties and methods. + +```mermaid +classDiagram +class AntdDivider { ++__init__(value, dashed, variant, orientation, orientation_margin, plain, type, size, ...) ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdFlex { ++__init__(orientation, vertical, wrap, justify, align, flex, gap, component, ...) ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdRow { ++__init__(align, gutter, justify, wrap, ...) +} +class AntdCol { ++__init__(flex, offset, order, pull, push, span, xs, sm, md, lg, xl, xxl, ...) +} +class AntdLayout { ++__init__(has_sider, ...) ++Content ++Footer ++Header ++Sider +} +class AntdLayoutContent +class AntdLayoutFooter +class AntdLayoutHeader +class AntdLayoutSider { ++__init__(breakpoint, collapsed, collapsed_width, collapsible, default_collapsed, reverse_arrow, theme_value, trigger, width, ...) +} +class AntdSpace { ++__init__(align, direction/orientation, size, split/separator, wrap, ...) ++Compact +} +class AntdSpaceCompact { ++__init__(block, direction, size, ...) +} +class AntdSplitter { ++__init__(layout/orientation, lazy, ...) ++Panel +} +class AntdSplitterPanel { ++__init__(default_size, min, max, size, collapsible, resizable, ...) +} +AntdLayout --> AntdLayoutContent : "contains" +AntdLayout --> AntdLayoutFooter : "contains" +AntdLayout --> AntdLayoutHeader : "contains" +AntdLayout --> AntdLayoutSider : "contains" +AntdSpace --> AntdSpaceCompact : "contains" +AntdSplitter --> AntdSplitterPanel : "contains" +``` + +**Diagram sources** + +- [divider/**init**.py:8-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L8-L95) +- [flex/**init**.py:8-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L8-L98) +- [grid/row/**init**.py:8-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L8-L94) +- [grid/col/**init**.py:8-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L8-L114) +- [layout/**init**.py:14-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L14-L91) +- [layout/sider/**init**.py:11-128](file://backend/modelscope_studio/components/antd/layout/sider/__init__.py#L11-L128) +- [space/**init**.py:9-104](file://backend/modelscope_studio/components/antd/space/__init__.py#L9-L104) +- [splitter/**init**.py:11-97](file://backend/modelscope_studio/components/antd/splitter/__init__.py#L11-L97) +- [splitter/panel/**init**.py:8-86](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L8-L86) + +## Detailed Component Analysis + +### Divider + +- Constructor parameters + - `value`: Optional string as the title text inside the divider + - `dashed`: Optional boolean, whether to use dashed line + - `variant`: Enum value, `'dashed'` | `'dotted'` | `'solid'` + - `orientation`: Enum value, `'left'` | `'right'` | `'center'` | `'start'` | `'end'` + - `orientation_margin`: Optional string or number, margin between title and boundary + - `plain`: Optional boolean, plain text style + - `type`: Enum value, `'horizontal'` | `'vertical'` + - `size`: Optional enum value, `'small'` | `'middle'` | `'large'` (only valid for horizontal) + - Other common properties: `root_class_name`, `class_names`, `styles`, `as_item`, `elem_id`, `elem_classes`, `elem_style`, `visible`, `render`, etc. +- Methods + - `preprocess(payload)`: Accepts string or None, returns string or None + - `postprocess(value)`: Accepts string or None, returns string or None + - `example_payload`/`example_value`: Returns None +- Use cases + - Separating article paragraphs, table action columns, etc. + +**Section sources** + +- [divider/**init**.py:21-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L21-L95) + +### Flex (Flex Layout) + +- Constructor parameters + - `orientation`: Enum value, `'horizontal'` | `'vertical'` + - `vertical`: Boolean, vertical direction (equivalent to `flex-direction: column`) + - `wrap`: Enum value or boolean, `'nowrap'` | `'wrap'` | `'wrap-reverse'` or boolean + - `justify`: Main-axis alignment (various values) + - `align`: Cross-axis alignment (various values) + - `flex`: Flex shorthand property + - `gap`: Spacing size, supports enum or number + - `component`: Custom element type + - Other common properties as above +- Methods + - `preprocess`/`postprocess`: Accepts/returns None + - `example_payload`/`example_value`: Returns None +- Use cases + - Setting element spacing and alignment as a replacement for traditional CSS flex layout + +**Section sources** + +- [flex/**init**.py:21-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L21-L98) + +### Grid (Grid System) + +- Row + - Constructor parameters + - `align`: Vertical alignment, `'top'` | `'middle'` | `'bottom'` | `'stretch'` or object + - `gutter`: Grid spacing, supports number, string, object, or array + - `justify`: Horizontal arrangement, various values + - `wrap`: Boolean, auto wrap + - Other common properties as above + - Methods + - `preprocess`/`postprocess`: Accepts/returns None + - `example_payload`/`example_value`: Returns None +- Col + - Constructor parameters + - `flex`: Flex layout style + - `offset`: Number of grid columns to offset to the right + - `order`: Sort order + - `pull`/`push`: Move left/right + - `span`: Number of grid columns to occupy (0 corresponds to `display: none`) + - `xs`/`sm`/`md`/`lg`/`xl`/`xxl`: Span at different breakpoints or objects containing the above properties + - Other common properties as above + - Methods + - `preprocess`/`postprocess`: Accepts/returns None + - `example_payload`/`example_value`: Returns None +- Use cases + - Responsive layout based on 24-column grid; supports horizontal/vertical alignment, spacing, and breakpoints + +**Section sources** + +- [grid/row/**init**.py:30-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L30-L94) +- [grid/col/**init**.py:30-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L30-L114) + +### Layout (Page Layout) + +- Layout + - Nested sub-components: `Content`, `Footer`, `Header`, `Sider` + - Constructor parameters + - `has_sider`: Whether to include a sidebar (avoids SSR flickering) + - Other common properties as above + - Methods + - `preprocess`/`postprocess`: Accepts/returns None + - `example_payload`/`example_value`: Returns None +- Header/Footer/Content + - Constructor parameters: `class_names`, `styles`, `additional_props`, `root_class_name`, `elem_id`, `elem_classes`, `elem_style`, `visible`, `render`, etc. + - Methods: Same as above +- Sider + - Constructor parameters + - `breakpoint`: Responsive breakpoint + - `collapsed`/`collapsible`/`default_collapsed`: Collapse state related + - `collapsed_width`: Width when collapsed + - `reverse_arrow`: Reverse arrow direction (expands to the right) + - `theme_value`: Theme (light/dark); use when conflicting with Gradio preset attribute + - `trigger`: Custom trigger + - `width`: Width + - `zero_width_trigger_style`: Special trigger style when `collapsed_width` is 0 + - Other common properties as above + - Methods: Same as above +- Events + - Layout/Sider/Header/Footer/Content: Support `click` event binding + - Sider: Supports `collapse`, `breakpoint` events +- Use cases + - Overall page layout; combined with Sider for sidebar navigation and responsive collapse + +**Section sources** + +- [layout/**init**.py:14-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L14-L91) +- [layout/content/**init**.py:10-75](file://backend/modelscope_studio/components/antd/layout/content/__init__.py#L10-L75) +- [layout/footer/**init**.py:10-75](file://backend/modelscope_studio/components/antd/layout/footer/__init__.py#L10-L75) +- [layout/header/**init**.py:10-75](file://backend/modelscope_studio/components/antd/layout/header/__init__.py#L10-L75) +- [layout/sider/**init**.py:11-128](file://backend/modelscope_studio/components/antd/layout/sider/__init__.py#L11-L128) + +### Space + +- Space + - Nested sub-component: `Compact` + - Constructor parameters + - `align`: Child item alignment + - `direction`/`orientation`: Direction (`orientation` is v6 alias) + - `size`: Spacing size, supports enum, number, or array + - `split`/`separator`: Separator (`separator` is v6 alias) + - `wrap`: Auto wrap when horizontal + - Other common properties as above + - Methods + - `preprocess`/`postprocess`: Accepts/returns None + - `example_payload`/`example_value`: Returns None +- Space.Compact + - Constructor parameters + - `block`: Whether to fill parent width + - `direction`: Direction + - `size`: Child component size + - Other common properties as above + - Methods: Same as above +- Use cases + - Equal spacing arrangement of multiple inline elements; use `Compact` for compact form connections + +**Section sources** + +- [space/**init**.py:9-104](file://backend/modelscope_studio/components/antd/space/__init__.py#L9-L104) +- [space/compact/**init**.py:8-81](file://backend/modelscope_studio/components/antd/space/compact/__init__.py#L8-L81) + +### Splitter (Split Panel) + +- Splitter + - Nested sub-component: `Panel` + - Constructor parameters + - `layout`/`orientation`: Layout direction (`orientation` is v6 alias) + - `lazy`: Whether to use lazy rendering + - Other common properties as above + - Events + - `resize_start`, `resize`, `resize_end`, `collapse` + - Methods + - `preprocess`/`postprocess`: Accepts/returns None + - `example_payload`/`example_value`: Returns None +- Splitter.Panel + - Constructor parameters + - `default_size`/`min`/`max`/`size`: Initial/minimum/maximum/controlled size (supports px or percentage) + - `collapsible`: Quick collapse + - `resizable`: Whether to enable drag-and-drop + - Other common properties as above + - Methods: Same as above +- Use cases + - Divides the page into multiple draggable and resizable areas; supports collapse and range restrictions + +**Section sources** + +- [splitter/**init**.py:11-97](file://backend/modelscope_studio/components/antd/splitter/__init__.py#L11-L97) +- [splitter/panel/**init**.py:8-86](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L8-L86) + +## Dependency Analysis + +- Common component characteristics + - All inherit from the unified layout component base class, with the same preprocessing/postprocessing interface and common properties (e.g., `visible`, `elem_id`, `elem_classes`, `elem_style`, `render`, etc.) + - Locate corresponding frontend component implementations via the frontend directory resolution function +- Inter-component coupling + - Layout acts as the root container, internally composing Header/Sider/Content/Footer + - Space and Flex are semantically complementary: Space focuses on "spacing", Flex focuses on "layout" + - Grid's Row/Col can be combined with Flex/Splitter to achieve complex layouts + - Splitter can work with Space/Divider to implement panel separation and spacing control + +```mermaid +graph LR +L["Layout"] --> H["Header"] +L --> SD["Sider"] +L --> C["Content"] +L --> F["Footer"] +G["Grid.Row"] --> GC["Grid.Col"] +Fx["Flex"] -.-> G +Sp["Space"] -.-> G +Spp["Splitter"] -.-> G +Dv["Divider"] -.-> G +``` + +**Diagram sources** + +- [layout/**init**.py:28-31](file://backend/modelscope_studio/components/antd/layout/__init__.py#L28-L31) +- [grid/row/**init**.py:1-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L1-L94) +- [grid/col/**init**.py:1-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L1-L114) +- [flex/**init**.py:1-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L1-L98) +- [space/**init**.py:1-104](file://backend/modelscope_studio/components/antd/space/__init__.py#L1-L104) +- [splitter/**init**.py:1-97](file://backend/modelscope_studio/components/antd/splitter/__init__.py#L1-L97) +- [divider/**init**.py:1-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L1-L95) + +## Performance Considerations + +- Use lazy loading and deferred rendering appropriately: Splitter supports `lazy` to avoid unnecessary panel initialization +- Control the number of event bindings: Layout/Sider event callbacks should be enabled on demand to reduce unnecessary DOM updates +- Choose between grid and flex layout: Use Space for spacing between many inline elements, Flex for block-level layouts; avoid redundant wrapping +- Responsive breakpoints: Configure Grid's `xs`/`sm`/`md`/`lg`/`xl`/`xxl` based on actual device distribution; avoid excessive granularity causing computation overhead +- SSR optimization: Layout's `has_sider` can avoid flickering during server-side rendering + +## Troubleshooting Guide + +- Theme conflict hint: Sider's `theme` conflicts with Gradio preset attributes; use `theme_value` instead +- Events not working: Confirm event listeners are correctly bound (e.g., `click`, `collapse`, `breakpoint`) and the corresponding callbacks are enabled on the frontend side +- Grid overflow: When the sum of Col `span` values in a Row exceeds 24, they will wrap; check breakpoint configuration and layout logic +- Split panel anomalies: Ensure panel size units are consistent (px or percentage) and set reasonable `min`/`max` values + +**Section sources** + +- [layout/sider/**init**.py:101-104](file://backend/modelscope_studio/components/antd/layout/sider/__init__.py#L101-L104) + +## Conclusion + +This reference document covers the Python API for Antd layout components, clearly defining constructor parameters, methods, and typical usage for each component, while providing combination usage recommendations and performance optimization strategies. Through the collaboration of Layout, Grid, Flex, Space, Splitter, and Divider, a diverse range of layouts can be built from basic grids to complex interactive designs. + +## Appendix + +### Common Layout Combination Examples (Conceptual) + +- Responsive layout + - Use Layout + Sider with collapse/expand at different breakpoints; Sider supports `breakpoint` and `collapse` events + - Grid's `xs`/`sm`/`md`/`lg`/`xl`/`xxl` breakpoint configuration for multi-device adaptation +- Grid system + - Row provides `gutter`, `justify`, `align`, `wrap`; Col provides `span`, `offset`, `order`, `pull`/`push`, responsive breakpoints +- Flex layout + - Flex provides `orientation`/`vertical`, `wrap`, `justify`, `align`, `gap`, `flex`, etc.; suitable for flexible alignment and spacing control +- Spacing and separation + - Space for inline element spacing; `Space.Compact` for compact form arrangements; Divider for content separation + +### Breakpoints and Media Queries + +- Breakpoint constants: `xs` (<576px), `sm` (≥576px), `md` (≥768px), `lg` (≥992px), `xl` (≥1200px), `xxl` (≥1600px) +- Media query integration: Map to layout behavior at different screen sizes via Grid's `xs`/`sm`/`md`/`lg`/`xl`/`xxl` parameters + +### Nesting Rules and Best Practices + +- Layout must contain some sub-components from Header/Sider/Content/Footer, and sub-components must be placed inside Layout +- Grid's Col must be placed directly inside Row, and content elements placed inside Col +- Flex adds no extra wrapper, suitable for block-level layouts; Space adds a wrapper around each child element for inline alignment +- Splitter Panels are resized by dragging; it is recommended to set `min`/`max` and `collapsible` to improve usability diff --git a/.wiki/en/API Reference/Python API/Antd Components API/Navigation Components API.md b/.wiki/en/API Reference/Python API/Antd Components API/Navigation Components API.md new file mode 100644 index 00000000..ed52390f --- /dev/null +++ b/.wiki/en/API Reference/Python API/Antd Components API/Navigation Components API.md @@ -0,0 +1,569 @@ +# Navigation Components API + + +**Files Referenced in This Document** +- [anchor/__init__.py](file://backend/modelscope_studio/components/antd/anchor/__init__.py) +- [anchor/item/__init__.py](file://backend/modelscope_studio/components/antd/anchor/item/__init__.py) +- [breadcrumb/__init__.py](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py) +- [breadcrumb/item/__init__.py](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py) +- [dropdown/__init__.py](file://backend/modelscope_studio/components/antd/dropdown/__init__.py) +- [dropdown/button/__init__.py](file://backend/modelscope_studio/components/antd/dropdown/button/__init__.py) +- [menu/__init__.py](file://backend/modelscope_studio/components/antd/menu/__init__.py) +- [menu/item/__init__.py](file://backend/modelscope_studio/components/antd/menu/item/__init__.py) +- [pagination/__init__.py](file://backend/modelscope_studio/components/antd/pagination/__init__.py) +- [steps/__init__.py](file://backend/modelscope_studio/components/antd/steps/__init__.py) +- [steps/item/__init__.py](file://backend/modelscope_studio/components/antd/steps/item/__init__.py) + + +## Update Summary + +**Changes** + +- Updated Menu component API documentation with new `popupRender` slot feature description +- Added detailed description of the `popup_render` parameter for the Menu component +- Compared the difference in `popupRender` functionality between Menu and Dropdown components + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the Python API reference and usage guide for Ant Design navigation-related components, covering the following components: + +- Anchor +- Breadcrumb +- Dropdown +- Menu +- Pagination +- Steps + +Contents include: constructor parameters for component and sub-item classes, event listening, slots, state management key points, routing/frontend interaction patterns, accessibility and keyboard navigation recommendations, as well as performance optimization and best practices. + +## Project Structure + +Navigation components reside in the backend Python package, organized in a "component-level directory + sub-item directory" pattern for easy extension and maintenance. Each component class is responsible for rendering and event binding; sub-item classes carry specific item data structures. + +```mermaid +graph TB +subgraph "Antd Components" +A["anchor/__init__.py"] +B["breadcrumb/__init__.py"] +C["dropdown/__init__.py"] +D["menu/__init__.py"] +E["pagination/__init__.py"] +F["steps/__init__.py"] +end +subgraph "Sub-items" +A1["anchor/item/__init__.py"] +B1["breadcrumb/item/__init__.py"] +C1["dropdown/button/__init__.py"] +D1["menu/item/__init__.py"] +F1["steps/item/__init__.py"] +end +A --> A1 +B --> B1 +C --> C1 +D --> D1 +F --> F1 +``` + +**Section sources** + +- [anchor/**init**.py:1-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L1-L117) +- [breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [dropdown/**init**.py:1-119](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L1-L119) +- [menu/**init**.py:1-125](file://backend/modelscope_studio/components/antd/menu/__init__.py#L1-L125) +- [pagination/**init**.py:1-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L1-L107) +- [steps/**init**.py:1-95](file://backend/modelscope_studio/components/antd/steps/__init__.py#L1-L95) + +## Core Components + +This section provides an overview of the responsibilities, typical usage, and key parameters of each navigation component. + +- **Anchor** + - Responsibility: Provides anchor jumps within a single page; supports fixed mode and direction settings. + - Key parameters: `affix`, `bounds`, `get_container`, `offset_top`, `direction`, `replace`, `items`, etc. + - Events: `change`, `click`, `affix_change`. + - Slots: `items`. + - Use cases: Long document table of contents, section positioning. + +- **Breadcrumb** + - Responsibility: Displays the current page's position in the hierarchy. + - Key parameters: `item_render`, `params`, `items`, `separator`. + - Slots: `separator`, `itemRender`, `items`, `dropdownIcon`. + - Use cases: Page path navigation, hierarchical browsing. + +- **Dropdown** + - Responsibility: Pop-up menu triggered by click/hover. + - Key parameters: `arrow`, `auto_adjust_overflow`, `disabled`, `placement`, `trigger`, `menu`, `open`, etc. + - Events: `open_change`, `menu_click`, `menu_select`, `menu_deselect`, `menu_open_change`. + - Slots: `menu.expandIcon`, `menu.overflowedIndicator`, `menu.items`, `dropdownRender`, `popupRender`. + - Use cases: Action entry points, feature set expansion. + +- **Menu** + - Responsibility: Vertical/horizontal/inline navigation menu. + - Key parameters: `open_keys`, `selected_keys`, `mode`, `theme`/`theme_value`, `inline_indent`, `items`, `multiple`, `trigger_sub_menu_action`, `popup_render`, etc. + - Events: `click`, `deselect`, `open_change`, `select`. + - Slots: `expandIcon`, `overflowedIndicator`, `items`, `popupRender`. + - Use cases: Site main navigation, sidebar navigation. + +- **Pagination** + - Responsibility: Page display and navigation for large datasets. + - Key parameters: `current`, `default_current`, `page_size`, `default_page_size`, `total`, `pageSizeOptions`, `showQuickJumper`, `showSizeChanger`, `simple`, `size`, etc. + - Events: `change`, `show_size_change`. + - Slots: `showQuickJumper.goButton`, `itemRender`. + - Use cases: List/table pagination. + +- **Steps** + - Responsibility: Guides users through multi-step processes. + - Key parameters: `current`, `direction`, `label_placement`, `title_placement`, `percent`, `progress_dot`, `size`, `status`, `type`, `items`. + - Events: `change`. + - Slots: `progressDot`, `items`. + - Use cases: Wizards, multi-step form submissions. + +**Section sources** + +- [anchor/**init**.py:11-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L11-L117) +- [breadcrumb/**init**.py:9-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L9-L73) +- [dropdown/**init**.py:11-119](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L11-L119) +- [menu/**init**.py:12-125](file://backend/modelscope_studio/components/antd/menu/__init__.py#L12-L125) +- [pagination/**init**.py:10-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L10-L107) +- [steps/**init**.py:11-95](file://backend/modelscope_studio/components/antd/steps/__init__.py#L11-L95) + +## Architecture Overview + +Navigation components uniformly inherit from the layout component base class, and interact with the frontend through frontend directory mapping and event binding. Components support additional property passing, style/class name injection, visibility and render control, and other common capabilities. + +```mermaid +classDiagram +class ModelScopeLayoutComponent +class AntdAnchor { ++__init__(...) ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess(...) ++postprocess(...) ++example_payload() ++example_value() +} +class AntdBreadcrumb { ++__init__(...) ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess(...) ++postprocess(...) ++example_payload() ++example_value() +} +class AntdDropdown { ++__init__(...) ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess(...) ++postprocess(...) ++example_payload() ++example_value() +} +class AntdMenu { ++__init__(...) ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess(...) ++postprocess(...) ++example_payload() ++example_value() +} +class AntdPagination { ++__init__(...) ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess(...) ++postprocess(...) ++example_payload() ++example_value() +} +class AntdSteps { ++__init__(...) ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess(...) ++postprocess(...) ++example_payload() ++example_value() +} +AntdAnchor --> ModelScopeLayoutComponent +AntdBreadcrumb --> ModelScopeLayoutComponent +AntdDropdown --> ModelScopeLayoutComponent +AntdMenu --> ModelScopeLayoutComponent +AntdPagination --> ModelScopeLayoutComponent +AntdSteps --> ModelScopeLayoutComponent +``` + +**Diagram sources** + +- [anchor/**init**.py:11-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L11-L117) +- [breadcrumb/**init**.py:9-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L9-L73) +- [dropdown/**init**.py:11-119](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L11-L119) +- [menu/**init**.py:12-125](file://backend/modelscope_studio/components/antd/menu/__init__.py#L12-L125) +- [pagination/**init**.py:10-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L10-L107) +- [steps/**init**.py:11-95](file://backend/modelscope_studio/components/antd/steps/__init__.py#L11-L95) + +## Detailed Component Analysis + +### Anchor API + +- Class: `AntdAnchor` +- Sub-item class: `AntdAnchorItem` +- Events + - `change`: Monitors anchor link changes + - `click`: Handles click events + - `affix_change`: Fixed state change callback +- Slots + - `items`: Anchor item collection +- Key parameters + - `affix`: Whether to enable fixed mode + - `bounds`: Boundary distance of anchor area + - `get_container`: Scroll container selector + - `get_current_anchor`: Custom highlighted anchor + - `offset_top`: Top offset when calculating scroll position + - `show_ink_in_fixed`: Whether to show ink bar in fixed mode + - `target_offset`: Anchor scroll offset, defaults to `offsetTop` + - `items`: Item data, supports nested `children` + - `direction`: Vertical or horizontal direction + - `replace`: Replace browser history instead of adding +- Methods + - `preprocess(payload)`: Returns None + - `postprocess(value)`: Returns None + - `example_payload()`: Returns None + - `example_value()`: Returns None +- Usage examples (path reference) + - Page anchor navigation: [anchor/**init**.py:38-98](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L38-L98) + +**Section sources** + +- [anchor/**init**.py:11-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L11-L117) +- [anchor/item/**init**.py](file://backend/modelscope_studio/components/antd/anchor/item/__init__.py) + +### Breadcrumb API + +- Class: `AntdBreadcrumb` +- Sub-item class: `AntdBreadcrumbItem` +- Slots + - `separator`: Separator + - `itemRender`: Custom item rendering + - `items`: Item collection + - `dropdownIcon`: Dropdown icon +- Key parameters + - `item_render`: Custom item rendering function + - `params`: Rendering parameters + - `items`: Item array + - `separator`: Separator string +- Methods + - `preprocess(payload)`: Returns None + - `postprocess(value)`: Returns None + - `example_payload()`: Returns None + - `example_value()`: Returns None +- Usage examples (path reference) + - Breadcrumb navigation: [breadcrumb/**init**.py:20-54](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L20-L54) + +**Section sources** + +- [breadcrumb/**init**.py:9-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L9-L73) +- [breadcrumb/item/**init**.py](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py) + +### Dropdown API + +- Class: `AntdDropdown` +- Sub-item class: `AntdDropdownButton` +- Events + - `open_change`: Dropdown open/close state change + - `menu_click`: Menu item click + - `menu_select`: Menu item selected + - `menu_deselect`: Menu item deselected + - `menu_open_change`: Sub-menu open/close state change +- Slots + - `menu.expandIcon`: Menu expand icon + - `menu.overflowedIndicator`: Overflow indicator + - `menu.items`: Menu item collection + - `dropdownRender`: Custom dropdown rendering + - `popupRender`: Custom popup rendering +- Key parameters + - `arrow`: Whether to show arrow + - `auto_adjust_overflow`: Whether to auto-adjust overflow + - `auto_focus`: Whether to auto-focus + - `disabled`: Whether to disable + - `destroy_popup_on_hide`: Destroy popup when hidden + - `destroy_on_hidden`: Destroy after hidden + - `dropdown_render`: Dropdown rendering function + - `popup_render`: Popup rendering function + - `get_popup_container`: Popup mount container + - `menu`: Menu configuration object + - `overlay_class_name`: Overlay class name + - `overlay_style`: Overlay style + - `placement`: Popup placement + - `trigger`: Trigger mode (`click`/`hover`/`contextMenu`) + - `open`: Controlled open state + - `inner_elem_style`: Inner element style +- Methods + - `preprocess(payload)`: Returns None + - `postprocess(value)`: Returns None + - `example_payload()`: Returns None + - `example_value()`: Returns None +- Usage examples (path reference) + - Dropdown menu: [dropdown/**init**.py:40-100](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L40-L100) + +**Section sources** + +- [dropdown/**init**.py:11-119](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L11-L119) +- [dropdown/button/**init**.py](file://backend/modelscope_studio/components/antd/dropdown/button/__init__.py) + +### Menu API + +- Class: `AntdMenu` +- Sub-item class: `AntdMenuItem` +- Events + - `click`: Menu item click + - `deselect`: Menu item deselected + - `open_change`: Sub-menu open/close state change + - `select`: Menu item selected +- Slots + - `expandIcon`: Expand icon + - `overflowedIndicator`: Overflow indicator + - `items`: Menu item collection + - `popupRender`: Popup rendering +- Key parameters + - `open_keys`: Controlled open sub-menu keys + - `selected_keys`: Controlled selected menu keys + - `selectable`: Whether selectable + - `default_open_keys`: Default open sub-menu keys + - `default_selected_keys`: Default selected menu keys + - `expand_icon`: Expand icon + - `force_sub_menu_render`: Whether to force render sub-menus + - `inline_collapsed`: Inline collapse + - `inline_indent`: Inline indent pixels + - `items`: Menu item array + - `mode`: Mode (`vertical`/`horizontal`/`inline`) + - `multiple`: Whether multi-select + - `overflowed_indicator`: Overflow indicator + - `sub_menu_close_delay`: Sub-menu close delay + - `sub_menu_open_delay`: Sub-menu open delay + - `theme`/`theme_value`: Theme (light/dark); prefer `theme_value` + - `trigger_sub_menu_action`: Trigger sub-menu action (`click`/`hover`) + - `popup_render`: Popup rendering function +- Methods + - `preprocess(payload)`: Returns None + - `postprocess(value)`: Returns None + - `example_payload()`: Returns None + - `example_value()`: Returns None +- Usage examples (path reference) + - Navigation menu: [menu/**init**.py:36-103](file://backend/modelscope_studio/components/antd/menu/__init__.py#L36-L103) + +**Update** Added `popupRender` parameter for custom menu popup rendering + +**Section sources** + +- [menu/**init**.py:12-125](file://backend/modelscope_studio/components/antd/menu/__init__.py#L12-L125) +- [menu/item/**init**.py](file://backend/modelscope_studio/components/antd/menu/item/__init__.py) + +### Pagination API + +- Class: `AntdPagination` +- Events + - `change`: Page number or page size change + - `show_size_change`: Page size changed +- Slots + - `showQuickJumper.goButton`: Quick jump button + - `itemRender`: Custom page number rendering +- Key parameters + - `align`: Alignment (`start`/`center`/`end`) + - `current`: Current page + - `default_current`: Default current page + - `default_page_size`: Default page size + - `page_size`: Current page size + - `disabled`: Whether to disable + - `hide_on_single_page`: Hide when single page + - `item_render`: Page item rendering function + - `page_size_options`: Page size options + - `responsive`: Responsive layout + - `show_less_items`: Show fewer page numbers + - `show_quick_jumper`: Quick jump toggle or config + - `show_size_changer`: Page size changer toggle or config + - `show_title`: Whether to show title + - `show_total`: Total count rendering template + - `simple`: Simple mode toggle or config + - `size`: Size (`small`/`default`) + - `total`: Total item count +- Methods + - `preprocess(payload)`: Returns None + - `postprocess(value)`: Returns None + - `example_payload()`: Returns None + - `example_value()`: Returns None +- Usage examples (path reference) + - Pagination control: [pagination/**init**.py:26-88](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L26-L88) + +**Section sources** + +- [pagination/**init**.py:10-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L10-L107) + +### Steps API + +- Class: `AntdSteps` +- Sub-item class: `AntdStepsItem` +- Events + - `change`: Step change +- Slots + - `progressDot`: Progress dot rendering + - `items`: Step item collection +- Key parameters + - `current`: Current step index + - `direction`: Direction (`horizontal`/`vertical`) + - `initial`: Initial step + - `label_placement`: Label placement (`horizontal`/`vertical`) + - `title_placement`: Title placement + - `percent`: Completion percentage + - `progress_dot`: Whether to use dot-style progress + - `responsive`: Responsive + - `size`: Size (`small`/`default`) + - `status`: Status (`wait`/`process`/`finish`/`error`) + - `type`: Type (`default`/`navigation`/`inline`) + - `items`: Step item array +- Methods + - `preprocess(payload)`: Returns None + - `postprocess(value)`: Returns None + - `example_payload()`: Returns None + - `example_value()`: Returns None +- Usage examples (path reference) + - Steps bar: [steps/**init**.py:25-75](file://backend/modelscope_studio/components/antd/steps/__init__.py#L25-L75) + +**Section sources** + +- [steps/**init**.py:11-95](file://backend/modelscope_studio/components/antd/steps/__init__.py#L11-L95) +- [steps/item/**init**.py](file://backend/modelscope_studio/components/antd/steps/item/__init__.py) + +## Dependency Analysis + +- Common dependencies + - Base class: `ModelScopeLayoutComponent` (unified lifecycle and rendering) + - Event system: `gradio.events.EventListener` (event binding) + - Frontend directory resolution: `resolve_frontend_dir` (maps frontend directories by component name) +- Inter-component coupling + - Components are relatively independent; each carries item data via its own sub-item class, reducing coupling + - Unified event and slot mechanism for easy extension and reuse +- External dependencies + - Works with frontend Svelte components through event binding and props passing for interaction + +```mermaid +graph LR +Base["ModelScopeLayoutComponent"] --> Anchor["AntdAnchor"] +Base --> Breadcrumb["AntdBreadcrumb"] +Base --> Dropdown["AntdDropdown"] +Base --> Menu["AntdMenu"] +Base --> Pagination["AntdPagination"] +Base --> Steps["AntdSteps"] +Events["EventListener"] --> Anchor +Events --> Breadcrumb +Events --> Dropdown +Events --> Menu +Events --> Pagination +Events --> Steps +Resolve["resolve_frontend_dir"] --> Anchor +Resolve --> Breadcrumb +Resolve --> Dropdown +Resolve --> Menu +Resolve --> Pagination +Resolve --> Steps +``` + +**Diagram sources** + +- [anchor/**init**.py:7-99](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L7-L99) +- [breadcrumb/**init**.py:5-56](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L5-L56) +- [dropdown/**init**.py:5-102](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L5-L102) +- [menu/**init**.py:6-105](file://backend/modelscope_studio/components/antd/menu/__init__.py#L6-L105) +- [pagination/**init**.py:5-90](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L5-L90) +- [steps/**init**.py:5-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L5-L77) + +## Performance Considerations + +- Enable event binding on demand: Enable frontend binding only when the corresponding event listener is registered, avoiding unnecessary overhead. +- Controlled state: Use controlled properties like `open_keys`, `selected_keys`, `current` to reduce repeated renders. +- Slots and custom rendering: Use `itemRender`/`dropdownRender` and other slots appropriately; avoid overly complex logic causing re-renders. +- List rendering: Pagination and Menu `items` should be as flat as possible to reduce rendering costs from deep nesting. +- Fixed and scrolling: Anchor's `affix` and `bounds` parameters should be optimized in conjunction with page scroll performance to avoid frequent reflows. +- `popupRender` usage: Menu component's `popupRender` functionality should be used carefully; avoid heavy computations in rendering functions to avoid affecting menu performance. + +## Troubleshooting Guide + +- Events not triggering + - Check if event listeners are correctly registered (e.g., `change`, `click`, `open_change`, etc.) + - Confirm the frontend has the corresponding event binding enabled (triggered by component's internal `_internal` property update) +- Styles/class names not taking effect + - Confirm that `class_names`/`styles`/`root_class_name` are correctly passed + - Check for conflicts with overlay style `overlay_style`/`overlay_class_name` +- Dropdown not showing + - Check `disabled`, `destroy_on_hidden`, `get_popup_container`, and other configurations + - Confirm trigger mode `trigger` and `placement` are appropriate + - Verify `popupRender` slot is correctly configured +- Pagination not working + - Check `total`, `page_size`, `current`, and other parameters for consistency + - Confirm event callbacks update controlled state +- Steps state anomaly + - Check the `current`, `status`, `type`, `direction` parameter combination + - Confirm `items` structure matches the index +- Menu component `popupRender` issues + - Confirm the `popupRender` function or slot is correctly passed to the frontend component + - Check if the return value format of `popupRender` meets Ant Design requirements + - Verify `popupRender` does not cause menu rendering performance issues + +**Section sources** + +- [anchor/**init**.py:20-33](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L20-L33) +- [dropdown/**init**.py:16-32](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L16-L32) +- [menu/**init**.py:18-31](file://backend/modelscope_studio/components/antd/menu/__init__.py#L18-L31) +- [pagination/**init**.py:14-21](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L14-L21) +- [steps/**init**.py:16-20](file://backend/modelscope_studio/components/antd/steps/__init__.py#L16-L20) + +## Conclusion + +This guide systematically covers navigation component APIs, events, slots, and usage points, providing practical recommendations for frontend interaction, state management, accessibility, and performance optimization. It is recommended to choose the appropriate component and parameter combination for the business scenario in real projects to ensure a good user experience and development efficiency. + +**Update** The new `popupRender` slot feature added to the Menu component provides developers with more flexible menu popup customization capabilities; however, performance impact and compatibility requirements must be considered when using it. + +## Appendix + +- Accessibility and keyboard navigation recommendations + - Provide a clear focus order and keyboard operations for interactive elements (e.g., Enter/Space to trigger, Esc to close) + - Provide ARIA attributes for menus and dropdowns (role, aria-expanded, aria-haspopup, etc.) + - Provide clear semantic labels and status hints for pagination and steps +- Routing integration + - Anchor and Steps can be linked with frontend routing, updating current state via event callbacks + - Breadcrumb can dynamically generate items based on the routing path + - Menu component's `popupRender` can be used to implement custom routing navigation popups +- Best practices + - Structure `items` data and avoid heavy computations in rendering functions + - Use controlled properties appropriately to avoid state desynchronization + - Adapt responsive layouts and touch interactions for mobile + - When using `popupRender`, ensure the returned React component structure conforms to Ant Design specifications + - Avoid async operations in `popupRender` to prevent affecting menu response performance diff --git a/.wiki/en/API Reference/Python API/Antd Components API/Other Components API.md b/.wiki/en/API Reference/Python API/Antd Components API/Other Components API.md new file mode 100644 index 00000000..44723699 --- /dev/null +++ b/.wiki/en/API Reference/Python API/Antd Components API/Other Components API.md @@ -0,0 +1,422 @@ +# Other Components API + + +**Files referenced in this document** +- [backend/modelscope_studio/components/antd/config_provider/__init__.py](file://backend/modelscope_studio/components/antd/config_provider/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) +- [frontend/antd/config-provider/Index.svelte](file://frontend/antd/config-provider/Index.svelte) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [docs/demos/example.py](file://docs/demos/example.py) +- [docs/components/antd/config_provider/README.md](file://docs/components/antd/config_provider/README.md) +- [frontend/antd/config-provider/package.json](file://frontend/antd/config-provider/package.json) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the Python API reference for "Other Components" in Ant Design Studio, focusing on the complete API specification and usage instructions for ConfigProvider (global configuration provider). Content covers: + +- Constructor parameters, property definitions, method signatures and return types +- Standard global configuration usage: theme customization, language settings, component defaults +- Scope management, configuration inheritance, and dynamic update mechanisms +- Internationalization configuration, theme switching, and component behavior customization +- Best practices and performance optimization recommendations + +## Project Structure + +ConfigProvider is implemented as a Python class in the backend and wrapped in Svelte on the frontend, interfacing with Ant Design's ConfigProvider while supporting multiple languages through the localization module. + +```mermaid +graph TB +subgraph "Python Backend" +PY_INIT["backend/modelscope_studio/components/antd/__init__.py"] +PY_CP["backend/modelscope_studio/components/antd/config_provider/__init__.py"] +PY_DEV["backend/modelscope_studio/utils/dev/component.py"] +PY_RESOLVE["backend/modelscope_studio/utils/dev/resolve_frontend_dir.py"] +end +subgraph "Frontend" +FE_INDEX["frontend/antd/config-provider/Index.svelte"] +FE_TSX["frontend/antd/config-provider/config-provider.tsx"] +FE_LOCALES["frontend/antd/config-provider/locales.ts"] +FE_PKG["frontend/antd/config-provider/package.json"] +end +PY_INIT --> PY_CP +PY_CP --> PY_RESOLVE +PY_CP --> PY_DEV +PY_CP --> FE_INDEX +FE_INDEX --> FE_TSX +FE_TSX --> FE_LOCALES +FE_INDEX --> FE_PKG +``` + +**Chart sources** + +- [backend/modelscope_studio/components/antd/**init**.py:32](file://backend/modelscope_studio/components/antd/__init__.py#L32) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:22](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L22) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4) +- [frontend/antd/config-provider/Index.svelte:11](file://frontend/antd/config-provider/Index.svelte#L11) +- [frontend/antd/config-provider/config-provider.tsx:51](file://frontend/antd/config-provider/config-provider.tsx#L51) +- [frontend/antd/config-provider/locales.ts:7](file://frontend/antd/config-provider/locales.ts#L7) +- [frontend/antd/config-provider/package.json:1](file://frontend/antd/config-provider/package.json#L1) + +**Section sources** + +- [backend/modelscope_studio/components/antd/**init**.py:32](file://backend/modelscope_studio/components/antd/__init__.py#L32) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:22](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L22) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4) +- [frontend/antd/config-provider/Index.svelte:11](file://frontend/antd/config-provider/Index.svelte#L11) +- [frontend/antd/config-provider/config-provider.tsx:51](file://frontend/antd/config-provider/config-provider.tsx#L51) +- [frontend/antd/config-provider/locales.ts:7](file://frontend/antd/config-provider/locales.ts#L7) +- [frontend/antd/config-provider/package.json:1](file://frontend/antd/config-provider/package.json#L1) + +## Core Components + +- Component name: AntdConfigProvider +- Module: backend.modelscope_studio.components.antd.config_provider +- Base class: ModelScopeLayoutComponent +- Frontend mapping: frontend/antd/config-provider/Index.svelte → frontend/antd/config-provider/config-provider.tsx +- Purpose: Provides unified global configuration (theme, language, size, prefix, popup container, etc.) to all Ant Design components within the application, supporting slot injection and dynamic updates. + +Key points: + +- Supported slots: renderEmpty +- Events: none +- Frontend directory resolution: points to frontend component directory via resolve_frontend_dir("config-provider") +- Skip API export: skip_api returns True to avoid exposing this component in certain automated exports + +**Section sources** + +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:22](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L22) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:28](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L28) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:95](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L95) +- [backend/modelscope_studio/utils/dev/component.py:20](file://backend/modelscope_studio/utils/dev/component.py#L20) + +## Architecture Overview + +The ConfigProvider call chain is as follows: + +```mermaid +sequenceDiagram +participant App as "Application Blocks" +participant CP_Py as "AntdConfigProvider (Python)" +participant CP_Index as "Index.svelte" +participant CP_TSX as "config-provider.tsx" +participant AD as "Ant Design ConfigProvider" +App->>CP_Py : Create and pass configuration parameters +CP_Py->>CP_Index : Resolve frontend directory and render +CP_Index->>CP_TSX : Pass props and slots +CP_TSX->>AD : Inject theme, language, container callback, etc. +AD-->>CP_TSX : Provide context +CP_TSX-->>CP_Index : Render sub-tree +CP_Index-->>App : Child components inherit global configuration +``` + +**Chart sources** + +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:95](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L95) +- [frontend/antd/config-provider/Index.svelte:11](file://frontend/antd/config-provider/Index.svelte#L11) +- [frontend/antd/config-provider/config-provider.tsx:108](file://frontend/antd/config-provider/config-provider.tsx#L108) + +## Detailed Component Analysis + +### Constructor and Property Definitions + +- Class name: AntdConfigProvider +- Inherits: ModelScopeLayoutComponent +- Key properties (partial): + - component_disabled: optional boolean, controls component disabled state + - component_size: optional string, values small/middle/large or None + - csp: optional dict, for CSP configuration + - direction: optional string, values ltr/rtl or None + - get_popup_container: optional string, specifies the popup mount container + - get_target_container: optional string, specifies the target container + - icon_prefix_cls: optional string, icon prefix class name + - locale: optional string, value is a predefined LocaleType + - popup_match_select_width: optional boolean or number, affects popup width strategy + - popup_overflow: optional string, values viewport/scroll + - prefix_cls: optional string, component prefix class name + - render_empty: optional string, for empty state rendering + - theme: optional dict (deprecated), warning prompts to use theme_config + - theme_config: optional dict, theme configuration (recommended) + - variant: optional string, values outlined/filled/borderless + - virtual: optional boolean + - warning: optional dict, warning configuration + - Element-level styles and class names: class_names, styles + - Layout and visibility: visible, elem_id, elem_classes, elem_style, render, as_item + - Extra properties: additional_props + - Other common properties: \_internal (internally reserved) + +Note: + +- Relationship between theme and theme_config: passing theme will trigger a warning; use theme_config instead +- Slots: only renderEmpty is supported + +Method signatures and return types: + +- preprocess(payload: None) -> None +- postprocess(value: None) -> None +- example_payload() -> Any +- example_value() -> Any + +**Section sources** + +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:31](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L31) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:42](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L42) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:86](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L86) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:101](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L101) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:104](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L104) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:108](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L108) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:111](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L111) + +### Frontend Implementation Key Points + +- Types and imports: based on Ant Design's ConfigProvider types, extended with themeMode and theme.algorithm fields +- Theme algorithm: automatically selects dark/compact algorithm based on themeMode, can be merged with external theme.algorithm +- Language settings: locale is inferred from browser environment by default, with en_US as fallback; loads corresponding language packs and dayjs language asynchronously on demand +- Container callbacks: getPopupContainer, getTargetContainer, renderEmpty are wrapped via useFunction to ensure reactive updates +- Slot handling: injects dot-separated paths from slots into corresponding prop positions; renderEmpty supports ReactSlot + +```mermaid +flowchart TD +Start(["Enter Component"]) --> LocaleCheck["Check if localeProp exists"] +LocaleCheck --> HasLocale{"Exists?"} +HasLocale --> |Yes| LoadLocale["Load Antd locale and dayjs locale by locale"] +HasLocale --> |No| UseDefault["Use en_US and default dayjs locale"] +LoadLocale --> ApplyLocale["Set antd locale and dayjs locale"] +UseDefault --> ApplyLocale +ApplyLocale --> ThemeAlg["Merge themeMode and theme.algorithm"] +ThemeAlg --> Render["Render
modelscope_studio.components.antdx"] --> B["actions/*"] +A --> C["attachments/*"] +A --> D["bubble/*"] +A --> E["conversations/*"] +A --> F["file_card/*"] +A --> G["folder/*"] +A --> H["prompts/*"] +A --> I["sender/*"] +A --> J["sources/*"] +A --> K["suggestion/*"] +A --> L["think/*"] +A --> M["thought_chain/*"] +A --> N["notification/*"] +A --> O["code_highlighter/*"] +A --> P["x_provider/*"] +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +Section Sources + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## Core Components + +The following lists all ML and AI scenario-related component classes in `modelscope_studio.components.antdx.*` with their import paths and usage overview: + +- Layout & Display + - Bubble: For message/text display and interaction, supports editing, typing animation, variants, shapes, etc. + - Conversations: For multi-conversation management and menu interactions. + - Prompts: For displaying a set of clickable prompt items. + - Suggestions: For input suggestions and selection. + - Think: For displaying a "thinking" state and expand control. + - ThoughtChain: For displaying reasoning processes in tree/chain form. + - CodeHighlighter: For code block rendering and theme control. + - Notification: For Web Notification integration and event binding. + - Sources: For displaying source entries and expand control. + - Welcome: For landing page or welcome message display (present in exports). + - XProvider: For global context injection (present in exports). + +- Data & Input + - Attachments: For file upload, drag-and-drop, preview, download, and removal. + - Sender: For user input, keyboard shortcuts, voice, paste, and submit events. + - FileCard: For card-style display and operations on individual files. + - Folder: For tree-style directory browsing and file/folder selection. + - Actions: For a group of clickable action items and dropdown menus. + +- Pro Extensions (Pro module) + - Chatbot: For conversational flows and message stream management (present in exports). + - MultimodalInput: For multimodal input including text, images, audio, and video (present in exports). + - MonacoEditor: For code editing and highlighting (present in exports). + - WebSandbox: For secure sandbox execution (present in exports). + +Section Sources + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## Architecture Overview + +Antdx components are wrapped through a unified base class, inheriting from Gradio's component system, supporting event listeners, slots, style and class name injection, and frontend resource directory resolution. Most components are layout-type components (`skip_api=True`) that do not directly expose API schemas; a few data-type components (such as Attachments and Sender) implement `preprocess/postprocess` and expose API specifications. + +```mermaid +classDiagram +class ModelScopeLayoutComponent +class ModelScopeDataLayoutComponent +class AntdXBubble +class AntdXConversations +class AntdXPrompts +class AntdXAttachments +class AntdXSender +class AntdXActions +class AntdXFileCard +class AntdXFolder +class AntdXCodeHighlighter +class AntdXNotification +class AntdXSources +class AntdXSuggestion +class AntdXThink +class AntdXThoughtChain +AntdXBubble --|> ModelScopeLayoutComponent +AntdXConversations --|> ModelScopeLayoutComponent +AntdXPrompts --|> ModelScopeLayoutComponent +AntdXFileCard --|> ModelScopeLayoutComponent +AntdXFolder --|> ModelScopeLayoutComponent +AntdXCodeHighlighter --|> ModelScopeLayoutComponent +AntdXNotification --|> ModelScopeLayoutComponent +AntdXSources --|> ModelScopeLayoutComponent +AntdXSuggestion --|> ModelScopeLayoutComponent +AntdXThink --|> ModelScopeLayoutComponent +AntdXThoughtChain --|> ModelScopeLayoutComponent +AntdXAttachments --|> ModelScopeDataLayoutComponent +AntdXSender --|> ModelScopeDataLayoutComponent +AntdXActions --|> ModelScopeLayoutComponent +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:13-135](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L13-L135) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) +- [backend/modelscope_studio/components/antdx/attachments/**init**.py:22-227](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L22-L227) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:14-149](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L14-L149) +- [backend/modelscope_studio/components/antdx/actions/**init**.py:15-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L112) +- [backend/modelscope_studio/components/antdx/file_card/**init**.py:11-112](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L11-L112) +- [backend/modelscope_studio/components/antdx/folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) +- [backend/modelscope_studio/components/antdx/code_highlighter/**init**.py:6-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L6-L71) +- [backend/modelscope_studio/components/antdx/notification/**init**.py:10-97](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L10-L97) +- [backend/modelscope_studio/components/antdx/sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) + +## Detailed Component Analysis + +### Bubble + +- Import Path: `modelscope_studio.components.antdx.Bubble` +- Purpose: Message/text display, supports editing, typing animation, variants, shapes, etc. +- Key Parameters (selected): content, avatar, footer, header, loading, placement, editable, shape, typing, streaming, variant, footer_placement, loading_render, content_render, root_class_name, class_names, styles, additional_props, visibility and style attributes. +- Events: typing, typing_complete, edit_confirm, edit_cancel. +- Slots: avatar, editable.okText, editable.cancelText, content, footer, header, extra, loadingRender, contentRender. +- Lifecycle & API: skip*api=True, does not expose API; preprocess/postprocess/example*\* are empty implementations. + +Section Sources + +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:13-135](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L13-L135) + +### Conversations + +- Import Path: `modelscope_studio.components.antdx.Conversations` +- Sub-components: Item +- Key Parameters: active_key, default_active_key, items, menu, groupable, shortcut_keys, creation, styles, class_names, root_class_name, additional_props. +- Events: active_change, menu_click, menu_deselect, menu_open_change, menu_select, groupable_expand, creation_click. +- Slots: menu.expandIcon, menu.overflowedIndicator, menu.trigger, groupable.label, items, creation.icon, creation.label. +- Lifecycle & API: skip_api=True. + +Section Sources + +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) + +### Prompts + +- Import Path: `modelscope_studio.components.antdx.Prompts` +- Sub-components: Item +- Key Parameters: items, prefix_cls, title, vertical, fade_in, fade_in_left, wrap, styles, class_names, root_class_name, additional_props. +- Events: item_click. +- Slots: title, items. +- Lifecycle & API: skip_api=True. + +Section Sources + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) + +### Attachments + +- Import Path: `modelscope_studio.components.antdx.Attachments` +- Data Model: ListFiles +- Key Parameters: image_props, accept, action, before_upload, custom_request, data, default_file_list, directory, disabled, items, get_drop_container, overflow, placeholder, headers, icon_render, is_image_url, item_render, list_type, max_count, method, multiple, form_name, open_file_dialog_on_click, preview_file, progress, show_upload_list, with_credentials, class_names, root_style, styles, root_class_name, visibility and polling attributes. +- Events: change, drop, download, preview, remove. +- Lifecycle & API: skip_api=False; preprocess converts payload to file path list; postprocess converts file path list to ListFiles; api_info returns ListFiles JSON Schema. +- Typical Usage: As an input component receiving file lists, as an output component returning file metadata. + +Section Sources + +- [backend/modelscope_studio/components/antdx/attachments/**init**.py:22-227](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L22-L227) + +### Sender + +- Import Path: `modelscope_studio.components.antdx.Sender` +- Sub-components: Header, Switch +- Key Parameters: value, allow_speech, class_names, components, default_value, disabled, auto_size, loading, suffix, footer, header, prefix, read_only, styles, submit_type, placeholder, slot_config, skill, root_class_name, additional_props. +- Events: change, submit, cancel, allow_speech_recording_change, key_down, key_press, focus, blur, paste, paste_file, skill_closable_close. +- Slots: suffix, header, prefix, footer, skill.title, skill.toolTip.title, skill.closable.closeIcon. +- Lifecycle & API: skip*api=False; preprocess/postprocess return string; api_info returns string type description; example*\* returns None. + +Section Sources + +- [backend/modelscope_studio/components/antdx/sender/**init**.py:14-149](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L14-L149) + +### Actions + +- Import Path: `modelscope_studio.components.antdx.Actions` +- Sub-components: ActionItem, Item, Feedback, Copy, Audio +- Key Parameters: additional_props, items, variant, dropdown_props, fade_in, fade_in_left, class_names, styles. +- Events: click, dropdown_open_change, dropdown_menu_click, dropdown_menu_deselect, dropdown_menu_open_change, dropdown_menu_select. +- Slots: items, dropdownProps.dropdownRender, dropdownProps.popupRender, dropdownProps.menu.expandIcon, dropdownProps.menu.overflowedIndicator, dropdownProps.menu.items. +- Lifecycle & API: skip_api=True. + +Section Sources + +- [backend/modelscope_studio/components/antdx/actions/**init**.py:15-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L112) + +### FileCard + +- Import Path: `modelscope_studio.components.antdx.FileCard` +- Sub-components: List +- Key Parameters: image_props, filename, byte, size, description, loading, type, src, mask, icon, video_props, audio_props, spin_props, class_names, styles, additional_props. +- Events: click. +- Slots: imageProps.placeholder, imageProps.preview.mask, imageProps.preview.closeIcon, imageProps.preview.toolbarRender, imageProps.preview.imageRender, description, icon, mask, spinProps.icon, spinProps.description, spinProps.indicator. +- Lifecycle & API: skip_api=True. + +Section Sources + +- [backend/modelscope_studio/components/antdx/file_card/**init**.py:11-112](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L11-L112) + +### Folder + +- Import Path: `modelscope_studio.components.antdx.Folder` +- Sub-components: TreeNode, DirectoryIcon +- Key Parameters: additional_props, tree_data, selectable, selected_file, default_selected_file, directory_tree_width, empty_render, preview_render, expanded_paths, default_expanded_paths, default_expand_all, directory_title, preview_title, directory_icons, class_names, styles, root_class_name. +- Events: file_click, folder_click, selected_file_change, expanded_paths_change, file_content_service_load_file_content. +- Slots: emptyRender, previewRender, directoryTitle, previewTitle, treeData, directoryIcons. +- Lifecycle & API: skip_api=True. + +Section Sources + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) + +### CodeHighlighter + +- Import Path: `modelscope_studio.components.antdx.CodeHighlighter` +- Key Parameters: value, lang, header, highlight_props, prism_light_mode, styles, class_names, additional_props, root_class_name. +- Slots: header. +- Lifecycle & API: skip_api=True. + +Section Sources + +- [backend/modelscope_studio/components/antdx/code_highlighter/**init**.py:6-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L6-L71) + +### Notification + +- Import Path: `modelscope_studio.components.antdx.Notification` +- Key Parameters: title, duration, badge, body, data, dir, icon, lang, require_interaction, silent, tag, additional_props. +- Events: permission, click, close, error, show. +- Lifecycle & API: skip_api=True. + +Section Sources + +- [backend/modelscope_studio/components/antdx/notification/**init**.py:10-97](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L10-L97) + +### Sources + +- Import Path: `modelscope_studio.components.antdx.Sources` +- Sub-components: Item +- Key Parameters: title, items, expand_icon_position, default_expanded, expanded, inline, active_key, popover_overlay_width, styles, class_names, root_class_name, additional_props. +- Events: expand, click. +- Slots: items. +- Lifecycle & API: skip_api=True. + +Section Sources + +- [backend/modelscope_studio/components/antdx/sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) + +### Suggestion + +- Import Path: `modelscope_studio.components.antdx.Suggestion` +- Sub-components: Item +- Key Parameters: additional_props, items, block, open, should_trigger, class_names, styles, root_class_name. +- Events: select, open_change. +- Slots: items, children. +- Lifecycle & API: skip_api=True. + +Section Sources + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) + +### Think + +- Import Path: `modelscope_studio.components.antdx.Think` +- Key Parameters: additional_props, icon, styles, class_names, loading, title, root_class_name, default_expanded, expanded, blink. +- Events: expand. +- Slots: loading, icon, title. +- Lifecycle & API: skip_api=True. + +Section Sources + +- [backend/modelscope_studio/components/antdx/think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) + +### ThoughtChain + +- Import Path: `modelscope_studio.components.antdx.ThoughtChain` +- Sub-components: Item, ThoughtChainItem +- Key Parameters: expanded_keys, default_expanded_keys, items, line, prefix_cls, styles, class_names, root_class_name, additional_props. +- Events: expand. +- Slots: items. +- Lifecycle & API: skip_api=True. + +Section Sources + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) + +## Dependency Analysis + +- Components uniformly inherit from `ModelScopeLayoutComponent` or `ModelScopeDataLayoutComponent`; the latter supports `preprocess/postprocess` and API specification export for data types. +- Most components are layout-type components with `skip_api=True` that do not expose an API; a few data-type components (Attachments, Sender) implement data serialization specifications. +- Components resolve frontend resource directories via `resolve_frontend_dir("xxx", type="antdx")`, ensuring one-to-one correspondence with frontend components. + +```mermaid +graph LR +A["AntdXBubble"] --> B["ModelScopeLayoutComponent"] +C["AntdXAttachments"] --> D["ModelScopeDataLayoutComponent"] +E["AntdXSender"] --> D +F["AntdXConversations"] --> B +G["AntdXPrompts"] --> B +H["AntdXActions"] --> B +I["AntdXFileCard"] --> B +J["AntdXFolder"] --> B +K["AntdXCodeHighlighter"] --> B +L["AntdXNotification"] --> B +M["AntdXSources"] --> B +N["AntdXSuggestion"] --> B +O["AntdXThink"] --> B +P["AntdXThoughtChain"] --> B +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:13-135](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L13-L135) +- [backend/modelscope_studio/components/antdx/attachments/**init**.py:22-227](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L22-L227) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:14-149](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L14-L149) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) +- [backend/modelscope_studio/components/antdx/actions/**init**.py:15-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L112) +- [backend/modelscope_studio/components/antdx/file_card/**init**.py:11-112](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L11-L112) +- [backend/modelscope_studio/components/antdx/folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) +- [backend/modelscope_studio/components/antdx/code_highlighter/**init**.py:6-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L6-L71) +- [backend/modelscope_studio/components/antdx/notification/**init**.py:10-97](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L10-L97) +- [backend/modelscope_studio/components/antdx/sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) + +## Performance Considerations + +- Event Binding: Callbacks are bound via `EventListener` at construction time, avoiding performance overhead from duplicate bindings. +- Data Component Serialization: Attachments and Sender explicitly implement `preprocess/postprocess`, reducing unnecessary data conversion overhead. +- Frontend Resources: `resolve_frontend_dir` ensures only necessary resources are loaded, avoiding redundant bundling. +- Rendering Optimization: Layout-type components with `skip_api=True` reduce additional processing at the API layer. + +## Troubleshooting Guide + +- Events Not Triggering: Check that callbacks in the EVENTS list are correctly bound, and confirm that the frontend component has the corresponding events enabled. +- File Upload Issues: Verify the Attachments parameters such as action, headers, with_credentials, and max_count; ensure the server is accessible and the cache directory has proper permissions. +- Input Value Not Updating: The value and default_value of Sender must maintain consistent data types; pay attention to the timing of change/submit/cancel events. +- Style and Slots: If slot content is not displayed, check whether the SLOTS definition matches the slot names passed in. + +## Conclusion + +The Antdx component library provides a rich set of layout, input, and data components centered around AI/ML application scenarios. It meets typical requirements for conversational systems, file handling, and user input while ensuring good extensibility and consistency through unified event and slot mechanisms. In practice, it is recommended to prioritize data-type components (such as Attachments and Sender) for clearer API behavior and data flow, while using layout-type components to build friendly interactive interfaces. + +## Appendix + +### API Index (by Scenario) + +- General Components + - Bubble, Conversations, Prompts, Suggestions, Think, ThoughtChain, CodeHighlighter, Notification, Sources, FileCard, Folder, Actions +- Wake/Input Components + - Sender (with Header, Switch) +- Utility Components + - Attachments (file upload/download/preview/removal) +- Feedback Components + - Actions (action group and feedback) +- Expression Components + - CodeHighlighter (code highlighting) +- State & Process Components + - Think, ThoughtChain, Notification, Sources, Folder, FileCard + +### Standard Instantiation Examples (Path References) + +- Conversational System + - Use Bubble, Conversations, Prompts, Sender, and Actions together to build a conversational interface. + - Example path references: [Bubble constructor:56-116](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L56-L116), [Conversations constructor:49-91](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L49-L91), [Prompts constructor:28-71](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L28-L71), [Sender constructor:68-128](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L68-L128), [Actions constructor:58-94](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L58-L94) +- File Handling + - Use Attachments to receive file lists, combined with Sender's paste/paste_file events for drag-and-drop and clipboard upload. + - Example path references: [Attachments constructor:66-160](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L66-L160), [Sender events and parameters:21-59](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L21-L59) +- User Input + - Use Sender's submit/cancel events and value/default_value to control input state. + - Example path references: [Sender events and parameters:21-99](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L21-L99) + +### ML Integration Interfaces and Data Formats + +- Data-type Components (Attachments, Sender) + - preprocess: Converts payload to the internal representation expected by the component (e.g., file path list). + - postprocess: Converts internal value to the data structure for external output (e.g., ListFiles). + - api_info: Exports JSON Schema, specifying API input/output types. +- Layout-type Components (all other components) + - Typically skip_api=True, not exposing an API; state changes are driven by properties and events. + +### Lifecycle and Event Handling Mechanism + +- Event Binding: Callbacks are registered via `EventListener` in the constructor; the component internally binds to frontend events via `_internal.update`. +- Slots: Supported slot names are defined via SLOTS; the component internally parses and renders the corresponding content. +- Styles and Class Names: Uniform style injection is supported via styles, class_names, and root_class_name. diff --git a/.wiki/en/API Reference/Python API/Antdx Components API/Confirmation Components API.md b/.wiki/en/API Reference/Python API/Antdx Components API/Confirmation Components API.md new file mode 100644 index 00000000..bc2b26d8 --- /dev/null +++ b/.wiki/en/API Reference/Python API/Antdx Components API/Confirmation Components API.md @@ -0,0 +1,366 @@ +# Confirmation Components API + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/antdx/thought_chain/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py) +- [backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py) +- [frontend/antdx/thought-chain/thought-chain.tsx](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [frontend/antdx/thought-chain/item/thought-chain.item.tsx](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx) +- [frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [docs/components/antdx/thought_chain/demos/basic.py](file://docs/components/antdx/thought_chain/demos/basic.py) +- [docs/components/antdx/thought_chain/demos/item_status.py](file://docs/components/antdx/thought_chain/demos/item_status.py) +- [docs/components/antdx/thought_chain/demos/nested_use.py](file://docs/components/antdx/thought_chain/demos/nested_use.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the Python API reference for Antdx confirmation components (AntdX), focusing on the ThoughtChain component's thought chain management, decision process tracking, and state visualization capabilities. Key areas covered: + +- Hierarchical structure management and node state control for ThoughtChain and ThoughtChainItem +- Chain operation processing and node connection relationships +- Data structure definitions, state change listeners, and result output mechanisms +- Standard usage examples for scenarios such as AI decision process display, thought chain analysis, and action confirmation +- Component state management strategies, event propagation mechanisms, and performance monitoring configurations +- Integration approaches with chatbots (Chatbot) and reasoning process visualization + +## Project Structure + +The ThoughtChain-related implementation in Antdx consists of backend Python components and a frontend Svelte/React wrapper layer: + +- Backend Python Components: Wrap Gradio layout components, responsible for property forwarding and frontend resource location +- Frontend Wrapper Layer: Bridges Ant Design X's ThoughtChain and ThoughtChain.Item components to the Gradio ecosystem, supporting slot rendering and context injection + +```mermaid +graph TB +subgraph "Backend Python Components" +A["AntdXThoughtChain
__init__.py"] +B["AntdXThoughtChainItem
item/__init__.py"] +C["AntdXThoughtChainThoughtChainItem
thought_chain_item/__init__.py"] +end +subgraph "Frontend Wrapper Layer" +D["thought-chain/thought-chain.tsx"] +E["thought-chain/item/thought-chain.item.tsx"] +F["thought-chain-item/thought-chain.thought-chain-item.tsx"] +end +A --> D +B --> E +C --> F +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [backend/modelscope_studio/components/antdx/thought_chain/item/**init**.py:8-78](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L8-L78) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L8-L81) +- [frontend/antdx/thought-chain/thought-chain.tsx:11-42](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L42) +- [frontend/antdx/thought-chain/item/thought-chain.item.tsx:9-32](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L9-L32) +- [frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx:7-13](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L7-L13) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [frontend/antdx/thought-chain/thought-chain.tsx:11-42](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L42) + +## Core Components + +- AntdXThoughtChain: Thought chain container, supports expanded keys, line styles, prefix class names, and other properties; listens for "expand" events to implement expanded key change callbacks; supports the "items" slot +- AntdXThoughtChainItem: Top-level node, supports title, description, icon, status, variant, blink, and other properties; supports "description", "icon", "title" slots +- AntdXThoughtChainThoughtChainItem: Nested node, supports content, extra, footer, icon, title, status, collapsible, blink, and other properties; supports "content", "description", "footer", "icon", "title" slots + +All of the above components inherit from ModelScopeLayoutComponent, with general Gradio layout component features, and specify the frontend directory via `resolve_frontend_dir`. + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [backend/modelscope_studio/components/antdx/thought_chain/item/**init**.py:8-78](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L8-L78) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L8-L81) + +## Architecture Overview + +The diagram below shows the complete chain from Python calls to frontend rendering, as well as the role positions of slots and context: + +```mermaid +sequenceDiagram +participant Py as "Python Components
AntdXThoughtChain/AntdXThoughtChainItem" +participant Wrap as "Frontend Wrapper Layer
thought-chain.tsx / item/thought-chain.item.tsx" +participant ADX as "Ant Design X
@ant-design/x" +participant Slot as "Slot System
ReactSlot / renderItems" +Py->>Wrap : Pass properties and visibility +Wrap->>ADX : Render ThoughtChain/Item +Wrap->>Slot : Parse and render slot content +ADX-->>Wrap : Render result +Wrap-->>Py : Return value/placeholder render +``` + +**Diagram Sources** + +- [frontend/antdx/thought-chain/thought-chain.tsx:11-42](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L42) +- [frontend/antdx/thought-chain/item/thought-chain.item.tsx:9-32](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L9-L32) +- [frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx:7-13](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L7-L13) + +## Detailed Component Analysis + +### AntdXThoughtChain (Thought Chain Container) + +- Role and Responsibility + - Container for displaying multiple thought chain nodes + - Supports expanded key control, default expanded keys, line styles, prefix class names, and other appearance and interaction parameters + - Events: expand (triggered when expanded keys change) + - Slots: items (for batch injecting nodes) +- Key Properties + - expanded_keys: Currently expanded node key list + - default_expanded_keys: Initial default expanded key list + - items: Node data array (optional) + - line: Line style (boolean or specific string) + - prefix_cls: Prefix class name + - styles/class_names/root_class_name: Style and class name extensions +- Processing Flow + - Frontend parses slot items via context or directly uses the passed items + - Uses renderItems to clone slot nodes into React structures + - Renders the @ant-design/x ThoughtChain component + +```mermaid +flowchart TD +Start(["Enter AntdXThoughtChain"]) --> CheckItems["Check if items are passed"] +CheckItems --> |Yes| UsePassed["Use passed items"] +CheckItems --> |No| ResolveSlot["Resolve slot items/default"] +ResolveSlot --> RenderItems["Call renderItems to clone nodes"] +UsePassed --> RenderItems +RenderItems --> RenderADX["Render @ant-design/x ThoughtChain"] +RenderADX --> End(["Complete"]) +``` + +**Diagram Sources** + +- [frontend/antdx/thought-chain/thought-chain.tsx:14-39](file://frontend/antdx/thought-chain/thought-chain.tsx#L14-L39) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [frontend/antdx/thought-chain/thought-chain.tsx:11-42](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L42) + +### AntdXThoughtChainItem (Top-level Node) + +- Role and Responsibility + - Represents a top-level node in the thought chain + - Supports title, description, icon, status, variant, blink, and other properties + - Supports "description", "icon", "title" slots for custom rendering +- Key Properties + - title/description/icon: Node title, description, icon + - status: Node status (pending/success/error/abort) + - variant: Node appearance variant (solid/outlined/text) + - blink: Whether to blink as a prompt + - prefix_cls/class_names/styles: Style and class name extensions +- Slots + - description/title/icon: Replace the content of the corresponding area + +```mermaid +classDiagram +class AntdXThoughtChainItem { ++title : str|None ++description : str|None ++icon : str|None ++status : enum ++variant : enum ++blink : bool|None ++prefix_cls : str|None ++class_names : dict|str|None ++styles : dict|str|None +} +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/item/**init**.py:18-58](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L18-L58) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/item/**init**.py:8-78](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L8-L78) +- [frontend/antdx/thought-chain/item/thought-chain.item.tsx:9-32](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L9-L32) + +### AntdXThoughtChainThoughtChainItem (Nested Node) + +- Role and Responsibility + - Represents a nested node used inside a ThoughtChain + - Supports content, extra, footer, icon, title, status, collapsible, blink, and other properties + - Supports "content", "description", "footer", "icon", "title" slots +- Key Properties + - key: Node unique identifier + - title/description/content/extra/footer/icon: Content for each area of the node + - status: Node status + - collapsible: Whether collapsible + - blink: Whether to blink as a prompt +- Slots + - content/description/footer/icon/title: Replace the content of the corresponding area + +```mermaid +classDiagram +class AntdXThoughtChainThoughtChainItem { ++key : str|None ++title : str|None ++description : str|None ++content : str|None ++extra : str|None ++footer : str|None ++icon : str|None ++status : enum ++collapsible : bool|None ++blink : bool|None +} +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:18-60](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L18-L60) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L8-L81) +- [frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx:7-13](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L7-L13) + +### Data Structures and Node Connection Relationships + +- Node Data Structure + - items array: Each element corresponds to a ThoughtChainItem or ThoughtChainThoughtChainItem + - Fields include but are not limited to: title, description, content, icon, status, key, collapsible, etc. +- Connection Relationships + - AntdXThoughtChain acts as the root container; multiple ThoughtChainItems can be nested inside + - The content slot of each ThoughtChainItem can nest another ThoughtChain again, forming multi-level nesting +- State Changes and Listeners + - expand event: Triggered when expanded keys change; can be used for dynamically updating UI or logging + - status property: Used to intuitively reflect the execution status of nodes (success/failure/in-progress/abort) + +**Section Sources** + +- [frontend/antdx/thought-chain/thought-chain.tsx:14-39](file://frontend/antdx/thought-chain/thought-chain.tsx#L14-L39) +- [docs/components/antdx/thought_chain/demos/nested_use.py:10-64](file://docs/components/antdx/thought_chain/demos/nested_use.py#L10-L64) +- [docs/components/antdx/thought_chain/demos/item_status.py:9-33](file://docs/components/antdx/thought_chain/demos/item_status.py#L9-L33) + +### State Management Strategy and Event Propagation + +- State Management + - Drive UI state changes via the status property (e.g., color, icon, blink) + - Control node expansion/collapse via expanded_keys/default_expanded_keys +- Event Propagation + - The expand event is listened to at the container level; `bind_expand_event` can be set in the callback to enable event binding + - Event callbacks are typically used for linked updates to other components or logging +- Result Output Mechanism + - The component does not directly produce output values; external logic (e.g., button click) can be used to update the items or state of ThoughtChain via Gradio + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:20-25](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L20-L25) + +### Performance Monitoring Configuration + +- Recommended Practices + - For scenarios with large numbers of nodes, prefer passing data via the items parameter at once to reduce slot parsing overhead + - Use expanded_keys/default_expanded_keys wisely to avoid rendering too many nodes at once + - When frequent state updates are needed, batch update items to reduce multiple re-renders +- Monitoring Metrics + - Page rendering time, node count, expand/collapse frequency, state switch count + +[This section contains general recommendations and does not require specific file references] + +## Dependency Analysis + +- Component Export and Aggregation + - The antdx component module uniformly exports ThoughtChain and its sub-items for on-demand import in business code +- Frontend Dependencies + - @ant-design/x provides core rendering capabilities + - sveltify bridges Svelte components to React/Gradio + - renderItems is used for cloning and rendering slot nodes + +```mermaid +graph LR +Export["antdx/components.py Export"] --> A["AntdXThoughtChain"] +Export --> B["AntdXThoughtChainItem"] +Export --> C["AntdXThoughtChainThoughtChainItem"] +A --> D["thought-chain/thought-chain.tsx"] +B --> E["thought-chain/item/thought-chain.item.tsx"] +C --> F["thought-chain-item/thought-chain.thought-chain-item.tsx"] +D --> ADX["@ant-design/x"] +E --> ADX +F --> ADX +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/components.py:35-40](file://backend/modelscope_studio/components/antdx/components.py#L35-L40) +- [frontend/antdx/thought-chain/thought-chain.tsx:3-6](file://frontend/antdx/thought-chain/thought-chain.tsx#L3-L6) +- [frontend/antdx/thought-chain/item/thought-chain.item.tsx:4-7](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L4-L7) +- [frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx:3-5](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L3-L5) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/components.py:35-40](file://backend/modelscope_studio/components/antdx/components.py#L35-L40) + +## Performance Considerations + +- Rendering Optimization + - Use the items parameter rather than numerous slots to reduce frontend parsing costs + - For long lists, consider pagination or lazy loading +- State Updates + - Batch update items to avoid frequent incremental changes + - Use the expand event wisely to avoid excessive responses causing redraws +- Styles and Class Names + - Use styles/class_names/root_class_name to precisely control styles and avoid global pollution + +[This section contains general recommendations and does not require specific file references] + +## Troubleshooting Guide + +- Common Issues + - Slot not taking effect: Confirm the slot name is correct and matches the slots supported by the component + - State not updating: Check whether status is correctly set and ensure external logic has triggered a Gradio update + - Expanded keys not working: Confirm that the expand event is bound and expanded_keys/default_expanded_keys are set appropriately +- Troubleshooting Steps + - Validate component behavior using a minimal example + - Gradually add slots and state to narrow down the problem scope + - Check the browser console and network panel to confirm that frontend resources are loading normally + +**Section Sources** + +- [docs/components/antdx/thought_chain/demos/basic.py:31-74](file://docs/components/antdx/thought_chain/demos/basic.py#L31-L74) +- [docs/components/antdx/thought_chain/demos/item_status.py:9-33](file://docs/components/antdx/thought_chain/demos/item_status.py#L9-L33) + +## Conclusion + +Antdx's ThoughtChain component provides a reliable visualization foundation for AI decision process display, thought chain analysis, and action confirmation through a clear hierarchical structure and rich state control. Combined with the slot system and event mechanism, it can be flexibly extended and customized in complex scenarios. For large-scale data scenarios, it is recommended to use item parameter passing and batch update strategies for better performance. + +[This section contains summary content and does not require specific file references] + +## Appendix + +### Standard Usage Examples (Paths) + +- Basic Usage: Display multiple ThoughtChainItems with configured states and slots + - [docs/components/antdx/thought_chain/demos/basic.py:31-74](file://docs/components/antdx/thought_chain/demos/basic.py#L31-L74) +- State Toggle Demo: Drive node state changes via buttons + - [docs/components/antdx/thought_chain/demos/item_status.py:46-67](file://docs/components/antdx/thought_chain/demos/item_status.py#L46-L67) +- Nested Usage: Nest another ThoughtChain within node content + - [docs/components/antdx/thought_chain/demos/nested_use.py:19-64](file://docs/components/antdx/thought_chain/demos/nested_use.py#L19-L64) + +### Quick API Reference (Paths) + +- Container Component: AntdXThoughtChain + - [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:30-68](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L30-L68) +- Top-level Node: AntdXThoughtChainItem + - [backend/modelscope_studio/components/antdx/thought_chain/item/**init**.py:18-60](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L18-L60) +- Nested Node: AntdXThoughtChainThoughtChainItem + - [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:18-63](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L18-L63) diff --git a/.wiki/en/API Reference/Python API/Antdx Components API/Expression Components API.md b/.wiki/en/API Reference/Python API/Antdx Components API/Expression Components API.md new file mode 100644 index 00000000..ead87d5c --- /dev/null +++ b/.wiki/en/API Reference/Python API/Antdx Components API/Expression Components API.md @@ -0,0 +1,359 @@ +# Expression Components API + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/antdx/attachments/__init__.py](file://backend/modelscope_studio/components/antdx/attachments/__init__.py) +- [backend/modelscope_studio/components/antdx/sender/__init__.py](file://backend/modelscope_studio/components/antdx/sender/__init__.py) +- [backend/modelscope_studio/components/antdx/sender/header/__init__.py](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py) +- [backend/modelscope_studio/components/antdx/sender/switch/__init__.py](file://backend/modelscope_studio/components/antdx/sender/switch/__init__.py) +- [backend/modelscope_studio/components/antdx/suggestion/__init__.py](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py) +- [backend/modelscope_studio/components/antdx/suggestion/item/__init__.py](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Usage Examples and Best Practices](#appendix-usage-examples-and-best-practices) + +## Introduction + +This document is the Python API reference for Antdx expression components, focusing on the following capabilities: + +- File attachment handling: Upload, drag-and-drop, download, preview, removal, type restrictions, and list display strategies +- Input and send control: Text input box management, submit types (Enter/Shift+Enter), paste and keyboard events, voice input toggle +- Multimodal input support: Extended header area, switch, and skill panel via Sender sub-components +- Quick commands: Suggestion component and its items' triggering, selection, and panel state management +- Chatbot integration: Data flow and interaction protocol based on Gradio data classes and event callbacks + +## Project Structure + +Antdx components reside in the backend Python package, exported through a unified entry point, and mapped to Svelte implementations in the frontend via corresponding directory mappings. The expression component-related modules are organized as follows: + +- Top-level exports: `antdx/__init__.py` and `antdx/components.py` provide aggregated component exports +- Attachments: `antdx/attachments` +- Sender: `antdx/sender` (with header, switch sub-components) +- Suggestion: `antdx/suggestion` (with item sub-component) + +```mermaid +graph TB +subgraph "Python Backend" +A["antdx/__init__.py"] +B["antdx/components.py"] +C["attachments/__init__.py"] +D["sender/__init__.py"] +E["sender/header/__init__.py"] +F["sender/switch/__init__.py"] +G["suggestion/__init__.py"] +H["suggestion/item/__init__.py"] +end +A --> C +A --> D +A --> E +A --> F +A --> G +A --> H +B --> C +B --> D +B --> E +B --> F +B --> G +B --> H +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +Section Sources + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## Core Components + +- AntdXAttachments: File attachment upload and management, supports drag-and-drop, preview, download, removal, type filtering, list styles, placeholders, etc. +- AntdXSender: Input and send control, supports auto height, read-only, loading state, placeholder, submit type, voice input, file paste, keyboard events, etc. +- AntdXSenderHeader: Sender header area, supports expand/collapse, title, closable, etc. +- AntdXSenderSwitch: Built-in switch for Sender, supports checked/unchecked labels and icons +- AntdXSuggestion: Quick command suggestion panel, supports items list, open state, select event +- AntdXSuggestionItem: Suggestion item, supports label, icon, extra content, and other slots + +Section Sources + +- [backend/modelscope_studio/components/antdx/attachments/**init**.py:22-227](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L22-L227) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:14-149](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L14-L149) +- [backend/modelscope_studio/components/antdx/sender/header/**init**.py:8-74](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py#L8-L74) +- [backend/modelscope_studio/components/antdx/sender/switch/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/sender/switch/__init__.py#L8-L81) +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/suggestion/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py#L8-L68) + +## Architecture Overview + +The frontend-backend interaction of expression components follows the Gradio data class and event model: + +- Backend components define data models (e.g., ListFiles) and event listeners +- Frontend maps to the corresponding Svelte components based on FRONTEND_DIR +- Data format conversion between Python and frontend is done via preprocess/postprocess +- Event callbacks are bound to frontend events via `_internal.update` + +```mermaid +sequenceDiagram +participant U as "User" +participant FE as "Frontend Component (Svelte)" +participant PY as "Backend Component (Python)" +participant GR as "Gradio Data Class" +U->>FE : Trigger event (input/paste/drag-and-drop/click) +FE->>PY : Event callback binding (_internal.update) +PY->>GR : preprocess(payload) convert to internal value +GR-->>PY : Return processed value +PY-->>FE : postprocess(value) return frontend display value +FE-->>U : Update UI (list/preview/state) +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/attachments/**init**.py:168-207](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L168-L207) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:134-142](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L134-L142) + +## Component Details + +### Attachments Component (AntdXAttachments) + +- Key Features + - Supports file upload, drag-and-drop upload, batch selection, maximum count limit + - Supports file type filtering (accept), HTTP request parameters (headers, data, method) + - Supports custom upload requests (custom_request), pre-upload hooks (before_upload) + - List styles and overflow strategies (list_type, overflow), shows upload list by default + - Placeholder and image preview enhancements (placeholder, imageProps.\*) + - Events: change, drop, download, preview, remove + - Slots: showUploadList._, iconRender, itemRender, placeholder._, imageProps.\*, etc. +- Data Flow + - preprocess: Converts the ListFiles passed from the frontend to a local path string list + - postprocess: Downloads local paths/URLs to the cache and packages them as ListFiles to return to the frontend +- File Handling Strategy + - Remote URLs: Downloaded to cache directory + - Local paths: Used directly + - Preview: Uses Gradio FileData metadata (orig_name, size) + +```mermaid +flowchart TD +Start(["Enter preprocess"]) --> CheckNull{"Is payload empty?"} +CheckNull --> |Yes| ReturnNone["Return None"] +CheckNull --> |No| Loop["Iterate each FileData"] +Loop --> Process["_process_single_file
Generate temp filename"] +Process --> Append["Collect string paths"] +Append --> DonePre["Return string list"] +subgraph "postprocess" +PStart["Receive string list"] --> PNull{"Is empty?"} +PNull --> |Yes| PEmpty["Return empty list"] +PNull --> |No| PLoop["Iterate paths"] +PLoop --> PType{"Is URL?"} +PType --> |Yes| PDownload["Download to cache"] +PType --> |No| PUse["Use directly"] +PDownload --> PBuild["Build FileData(orig_name,size)"] +PUse --> PBuild +PBuild --> PEnd["Return ListFiles"] +end +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/attachments/**init**.py:162-207](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L162-L207) + +Section Sources + +- [backend/modelscope_studio/components/antdx/attachments/**init**.py:22-227](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L22-L227) + +### Sender Component (AntdXSender) + +- Key Features + - Input box management: auto_size, placeholder, disabled, read_only, loading + - Submit control: submit_type (enter or shiftEnter) + - Events: change, submit, cancel, allow_speech_recording_change, key_down/key_press, focus/blur, paste/paste_file, skill_closable_close + - Slots: suffix, header, prefix, footer, skill.\*, etc. + - Sub-components: Header, Switch (for extending the header area and switch) +- Data Flow + - preprocess/postprocess: Pass through string values +- Multimodal Input Support + - allow_speech: Enable voice input (boolean or dict) + - paste_file: File paste event + - skill.\*: Skill panel title, tooltip, and closable icon + +```mermaid +sequenceDiagram +participant U as "User" +participant FE as "Sender Frontend" +participant PY as "AntdXSender" +U->>FE : Input/keypress/paste/click send +FE->>PY : Event callback (e.g. change/submit/paste_file) +PY-->>FE : Control submit behavior based on submit_type +FE-->>U : Update state (loading/disabled) +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/sender/**init**.py:21-59](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L21-L59) + +Section Sources + +- [backend/modelscope_studio/components/antdx/sender/**init**.py:14-149](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L14-L149) + +### Sender Header (AntdXSenderHeader) + +- Key Features + - Expand/collapse: open, closable + - Title: title + - Slots: title +- Usage + - Used as a Sender sub-component for holding the header title and close button + +Section Sources + +- [backend/modelscope_studio/components/antdx/sender/header/**init**.py:8-74](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py#L8-L74) + +### Sender Switch (AntdXSenderSwitch) + +- Key Features + - Value: value (bool) + - Labels and Icons: checked_children, un_checked_children, icon + - States: disabled, loading + - Slots: checkedChildren, unCheckedChildren, icon +- Usage + - Used as a Sender sub-component for toggling certain send behaviors or modes + +Section Sources + +- [backend/modelscope_studio/components/antdx/sender/switch/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/sender/switch/__init__.py#L8-L81) + +### Suggestion Component (AntdXSuggestion) and Item (AntdXSuggestionItem) + +- Suggestion Panel + - items: Suggestion item list (string or dict) + - Open state: open, block, should_trigger + - Events: select, open_change + - Slots: items, children +- Suggestion Item + - label, icon, extra, key + - Slots: label, icon, extra + +```mermaid +classDiagram +class AntdXSuggestion { ++items ++open ++block ++should_trigger ++EVENTS ++SLOTS +} +class AntdXSuggestionItem { ++value ++label ++icon ++extra ++key ++EVENTS ++SLOTS +} +AntdXSuggestion --> AntdXSuggestionItem : "contains multiple items" +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/suggestion/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py#L8-L68) + +Section Sources + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/suggestion/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py#L8-L68) + +## Dependency Analysis + +- Component Aggregation + - `antdx/__init__.py` and `antdx/components.py` uniformly export all sub-components for on-demand import by upper-level applications +- Component Cohesion + - Each component independently defines EVENTS, SLOTS, FRONTEND_DIR with clear responsibilities +- Event Coupling + - Frontend events are mapped to backend callbacks via EventListener and `_internal.update` +- Data Class Dependencies + - The Attachments component uses Gradio ListFiles and FileData to ensure cross-platform data consistency + +```mermaid +graph LR +A["antdx/__init__.py"] --> C["attachments/__init__.py"] +A --> D["sender/__init__.py"] +D --> E["sender/header/__init__.py"] +D --> F["sender/switch/__init__.py"] +A --> G["suggestion/__init__.py"] +G --> H["suggestion/item/__init__.py"] +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +Section Sources + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## Performance Considerations + +- File Handling + - Remote URL downloads should be combined with cache directories and async strategies to avoid blocking the main thread + - Large file uploads should use chunked or server-side direct upload strategies +- Event Callbacks + - Avoid heavy computations in callbacks for high-frequency events (e.g., change, key_down) +- UI Rendering + - Enable virtualization (if applicable) during list rendering to reduce DOM nodes + - Image preview and thumbnail generation should be done in background threads whenever possible + +## Troubleshooting Guide + +- Attachments Cannot Upload/Preview + - Check that accept and headers/data/method configurations are correct + - Confirm that custom_request and before_upload callbacks do not throw errors +- Remote Files Cannot Download + - Check URL accessibility and with_credentials settings + - Check cache directory permissions and disk space +- Sender Events Not Working + - Confirm that submit_type and keyboard event bindings match + - Check whether disabled/read_only/loading states are preventing interaction +- Suggestion Panel Not Showing + - Check whether items is empty or the should_trigger condition is met + - Confirm that open/open_change events are correctly bound + +## Conclusion + +Antdx expression components provide complete file attachment, input sending, and quick command capabilities through a clear event and slot system. Relying on Gradio data classes and the event model, flexible data conversion and interaction control can be performed on the Python side while maintaining a consistent frontend UI experience. + +## Appendix: Usage Examples and Best Practices + +- File Upload and Preview + - Use AntdXAttachments' accept to restrict types; set headers and data for authentication and additional parameter passing + - Control list styles and visibility via list_type and show_upload_list + - Enhance image preview experience with preview_file and imageProps.\* +- Input and Send Control + - Use submit_type to precisely control submit timing (enter/shiftEnter) + - Extend the header area and toggle via Sender.Header and Sender.Switch + - Handle file paste scenarios via paste/paste_file events +- Quick Commands + - Control the suggestion panel using AntdXSuggestion's items and open + - Enrich command display with AntdXSuggestionItem's label/icon/extra +- Integration with Chatbot + - Use Sender's value as the message body, and the attachment list as multimodal input + - Assemble the message body via event callbacks on the backend and call the bot API + - Use preprocess/postprocess for message and file serialization/deserialization diff --git a/.wiki/en/API Reference/Python API/Antdx Components API/Feedback Components API.md b/.wiki/en/API Reference/Python API/Antdx Components API/Feedback Components API.md new file mode 100644 index 00000000..f6018c66 --- /dev/null +++ b/.wiki/en/API Reference/Python API/Antdx Components API/Feedback Components API.md @@ -0,0 +1,446 @@ +# Feedback Components API + + +**Files Referenced in This Document** +- [actions/__init__.py](file://backend/modelscope_studio/components/antdx/actions/__init__.py) +- [action_item/__init__.py](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py) +- [item/__init__.py](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py) +- [copy/__init__.py](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py) +- [audio/__init__.py](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py) +- [feedback/__init__.py](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py) +- [notification/__init__.py](file://backend/modelscope_studio/components/antdx/notification/__init__.py) +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Usage Examples and Best Practices](#appendix-usage-examples-and-best-practices) + +## Introduction + +This document is the Python API reference for Antdx feedback components, covering: the Actions component for action list management, action item configuration, and user interaction; ActionsItem for defining action items; ActionItem for specific action implementations; the Copy component for copy functionality; the Audio component for audio processing; the Feedback component for user feedback collection; and the Notification component for notification management, message push, and user feedback responses. The document also provides event handling strategies, state synchronization mechanisms, and user experience optimization configurations, along with reference solutions for chatbot integration and real-time user behavior feedback. + +## Project Structure + +Antdx feedback-related components reside in the backend Python package, organized by functional modules. Frontend resources are provided by Svelte components in the frontend directory. The Python layer exposes a unified interface to the application layer through Gradio component encapsulation and event binding. + +```mermaid +graph TB +subgraph "Antdx Components (Python)" +A["actions/__init__.py
AntdXActions"] +B["actions/action_item/__init__.py
AntdXActionsActionItem"] +C["actions/item/__init__.py
AntdXActionsItem"] +D["actions/copy/__init__.py
AntdXActionsCopy"] +E["actions/audio/__init__.py
AntdXActionsAudio"] +F["actions/feedback/__init__.py
AntdXActionsFeedback"] +G["notification/__init__.py
AntdXNotification"] +end +subgraph "Export Entry" +H["components.py
Unified Export"] +end +A --> B +A --> C +A --> D +A --> E +A --> F +H --> A +H --> G +``` + +**Diagram Sources** + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [actions/**init**.py:15-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L112) +- [action_item/**init**.py:10-80](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L10-L80) +- [item/**init**.py:10-77](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L10-L77) +- [copy/**init**.py:10-72](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L10-L72) +- [audio/**init**.py:10-71](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L10-L71) +- [feedback/**init**.py:10-74](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L10-L74) +- [notification/**init**.py:10-97](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L10-L97) + +**Section Sources** + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## Core Components + +- AntdXActions: Action set container, supports event binding and slot extension, used to hold multiple action items and submenus. +- AntdXActionsActionItem: Custom action item, supports label, icon, danger style, trigger method, and sub-items. +- AntdXActionsItem: Standard action item, supports states (loading/running/error/default), icon switching, and style customization. +- AntdXActionsCopy: Copy action, bound to click event, supports custom icon and text. +- AntdXActionsAudio: Audio status indicator, supports state enumeration and style customization. +- AntdXActionsFeedback: Feedback component for like/dislike/default states, supports click and state change events. +- AntdXNotification: Notification component, supports permission, click, close, error, show events, and multilingual/direction attributes. + +All of the above components inherit from a unified layout component base class, with Gradio-compatible event binding and rendering control capabilities. + +**Section Sources** + +- [actions/**init**.py:15-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L112) +- [action_item/**init**.py:10-80](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L10-L80) +- [item/**init**.py:10-77](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L10-L77) +- [copy/**init**.py:10-72](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L10-L72) +- [audio/**init**.py:10-71](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L10-L71) +- [feedback/**init**.py:10-74](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L10-L74) +- [notification/**init**.py:10-97](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L10-L97) + +## Architecture Overview + +Antdx feedback components are exposed at the Python layer as Gradio components; the frontend implements UI behavior and interaction through corresponding Svelte components. Components bind callbacks via event listeners to relay user operations to the backend for event delivery and state updates. + +```mermaid +sequenceDiagram +participant U as "User" +participant A as "AntdXActions" +participant AI as "AntdXActionsActionItem" +participant AF as "AntdXActionsFeedback" +participant AN as "AntdXNotification" +U->>A : Trigger click/dropdown event +A-->>U : Trigger bound event callback +U->>AI : Click custom action item +AI-->>U : Trigger item_click callback +U->>AF : Click feedback button +AF-->>U : Trigger click/change callback +U->>AN : Trigger notification show/click/close +AN-->>U : Trigger permission/click/close/error/show callback +``` + +**Diagram Sources** + +- [actions/**init**.py:26-46](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L26-L46) +- [action_item/**init**.py:15-21](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L15-L21) +- [feedback/**init**.py:15-23](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L15-L23) +- [notification/**init**.py:14-30](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L14-L30) + +## Detailed Component Analysis + +### Actions Component (AntdXActions) + +- Responsibility: Serves as the action set container, managing action item lists, dropdown menu properties, and animation effects; supports event binding and slot extension. +- Key Properties + - items: Action item array for initializing the action list. + - variant: Appearance variant (e.g., borderless/outlined/filled). + - dropdown_props: Dropdown menu related property object. + - fade_in/fade_in_left: Entry animation toggles. + - class_names/styles: Style class names and inline style mappings. + - Slots: items, dropdownRender, popupRender, menu.expandIcon, overflowedIndicator, menu.items. +- Events + - click: Triggered when any action item is clicked. + - dropdown_open_change/dropdown_menu_open_change: Dropdown open/menu open state changes. + - dropdown_menu_click/dropdown_menu_deselect/dropdown_menu_select: Menu item click/deselect/select events. +- Processing Flow + - Internal binding flags are set at initialization so frontend events can be sent back to the backend. + - During rendering, action items and menu structures are dynamically generated based on items and dropdown_props. + - Custom rendering logic is extended through slots. + +```mermaid +classDiagram +class AntdXActions { ++Properties : items, variant, dropdown_props, fade_in, fade_in_left ++Methods : preprocess(), postprocess() ++Events : click, dropdown_open_change, dropdown_menu_*... ++Slots : items, dropdownRender, popupRender, menu.expandIcon, overflowedIndicator, menu.items +} +``` + +**Diagram Sources** + +- [actions/**init**.py:58-94](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L58-L94) + +**Section Sources** + +- [actions/**init**.py:15-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L112) + +### ActionsItem (AntdXActionsItem) + +- Responsibility: Standard action item, supports state switching and icon replacement. +- Key Properties + - status: State enumeration (loading/error/running/default). + - label: Display label. + - default_icon/running_icon: Default icon and running icon. + - class_names/styles: Style class names and inline style mappings. + - Slots: defaultIcon, runningIcon. +- Events + - click: Triggered when the item is clicked. +- Usage Recommendations + - Use with the items field of the Actions component for batch configuration. + - Customize icons and labels in different states through slots. + +```mermaid +classDiagram +class AntdXActionsItem { ++Properties : status, label, default_icon, running_icon ++Methods : preprocess(), postprocess() ++Events : click ++Slots : defaultIcon, runningIcon +} +``` + +**Diagram Sources** + +- [item/**init**.py:24-59](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L24-L59) + +**Section Sources** + +- [item/**init**.py:10-77](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L10-L77) + +### ActionItem (AntdXActionsActionItem) + +- Responsibility: Custom action item, supports label, icon, danger style, sub-items, and trigger method. +- Key Properties + - label/icon: Label and icon. + - danger: Whether to use danger style. + - trigger_sub_menu_action: Sub-menu trigger method (hover/click). + - sub_items: Sub-item array. + - action_render: Custom rendering function identifier. + - Slots: label, icon, actionRender, subItems. +- Events + - item_click: Triggered when the custom action button is clicked. +- Usage Recommendations + - Suitable for complex menus or scenarios requiring custom rendering. + - Sub-items are injected via the subItems slot, forming a nested menu tree. + +```mermaid +classDiagram +class AntdXActionsActionItem { ++Properties : label, icon, danger, trigger_sub_menu_action, sub_items, action_render ++Methods : preprocess(), postprocess() ++Events : item_click ++Slots : label, icon, actionRender, subItems +} +``` + +**Diagram Sources** + +- [action_item/**init**.py:26-62](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L26-L62) + +**Section Sources** + +- [action_item/**init**.py:10-80](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L10-L80) + +### Copy Component (AntdXActionsCopy) + +- Responsibility: Provides one-click copy functionality, commonly used for copying code blocks, links, and other text. +- Key Properties + - text: Text to be copied. + - icon: Custom icon. + - class_names/styles: Style class names and inline style mappings. + - Slots: icon. +- Events + - click: Triggered when the copy button is clicked. +- Usage Recommendations + - Use in combination with ActionItem or ActionsItem to improve user operation efficiency. + - Be mindful of browser permission and Clipboard API compatibility. + +```mermaid +classDiagram +class AntdXActionsCopy { ++Properties : text, icon ++Methods : preprocess(), postprocess() ++Events : click ++Slots : icon +} +``` + +**Diagram Sources** + +- [copy/**init**.py:24-54](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L24-L54) + +**Section Sources** + +- [copy/**init**.py:10-72](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L10-L72) + +### Audio Component (AntdXActionsAudio) + +- Responsibility: Audio status indicator for displaying recording/playback/loading/error states. +- Key Properties + - status: State enumeration (loading/error/running/default). + - class_names/styles: Style class names and inline style mappings. + - Slots: None. +- Events + - click: Triggered when the audio control is clicked. +- Usage Recommendations + - Pair with recording/playback functionality to provide immediate status feedback. + - Customize through styles to match the theme palette. + +```mermaid +classDiagram +class AntdXActionsAudio { ++Properties : status ++Methods : preprocess(), postprocess() ++Events : click +} +``` + +**Diagram Sources** + +- [audio/**init**.py:24-53](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L24-L53) + +**Section Sources** + +- [audio/**init**.py:10-71](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L10-L71) + +### Feedback Component (AntdXActionsFeedback) + +- Responsibility: Collects user feedback on content/conversations, supports like/dislike/default states. +- Key Properties + - value: Current feedback value (like/dislike/default). + - class_names/styles: Style class names and inline style mappings. + - Slots: None. +- Events + - click: Triggered when the feedback button is clicked. + - change: Triggered when the feedback state changes. +- Usage Recommendations + - Pair with chatbot outputs or content cards to form a complete feedback loop. + - Report data via the change event, combined with backend storage and statistics. + +```mermaid +classDiagram +class AntdXActionsFeedback { ++Properties : value ++Methods : preprocess(), postprocess() ++Events : click, change +} +``` + +**Diagram Sources** + +- [feedback/**init**.py:28-56](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L28-L56) + +**Section Sources** + +- [feedback/**init**.py:10-74](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L10-L74) + +### Notification Component (AntdXNotification) + +- Responsibility: System notification management, supports permission, click, close, error, show events, and internationalization/direction attributes. +- Key Properties + - title/body: Title and body text. + - duration: Display duration. + - badge/lang/dir/icon/tag/data/silent/require_interaction: Badge, language, direction, icon, tag, data, silent mode, require interaction. + - Slots: None. +- Events + - permission/click/close/error/show: Permission request, click, close, error, show. +- Usage Recommendations + - Used for system notifications, permission prompts, error alerts, and user feedback responses. + - Combine with the Feedback component to form a "notification-feedback" closed loop. + +```mermaid +classDiagram +class AntdXNotification { ++Properties : title, body, duration, badge, lang, dir, icon, tag, data, silent, require_interaction ++Methods : preprocess(), postprocess() ++Events : permission, click, close, error, show +} +``` + +**Diagram Sources** + +- [notification/**init**.py:35-79](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L35-L79) + +**Section Sources** + +- [notification/**init**.py:10-97](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L10-L97) + +## Dependency Analysis + +- Unified Export: `components.py` centralizes all Antdx component exports for on-demand import by upper-level applications. +- Component Relationships: The Actions container combines ActionItem, Item, Copy, Audio, Feedback, and other sub-components; Notification exists independently and can work in conjunction with Feedback. + +```mermaid +graph LR +subgraph "Export Layer" +C["components.py"] +end +subgraph "Actions Family" +A1["AntdXActions"] +A2["AntdXActionsActionItem"] +A3["AntdXActionsItem"] +A4["AntdXActionsCopy"] +A5["AntdXActionsAudio"] +A6["AntdXActionsFeedback"] +end +subgraph "Notification" +N1["AntdXNotification"] +end +C --> A1 +C --> N1 +A1 --> A2 +A1 --> A3 +A1 --> A4 +A1 --> A5 +A1 --> A6 +``` + +**Diagram Sources** + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [actions/**init**.py:15-25](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L25) +- [notification/**init**.py:10-13](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L10-L13) + +**Section Sources** + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## Performance Considerations + +- Minimize Event Binding: Only enable event binding when needed to avoid unnecessary callback overhead. +- Slot Rendering: Use slots wisely to reduce repeated rendering and keep the DOM structure concise. +- State Synchronization: Use component state and event linkage to avoid frequent full refreshes. +- Styles and Animation: Use entry animations and complex styles cautiously to ensure smooth performance on low-end devices. + +## Troubleshooting Guide + +- Events Not Triggering + - Check that event bindings are correctly enabled (e.g., click, dropdown\_\*, item_click, change). + - Confirm that frontend slot and property configurations match. +- State Inconsistency + - Verify the value range and default value of value/status. + - Check the state change logic in the change event. +- Style Issues + - Check whether class_names/styles has overridden the default styles. + - Confirm theme and global style conflicts. +- Notification Not Working + - Check the handling flow for the permission event. + - Confirm display duration and interaction requirement configurations. + +**Section Sources** + +- [actions/**init**.py:26-46](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L26-L46) +- [action_item/**init**.py:15-21](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L15-L21) +- [feedback/**init**.py:15-23](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L15-L23) +- [notification/**init**.py:14-30](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L14-L30) + +## Conclusion + +Antdx feedback components provide complete capabilities from action item management, copy and audio status indication to user feedback and notification management through a clear component layering and event binding mechanism. Combined with unified exports and slot extensions, developers can quickly build high-quality user feedback and interaction experiences across various scenarios. + +## Appendix: Usage Examples and Best Practices + +- User Operation Feedback + - Add the Feedback component after content cards or conversation outputs, bind click and change events to report user preferences. + - Example path: [feedback/**init**.py:15-23](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L15-L23) +- Quick Actions + - Use Actions to combine ActionItem and Item, configure subItems to form secondary menus; customize icons and labels through slots. + - Example paths: [actions/**init**.py:48-56](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L48-L56), [action_item/**init**.py:23-24](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L23-L24) +- Audio Interaction + - Use the Audio component to display recording/playback states, combined with the click event to control play/pause. + - Example path: [audio/**init**.py:15-19](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L15-L19) +- Copy Functionality + - Place the Copy component next to code blocks or links, bind the click event to improve copy efficiency. + - Example path: [copy/**init**.py:15-19](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L15-L19) +- Notification Management + - Use the Notification component for system prompts and permission alerts, bind permission/click/close/error/show events. + - Example path: [notification/**init**.py:14-30](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L14-L30) +- Integration with Chatbot + - Insert the Feedback component after chat outputs, report user feedback through the change event; use Notification when needed for confirmation or error alerts. + - Example paths: [feedback/**init**.py:15-23](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L15-L23), [notification/**init**.py:14-30](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L14-L30) diff --git a/.wiki/en/API Reference/Python API/Antdx Components API/General Components API.md b/.wiki/en/API Reference/Python API/Antdx Components API/General Components API.md new file mode 100644 index 00000000..ecfb2e3d --- /dev/null +++ b/.wiki/en/API Reference/Python API/Antdx Components API/General Components API.md @@ -0,0 +1,390 @@ +# General Components API + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/antdx/bubble/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/__init__.py) +- [backend/modelscope_studio/components/antdx/bubble/list/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py) +- [backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py) +- [backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py) +- [backend/modelscope_studio/components/antdx/conversations/__init__.py](file://backend/modelscope_studio/components/antdx/conversations/__init__.py) +- [backend/modelscope_studio/components/antdx/conversations/item/__init__.py](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py) +- [backend/modelscope_studio/components/antdx/prompts/__init__.py](file://backend/modelscope_studio/components/antdx/prompts/__init__.py) +- [backend/modelscope_studio/components/antdx/prompts/item/__init__.py](file://backend/modelscope_studio/components/antdx/prompts/item/__init__.py) +- [docs/components/antdx/bubble/README-zh_CN.md](file://docs/components/antdx/bubble/README-zh_CN.md) +- [docs/components/antdx/conversations/README-zh_CN.md](file://docs/components/antdx/conversations/README-zh_CN.md) +- [docs/components/antdx/prompts/README-zh_CN.md](file://docs/components/antdx/prompts/README-zh_CN.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the Python API reference for Antdx general components, focusing on the following core components: + +- Bubble: Conversation bubble rendering and interaction +- BubbleList: Message list management +- BubbleListItem: Message item processing +- BubbleListRole: Role identification +- Conversations: Conversation management, message storage, and state synchronization +- Prompts: Prompt template management, dynamic content rendering, and user interaction + +The documentation provides constructor parameters, property definitions, event and slot (slots) specifications for each component, and gives standard component instantiation and composition patterns for typical AI scenarios, helping developers quickly build conversational systems, message display, and prompt management features. + +## Project Structure + +Antdx components reside in the backend Python package, wrapped through a unified layout component base class, and mapped to the corresponding frontend component directories. Component export entry points are centralized in `antdx/components.py` for on-demand import. + +```mermaid +graph TB +subgraph "Python Backend" +A["components.py
Export Entry"] +B["bubble/*
Conversation Bubble Component Family"] +C["conversations/*
Conversation List Component Family"] +D["prompts/*
Prompts Component Family"] +end +A --> B +A --> C +A --> D +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +Section Sources + +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## Core Components + +This section provides an overview of the three core component families and their responsibility boundaries: + +- Bubble Family: Responsible for rendering and interaction of individual messages or role-level bubbles, supporting typing animation, editability, variants, shapes, etc. +- BubbleList Family: Responsible for scrolling, role grouping, and item rendering in message lists, supporting auto-scroll and role configuration. +- Conversations Family: Responsible for conversation list management, selection state toggling, menu operations, and creation buttons. +- Prompts Family: Responsible for displaying preset prompts and click interactions, supporting vertical arrangement, fade-in effects, line wrapping, etc. + +Section Sources + +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:13-135](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L13-L135) +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:12-84](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L12-L84) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) + +## Architecture Overview + +The diagram below shows the organization and dependency relationships of Antdx components at the Python layer: + +```mermaid +graph TB +subgraph "Antdx Components" +B1["AntdXBubble"] +B2["AntdXBubbleList"] +B3["AntdXBubbleListItem"] +B4["AntdXBubbleListRole"] +C1["AntdXConversations"] +C2["AntdXConversationsItem"] +P1["AntdXPrompts"] +P2["AntdXPromptsItem"] +end +E1["Event Binding
EventListener"] +S1["Slot Definition
SLOTS"] +B1 --> B2 +B2 --> B3 +B2 --> B4 +C1 --> C2 +P1 --> P2 +B1 --- E1 +B2 --- E1 +B3 --- E1 +B4 --- E1 +C1 --- E1 +P1 --- E1 +B1 --- S1 +B2 --- S1 +B3 --- S1 +B4 --- S1 +C1 --- S1 +P1 --- S1 +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:21-54](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L21-L54) +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:19-30](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L19-L30) +- [backend/modelscope_studio/components/antdx/bubble/list/item/**init**.py:14-47](file://backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py#L14-L47) +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:14-46](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L14-L46) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:18-47](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L18-L47) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-26](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L26) + +## Detailed Component Analysis + +### Bubble Component + +- Component Purpose: Used to render a single conversation bubble, supports multiple appearance variants, shapes, typing animation, editability, avatar, header/footer, extra area, loading, and custom content rendering. +- Key Properties (constructor parameters) + - content: Bubble content text + - avatar: Avatar URL or placeholder + - extra: Additional elements + - footer/header: Footer/header content + - loading: Whether to show loading state + - placement: Alignment position (start/end) + - editable: Whether editable (boolean or dict) + - shape: Bubble shape (round/corner/default) + - typing: Typing animation (bool/dict/string) + - streaming: Streaming render toggle + - variant: Appearance variant (filled/borderless/outlined/shadow) + - footer_placement: Footer position (outside/inside-start/end) + - loading_render/content_render: Custom loading and content rendering + - class_names/styles/root_class_name: Style and class name control + - Other general properties: visible, elem_id, elem_classes, elem_style, render, etc. +- Events + - typing: Typing animation callback + - typing_complete: Typing complete callback; triggers immediately on render if typing is not set + - edit_confirm: Edit confirmation callback + - edit_cancel: Edit cancellation callback +- Slots + - avatar, editable.okText, editable.cancelText, content, footer, header, extra, loadingRender, contentRender +- Nested Sub-components + - List: Message list container + - System: System message bubble + - Divider: Divider line + +Section Sources + +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:56-116](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L56-L116) +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:21-54](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L21-L54) + +### BubbleList Component + +- Component Purpose: Message list container, responsible for scrolling, role grouping, and item rendering, supports auto-scroll and role configuration. +- Key Properties + - items: Message item array (dict) + - role: Role configuration (dict) + - auto_scroll: Whether to auto-scroll to the bottom + - class_names/styles/root_class_name: Style and class name control + - Other general properties: visible, elem_id, elem_classes, elem_style, render, etc. +- Events + - scroll: List scroll callback +- Slots + - items, role +- Nested Sub-components + - Item: Message item + - Role: Role identifier + +Section Sources + +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:32-64](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L32-L64) +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:19-30](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L19-L30) + +### BubbleListItem Component + +- Component Purpose: A single item in the message list, behaves essentially the same as Bubble but used as a list item. +- Key Properties + - content, avatar, extra, footer, header, loading, placement, editable, shape, typing, streaming, variant, footer_placement, loading_render, content_render, class_names/styles/root_class_name, etc. +- Events + - typing, typing_complete, edit_confirm, edit_cancel +- Slots + - avatar, editable.okText, editable.cancelText, content, footer, header, extra, loadingRender, contentRender + +Section Sources + +- [backend/modelscope_studio/components/antdx/bubble/list/item/**init**.py:49-108](file://backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py#L49-L108) +- [backend/modelscope_studio/components/antdx/bubble/list/item/**init**.py:14-47](file://backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py#L14-L47) + +### BubbleListRole Component + +- Component Purpose: Used to identify roles in lists, supports role avatar, header/footer, extra area, loading, and custom content rendering. +- Key Properties + - role: Role identifier text + - avatar, extra, footer, header, loading, placement, editable, shape, typing, streaming, variant, footer_placement, loading_render, content_render, class_names/styles/root_class_name, etc. +- Events + - typing, typing_complete, edit_confirm, edit_cancel +- Slots + - avatar, editable.okText, editable.cancelText, footer, header, extra, loadingRender, contentRender + +Section Sources + +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:48-107](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L48-L107) +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:14-46](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L14-L46) + +### Conversations Component + +- Component Purpose: For managing and viewing conversation lists, supports selection state toggling, menu operations, grouping, keyboard shortcuts, and creation buttons. +- Key Properties + - active_key/default_active_key: Current active item key + - items: Conversation item array (dict) + - menu: Menu configuration (string or dict) + - groupable: Whether groupable (boolean or dict) + - shortcut_keys: Keyboard shortcut mappings + - creation: Create button configuration (dict) + - styles/class_names/root_class_name: Style and class name control + - Other general properties: visible, elem_id, elem_classes, elem_style, render, etc. +- Events + - active_change: Selection change callback + - menu_click/menu_deselect/menu_open_change/menu_select: Menu-related callbacks + - groupable_expand: Group expand callback + - creation_click: Create button click callback +- Slots + - menu.expandIcon, menu.overflowedIndicator, menu.trigger, groupable.label, items, creation.icon, creation.label +- Nested Sub-components + - Item: Conversation item + +Section Sources + +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:49-89](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L49-L89) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:18-47](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L18-L47) + +### ConversationsItem Component + +- Component Purpose: A single item in the conversation list, supports label, icon, type, group, disabled, dashed, etc. +- Key Properties + - label: Label text + - key: Unique key + - type: Type (e.g., divider) + - group: Belonging group + - icon: Icon + - disabled: Whether disabled + - dashed: Whether dashed + - additional_props/as_item/\_internal: Internal and extension properties + - Other general properties: visible, elem_id, elem_classes, elem_style, render, etc. + +Section Sources + +- [backend/modelscope_studio/components/antdx/conversations/item/**init**.py:21-55](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L21-L55) + +### Prompts Component + +- Component Purpose: For displaying preset prompts, supports title, vertical arrangement, fade-in effect, line wrapping, etc. +- Key Properties + - items: Prompt item array (dict) + - prefix_cls: Prefix class name + - title: Title + - vertical: Whether vertically arranged + - fade_in/fade_in_left: Fade-in effect (left/right) + - wrap: Whether to wrap + - styles/class_names/root_class_name: Style and class name control + - Other general properties: visible, elem_id, elem_classes, elem_style, render, etc. +- Events + - item_click: Prompt item click callback +- Slots + - title, items +- Nested Sub-components + - Item: Prompt item + +Section Sources + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:28-68](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L28-L68) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-26](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L26) + +### PromptsItem Component + +- Component Purpose: A single item in the prompt list, supports label, description, icon, disabled, and key. +- Key Properties + - label: Label text + - key: Unique key + - description: Description text + - icon: Icon + - disabled: Whether disabled + - additional_props/as_item/\_internal: Internal and extension properties + - Other general properties: visible, elem_id, elem_classes, elem_style, render, etc. + +Section Sources + +- [backend/modelscope_studio/components/antdx/prompts/item/**init**.py:18-48](file://backend/modelscope_studio/components/antdx/prompts/item/__init__.py#L18-L48) + +## Dependency Analysis + +- Component Export: All antdx components are centrally exported through `components.py` for unified import and use. +- Component Hierarchy: The Bubble family (Bubble, BubbleList, BubbleListItem, BubbleListRole) forms a complete message rendering chain; the Conversations family and Prompts family handle conversation management and prompt management respectively. +- Events and Slots: Each component defines EVENTS and SLOTS lists to declare supported event callbacks and slot names, ensuring consistency between frontend and backend conventions. + +```mermaid +graph LR +A["components.py Export"] --> B["Bubble Family"] +A --> C["Conversations Family"] +A --> D["Prompts Family"] +B --> B1["Bubble"] +B --> B2["BubbleList"] +B2 --> B3["BubbleListItem"] +B2 --> B4["BubbleListRole"] +C --> C1["Conversations"] +C1 --> C2["ConversationsItem"] +D --> D1["Prompts"] +D1 --> D2["PromptsItem"] +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +Section Sources + +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## Performance Considerations + +- Streaming Rendering and Typing Animation: Use streaming and typing parameters wisely to avoid stuttering when rendering large numbers of messages simultaneously. +- Auto-scroll: It is recommended to enable auto_scroll in BubbleList when messages are frequently updated to maintain the best user experience. +- Slots and Custom Rendering: Although loadingRender and contentRender are flexible, avoid heavy computations in rendering functions; cache results when necessary. +- Event Binding: Only enable relevant event bindings when needed (e.g., typing_complete) to reduce unnecessary callback overhead. +- Appearance and Shape: variant and shape affect rendering complexity; choose based on actual needs. + +## Troubleshooting Guide + +- Events Not Triggering + - Check that the binding names in EVENTS are correct, and confirm that the frontend has the corresponding `bind_*` events enabled. + - Confirm whether the visible and render states of the component affect event propagation. +- Slot Content Not Displaying + - Confirm that the slot name spelling matches the SLOTS list. + - Check whether the slot scope matches the slot content passed from the parent component. +- Style Issues + - Use class_names/styles/root_class_name for local overrides to avoid global style conflicts. +- Scroll Problems + - BubbleList's auto_scroll is related to the external container height setting; check container height and overflow settings. +- Typing Animation Not Working + - Confirm the type and value range of the typing parameter; avoid passing unsupported types. + +## Conclusion + +Antdx general components provide complete capabilities from message rendering and list management to conversation and prompt management. Through unified event and slot conventions, developers can quickly build conversational systems and prompt panels, and achieve high-performance, maintainable frontend experiences by combining style and interaction configurations. + +## Appendix + +### Typical Scenarios and Instantiation Paths + +- Conversation Bubble Basic Rendering and Typing Animation + - Reference path: [docs/components/antdx/bubble/README-zh_CN.md:7-12](file://docs/components/antdx/bubble/README-zh_CN.md#L7-L12) +- Message List and Auto-scroll + - Reference path: [docs/components/antdx/bubble/README-zh_CN.md:10-12](file://docs/components/antdx/bubble/README-zh_CN.md#L10-L12) +- Conversation List and Menu Operations + - Reference path: [docs/components/antdx/conversations/README-zh_CN.md:7-9](file://docs/components/antdx/conversations/README-zh_CN.md#L7-L9) +- Prompt Panel and Nested Usage + - Reference path: [docs/components/antdx/prompts/README-zh_CN.md:7-8](file://docs/components/antdx/prompts/README-zh_CN.md#L7-L8) + +### Data Formats and Field Descriptions (Summary) + +- Bubble/BubbleListItem/BubbleListRole + - content, avatar, extra, footer, header, loading, placement, editable, shape, typing, streaming, variant, footer_placement, loading_render, content_render, class_names, styles, root_class_name +- BubbleList + - items, role, auto_scroll, class_names, styles, root_class_name +- Conversations + - active_key, default_active_key, items, menu, groupable, shortcut_keys, creation, styles, class_names, root_class_name +- ConversationsItem + - label, key, type, group, icon, disabled, dashed, additional_props, as_item, \_internal +- Prompts + - items, prefix_cls, title, vertical, fade_in, fade_in_left, wrap, styles, class_names, root_class_name +- PromptsItem + - label, key, description, icon, disabled, additional_props, as_item, \_internal diff --git a/.wiki/en/API Reference/Python API/Antdx Components API/Utility Components API.md b/.wiki/en/API Reference/Python API/Antdx Components API/Utility Components API.md new file mode 100644 index 00000000..83a58798 --- /dev/null +++ b/.wiki/en/API Reference/Python API/Antdx Components API/Utility Components API.md @@ -0,0 +1,399 @@ +# Utility Components API + + +**Files Referenced in This Document** +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [code_highlighter/__init__.py](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py) +- [file_card/__init__.py](file://backend/modelscope_studio/components/antdx/file_card/__init__.py) +- [folder/__init__.py](file://backend/modelscope_studio/components/antdx/folder/__init__.py) +- [mermaid/__init__.py](file://backend/modelscope_studio/components/antdx/mermaid/__init__.py) +- [sources/__init__.py](file://backend/modelscope_studio/components/antdx/sources/__init__.py) +- [think/__init__.py](file://backend/modelscope_studio/components/antdx/think/__init__.py) +- [x_provider/__init__.py](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Usage Examples and Best Practices](#appendix-usage-examples-and-best-practices) + +## Introduction + +This document is the Python API reference for Antdx utility components, covering the complete API specifications and usage instructions for the following components: + +- CodeHighlighter: Code syntax highlighting +- FileCard: File card display (with List sub-component) +- Folder: Folder tree structure (with directory icon and tree node sub-components) +- Mermaid: Diagram rendering +- Sources: Source reference management (with item sub-component) +- Think: Thought annotation +- XProvider: Global configuration container + +The document systematically covers constructor parameters, property definitions, events and slots, data processing and formatting options, style and class name customization, as well as performance and rendering strategies, and provides standard usage examples and extension recommendations. + +## Project Structure + +Antdx components reside in the backend Python package, wrapped through a unified layout component base class for frontend components, with exported aliases for direct use. The core entry is in antdx's `__init__.py`, and `components.py` handles aggregated exports. + +```mermaid +graph TB +A["backend/modelscope_studio/components/antdx/components.py"] --> B["backend/modelscope_studio/components/antdx/__init__.py"] +B --> C1["CodeHighlighter"] +B --> C2["FileCard"] +B --> C3["Folder"] +B --> C4["Mermaid"] +B --> C5["Sources"] +B --> C6["Think"] +B --> C7["XProvider"] +``` + +Diagram Sources + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [**init**.py:14-41](file://backend/modelscope_studio/components/antdx/__init__.py#L14-L41) + +Section Sources + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [**init**.py:14-41](file://backend/modelscope_studio/components/antdx/__init__.py#L14-L41) + +## Core Components + +This section provides an overview of the responsibilities and general features of each component: + +- All inherit from the unified layout component base class, with general properties for visibility, element ID, class names, inline styles, and render toggle. +- Most components declare supported slots (SLOTS) and events (EVENTS) for frontend rendering and interaction binding. +- Most components set skip_api to True, indicating they do not participate in standard API serialization and are rendered directly by the frontend. + +Section Sources + +- [code_highlighter/**init**.py:6-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L6-L71) +- [file_card/**init**.py:11-112](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L11-L112) +- [folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) +- [mermaid/**init**.py:8-77](file://backend/modelscope_studio/components/antdx/mermaid/__init__.py#L8-L77) +- [sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [x_provider/**init**.py:10-101](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L10-L101) + +## Architecture Overview + +The diagram below shows the encapsulation relationship and export paths of Python layer to frontend components: + +```mermaid +classDiagram +class AntdXCodeHighlighter { ++Constructor Parameters : value, lang, header, highlight_props, prism_light_mode, styles, class_names, additional_props, root_class_name, as_item, visible, elem_id, elem_classes, elem_style, render ++Properties : SLOTS, EVENTS, skip_api ++Methods : preprocess(), postprocess(), example_payload(), example_value() +} +class AntdXFileCard { ++Constructor Parameters : image_props, filename, byte, size, description, loading, type, src, mask, icon, video_props, audio_props, spin_props, styles, class_names, additional_props, as_item, visible, elem_id, elem_classes, elem_style, render ++Properties : SLOTS, EVENTS(List), skip_api ++Methods : preprocess(), postprocess(), example_payload(), example_value() +} +class AntdXFolder { ++Constructor Parameters : tree_data, selectable, selected_file, default_selected_file, directory_tree_width, empty_render, preview_render, expanded_paths, default_expanded_paths, default_expand_all, directory_title, preview_title, directory_icons, styles, class_names, additional_props, as_item, visible, elem_id, elem_classes, elem_style, render ++Properties : SLOTS, EVENTS, TreeNode, DirectoryIcon, skip_api ++Methods : preprocess(), postprocess(), example_payload(), example_value() +} +class AntdXMermaid { ++Constructor Parameters : value, highlight_props, config, actions, prefix_cls, styles, class_names, additional_props, root_class_name, as_item, visible, elem_id, elem_classes, elem_style, render ++Properties : SLOTS, EVENTS, skip_api ++Methods : preprocess(), postprocess(), example_payload(), example_value() +} +class AntdXSources { ++Constructor Parameters : title, items, expand_icon_position, default_expanded, expanded, inline, active_key, popover_overlay_width, styles, class_names, additional_props, as_item, visible, elem_id, elem_classes, elem_style, render ++Properties : SLOTS, EVENTS(Item), skip_api ++Methods : preprocess(), postprocess(), example_payload(), example_value() +} +class AntdXThink { ++Constructor Parameters : icon, styles, class_names, loading, title, root_class_name, default_expanded, expanded, blink, as_item, visible, elem_id, elem_classes, elem_style, render ++Properties : SLOTS, EVENTS, skip_api ++Methods : preprocess(), postprocess(), example_payload(), example_value() +} +class AntdXXProvider { ++Constructor Parameters : component_disabled, component_size, csp, direction, get_popup_container, get_target_container, icon_prefix_cls, locale, popup_match_select_width, popup_overflow, prefix_cls, render_empty, theme, theme_config, variant, virtual, warning, styles, class_names, additional_props, as_item, visible, elem_id, elem_classes, elem_style, render ++Properties : SLOTS, EVENTS, skip_api ++Methods : preprocess(), postprocess(), example_payload(), example_value() +} +``` + +Diagram Sources + +- [code_highlighter/**init**.py:6-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L6-L71) +- [file_card/**init**.py:11-112](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L11-L112) +- [folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) +- [mermaid/**init**.py:8-77](file://backend/modelscope_studio/components/antdx/mermaid/__init__.py#L8-L77) +- [sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [x_provider/**init**.py:10-101](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L10-L101) + +## Detailed Component Analysis + +### CodeHighlighter (Code Syntax Highlighting) + +- Component Purpose: For highlighting code snippets, supports language and theme mode configurations. +- Key Parameters + - value: Code string to highlight + - lang: Language identifier + - header: Title or boolean control + - highlight_props: Highlight-related configuration + - prism_light_mode: Light mode toggle + - styles/class_names/additional_props/root_class_name/as_item: Style and class names, additional properties, root class name, as item + - visible/elem_id/elem_classes/elem_style/render: General layout properties +- Slots: header +- Events: None +- Data Processing: skip_api is True, not participating in standard API; preprocess/postprocess return original value +- Performance: Direct frontend rendering, avoids extra serialization overhead + +Section Sources + +- [code_highlighter/**init**.py:6-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L6-L71) + +### FileCard (File Card) + +- Component Purpose: Displays file information, supports multiple types including image, audio, video, and ordinary files, configurable size, loading state, mask, and media properties. +- Key Parameters + - image_props: Image preview related properties + - filename: File name + - byte: Byte count + - size: Size small/default + - description: Description text + - loading: Whether to show loading state + - type: Type image/file/audio/video or custom string + - src: Resource URL (supports string or dict containing path/url) + - mask: Mask text + - icon: Built-in icon category or custom string + - video_props/audio_props/spin_props: Video/audio/loading indicator configurations + - styles/class_names/additional_props/as_item/visible/elem_id/elem_classes/elem_style/render: General layout properties +- Slots: imageProps.placeholder, imageProps.preview.mask, imageProps.preview.closeIcon, imageProps.preview.toolbarRender, imageProps.preview.imageRender, description, icon, mask, spinProps.icon, spinProps.description, spinProps.indicator +- Events: click (bound to internal event) +- Data Processing: skip_api is True; preprocess/postprocess return original value; src supports static file service wrapping +- Performance: Direct frontend rendering; src field automatically handles static resource paths + +Section Sources + +- [file_card/**init**.py:11-112](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L11-L112) + +### Folder (Folder Tree Structure) + +- Component Purpose: Displays folder tree and selection/expansion behavior, supports preview rendering, empty state rendering, directory icons, etc. +- Key Parameters + - tree_data: Tree data + - selectable: Whether selectable + - selected_file/default_selected_file: Selected file list + - directory_tree_width: Directory tree width + - empty_render/preview_render: Empty state and preview rendering + - expanded_paths/default_expanded_paths/default_expand_all: Expansion path control + - directory_title/preview_title: Titles + - directory_icons: Directory icon mappings + - styles/class_names/additional_props/root_class_name/as_item/visible/elem_id/elem_classes/elem_style/render: General layout properties +- Sub-components: TreeNode, DirectoryIcon +- Slots: emptyRender, previewRender, directoryTitle, previewTitle, treeData, directoryIcons +- Events: file_click, folder_click, selected_file_change, expanded_paths_change, file_content_service_load_file_content (bound to internal events) +- Data Processing: skip_api is True; preprocess/postprocess return original value +- Performance: Direct frontend rendering; supports default expand all + +Section Sources + +- [folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) + +### Mermaid (Diagram Rendering) + +- Component Purpose: Renders diagrams based on Mermaid syntax, supports highlight configuration, theme configuration, and custom actions. +- Key Parameters + - value: Mermaid text + - highlight_props: Highlight configuration + - config: Global configuration + - actions: Custom actions + - prefix_cls: Prefix class name + - styles/class_names/additional_props/root_class_name/as_item/visible/elem_id/elem_classes/elem_style/render: General layout properties +- Slots: header, actions.customActions +- Events: render_type_change (bound to internal event) +- Data Processing: skip_api is True; preprocess/postprocess return original value +- Performance: Direct frontend rendering + +Section Sources + +- [mermaid/**init**.py:8-77](file://backend/modelscope_studio/components/antdx/mermaid/__init__.py#L8-L77) + +### Sources (Source Reference Management) + +- Component Purpose: Manages source reference entries in a collapsible panel form, supports expansion position, active key, popover width, etc. +- Key Parameters + - title: Title + - items: Entry list + - expand_icon_position: Expansion icon position start/end + - default_expanded/expanded: Default/current expanded state + - inline: Whether inline + - active_key: Active key + - popover_overlay_width: Popover width + - styles/class_names/additional_props/root_class_name/as_item/visible/elem_id/elem_classes/elem_style/render: General layout properties +- Sub-components: Item +- Slots: items +- Events: expand, click (bound to internal events) +- Data Processing: skip_api is True; preprocess/postprocess return original value +- Performance: Direct frontend rendering + +Section Sources + +- [sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) + +### Think (Thought Annotation) + +- Component Purpose: Used to display thought processes or prompt information, supports loading state, title, blink, etc. +- Key Parameters + - icon: Icon + - styles/class_names/additional_props/root_class_name/as_item/visible/elem_id/elem_classes/elem_style/render: General layout properties + - loading: Loading state (string or boolean) + - title: Title + - default_expanded/expanded: Default/current expanded state + - blink: Blink toggle +- Slots: loading, icon, title +- Events: expand (bound to internal event) +- Data Processing: skip_api is True; preprocess/postprocess return original value +- Performance: Direct frontend rendering + +Section Sources + +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) + +### XProvider (Global Configuration) + +- Component Purpose: Global configuration container, passes theme, language, direction, variant, and other configurations to the sub-component tree. +- Key Parameters + - component_disabled: Disable component + - component_size: Component size small/middle/large + - csp: Content Security Policy + - direction: Direction ltr/rtl + - get_popup_container/get_target_container: Popup container selector + - icon_prefix_cls: Icon prefix class name + - locale: Locale environment + - popup_match_select_width: Popup matches select width + - popup_overflow: Popup overflow strategy viewport/scroll + - prefix_cls: Component prefix class name + - render_empty: Empty state rendering + - theme/theme_config: Theme and theme configuration (conflict warning exists) + - variant: Appearance outlined/filled/borderless + - virtual: Virtualization + - warning: Warning configuration + - styles/class_names/additional_props/as_item/visible/elem_id/elem_classes/elem_style/render: General layout properties +- Slots: renderEmpty +- Events: None +- Data Processing: skip_api is True; preprocess/postprocess return original value +- Performance: Direct frontend rendering; note the conflict warning between theme and theme_config + +Section Sources + +- [x_provider/**init**.py:10-101](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L10-L101) + +## Dependency Analysis + +- Export Relationships: `components.py` aggregates imports from all component modules under antdx; `__init__.py` exports component classes as user-friendly aliases. +- Component Relationships: Some components provide sub-components (e.g., FileCard.List, Folder.TreeNode/Folder.DirectoryIcon, Sources.Item, Think, etc.) for composing complex UIs. +- Event Binding: Most components update internal state flags through event listener callbacks, thereby triggering frontend event binding. + +```mermaid +graph LR +subgraph "Export Layer" +E1["components.py"] --> E2["__init__.py"] +end +subgraph "Component Layer" +F1["code_highlighter/__init__.py"] +F2["file_card/__init__.py"] +F3["folder/__init__.py"] +F4["mermaid/__init__.py"] +F5["sources/__init__.py"] +F6["think/__init__.py"] +F7["x_provider/__init__.py"] +end +E2 --> F1 +E2 --> F2 +E2 --> F3 +E2 --> F4 +E2 --> F5 +E2 --> F6 +E2 --> F7 +``` + +Diagram Sources + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [**init**.py:14-41](file://backend/modelscope_studio/components/antdx/__init__.py#L14-L41) + +Section Sources + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [**init**.py:14-41](file://backend/modelscope_studio/components/antdx/__init__.py#L14-L41) + +## Performance Considerations + +- Skip API Serialization: All components set skip_api to True, avoiding unnecessary Python-to-frontend data round trips and improving rendering efficiency. +- Direct Frontend Connection: Components point to frontend component directories via `resolve_frontend_dir`, reducing intermediate layer conversion costs. +- Static Resources: FileCard wraps src with static file service, reducing resource access latency. +- Default Expand All: Folder supports `default_expand_all`, which can expand everything at initialization to reduce user interaction steps. +- Theme and Variants: XProvider provides unified theme and appearance configuration, avoiding repeated computations and style switching overhead. + +## Troubleshooting Guide + +- Component Not Working + - Check whether visible and render are True + - Confirm that elem_id/elem_classes/elem_style are correctly passed in +- File Resources Cannot Load + - When FileCard's src is a dict, ensure it contains path or url; use static file service wrapping if necessary +- Events Not Triggering + - Confirm that event listener names match the EVENTS definitions of the component + - Check whether the frontend correctly binds the internal event flag +- Theme Conflicts + - The theme property in XProvider conflicts with Gradio presets; use theme_config instead +- Rendering Issues + - Slot content for Mermaid/CodeHighlighter/Sources/Think must be provided according to specifications to avoid frontend parsing errors + +Section Sources + +- [file_card/**init**.py:87-93](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L87-L93) +- [x_provider/**init**.py:74-78](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L74-L78) + +## Conclusion + +Antdx utility components provide a concise and powerful Python API through the unified layout component base class and direct frontend rendering strategy. Each component is organized around the pattern of "parameter-driven + slots + event binding", meeting common scenarios (code highlighting, file display, tree navigation, diagrams, source references, thought annotation, global configuration) while leaving ample room for extension and customization. In practice, it is recommended to prioritize using the sub-components and slots provided by each component, use XProvider for global style and theme management, and follow the best practices for static resources and event binding. + +## Appendix: Usage Examples and Best Practices + +- Code Highlighting + - Scenario: Display code snippets in conversations or documents + - Recommendations: Specify lang and highlight_props; enable prism_light_mode if necessary + - Reference path: [code_highlighter/**init**.py:15-52](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L15-L52) +- File Card + - Scenario: Upload or browse file lists + - Recommendations: Set icon based on type; wrap src with static file service; set size and loading appropriately + - Reference path: [file_card/**init**.py:32-94](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L32-L94) +- Folder Tree + - Scenario: File browsing and selection + - Recommendations: Keep tree_data structure clear; enable default_expand_all only with manageable data volume; use directory_icons for custom icons + - Reference path: [folder/**init**.py:43-96](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L43-L96) +- Diagram + - Scenario: Visualize algorithms or business processes + - Recommendations: Use standard Mermaid syntax for value; configure config and actions as needed + - Reference path: [mermaid/**init**.py:21-58](file://backend/modelscope_studio/components/antdx/mermaid/__init__.py#L21-L58) +- Source References + - Scenario: Display reference sources and entries + - Recommendations: Standardize items structure; choose inline and expand_icon_position based on interface style + - Reference path: [sources/**init**.py:30-73](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L30-L73) +- Thought Annotation + - Scenario: Prompt users to focus on key points or loading state + - Recommendations: Express intent clearly with title and icon; use blink only for emphasis + - Reference path: [think/**init**.py:21-60](file://backend/modelscope_studio/components/antdx/think/__init__.py#L21-L60) +- Global Configuration + - Scenario: Unify theme, language, direction, and appearance + - Recommendations: Prefer theme_config; configure locale and direction by region; maintain consistency between prefix_cls and icon_prefix_cls + - Reference path: [x_provider/**init**.py:19-82](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L19-L82) diff --git a/.wiki/en/API Reference/Python API/Antdx Components API/Wake Components API.md b/.wiki/en/API Reference/Python API/Antdx Components API/Wake Components API.md new file mode 100644 index 00000000..fb4cbc6e --- /dev/null +++ b/.wiki/en/API Reference/Python API/Antdx Components API/Wake Components API.md @@ -0,0 +1,334 @@ +# Wake Components API + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/antdx/welcome/__init__.py](file://backend/modelscope_studio/components/antdx/welcome/__init__.py) +- [backend/modelscope_studio/components/antdx/prompts/__init__.py](file://backend/modelscope_studio/components/antdx/prompts/__init__.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) +- [docs/components/antdx/welcome/app.py](file://docs/components/antdx/welcome/app.py) +- [docs/components/antdx/prompts/app.py](file://docs/components/antdx/prompts/app.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the Python API reference for Antdx wake components, focusing on the following goals: + +- Document the welcome interface display, welcome message configuration, and user guidance flow of the Welcome component +- Explain the prompt set management, prompt template definition, and dynamic prompt generation mechanisms of the Prompts component +- Provide the message format, personalization configuration options, and multilingual support descriptions for the Welcome component +- Give standard usage examples for AI assistant startup, user guidance, and prompt activation scenarios +- Explain initialization parameters, callback function configurations, and user experience optimization strategies +- Describe integration approaches with conversational systems and state synchronization mechanisms + +## Project Structure + +Antdx components reside in the backend Python package, bridged through a unified layout component base class and frontend directory resolution mechanism. Both Welcome and Prompts components inherit from the general layout component base class and point to the corresponding frontend component directory via `resolve_frontend_dir`. + +```mermaid +graph TB +subgraph "Python Backend" +A["ModelScopeLayoutComponent
Component Base Class"] +B["AntdXWelcome
Welcome Component"] +C["AntdXPrompts
Prompts Component"] +D["AntdXPromptsItem
Prompt Item Component"] +E["resolve_frontend_dir
Frontend Directory Resolver"] +end +subgraph "Frontend Components" +F["welcome component directory"] +G["prompts component directory"] +H["prompts/item sub-component directory"] +end +A --> B +A --> C +C --> D +E --> F +E --> G +E --> H +B -.-> F +C -.-> G +D -.-> H +``` + +Diagram Sources + +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:55-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L55-L55) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:70-70](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L70-L70) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-16](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L16) + +Section Sources + +- [backend/modelscope_studio/components/antdx/components.py:24-39](file://backend/modelscope_studio/components/antdx/components.py#L24-L39) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) + +## Core Components + +- AntdXWelcome: For rendering a welcome interface, supports slot-based configuration for title, description, icon, extra content, and style and variant control. +- AntdXPrompts: For displaying a set of prompt word cards, supports title, vertical arrangement, fade-in animation, line wrapping, and other configurations; includes an item_click callback event to respond to click behavior. + +Section Sources + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) + +## Architecture Overview + +Antdx components connect to the corresponding frontend component directory through a unified layout component base class and frontend directory resolver. Components set the frontend directory path during initialization and participate in layout updates and internal state passing through Gradio's BlockContext mechanism. + +```mermaid +sequenceDiagram +participant Py as "Python Component" +participant Base as "ModelScopeLayoutComponent" +participant Resolver as "resolve_frontend_dir" +participant FE as "Frontend Component Directory" +Py->>Base : Initialize component, set visibility/element properties +Py->>Resolver : Resolve frontend directory component name/sub-component/type +Resolver-->>Py : Return relative path +Py->>FE : Load corresponding frontend component resources +Py->>Base : Enter context to trigger layout update +``` + +Diagram Sources + +- [backend/modelscope_studio/utils/dev/component.py:24-26](file://backend/modelscope_studio/utils/dev/component.py#L24-L26) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-16](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L16) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:55-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L55-L55) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:70-70](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L70-L70) + +## Detailed Component Analysis + +### Welcome Component API + +- Component: AntdXWelcome +- Inheritance: ModelScopeLayoutComponent +- Slot Support: extra, icon, description, title +- Key Parameters + - extra: Extra content (string or None) + - icon: Icon resource path (processed through static file service) + - description: Description text + - title: Title text + - variant: Appearance variant (filled or borderless) + - styles/class_names/root_class_name: Style and class name configuration + - Element properties: elem_id, elem_classes, elem_style, visible, render, etc. +- Lifecycle and Preprocessing + - preprocess/postprocess/example_payload/example_value all return empty values, indicating this component does not perform data conversion or example value generation +- Events + - No public event bindings (EVENTS is empty) + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__enter__() ++__exit__() ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdXWelcome { ++additional_props ++extra ++icon ++styles ++class_names ++description ++variant ++title ++root_class_name ++FRONTEND_DIR ++skip_api ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +ModelScopeLayoutComponent <|-- AntdXWelcome +``` + +Diagram Sources + +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) + +Section Sources + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:17-54](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L17-L54) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:57-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L57-L73) + +### Prompts Component API + +- Component: AntdXPrompts +- Inheritance: ModelScopeLayoutComponent +- Internal Items: AntdXPromptsItem (exposed via the Item property) +- Slot Support: title, items +- Key Parameters + - items: Prompt item list (list of dicts; specific fields are defined by the frontend convention) + - prefix_cls: Prefix class name (for style isolation) + - title: Prompt set title + - vertical: Whether to arrange vertically + - fade_in/fade_in_left: Fade-in animation toggles + - wrap: Whether to wrap + - styles/class_names/root_class_name/additional_props: Style and extension properties + - Element properties: elem_id, elem_classes, elem_style, visible, render, etc. +- Events + - item_click: Triggered when a prompt item is clicked; internally configured via `_internal.update(bind_itemClick_event=True)` for frontend event binding +- Lifecycle and Preprocessing + - preprocess/postprocess/example_payload/example_value all return empty values, indicating this component does not perform data conversion or example value generation + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__enter__() ++__exit__() ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdXPrompts { ++Item ++EVENTS ++SLOTS ++items ++prefix_cls ++title ++vertical ++fade_in ++fade_in_left ++wrap ++styles ++class_names ++root_class_name ++additional_props ++FRONTEND_DIR ++skip_api ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdXPromptsItem { ++... +} +ModelScopeLayoutComponent <|-- AntdXPrompts +AntdXPrompts o--> AntdXPromptsItem : "internal items" +``` + +Diagram Sources + +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) + +Section Sources + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-23](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L23) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:28-68](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L28-L68) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:72-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L72-L88) + +### Usage Examples and Best Practices + +- AI Assistant Startup and Welcome Page Display + - Render the Welcome component at application startup, set the title, description, and icon; add guidance buttons or action areas via the extra slot as needed + - Control appearance style via variant; achieve theme adaptation via styles/class_names/root_class_name +- User Guidance and Prompt Activation + - Use the Prompts component to display a set of prompt word cards, set title and items, and enable fade_in/fade_in_left for enhanced visual experience + - Monitor user selections via the item_click event; combined with the conversational system, inject the selected prompt into the input box or directly initiate a conversation +- Multilingual Support + - Title, description, and prompt text should come from localization resources; the text parameters of both Welcome and Prompts support string types, making it easy to replace with different language versions +- State Synchronization and Integration + - Components participate in layout updates via Gradio BlockContext; to integrate with a conversational system, trigger business logic in the item_click callback (e.g., write prompt content to the input field or send a request) and complete state rendering on the frontend + +Section Sources + +- [docs/components/antdx/welcome/app.py:1-7](file://docs/components/antdx/welcome/app.py#L1-L7) +- [docs/components/antdx/prompts/app.py:1-7](file://docs/components/antdx/prompts/app.py#L1-L7) + +## Dependency Analysis + +- Component Exports + - `antdx/__init__.py` exports Welcome and Prompts as aliases for easy named imports from outside + - `antdx/components.py` aggregates all sub-modules to ensure the complete import chain +- Base Class and Utilities + - ModelScopeLayoutComponent provides unified layout component capabilities and lifecycle hooks + - `resolve_frontend_dir` maps component names to frontend directories, supporting sub-components and multi-level directory concatenation + +```mermaid +graph LR +A["antdx/__init__.py"] --> B["Welcome Export"] +A --> C["Prompts Export"] +D["antdx/components.py"] --> E["Aggregated Import"] +E --> B +E --> C +F["utils/dev/component.py"] --> G["ModelScopeLayoutComponent"] +H["utils/dev/resolve_frontend_dir.py"] --> I["Frontend Directory Resolution"] +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:24-39](file://backend/modelscope_studio/components/antdx/components.py#L24-L39) +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-16](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L16) + +Section Sources + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:24-39](file://backend/modelscope_studio/components/antdx/components.py#L24-L39) + +## Performance Considerations + +- Component Skips API: Both components have skip_api returning True, meaning no additional API interface layer will be generated, reducing server-side overhead +- Preprocessing and Postprocessing: preprocess/postprocess return empty values, avoiding unnecessary data conversions and contributing to low-latency rendering +- Animation and Layout: Prompts' fade-in and line-wrap options only affect frontend rendering; exercise caution when enabling animations with large numbers of prompt items to balance smoothness and performance + +## Troubleshooting Guide + +- Component Not Displaying + - Check whether visible and render parameters are correctly set + - Confirm that elem_id/elem_classes/elem_style are not causing style overrides +- Icon or Resource Cannot Load + - Confirm that the icon path has been processed via the static file service (serve_static_file) +- Events Not Triggering + - Confirm that the item_click event was bound during initialization (internally triggered via `_internal.update(bind_itemClick_event=True)`) +- Frontend Directory Resolution Failed + - Check whether the component name and type in `resolve_frontend_dir` match the actual frontend directory structure + +Section Sources + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:47-47](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L47-L47) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:20-22](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L20-L22) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-16](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L16) + +## Conclusion + +AntdXWelcome and AntdXPrompts achieve seamless connection with frontend components through the unified layout component base class and frontend directory resolution mechanism. Welcome focuses on the copywriting and style configuration of the welcome page, while Prompts specializes in the display and interaction of prompt sets. Both can integrate with conversational systems through Gradio's layout and event mechanisms to realize a complete user experience loop from "welcome guidance" to "prompt activation". + +## Appendix + +- Initialization Parameter Quick Reference + - Welcome: extra, icon, description, title, variant, styles, class_names, root_class_name, elem_id, elem_classes, elem_style, visible, render + - Prompts: items, prefix_cls, title, vertical, fade_in, fade_in_left, wrap, styles, class_names, root_class_name, additional_props, elem_id, elem_classes, elem_style, visible, render +- Event Quick Reference + - Prompts: item_click (triggered when a prompt item is clicked) diff --git a/.wiki/en/API Reference/Python API/Basic Components API.md b/.wiki/en/API Reference/Python API/Basic Components API.md new file mode 100644 index 00000000..6ef5d075 --- /dev/null +++ b/.wiki/en/API Reference/Python API/Basic Components API.md @@ -0,0 +1,495 @@ +# Basic Components API + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/components/base/application/__init__.py](file://backend/modelscope_studio/components/base/application/__init__.py) +- [backend/modelscope_studio/components/base/auto_loading/__init__.py](file://backend/modelscope_studio/components/base/auto_loading/__init__.py) +- [backend/modelscope_studio/components/base/slot/__init__.py](file://backend/modelscope_studio/components/base/slot/__init__.py) +- [backend/modelscope_studio/components/base/each/__init__.py](file://backend/modelscope_studio/components/base/each/__init__.py) +- [backend/modelscope_studio/components/base/filter/__init__.py](file://backend/modelscope_studio/components/base/filter/__init__.py) +- [backend/modelscope_studio/components/base/fragment/__init__.py](file://backend/modelscope_studio/components/base/fragment/__init__.py) +- [backend/modelscope_studio/components/base/div/__init__.py](file://backend/modelscope_studio/components/base/div/__init__.py) +- [backend/modelscope_studio/components/base/text/__init__.py](file://backend/modelscope_studio/components/base/text/__init__.py) +- [backend/modelscope_studio/components/base/span/__init__.py](file://backend/modelscope_studio/components/base/span/__init__.py) +- [backend/modelscope_studio/components/base/markdown/__init__.py](file://backend/modelscope_studio/components/base/markdown/__init__.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/app_context.py](file://backend/modelscope_studio/utils/dev/app_context.py) +- [docs/components/base/application/README.md](file://docs/components/base/application/README.md) +- [docs/components/base/each/README.md](file://docs/components/base/each/README.md) +- [docs/components/base/slot/README.md](file://docs/components/base/slot/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Usage Examples and Best Practices](#appendix-usage-examples-and-best-practices) + +## Introduction + +This document is the Python API reference for the base component library, covering core components under `modelscope_studio.components.base.*`, including Application, AutoLoading, Slot, Each, Filter, Fragment, Layout components (represented by common layout components such as Div/Span/Markdown), Text, and others. The documentation is organized based on the repository source code and accompanying docs, focusing on: + +- Complete import paths and usage patterns +- Constructor parameters, property definitions, method signatures, and return types +- Component composition patterns (application containers, conditional rendering, list iteration) +- Lifecycle management, context passing, and slot system interfaces +- Performance optimization strategies, memory management, and error handling mechanisms +- Component inheritance patterns, extension development, and best practices + +## Project Structure + +Base components reside in the backend Python package `modelscope_studio/components/base`, aggregated through a unified export entry point; frontend resources are resolved by utility modules and bound to corresponding frontend directories. + +```mermaid +graph TB +subgraph "Python Backend" +BASE["backend/modelscope_studio/components/base/__init__.py"] +APP["application/__init__.py"] +AUTO["auto_loading/__init__.py"] +SLOT["slot/__init__.py"] +EACH["each/__init__.py"] +FILTER["filter/__init__.py"] +FRAG["fragment/__init__.py"] +DIV["div/__init__.py"] +TEXT["text/__init__.py"] +SPAN["span/__init__.py"] +MARK["markdown/__init__.py"] +DEV["utils/dev/component.py"] +CTX["utils/dev/app_context.py"] +end +BASE --> APP +BASE --> AUTO +BASE --> SLOT +BASE --> EACH +BASE --> FILTER +BASE --> FRAG +BASE --> DIV +BASE --> TEXT +BASE --> SPAN +BASE --> MARK +APP --> DEV +AUTO --> DEV +SLOT --> DEV +EACH --> DEV +FILTER --> DEV +FRAG --> DEV +DIV --> DEV +TEXT --> DEV +SPAN --> DEV +MARK --> DEV +APP --> CTX +DEV --> CTX +``` + +Diagram sources + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:8-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L8-L65) +- [backend/modelscope_studio/components/base/slot/**init**.py:8-50](file://backend/modelscope_studio/components/base/slot/__init__.py#L8-L50) +- [backend/modelscope_studio/components/base/each/**init**.py:17-73](file://backend/modelscope_studio/components/base/each/__init__.py#L17-L73) +- [backend/modelscope_studio/components/base/filter/**init**.py:8-45](file://backend/modelscope_studio/components/base/filter/__init__.py#L8-L45) +- [backend/modelscope_studio/components/base/fragment/**init**.py:8-49](file://backend/modelscope_studio/components/base/fragment/__init__.py#L8-L49) +- [backend/modelscope_studio/components/base/div/**init**.py:10-86](file://backend/modelscope_studio/components/base/div/__init__.py#L10-L86) +- [backend/modelscope_studio/components/base/text/**init**.py:8-57](file://backend/modelscope_studio/components/base/text/__init__.py#L8-L57) +- [backend/modelscope_studio/components/base/span/**init**.py:10-87](file://backend/modelscope_studio/components/base/span/__init__.py#L10-L87) +- [backend/modelscope_studio/components/base/markdown/**init**.py:11-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L11-L174) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) + +Section sources + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +## Core Components + +The following is an overview of import paths and key capabilities for each core base component (sorted alphabetically): + +- Application + - Import path: `from modelscope_studio.components.base import Application` + - Capabilities: Application root container; listens to page lifecycle events (mount, resize, unmount, custom); provides page environment data (screen size, language, theme, userAgent). + - Key notes: Must be used as the root container for all components; supports custom event bridging (`window.ms_globals.dispatch` → Python-side events). + +- AutoLoading + - Import path: `from modelscope_studio.components.base import AutoLoading` + - Capabilities: Auto-loading state wrapper; supports slots (render, errorRender, loadingText); controllable mask, timer, and error display. + +- Slot + - Import path: `from modelscope_studio.components.base import Slot` + - Capabilities: Slot placeholder component; used together with the target component's `SLOTS`; supports `params_mapping` for parameter mapping. + +- Each + - Import path: `from modelscope_studio.components.base import Each` + - Capabilities: List iteration rendering; injects context; supports `as_item` filtering and deep merge via `context_value`. + +- Filter + - Import path: `from modelscope_studio.components.base import Filter` + - Capabilities: Conditional filter component; determines whether to render a subtree based on parameter mapping. + +- Fragment + - Import path: `from modelscope_studio.components.base import Fragment` + - Capabilities: Grouping container; produces no additional DOM; suitable for logical grouping and slot mounting. + +- Div/Text/Span/Markdown + - Import path: `from modelscope_studio.components.base import Div, Text, Span, Markdown` + - Capabilities: Basic layout and text components; support additional properties, event binding, copy button, and other features. + +Section sources + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [docs/components/base/application/README.md:1-56](file://docs/components/base/application/README.md#L1-L56) +- [docs/components/base/each/README.md:1-32](file://docs/components/base/each/README.md#L1-L32) +- [docs/components/base/slot/README.md:1-17](file://docs/components/base/slot/README.md#L1-L17) + +## Architecture Overview + +The runtime architecture of base components revolves around "application context + component base classes + frontend resource resolution". Components assert the existence of an Application context during construction, and pass layout and index information to the frontend via the internal `_internal` dictionary; some components support slots and event binding, which are ultimately consumed by the frontend rendering engine. + +```mermaid +graph TB +APP["Application
Application Root Container"] --> CTX["AppContext
Global Context"] +CTX --> BASE["ModelScopeLayoutComponent / ModelScopeComponent
Component Base Class"] +BASE --> EACH["Each"] +BASE --> SLOT["Slot"] +BASE --> FILTER["Filter"] +BASE --> FRAG["Fragment"] +BASE --> LAYOUT["Div / Span / Markdown and other layout components"] +BASE --> AUTO["AutoLoading"] +BASE --> DATA["ModelScopeDataLayoutComponent
Layout Component with Data Model"] +DATA --> APPCOMP["Application"] +DATA --> MARK["Markdown"] +subgraph "Frontend Resource Resolution" +RESOLVE["resolve_frontend_dir(type='base')"] +end +BASE --> RESOLVE +DATA --> RESOLVE +AUTO --> RESOLVE +LAYOUT --> RESOLVE +``` + +Diagram sources + +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/components/base/markdown/**init**.py:11-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L11-L174) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:8-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L8-L65) +- [backend/modelscope_studio/components/base/div/**init**.py:10-86](file://backend/modelscope_studio/components/base/div/__init__.py#L10-L86) +- [backend/modelscope_studio/components/base/slot/**init**.py:8-50](file://backend/modelscope_studio/components/base/slot/__init__.py#L8-L50) +- [backend/modelscope_studio/components/base/each/**init**.py:17-73](file://backend/modelscope_studio/components/base/each/__init__.py#L17-L73) +- [backend/modelscope_studio/components/base/filter/**init**.py:8-45](file://backend/modelscope_studio/components/base/filter/__init__.py#L8-L45) +- [backend/modelscope_studio/components/base/fragment/**init**.py:8-49](file://backend/modelscope_studio/components/base/fragment/__init__.py#L8-L49) + +## Detailed Component Analysis + +### Application + +- Import path: `from modelscope_studio.components.base import Application` +- Inheritance: `ModelScopeDataLayoutComponent` +- Events: + - `mount`: Page mounted + - `resize`: Window size changed + - `unmount`: Page unmounted + - `custom`: Custom event triggered via `window.ms_globals.dispatch` +- Data models: + - `ApplicationPageScreenData`: width, height, scrollX, scrollY + - `ApplicationPageData`: screen, language, theme, userAgent +- Key behavior: + - Sets `AppContext` during construction + - Supports `preprocess`/`postprocess` pass-through + - Provides `example_payload`/`example_value` + +Section sources + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [docs/components/base/application/README.md:1-56](file://docs/components/base/application/README.md#L1-L56) + +### AutoLoading + +- Import path: `from modelscope_studio.components.base import AutoLoading` +- Inheritance: `ModelScopeLayoutComponent` +- Slots: `render`, `errorRender`, `loadingText` +- Key properties: + - `generating`, `show_error`, `show_mask`, `show_timer`, `loading_text` +- Key behavior: + - `skip_api=True`, does not participate in the standard API flow + - `preprocess`/`postprocess` handles strings as pass-through + +Section sources + +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:8-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L8-L65) + +### Slot + +- Import path: `from modelscope_studio.components.base import Slot` +- Inheritance: `ModelScopeLayoutComponent` +- Key properties: + - `value`: Slot name + - `params_mapping`: JavaScript function string for parameter mapping +- Key behavior: + - When the parent is also a Slot, `value` is concatenated to form a hierarchical path + - `skip_api=True` + +Section sources + +- [backend/modelscope_studio/components/base/slot/**init**.py:8-50](file://backend/modelscope_studio/components/base/slot/__init__.py#L8-L50) +- [docs/components/base/slot/README.md:1-17](file://docs/components/base/slot/README.md#L1-L17) + +### Each + +- Import path: `from modelscope_studio.components.base import Each` +- Inheritance: `ModelScopeDataLayoutComponent` +- Data model: `ModelScopeEachData` (root: list) +- Key properties: + - `value`: `list[dict]` or `Callable` + - `context_value`: `dict`, used for deep merge into context + - `as_item`: string, for filtering context fields +- Key behavior: + - `preprocess` unpacks `ModelScopeEachData` into a list + - `postprocess` returns a list + - `skip_api=False`, participates in the API flow + +Section sources + +- [backend/modelscope_studio/components/base/each/**init**.py:17-73](file://backend/modelscope_studio/components/base/each/__init__.py#L17-L73) +- [docs/components/base/each/README.md:1-32](file://docs/components/base/each/README.md#L1-L32) + +### Filter + +- Import path: `from modelscope_studio.components.base import Filter` +- Inheritance: `ModelScopeLayoutComponent` +- Key properties: + - `params_mapping`: Parameter mapping string +- Key behavior: + - `skip_api=True`, does not participate in the API flow + +Section sources + +- [backend/modelscope_studio/components/base/filter/**init**.py:8-45](file://backend/modelscope_studio/components/base/filter/__init__.py#L8-L45) + +### Fragment + +- Import path: `from modelscope_studio.components.base import Fragment` +- Inheritance: `ModelScopeLayoutComponent` +- Key behavior: + - `skip_api=True`, does not participate in the API flow + - Suitable for logical grouping and slot mounting + +Section sources + +- [backend/modelscope_studio/components/base/fragment/**init**.py:8-49](file://backend/modelscope_studio/components/base/fragment/__init__.py#L8-L49) + +### Div + +- Import path: `from modelscope_studio.components.base import Div` +- Inheritance: `ModelScopeLayoutComponent` +- Events: `click`, `dblclick`, `mousedown`, `mouseup`, `mouseover`, `mouseout`, `mousemove`, `scroll` +- Key properties: + - `value`: string + - `additional_props`: dict, additional properties +- Key behavior: + - `skip_api=True` + +Section sources + +- [backend/modelscope_studio/components/base/div/**init**.py:10-86](file://backend/modelscope_studio/components/base/div/__init__.py#L10-L86) + +### Text + +- Import path: `from modelscope_studio.components.base import Text` +- Inheritance: `ModelScopeComponent` +- Key behavior: + - `skip_api=True` + +Section sources + +- [backend/modelscope_studio/components/base/text/**init**.py:8-57](file://backend/modelscope_studio/components/base/text/__init__.py#L8-L57) + +### Span + +- Import path: `from modelscope_studio.components.base import Span` +- Inheritance: `ModelScopeLayoutComponent` +- Events: `click`, `dblclick`, `mousedown`, `mouseup`, `mouseover`, `mouseout`, `mousemove`, `scroll` +- Key properties: + - `value`: string + - `additional_props`: dict, additional properties +- Key behavior: + - `skip_api=True` + +Section sources + +- [backend/modelscope_studio/components/base/span/**init**.py:10-87](file://backend/modelscope_studio/components/base/span/__init__.py#L10-L87) + +### Markdown + +- Import path: `from modelscope_studio.components.base import Markdown` +- Inheritance: `ModelScopeDataLayoutComponent` +- Events: `change`, `copy`, `click`, `dblclick`, `mousedown`, `mouseup`, `mouseover`, `mouseout`, `mousemove`, `scroll` +- Slots: `copyButtons` +- Key properties: + - `value`: string + - `rtl`, `latex_delimiters`, `sanitize_html`, `line_breaks`, `header_links`, `allow_tags`, `show_copy_button`, `copy_buttons`, `additional_props` +- Key behavior: + - `preprocess` returns as-is + - `postprocess` strips indentation and returns a string + - `api_info` returns `{"type": "string"}` + +Section sources + +- [backend/modelscope_studio/components/base/markdown/**init**.py:11-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L11-L174) + +## Dependency Analysis + +- Component base classes and context + - All base components depend on the base classes (`ModelScopeLayoutComponent`, `ModelScopeComponent`, `ModelScopeDataLayoutComponent`) defined in `utils/dev/component.py`, and assert the existence of `AppContext` during construction. + - `utils/dev/app_context.py` provides `set_app`/`assert_app`/`get_app` to ensure components are used within an Application root container. + +- Frontend resource resolution + - Each component resolves its frontend directory via `resolve_frontend_dir("xxx", type="base")`, ensuring consistency between frontend and backend resources. + +```mermaid +graph LR +CTX["AppContext"] --> |assert_app| BASE["Component Base Class"] +BASE --> |inherits| LCOMP["ModelScopeLayoutComponent"] +BASE --> |inherits| DCOMP["ModelScopeDataLayoutComponent"] +BASE --> |inherits| SCOMP["ModelScopeComponent"] +LCOMP --> |frontend| RES["resolve_frontend_dir('...')"] +DCOMP --> |frontend| RES +SCOMP --> |frontend| RES +``` + +Diagram sources + +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +Section sources + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) + +## Performance Considerations + +- Avoiding unnecessary API interactions + - Most base components have `skip_api=True` (e.g., AutoLoading, Slot, Filter, Fragment, Div/Span/Text/Markdown), meaning they do not participate in the standard API flow, reducing frontend-backend round-trip overhead. +- List rendering optimization + - `Each`'s `value` supports `Callable` for lazy evaluation in complex scenarios; combining `as_item`/`context_value` reduces redundant attribute passing and conflicts. +- Event binding + - Bind events only when necessary (e.g., mouse and scroll events for Div/Markdown) to avoid excessive bindings that could increase frontend pressure. +- Memory management + - Components uniformly mark `layout=True` in `__exit__`, ensuring the frontend correctly releases and rebuilds; avoid holding long-lived references within the component tree. +- HTML sanitization + - `Markdown`'s `postprocess` sanitizes content, reducing rendering jitter and abnormal character issues. + +## Troubleshooting Guide + +- Missing Application root container + - Symptom: Warning indicating no Application component found. + - Resolution: Ensure all components are wrapped inside an Application. + - Reference: Warning message from `AppContext.assert_app`. + +- Slot not taking effect + - Symptom: Slot fails to be inserted into the target component. + - Resolution: Confirm the target component's `SLOTS` supports the slot name; verify that `params_mapping` is correctly configured. + +- Each context conflict + - Symptom: Attribute conflicts or overrides when iterating multiple components. + - Resolution: Use `as_item` for field filtering; use `context_value` for deep merge to inject uniformly if necessary. + +- AutoLoading not displaying + - Symptom: loading/error/render slots not showing. + - Resolution: Confirm that `generating`/`show_error`/`show_mask` state matches the slot naming. + +Section sources + +- [backend/modelscope_studio/utils/dev/app_context.py:16-20](file://backend/modelscope_studio/utils/dev/app_context.py#L16-L20) +- [docs/components/base/slot/README.md:1-17](file://docs/components/base/slot/README.md#L1-L17) +- [docs/components/base/each/README.md:16-22](file://docs/components/base/each/README.md#L16-L22) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:15-46](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L15-L46) + +## Conclusion + +The base component library provides a unified application root container, layout and text components, conditional and loop rendering helper components, and a slot system. Through strict context constraints and frontend resource resolution mechanisms, it ensures stable operation of components within the Gradio ecosystem. It is recommended to use `Each`'s `as_item` and `context_value` for context management, choose `skip_api` components appropriately to reduce API overhead, and leverage Application's lifecycle events and custom events for page behavior control when needed. + +## Appendix: Usage Examples and Best Practices + +### Application Container and Page Environment + +- Wrap the outermost layer of the application with Application, and listen to page lifecycle events. +- Obtain user language, theme, screen information, and UA from Application's `value`. + +Section sources + +- [docs/components/base/application/README.md:12-20](file://docs/components/base/application/README.md#L12-L20) +- [backend/modelscope_studio/components/base/application/**init**.py:30-54](file://backend/modelscope_studio/components/base/application/__init__.py#L30-L54) + +### Conditional Rendering (Filter) + +- Use Filter with `params_mapping` to determine whether to render a subtree. +- Suitable for dynamically hiding/showing parts of the content based on context parameters. + +Section sources + +- [backend/modelscope_studio/components/base/filter/**init**.py:13-25](file://backend/modelscope_studio/components/base/filter/__init__.py#L13-L25) + +### List Iteration (Each) + +- Each accepts a list or callable, injects context; supports `as_item` and `context_value`. +- Suitable for rendering lists of unknown length and injecting uniform attributes. + +Section sources + +- [docs/components/base/each/README.md:7-22](file://docs/components/base/each/README.md#L7-L22) +- [backend/modelscope_studio/components/base/each/**init**.py:23-52](file://backend/modelscope_studio/components/base/each/__init__.py#L23-L52) + +### Slot System (Slot) + +- Slot works with the target component's `SLOTS`; `params_mapping` supports parameter mapping. +- Suitable for complex layouts and pluggable content areas. + +Section sources + +- [docs/components/base/slot/README.md:1-17](file://docs/components/base/slot/README.md#L1-L17) +- [backend/modelscope_studio/components/base/slot/**init**.py:13-30](file://backend/modelscope_studio/components/base/slot/__init__.py#L13-L30) + +### Auto Loading (AutoLoading) + +- Wrap areas that may take time to load; use render/errorRender/loadingText slots. +- Control mask, timer, and error display to improve user experience. + +Section sources + +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:17-46](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L17-L46) + +### Layout and Text Components + +- Div/Span: For basic block-level/inline layout; support various mouse and scroll events. +- Text/Markdown: Text rendering; Markdown supports copy buttons and LaTeX expression configuration. + +Section sources + +- [backend/modelscope_studio/components/base/div/**init**.py:44-67](file://backend/modelscope_studio/components/base/div/__init__.py#L44-L67) +- [backend/modelscope_studio/components/base/span/**init**.py:44-67](file://backend/modelscope_studio/components/base/span/__init__.py#L44-L67) +- [backend/modelscope_studio/components/base/text/**init**.py:17-37](file://backend/modelscope_studio/components/base/text/__init__.py#L17-L37) +- [backend/modelscope_studio/components/base/markdown/**init**.py:54-141](file://backend/modelscope_studio/components/base/markdown/__init__.py#L54-L141) + +### Component Inheritance and Extension Development + +- New components are recommended to inherit the appropriate base class: + - Requires data model and layout: `ModelScopeDataLayoutComponent` + - Layout only: `ModelScopeLayoutComponent` + - Pure component: `ModelScopeComponent` +- Set `FRONTEND_DIR` in the constructor to ensure frontend resources are correctly resolved. +- If slots are needed, define `SLOTS` and document the supported slot names and their purposes. + +Section sources + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) diff --git a/.wiki/en/API Reference/Python API/Pro Components API.md b/.wiki/en/API Reference/Python API/Pro Components API.md new file mode 100644 index 00000000..ea03c438 --- /dev/null +++ b/.wiki/en/API Reference/Python API/Pro Components API.md @@ -0,0 +1,487 @@ +# Pro Components API + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/pro/__init__.py](file://backend/modelscope_studio/components/pro/__init__.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) +- [backend/modelscope_studio/components/pro/multimodal_input/__init__.py](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py) +- [backend/modelscope_studio/components/pro/web_sandbox/__init__.py](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py) +- [backend/modelscope_studio/components/pro/monaco_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) +- [backend/modelscope_studio/utils/dev/process_links.py](file://backend/modelscope_studio/utils/dev/process_links.py) +- [docs/demos/example.py](file://docs/demos/example.py) +- [docs/layout_templates/chatbot/app.py](file://docs/layout_templates/chatbot/app.py) +- [docs/layout_templates/chatbot/demos/basic.py](file://docs/layout_templates/chatbot/demos/basic.py) +- [docs/components/pro/chatbot/demos/chatbot_config.py](file://docs/components/pro/chatbot/demos/chatbot_config.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is the Python API reference for the pro component library (`modelscope_studio.components.pro`), covering the following AI application-specific components: + +- **Chatbot**: Conversational message container and rendering component; supports user/assistant messages, welcome prompts, suggested prompts, tool calls, file content, and other rich capabilities. +- **MultimodalInput**: Multimodal input component; supports text and attachment uploads, paste, drag-and-drop, voice, and other input modalities. +- **WebSandbox**: Web sandbox component; renders React/HTML templates in an isolated environment; supports compile and render error events. +- **MonacoEditor**: Code editor component; supports language highlighting, read-only mode, option configuration, mount/change/validate events; provides a DiffEditor subclass. + +This document records import paths, constructor parameters, property definitions, method signatures, and return types for each component. It provides standard instantiation and usage examples for complex AI applications, covering advanced use cases such as chatbot integration, multimodal input handling, and web sandbox isolation. It also explains event binding, data flow processing strategies, frontend/backend data conversion logic, and performance and concurrency considerations. + +## Project Structure + +Pro components reside in the backend Python package `modelscope_studio/components/pro`, divided into four submodules by function: chatbot, multimodal_input, web_sandbox, and monaco_editor, with a unified export entry and alias exports. + +```mermaid +graph TB +subgraph "Python Backend" +PRO["pro/__init__.py
Unified Exports"] +COMP["pro/components.py
Alias Exports"] +CHAT["pro/chatbot/__init__.py"] +MMI["pro/multimodal_input/__init__.py"] +WS["pro/web_sandbox/__init__.py"] +ME["pro/monaco_editor/__init__.py"] +MED["pro/monaco_editor/diff_editor/__init__.py"] +end +subgraph "Common Base Classes" +DEV["utils/dev/component.py
ModelScope*Component Family"] +RES["utils/dev/resolve_frontend_dir.py"] +LNK["utils/dev/process_links.py"] +end +PRO --> CHAT +PRO --> MMI +PRO --> WS +PRO --> ME +ME --> MED +COMP --> CHAT +COMP --> MMI +COMP --> WS +COMP --> ME +COMP --> MED +CHAT --> DEV +MMI --> DEV +WS --> DEV +ME --> DEV +MED --> DEV +CHAT --> RES +MMI --> RES +WS --> RES +ME --> RES +MED --> RES +CHAT --> LNK +``` + +Diagram sources + +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:15-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L86) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:10-106](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L10-L106) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L17) +- [backend/modelscope_studio/utils/dev/process_links.py:9-61](file://backend/modelscope_studio/utils/dev/process_links.py#L9-L61) + +Section sources + +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## Core Components + +This section provides an overview of the responsibilities and typical use cases for the four pro components: + +- **Chatbot**: Used to build conversational interfaces; manages message lists, welcome prompts, suggested prompts, action buttons, Markdown rendering, file/tool content, and more. +- **MultimodalInput**: Used to receive multimodal input with text and attachments; supports upload, paste, drag-and-drop, preview, download, and other workflows. +- **WebSandbox**: Used to render templates (React/HTML) in an isolated environment; captures compile and render error events. +- **MonacoEditor**: Used to embed a code editor in the browser; supports language, read-only, options, mount/change/validate events; provides DiffEditor for diff view. + +Section sources + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:15-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L86) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) + +## Architecture Overview + +Pro components extend the Gradio component system through unified base classes and frontend directory resolution to bridge frontend and backend. Components set `FRONTEND_DIR` during initialization, pointing to the corresponding frontend Svelte component directory; `preprocess`/`postprocess` handles frontend/backend data conversion; `EVENTS`/`SLOTS` provide event and slot extension points. + +```mermaid +sequenceDiagram +participant Py as "Python Component" +participant Base as "ModelScope*Component Base Class" +participant FE as "Frontend Component (Svelte)" +participant App as "Gradio App" +App->>Py : Instantiate component (pass value/config) +Py->>Base : Call parent constructor (inherit Gradio Component) +Py->>Py : Set FRONTEND_DIR / data model / events / SLOTS +Py->>FE : Pass config and data during rendering +FE-->>Py : Trigger event callbacks (e.g. change/copy/edit/delete/like/retry/suggestion_select/welcome_prompt_select) +Py-->>App : Return processed value (possibly via postprocess) +``` + +Diagram sources + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L17) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:15-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L86) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) + +## Detailed Component Analysis + +### Chatbot Component + +- Import paths + - Main class: `modelscope_studio.components.pro.Chatbot` + - Alias: `modelscope_studio.components.pro.ProChatbot` +- Purpose + - Manages conversational message lists; supports user/assistant messages, welcome prompts, suggested prompts, action buttons, Markdown rendering, file/tool content, and more. +- Key data models + - `ChatbotWelcomeConfig`, `ChatbotPromptsConfig`, `ChatbotPromptConfig`, `ChatbotMarkdownConfig`, `ChatbotUserConfig`, `ChatbotBotConfig`, `ChatbotDataMessageContent`, `ChatbotDataMessage`, `ChatbotDataMessages`, `ChatbotDataMeta` +- Constructor parameter highlights + - `value`: Can be a callback or message list/dict; supports message status `pending`/`done`, separators, metadata feedback, etc. + - Height and scrolling: `height`, `min_height`, `max_height`, `auto_scroll`, `show_scroll_to_bottom_button`, `scroll_to_bottom_button_offset` + - Welcome and Markdown: `welcome_config`, `markdown_config` + - User/assistant styles and actions: `user_config`, `bot_config` (includes `actions`/`disabled_actions`, `avatar`, `typing`, etc.) + - Others: `elem_id`, `elem_classes`, `elem_style`, `visible`, `render`, etc. +- Methods and behavior + - `preprocess`: Normalizes file paths in message content for frontend display + - `postprocess`: Converts file paths to `FileData` structures; supports local and remote URLs + - Events: `change`, `copy`, `edit`, `delete`, `like`, `retry`, `suggestion_select`, `welcome_prompt_select` + - Slots: `role` +- Usage examples (reference) + - Basic chat template app entry: [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) + - Chat config and event demo: [docs/components/pro/chatbot/demos/chatbot_config.py:1-40](file://docs/components/pro/chatbot/demos/chatbot_config.py#L1-L40) + +```mermaid +classDiagram +class ModelScopeProChatbot { ++EVENTS ++SLOTS ++FRONTEND_DIR ++data_model ++__init__(...) ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class ChatbotWelcomeConfig +class ChatbotPromptsConfig +class ChatbotPromptConfig +class ChatbotMarkdownConfig +class ChatbotUserConfig +class ChatbotBotConfig +class ChatbotDataMessageContent +class ChatbotDataMessage +class ChatbotDataMessages +class ChatbotDataMeta +ModelScopeProChatbot --> ChatbotWelcomeConfig : "uses" +ModelScopeProChatbot --> ChatbotPromptsConfig : "uses" +ModelScopeProChatbot --> ChatbotMarkdownConfig : "uses" +ModelScopeProChatbot --> ChatbotUserConfig : "uses" +ModelScopeProChatbot --> ChatbotBotConfig : "uses" +ModelScopeProChatbot --> ChatbotDataMessageContent : "uses" +ModelScopeProChatbot --> ChatbotDataMessage : "uses" +ModelScopeProChatbot --> ChatbotDataMessages : "uses" +ModelScopeProChatbot --> ChatbotDataMeta : "uses" +``` + +Diagram sources + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-285](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L285) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) + +Section sources + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-285](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L285) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) +- [docs/components/pro/chatbot/demos/chatbot_config.py:1-40](file://docs/components/pro/chatbot/demos/chatbot_config.py#L1-L40) + +### MultimodalInput Component + +- Import paths + - Main class: `modelscope_studio.components.pro.MultimodalInput` + - Alias: `modelscope_studio.components.pro.ProMultimodalInput` +- Purpose + - Accepts multimodal input with text and attachments; supports upload, paste, drag-and-drop, preview, download, and other workflows. +- Key data models + - `MultimodalInputUploadConfig`: Upload behavior and UI configuration + - `MultimodalInputValue`: Input value containing `files` and `text` +- Constructor parameter highlights + - `value`: `MultimodalInputValue` or its dict form + - Mode and size: `mode`, `auto_size`, `footer`/`header`/`prefix`/`suffix`, `placeholder`, `submit_type` + - Upload config: `upload_config` (includes `fullscreen_drop`, `allow_upload`, `allow_paste_file`, `allow_speech`, `max_count`, `directory`, `multiple`, `overflow`, `title`, `image_props`, `placeholder`, etc.) + - Style and state: `disabled`, `read_only`, `loading`, `class_names`, `styles`, `root_class_name` + - Others: `elem_id`, `elem_classes`, `elem_style`, `visible`, `render`, etc. +- Methods and behavior + - `preprocess`: Converts uploaded files to cacheable named strings for subsequent processing + - `postprocess`: Downloads remote URLs to local cache and wraps them as `FileData` lists + - Events: `change`, `submit`, `cancel`, `key_down`/`key_press`, `focus`, `blur`, `upload`, `paste`, `paste_file`, `skill_closable_close`, `drop`, `download`, `preview`, `remove` + - Slots: `suffix`, `header`, `prefix`, `footer`, `skill.title`, `skill.toolTip.title`, `skill.closable.closeIcon` +- Usage examples (reference) + - Example app entry: [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +```mermaid +classDiagram +class ModelScopeProMultimodalInput { ++EVENTS ++SLOTS ++FRONTEND_DIR ++data_model ++__init__(...) ++preprocess(payload) ++postprocess(value) ++_process_single_file(f) ++_download_files(value) ++skip_api ++example_payload() ++example_value() +} +class MultimodalInputUploadConfig +class MultimodalInputValue +ModelScopeProMultimodalInput --> MultimodalInputUploadConfig : "uses" +ModelScopeProMultimodalInput --> MultimodalInputValue : "uses" +``` + +Diagram sources + +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:18-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L18-L259) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) + +Section sources + +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:18-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L18-L259) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +### WebSandbox Component + +- Import paths + - Main class: `modelscope_studio.components.pro.WebSandbox` + - Alias: `modelscope_studio.components.pro.ProWebSandbox` +- Purpose + - Renders React/HTML templates in an isolated environment; supports compile and render error event monitoring. +- Key data models + - `SandboxFileData`: Template file structure (code, is_entry) +- Constructor parameter highlights + - `value`: dict where keys are file names and values are strings or `SandboxFileData` + - Template type: `template` (`'react'` | `'html'`) + - Error display: `show_render_error`, `show_compile_error`, `compile_error_render` + - External dependencies: `imports` (module mapping) + - Size: `height` + - Others: `elem_id`, `elem_classes`, `elem_style`, `visible`, `render`, etc. +- Methods and behavior + - `preprocess`/`postprocess`: Direct pass-through (`skip_api=True`) + - Events: `compile_success`, `compile_error`, `render_error`, `custom` + - Slots: `compileErrorRender` +- Usage examples (reference) + - Example app entry: [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +```mermaid +classDiagram +class ModelScopeProWebSandbox { ++EVENTS ++SLOTS ++FRONTEND_DIR ++__init__(...) ++preprocess(payload) ++postprocess(value) ++skip_api ++example_payload() ++example_value() +} +class SandboxFileData +ModelScopeProWebSandbox --> SandboxFileData : "uses" +``` + +Diagram sources + +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:10-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L10-L86) +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:15-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L86) + +Section sources + +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:10-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L10-L86) +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:15-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L86) +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +### MonacoEditor Component + +- Import paths + - Main class: `modelscope_studio.components.pro.MonacoEditor` + - Alias: `modelscope_studio.components.pro.ProMonacoEditor` + - DiffEditor: `modelscope_studio.components.pro.MonacoEditorDiffEditor` (as a subclass) +- Purpose + - Provides a code editor with language, read-only, options, mount/change/validate events; DiffEditor provides a diff view. +- Constructor parameter highlights + - `value`: Initial editing content + - Language and read-only: `language`, `read_only` + - Lifecycle hooks: `before_mount`, `after_mount` + - Service overrides: `override_services` + - Loading text: `loading` + - Editor options: `options` + - Line positioning: `line` + - Size: `height` + - Others: `elem_id`, `elem_classes`, `elem_style`, `visible`, `render`, etc. +- Methods and behavior + - `preprocess`/`postprocess`: Direct pass-through (`skip_api=False`) + - Events: `mount`, `change`, `validate` + - Slots: `loading` + - DiffEditor: Shares loader configuration with the main editor; supports `original`/`original_language`/`modified_language` +- Usage examples (reference) + - Example app entry: [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +```mermaid +classDiagram +class ModelScopeProMonacoEditor { ++EVENTS ++SLOTS ++LOADER ++FRONTEND_DIR ++__init__(...) ++preprocess(payload) ++postprocess(value) ++api_info() ++skip_api ++example_payload() ++example_value() +} +class ModelScopeProMonacoEditorDiffEditor { ++EVENTS ++SLOTS ++FRONTEND_DIR ++__init__(...) ++preprocess(payload) ++postprocess(value) ++api_info() ++skip_api ++example_payload() ++example_value() +} +ModelScopeProMonacoEditor <|-- ModelScopeProMonacoEditorDiffEditor : "subclass" +``` + +Diagram sources + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:10-106](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L10-L106) + +Section sources + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:10-106](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L10-L106) +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +## Dependency Analysis + +- Component base classes + - `ModelScopeLayoutComponent`: Layout component base class; suitable for container components that do not need data transfer (e.g., WebSandbox) + - `ModelScopeComponent`: Basic component base class; suitable for data-driven components (e.g., Chatbot/MultimodalInput/MonacoEditor) + - `ModelScopeDataLayoutComponent`: Combines data and layout capabilities; suitable for components that require frontend/backend data exchange (e.g., Chatbot/MultimodalInput/MonacoEditor) +- Frontend directory resolution + - `resolve_frontend_dir`: Generates relative paths based on component name and type (pro/antd/antdx/base) to ensure frontend resources load correctly +- Data link processing + - `process_links`: Converts links in HTML/Markdown, transforming local files into accessible cache URLs + +```mermaid +graph LR +A["ModelScopeLayoutComponent"] --> C["WebSandbox"] +B["ModelScopeComponent"] --> D["Chatbot"] +B --> E["MultimodalInput"] +B --> F["MonacoEditor"] +G["ModelScopeDataLayoutComponent"] --> D +G --> E +G --> F +H["resolve_frontend_dir"] --> C +H --> D +H --> E +H --> F +I["process_links"] --> D +``` + +Diagram sources + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L17) +- [backend/modelscope_studio/utils/dev/process_links.py:9-61](file://backend/modelscope_studio/utils/dev/process_links.py#L9-L61) + +Section sources + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L17) +- [backend/modelscope_studio/utils/dev/process_links.py:9-61](file://backend/modelscope_studio/utils/dev/process_links.py#L9-L61) + +## Performance Considerations + +- Data serialization and transmission + - Chatbot/MultimodalInput/MonacoEditor are data-driven components; `preprocess`/`postprocess` handles file path and `FileData` conversions, avoiding memory pressure from processing large files directly in the frontend. +- Frontend resource loading + - MonacoEditor supports local or CDN loader configuration; choosing appropriately can reduce initial load time; DiffEditor reuses the main editor's loader configuration. +- Event binding and updates + - Components dynamically bind events via `_internal.update`, avoiding unnecessary re-renders; WebSandbox's `skip_api=True` reduces API layer overhead. +- File processing + - MultimodalInput downloads remote URLs to the cache directory in `postprocess`, avoiding repeated network requests; `process_links` converts local resources to cache URLs, improving stability and performance. + +## Troubleshooting Guide + +- Editor loading failure + - Check MonacoEditor's `LOADER` configuration (mode/local/cdn); verify CDN reachability or switch to local loading. + - Check whether mount/change/validate events are triggered to locate the problem stage. +- Files cannot be displayed or download anomalies + - Chatbot's file content is converted to `FileData` in `postprocess`; check whether the path is a local file or a valid URL. + - MultimodalInput's `postprocess` downloads remote URLs to cache; verify cache directory permissions and network reachability. +- Sandbox compile/render errors + - WebSandbox provides `compile_error`/`render_error` events; combine with the `compileErrorRender` slot to locate errors. +- Broken links + - Use `process_links` to convert links in HTML/Markdown, ensuring local resources are correctly cached and accessible. + +Section sources + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:44-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L44-L107) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:475-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L475-L495) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:233-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L233-L259) +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:19-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L19-L86) +- [backend/modelscope_studio/utils/dev/process_links.py:9-61](file://backend/modelscope_studio/utils/dev/process_links.py#L9-L61) + +## Conclusion + +The pro component library, centered around conversation, multimodal input, web sandbox, and code editing, provides a complete Python API and frontend integration solution. Through a unified base class system, flexible event and slot mechanisms, and comprehensive frontend/backend data conversion, it meets the development requirements of complex AI applications. It is recommended to combine examples and best practices in real projects, and to configure loaders, events, and data flows appropriately for a stable and high-performance user experience. + +## Appendix + +- Unified exports and aliases + - Main module exports: `Chatbot`, `MonacoEditor`, `MonacoEditorDiffEditor`, `MultimodalInput`, `WebSandbox` + - Alias exports: `ProChatbot`, `ProMonacoEditor`, `ProMonacoEditorDiffEditor`, `ProMultimodalInput`, `ProWebSandbox` +- Example entries + - Basic example: [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + - Chat template app: [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) + - Chat config and event demo: [docs/components/pro/chatbot/demos/chatbot_config.py:1-40](file://docs/components/pro/chatbot/demos/chatbot_config.py#L1-L40) + +Section sources + +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) +- [docs/components/pro/chatbot/demos/chatbot_config.py:1-40](file://docs/components/pro/chatbot/demos/chatbot_config.py#L1-L40) diff --git a/.wiki/en/API Reference/Python API/Python API.md b/.wiki/en/API Reference/Python API/Python API.md new file mode 100644 index 00000000..50f1d05d --- /dev/null +++ b/.wiki/en/API Reference/Python API/Python API.md @@ -0,0 +1,433 @@ +# Python API + + +**Files Referenced in This Document** +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/components/pro/__init__.py](file://backend/modelscope_studio/components/pro/__init__.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [backend/modelscope_studio/components/antd/button/__init__.py](file://backend/modelscope_studio/components/antd/button/__init__.py) +- [backend/modelscope_studio/components/antd/form/__init__.py](file://backend/modelscope_studio/components/antd/form/__init__.py) +- [backend/modelscope_studio/components/base/application/__init__.py](file://backend/modelscope_studio/components/base/application/__init__.py) +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: API Index and Usage Examples](#appendix-api-index-and-usage-examples) + +## Introduction + +This document is the Python API reference for ModelScope Studio, focusing on the component system and calling conventions of the backend Python package `modelscope_studio`. The document covers: + +- Component import paths and named export conventions (`modelscope_studio.components.antd.*`, `modelscope_studio.components.antdx.*`, `modelscope_studio.components.base.*`, `modelscope_studio.components.pro.*`) +- Constructor parameters, supported events, slots, data models, and preprocess/postprocess flows for key component classes +- Standard instantiation examples (basic usage and advanced configuration), and lifecycle and state management essentials +- Parameter validation and exception handling mechanism notes +- Version compatibility information and common issue troubleshooting + +## Project Structure + +The Python package is located at `backend/modelscope_studio`; the top level aggregates sub-modules via `__all__` exports; components are organized hierarchically in four sub-packages: `antd`, `antdx`, `base`, and `pro`. Each sub-package provides both `__init__.py` and `components.py` entries for different aggregation strategies. + +```mermaid +graph TB +A["backend/modelscope_studio/__init__.py"] --> B["backend/modelscope_studio/components/__init__.py"] +B --> C["antd Sub-Package"] +B --> D["antdx Sub-Package"] +B --> E["base Sub-Package"] +B --> F["pro Sub-Package"] +C --> C1["antd/__init__.py
Named exports of component classes"] +D --> D1["antdx/__init__.py
Named exports of component classes"] +E --> E1["base/__init__.py
Named exports of base component classes"] +F --> F1["pro/__init__.py
Named exports of pro component classes"] +``` + +**Diagram Sources** + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) + +**Section Sources** + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) + +## Core Components + +This section provides an overview of import paths and named exports for the four component families, and explains the responsibility boundaries and typical use cases of each family. + +- `modelscope_studio.components.antd.*` + - Responsibility: Python wrappers for the Ant Design component ecosystem, covering common UI components for layout, forms, feedback, navigation, and data entry. + - Typical components: Button, Form, Input, Select, Table, Modal, Message, Notification, etc. + - Import: `from modelscope_studio.components.antd import Button, Form, ...` + - Named exports: See [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) and [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) + +- `modelscope_studio.components.antdx.*` + - Responsibility: Ant Design X extended component set, designed for conversational interaction and knowledge work scenarios (e.g., message bubbles, conversation lists, prompt panels, etc.). + - Typical components: Bubble, Conversations, Prompts, Sender, ThoughtChain, Welcome, etc. + - Import: `from modelscope_studio.components.antdx import Bubble, Conversations, ...` + - Named exports: See [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) and [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +- `modelscope_studio.components.base.*` + - Responsibility: Base layout and container components providing general capabilities such as application-level containers, loop rendering, conditional filtering, placeholder text, etc. + - Typical components: Application, Each, Filter, Fragment, Markdown, Slot, Text, Div, etc. + - Import: `from modelscope_studio.components.base import Application, Each, ...` + - Named exports: See [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +- `modelscope_studio.components.pro.*` + - Responsibility: Professional domain components designed for specific business scenarios (e.g., chatbot, code editor, multimodal input, web sandbox, etc.). + - Typical components: Chatbot, MonacoEditor, MultimodalInput, WebSandbox. + - Import: `from modelscope_studio.components.pro import Chatbot, MonacoEditor, ...` + - Named exports: See [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) and [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +**Section Sources** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## Architecture Overview + +The diagram below shows the relationship between Python layer component classes and frontend directory resolution, and the key nodes of event binding and data flow. + +```mermaid +graph TB +subgraph "Python Layer" +P1["AntdButton.__init__()
Constructor params & event binding"] +P2["AntdForm.__init__()
Form config & event binding"] +P3["ModelScopeApplication.__init__()
App context & event binding"] +P4["ModelScopeProChatbot.__init__()
Message config & static resource handling"] +end +subgraph "Frontend Directory Resolution" +F1["resolve_frontend_dir('button')"] +F2["resolve_frontend_dir('form')"] +F3["resolve_frontend_dir('application', type='base')"] +F4["resolve_frontend_dir('chatbot', type='pro')"] +end +P1 --> F1 +P2 --> F2 +P3 --> F3 +P4 --> F4 +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) + +## Detailed Component Analysis + +### Component: AntdButton + +- Import Path: `from modelscope_studio.components.antd import Button` +- Purpose: Wraps the Ant Design button, supporting multiple types, sizes, shapes, loading state, danger state, ghost state, etc. +- Key Points: + - Supported events: `click` + - Slots: `icon`, `loading.icon` + - Preprocess/postprocess: Simple string-to-string conversion + - Frontend directory: `resolve_frontend_dir("button")` + +```mermaid +classDiagram +class AntdButton { ++Constructor params(...) ++EVENTS ++SLOTS ++FRONTEND_DIR ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) + +**Section Sources** + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) + +### Component: AntdForm and AntdFormItem + +- Import Path: `from modelscope_studio.components.antd import Form, Form.Item` +- Purpose: Wraps the Ant Design form, supporting events for field changes, submit, failure, value changes, etc., as well as form item rules and providers. +- Key Points: + - Supported events: `fields_change`, `finish`, `finish_failed`, `values_change` + - Data model: `AntdFormData` + - Preprocess/postprocess: Extracts the `root` field from the data model or passes through as-is + - Frontend directory: `resolve_frontend_dir("form")` + +```mermaid +classDiagram +class AntdForm { ++Item ++Provider ++data_model ++EVENTS ++FRONTEND_DIR ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdFormItem { ++Constructor params(...) ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdFormProvider { ++Constructor params(...) ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdFormData { ++root +} +AntdForm --> AntdFormItem : "Contains" +AntdForm --> AntdFormProvider : "Contains" +AntdForm --> AntdFormData : "Uses" +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) + +**Section Sources** + +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) + +### Component: ModelScopeApplication + +- Import Path: `from modelscope_studio.components.base import Application` +- Purpose: Application-level container providing page environment data (screen size, theme, language, etc.) and lifecycle events (mount, resize, unmount, custom). +- Key Points: + - Supported events: `custom`, `mount`, `resize`, `unmount` + - Data model: `ApplicationPageData` + - Preprocess/postprocess: Pass-through + - Frontend directory: `resolve_frontend_dir("application", type="base")` + +```mermaid +classDiagram +class ModelScopeApplication { ++EVENTS ++data_model ++FRONTEND_DIR ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class ApplicationPageData { ++screen ++language ++theme ++userAgent +} +ModelScopeApplication --> ApplicationPageData : "Uses" +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) + +**Section Sources** + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) + +### Component: ModelScopeProChatbot + +- Import Path: `from modelscope_studio.components.pro import Chatbot` +- Purpose: Professional chatbot component supporting rich configurations including welcome messages, prompts, user/assistant messages, action buttons, file/tool/suggestion content, etc. +- Key Points: + - Supported events: `change`, `copy`, `edit`, `delete`, `like`, `retry`, `suggestion_select`, `welcome_prompt_select` + - Data model: `ChatbotDataMessages` (root is a message list) + - Preprocess/postprocess: Typed processing of message content (file to FileData, static resource path handling) + - Frontend directory: `resolve_frontend_dir("chatbot", type="pro")` + +```mermaid +classDiagram +class ModelScopeProChatbot { ++EVENTS ++data_model ++FRONTEND_DIR ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class ChatbotDataMessages { ++root +} +class ChatbotDataMessage { ++role ++status ++content ++meta +} +ModelScopeProChatbot --> ChatbotDataMessages : "Uses" +ChatbotDataMessages --> ChatbotDataMessage : "Contains" +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) + +**Section Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) + +## Dependency Analysis + +- Component classes generally inherit from `ModelScopeDataLayoutComponent` or `ModelScopeLayoutComponent`, unifying the frontend directory resolution and event binding mechanism. +- The event system is based on `gradio.events.EventListener`, injecting event binding flags into the internal update logic via callbacks. +- Data models mostly adopt `GradioRootModel`/`GradioModel` for consistent data structures and serialization between frontend and backend. + +```mermaid +graph LR +A["AntdButton"] --> B["ModelScopeLayoutComponent"] +C["AntdForm"] --> D["ModelScopeDataLayoutComponent"] +E["ModelScopeApplication"] --> D +F["ModelScopeProChatbot"] --> D +B --> G["resolve_frontend_dir(...)"] +D --> G +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antd/button/**init**.py:7-8](file://backend/modelscope_studio/components/antd/button/__init__.py#L7-L8) +- [backend/modelscope_studio/components/antd/form/**init**.py:8-9](file://backend/modelscope_studio/components/antd/form/__init__.py#L8-L9) +- [backend/modelscope_studio/components/base/application/**init**.py:8-9](file://backend/modelscope_studio/components/base/application/__init__.py#L8-L9) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:11](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L11) + +**Section Sources** + +- [backend/modelscope_studio/components/antd/button/**init**.py:7-8](file://backend/modelscope_studio/components/antd/button/__init__.py#L7-L8) +- [backend/modelscope_studio/components/antd/form/**init**.py:8-9](file://backend/modelscope_studio/components/antd/form/__init__.py#L8-L9) +- [backend/modelscope_studio/components/base/application/**init**.py:8-9](file://backend/modelscope_studio/components/base/application/__init__.py#L8-L9) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:11](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L11) + +## Performance Considerations + +- Keep component preprocess/postprocess lightweight; avoid heavy computations in the Python layer. +- For large file content (e.g., file messages in the chatbot), it is recommended to perform minimal wrapping during postprocessing (e.g., retaining only necessary metadata) to reduce transmission overhead. +- Set component height and scrolling behavior appropriately to avoid unnecessary reflow and repaints. + +## Troubleshooting Guide + +- Event Not Triggered + - Check that event listeners are correctly registered (e.g., Button's `click`, Form's `finish`), and confirm that the callback has injected the binding flag. + - Reference: [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46), [backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) +- Frontend Directory Resolution Failure + - Confirm that the path returned by `resolve_frontend_dir` exists and is accessible. + - Reference: [backend/modelscope_studio/components/antd/button/**init**.py:139](file://backend/modelscope_studio/components/antd/button/__init__.py#L139), [backend/modelscope_studio/components/antd/form/**init**.py:114](file://backend/modelscope_studio/components/antd/form/__init__.py#L114) +- Data Model Mismatch + - Use `data_model` for preprocess/postprocess to ensure the payload/value structure is consistent with the model. + - Reference: [backend/modelscope_studio/components/antd/form/**init**.py:13-14](file://backend/modelscope_studio/components/antd/form/__init__.py#L13-L14), [backend/modelscope_studio/components/pro/chatbot/**init**.py:388](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L388) + +**Section Sources** + +- [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) +- [backend/modelscope_studio/components/antd/form/**init**.py:13-14](file://backend/modelscope_studio/components/antd/form/__init__.py#L13-L14) +- [backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) +- [backend/modelscope_studio/components/antd/button/**init**.py:139](file://backend/modelscope_studio/components/antd/button/__init__.py#L139) +- [backend/modelscope_studio/components/antd/form/**init**.py:114](file://backend/modelscope_studio/components/antd/form/__init__.py#L114) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:388](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L388) + +## Conclusion + +ModelScope Studio's Python API, with its clear component family divisions and unified event/data model design, provides a complete component system from basic layout to professional domains. Through clearly defined import paths and named exports, developers can quickly locate and use the components they need; meanwhile, the event binding and data preprocess/postprocess mechanisms ensure consistency and extensibility of frontend-backend collaboration. + +## Appendix: API Index and Usage Examples + +### API Index (by Component Family) + +- `modelscope_studio.components.antd.*` + - Button: `from modelscope_studio.components.antd import Button` + - Form: `from modelscope_studio.components.antd import Form` + - Form.Item: `from modelscope_studio.components.antd import Form.Item` + - More components: See [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) + +- `modelscope_studio.components.antdx.*` + - Actions, Bubble, Conversations, Prompts, Sender, ThoughtChain, Welcome, etc. + - Import example: `from modelscope_studio.components.antdx import Bubble, Conversations` + - See [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) + +- `modelscope_studio.components.base.*` + - Application, Each, Filter, Fragment, Markdown, Slot, Text, Div, etc. + - Import example: `from modelscope_studio.components.base import Application` + - See [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +- `modelscope_studio.components.pro.*` + - Chatbot, MonacoEditor, MultimodalInput, WebSandbox, etc. + - Import example: `from modelscope_studio.components.pro import Chatbot` + - See [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) + +### Usage Examples (Path References) + +- Basic Button (AntdButton) + - Example path: [backend/modelscope_studio/components/antd/button/**init**.py:51-87](file://backend/modelscope_studio/components/antd/button/__init__.py#L51-L87) +- Form (AntdForm) and Form Item (AntdFormItem) + - Example path: [backend/modelscope_studio/components/antd/form/**init**.py:43-80](file://backend/modelscope_studio/components/antd/form/__init__.py#L43-L80) +- Application Container (ModelScopeApplication) + - Example path: [backend/modelscope_studio/components/base/application/**init**.py:59-71](file://backend/modelscope_studio/components/base/application/__init__.py#L59-L71) +- Chatbot (ModelScopeProChatbot) + - Example path: [backend/modelscope_studio/components/pro/chatbot/**init**.py:319-343](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L319-L343) + +### Lifecycle and Event Callbacks + +- AntdButton + - Events: `click` + - Slots: `icon`, `loading.icon` + - Reference: [backend/modelscope_studio/components/antd/button/**init**.py:41-49](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L49) +- AntdForm + - Events: `fields_change`, `finish`, `finish_failed`, `values_change` + - Data model: `AntdFormData` + - Reference: [backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) +- ModelScopeApplication + - Events: `custom`, `mount`, `resize`, `unmount` + - Data model: `ApplicationPageData` + - Reference: [backend/modelscope_studio/components/base/application/**init**.py:30-54](file://backend/modelscope_studio/components/base/application/__init__.py#L30-L54) +- ModelScopeProChatbot + - Events: `change`, `copy`, `edit`, `delete`, `like`, `retry`, `suggestion_select`, `welcome_prompt_select` + - Data model: `ChatbotDataMessages` + - Reference: [backend/modelscope_studio/components/pro/chatbot/**init**.py:289-314](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L289-L314) + +### Parameter Validation and Exception Handling + +- Parameter Validation + - Constructor parameters are mostly optional or have default values; type annotations cover common enums and dictionary structures. + - Reference: [backend/modelscope_studio/components/antd/button/**init**.py:51-87](file://backend/modelscope_studio/components/antd/button/__init__.py#L51-L87), [backend/modelscope_studio/components/antd/form/**init**.py:43-80](file://backend/modelscope_studio/components/antd/form/__init__.py#L43-L80) +- Exception Handling + - It is recommended to catch exceptions in event callbacks at the business layer and log the error context. + - When frontend directory resolution fails, check whether the path returned by `resolve_frontend_dir` exists. + +### Version Compatibility + +- Current version: 2.0.0 + - Reference: [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) diff --git a/.wiki/en/Ant Design Components/Ant Design Components.md b/.wiki/en/Ant Design Components/Ant Design Components.md new file mode 100644 index 00000000..4b73b6df --- /dev/null +++ b/.wiki/en/Ant Design Components/Ant Design Components.md @@ -0,0 +1,531 @@ +# Ant Design Components + + +**Files referenced in this document** +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [frontend/antdx/package.json](file://frontend/antdx/package.json) +- [docs/app.py](file://docs/app.py) +- [docs/helper/Docs.py](file://docs/helper/Docs.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [README-zh_CN.md](file://README-zh_CN.md) +- [.changeset/pink-sails-itch.md](file://.changeset/pink-sails-itch.md) +- [.changeset/eleven-aliens-sell.md](file://.changeset/eleven-aliens-sell.md) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py) +- [backend/modelscope_studio/components/antdx/folder/directory_icon/__init__.py](file://backend/modelscope_studio/components/antdx/folder/directory_icon/__init__.py) +- [backend/modelscope_studio/components/antdx/sender/header/__init__.py](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py) + + +## Update Summary + +**Changes made** + +- Updated version information reflecting major upgrades from Gradio 5.x to 6.0, Ant Design 5.x to 6.0, and Ant Design X 1.x to 2.0 +- Added complete feature introduction for Ant Design X component library, including new components like ThoughtChain, Folder, Sender, etc. +- Expanded component classification with new component groups and feature descriptions +- Updated architecture documentation to reflect the new component organization structure + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Ant Design X Component Library](#ant-design-x-component-library) +7. [Dependency Analysis](#dependency-analysis) +8. [Performance Considerations](#performance-considerations) +9. [Troubleshooting Guide](#troubleshooting-guide) +10. [Conclusion](#conclusion) +11. [Appendix](#appendix) + +## Introduction + +This document covers the Ant Design component library in ModelScope Studio, systematically organizing component classifications, features, and usage methods across six major categories: General Components, Layout Components, Navigation Components, Data Entry Components, Data Display Components, and Feedback Components. With the major upgrades to Gradio 6.0, Ant Design 6.0, and Ant Design X 2.0, the component library now supports richer interaction capabilities and a more modern design system. The documentation also provides property descriptions, event handling, style customization, responsive and internationalization support, performance optimization, and best practices, along with rich examples and scenario-based explanations to help developers get started quickly and achieve high-quality implementations. + +## Project Structure + +ModelScope Studio exports Ant Design components as a Python package and bridges them to Ant Design React components through frontend Svelte packages, forming a dual-layer architecture of "Python layer component definition + frontend rendering bridge". It now also integrates the Ant Design X component library, providing richer interactive components. The documentation site aggregates documentation and examples for each component through a unified entry point for easy browsing and comparison. + +```mermaid +graph TB +subgraph "Backend Python" +A["backend/modelscope_studio/components/antd/__init__.py
Export all Ant Design component classes"] +B["backend/modelscope_studio/components/antd/components.py
Centralized import and export"] +C["backend/modelscope_studio/components/antdx/__init__.py
Export all Ant Design X component classes"] +D["backend/modelscope_studio/components/antdx/components.py
Centralized import and export"] +E["backend/modelscope_studio/utils/dev/component.py
Component base class and context"] +end +subgraph "Frontend Svelte" +F["frontend/antd/package.json
Ant Design package metadata"] +G["frontend/antdx/package.json
Ant Design X package metadata"] +H["frontend/antd/button/Index.svelte
Button component bridge example"] +end +subgraph "Documentation and Site" +I["docs/app.py
Component classification and menu generation"] +J["docs/helper/Docs.py
Documentation parsing and example rendering"] +end +A --> H +C --> H +B --> H +D --> H +E --> A +F --> H +G --> H +I --> J +``` + +**Diagram Source** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-147](file://backend/modelscope_studio/components/antd/components.py#L1-L147) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [docs/app.py:19-438](file://docs/app.py#L19-L438) +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) + +**Section Source** + +- [docs/app.py:19-438](file://docs/app.py#L19-L438) +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-147](file://backend/modelscope_studio/components/antd/components.py#L1-L147) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +## Core Components + +- Component Export and Naming: The backend uniformly exports Ant Design component classes through **init**.py and components.py, now including Ant Design X components, facilitating on-demand import and batch usage. +- Component Base Classes: ModelScopeComponent/ModelScopeLayoutComponent/ModelScopeDataLayoutComponent provide unified visibility, element ID, class name, inline style, slot, and lifecycle behaviors. +- Frontend Bridge: Svelte components dynamically load Ant Design React components through importComponent, uniformly handling props, slots, and style injection. +- Version Upgrade: Upgraded from Gradio 5.x to 6.0, supporting a more powerful event system and component lifecycle management. + +**Section Source** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-147](file://backend/modelscope_studio/components/antd/components.py#L1-L147) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/utils/dev/component.py:54-169](file://backend/modelscope_studio/utils/dev/component.py#L54-L169) +- [frontend/antd/button/Index.svelte:10-74](file://frontend/antd/button/Index.svelte#L10-L74) + +## Architecture Overview + +The diagram below shows the key flow from Python component invocation to frontend rendering, and how the documentation site organizes and presents component examples. It now includes support for Ant Design X components. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Py as "Python Component Layer
antd/__init__.py + antdx/__init__.py" +participant Bridge as "Svelte Bridge Layer
Index.svelte" +participant Antd as "Ant Design React Component" +participant Antdx as "Ant Design X Component" +participant Docs as "Documentation Site
docs/app.py + Docs" +Dev->>Py : Import and instantiate component +Py->>Bridge : Pass component properties and slots +Bridge->>Bridge : processProps/className/id/style processing +Bridge->>Antd : Dynamically load and render Ant Design component +Bridge->>Antdx : Dynamically load and render Ant Design X component +Antd-->>Dev : Render result +Antdx-->>Dev : Render result +Docs->>Py : Aggregate component documentation and examples +Docs->>Bridge : Render examples and code blocks +``` + +**Diagram Source** + +- [docs/app.py:19-438](file://docs/app.py#L19-L438) +- [docs/helper/Docs.py:82-178](file://docs/helper/Docs.py#L82-L178) +- [frontend/antd/button/Index.svelte:24-74](file://frontend/antd/button/Index.svelte#L24-L74) + +## Component Details + +### General Components + +- Button: Supports link navigation, icons, sizes, and theme variants; controls target behavior through href_target; supports slots and style customization. +- FloatButton: Supports back-to-top, grouping, and icons; can combine multiple floating actions. +- Icon: Supports icon font providers; can be used with other components. +- Typography: Supports semantic typography elements like headings, text, paragraphs, and links. + +Usage Tips + +- Property Mapping: The frontend uniformly passes through visible, elem_id, elem_classes, elem_style, value, etc. through processProps. +- Slots: The Svelte side gets the default slot through getSlots for rendering child nodes. +- Example: The button component bridge example demonstrates dynamic loading and style concatenation. + +**Section Source** + +- [frontend/antd/button/Index.svelte:24-74](file://frontend/antd/button/Index.svelte#L24-L74) +- [docs/app.py:198-209](file://docs/app.py#L198-L209) + +### Layout Components + +- Divider: Supports horizontal/vertical and dashed styles. +- Flex: Provides flexible flex container capabilities. +- Grid: Row and Col support responsive breakpoints and gutters. +- Layout: Contains Header, Sider, Content, Footer subcomponents, suitable for building page skeletons. +- Space: Supports compact mode and wrapping child items. +- Splitter: Supports panels and drag splitting. +- Masonry: Supports responsive column count and automatic item height adjustment. + +Usage Tips + +- Responsive: Grid and Flex provide multi-breakpoint configurations for mobile and desktop adaptation. +- Styling: elem_style can be applied directly to containers for positioning, dimensions, and margin control. + +**Section Source** + +- [docs/app.py:216-233](file://docs/app.py#L216-L233) + +### Navigation Components + +- Anchor: Supports scroll positioning and anchor items. +- Breadcrumb: Supports custom separators and route items. +- Dropdown: Supports button dropdowns and menu items. +- Menu: Supports multi-level menus and selected state. +- Pagination: Supports page switching and sizes. +- Steps: Supports step status and descriptions. + +Usage Tips + +- Events: Navigation components typically trigger page transitions or content updates through callbacks or state changes. +- Internationalization: Language environment can be set uniformly through ConfigProvider (see "Internationalization Support"). + +**Section Source** + +- [docs/app.py:240-257](file://docs/app.py#L240-L257) + +### Data Entry Components + +- AutoComplete: Supports options and backfill. +- Cascader: Supports multi-level linkage and lazy loading. +- Checkbox: Supports groups and options. +- ColorPicker: Supports presets and formatting. +- DatePicker: Supports range selection and preset shortcuts. +- Form: Supports field validation rules, dynamic add/remove, and Provider. +- Input: Supports password, search, textarea, and OTP. +- InputNumber: Supports step and precision. +- Mentions: Supports keyword mentions and options. +- Radio: Supports buttons and groups. +- Rate: Supports readonly and half-star. +- Select: Supports multi-select and search. +- Slider: Supports marks and range. +- Switch: Supports disabled and loading. +- TimePicker: Supports range selection. +- Transfer: Supports source and target lists. +- TreeSelect: Supports directory tree and nodes. +- Upload: Supports drag and drop and custom requests. + +Usage Tips + +- Validation: FormItemRule provides validation rule definitions; dynamic forms support conditional rendering and field add/remove. +- Events: Common events like onChange/onFocus/onBlur can be used for linkage and state management. +- Styling: elem_style/elem_classes are used for fine-tuning appearance and layout. + +**Section Source** + +- [docs/app.py:264-317](file://docs/app.py#L264-L317) + +### Data Display Components + +- Avatar: Supports avatar groups and badges. +- Badge: Supports ribbons and badges. +- Calendar: Supports month view and event markers. +- Card: Supports grid and meta information. +- Carousel: Supports auto-play and indicators. +- Collapse: Supports accordion and panel items. +- Descriptions: Supports key-value pair display. +- Empty: Supports custom images and actions. +- Image: Supports preview groups and lazy loading. +- List: Supports items and meta information. +- Popover: Supports triggers and content. +- QRCode: Supports colors and sizes. +- Segmented: Supports options and disabled. +- Statistic: Supports countdown and timer. +- Table: Supports columns, expansion, selection, and sorting. +- Tabs: Supports tab items and types. +- Tag: Supports checkable tags. +- Timeline: Supports nodes and directions. +- Tooltip: Supports triggers and positions. +- Tour: Supports steps and highlights. +- Tree: Supports directory tree and nodes. + +Usage Tips + +- Table: Supports fixed columns, sorting, filtering, and pagination; can combine with Segmented for dimension switching. +- Image: ImagePreviewGroup provides multi-image preview capability. +- Interaction: Popover/Tooltip/Tour improve information density and guidance efficiency. + +**Section Source** + +- [docs/app.py:324-386](file://docs/app.py#L324-L386) + +### Feedback Components + +- Alert: Supports multiple types and closable. +- Drawer: Supports positions and nested content. +- Message: Supports global messages and duration. +- Modal: Supports static dialogs and mask layers. +- Notification: Supports multiple notifications and closable. +- Popconfirm: Supports confirm and cancel callbacks. +- Progress: Supports circle and percentage. +- Result: Supports success/error/waiting status pages. +- Skeleton: Supports avatar, button, input, and image. +- Spin: Supports fullscreen and inline. +- Watermark: Supports text and image watermarks. + +Usage Tips + +- Global Components: Message/Notification/Modal/Drawer are typically invoked through APIs rather than direct rendering. +- Animation and Transitions: Progress/Spin/Skeleton improve loading experience and placeholder effects. +- Accessibility: It is recommended to provide keyboard-accessible and screen-reader-friendly cues for interactive components. + +**Section Source** + +- [docs/app.py:393-425](file://docs/app.py#L393-L425) + +### Other Components + +- Affix: Supports pinning and offset. +- ConfigProvider: Provides theme, language, and global style overrides. + +Usage Tips + +- Internationalization: ConfigProvider supports locales injection for Chinese/English switching. +- Theme: Override global theme variables through ConfigProvider for consistent style. + +**Section Source** + +- [docs/app.py:432-437](file://docs/app.py#L432-L437) + +## Ant Design X Component Library + +### New Component Overview + +Ant Design X is an extension component library of Ant Design, providing richer interactive components and solutions for professional application scenarios. This upgrade includes the following main components: + +#### Thought Chain Component + +- ThoughtChain: Thought chain container component, supports multi-step thought process display +- ThoughtChainItem: Thought chain item component, supports state management, collapsible, and blinking effects +- Supports pending, success, error, abort states +- Configurable content, description, footer, icon, and title + +#### File Management Components + +- Folder: Folder component, supports directory tree and file management +- FolderDirectoryIcon: Directory icon component, supports different file type icon display +- FileCard: File card component, supports file list display +- FileCardList: File list component, supports file item management + +#### Conversation Interaction Components + +- Bubble: Message bubble component, supports user and system message display +- BubbleList: Message list component, supports message items and role management +- Conversations: Conversation component, supports history conversation management +- Sender: Sender component, supports message sending and header management +- SenderHeader: Sender header component, supports expand state control + +#### Content Display Components + +- CodeHighlighter: Code highlighting component, supports multiple programming language syntax highlighting +- Mermaid: Chart component, supports Mermaid syntax chart rendering +- Prompts: Prompt component, supports prompt management and display +- Sources: Source component, supports content source display +- Suggestion: Suggestion component, supports smart suggestion display + +#### Interaction Tool Components + +- Actions: Action component, supports multiple action buttons +- Attachments: Attachment component, supports file attachment management +- Notification: Notification component, supports system notification display +- Welcome: Welcome component, supports welcome page display +- XProvider: Provider component, supports context provision + +Usage Tips + +- Slot System: Most components support named slots like content, description, footer, icon, title, etc. +- Event System: Supports event listening like open_change +- State Management: Supports state properties like open, closable, collapsible, etc. +- Style Customization: Supports styles and class_names properties for style customization + +**Section Source** + +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:1-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L1-L81) +- [backend/modelscope_studio/components/antdx/folder/directory_icon/**init**.py:1-61](file://backend/modelscope_studio/components/antdx/folder/directory_icon/__init__.py#L1-L61) +- [backend/modelscope_studio/components/antdx/sender/header/**init**.py:1-74](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py#L1-L74) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## Dependency Analysis + +- Python Layer Export: **init**.py and components.py centrally export Ant Design and Ant Design X component classes for unified import. +- Frontend Bridge: Svelte components dynamically load Ant Design React and Ant Design X components through importComponent, with processProps uniformly handling properties and styles. +- Documentation Site: docs/app.py aggregates component documentation and examples, Docs.py parses Markdown and renders examples and code blocks. + +```mermaid +graph LR +PyInit["backend/.../antd/__init__.py"] --> PyComp["backend/.../antd/components.py"] +PyInitX["backend/.../antdx/__init__.py"] --> PyCompX["backend/.../antdx/components.py"] +PyComp --> SvelteBtn["frontend/antd/button/Index.svelte"] +PyCompX --> SvelteBtn +DocsApp["docs/app.py"] --> DocsHelper["docs/helper/Docs.py"] +DocsHelper --> SvelteBtn +``` + +**Diagram Source** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-147](file://backend/modelscope_studio/components/antd/components.py#L1-L147) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [frontend/antd/button/Index.svelte:10-74](file://frontend/antd/button/Index.svelte#L10-L74) +- [docs/app.py:19-438](file://docs/app.py#L19-L438) +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) + +**Section Source** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-147](file://backend/modelscope_studio/components/antd/components.py#L1-L147) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [frontend/antd/button/Index.svelte:10-74](file://frontend/antd/button/Index.svelte#L10-L74) +- [docs/app.py:19-438](file://docs/app.py#L19-L438) +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) + +## Performance Considerations + +- Dynamic Loading: The frontend implements on-demand loading through importComponent, reducing initial bundle size and first-screen blocking. +- Property Pass-through: processProps uniformly handles properties and styles, avoiding repeated calculations and redundant rendering. +- Tables and Lists: Use virtualization and pagination reasonably to avoid rendering large numbers of nodes at once. +- Images and Skeleton: Use Skeleton and Image.lazy to reduce resource pressure and blank screen time. +- Global Components: Message/Notification/Modal etc. should limit concurrent quantity to avoid lag caused by frequent popups. +- Styling: elem_style/elem_classes should be reused as much as possible to avoid excessive inline styles causing repaints. +- Component Lazy Loading: Ant Design X components support lazy loading to improve application startup performance. + +## Troubleshooting Guide + +- Blank page or component not displaying + - Confirm that Application and ConfigProvider are wrapped in the outer layer. + - Enable ssr_mode=False when starting in Hugging Face Space. + - Check dependency version compatibility of Ant Design X components. +- Abnormal component styles + - Use elem_style/elem_classes to adjust container styles; avoid conflicts with global styles. + - Check whether theme and font resources are correctly imported. + - Confirm that Ant Design X component style files are correctly loaded. +- Internationalization not taking effect + - Inject locales through ConfigProvider; ensure language keys match Ant Design language packs. +- Examples not running + - Confirm that component documentation paths and example files exist in docs/app.py; check Docs.py example module loading logic. + - Check whether import paths for new components are correct. +- Version compatibility issues + - Ensure Gradio, Ant Design, and Ant Design X versions match. + - Check whether component properties are compatible with new versions. + +**Section Source** + +- [README-zh_CN.md:32-32](file://README-zh_CN.md#L32-L32) +- [docs/app.py:577-595](file://docs/app.py#L577-L595) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) + +## Conclusion + +ModelScope Studio's Ant Design component library achieves seamless integration of Ant Design components in the Gradio ecosystem through a clear Python export layer and frontend bridge layer. With the major upgrades to Gradio 6.0, Ant Design 6.0, and Ant Design X 2.0, the component library now provides richer interaction capabilities and a more modern design system. With a unified base class system, slot mechanism, event system, and documentation site, developers can efficiently build beautiful and maintainable interfaces. It is recommended to combine responsive and internationalization strategies in actual projects, follow performance optimization and best practices to achieve a better user experience. + +## Appendix + +### Component Properties and Events Common Notes + +- Common Properties + - visible: Controls component visibility + - elem_id: Element ID + - elem_classes: Class name array or string + - elem_style: Inline style object + - value: Component value (if applicable) +- Events + - onChange/onFocus/onBlur: Common for input components + - onClick/onContextMenu: Common for button and interactive components + - onConfirm/onCancel: Common for confirmation components + - open_change: For state changes in expandable components +- Slots + - Default slot is used to render child nodes; some components support named slots like content, description, footer, icon, title, etc. + +**Section Source** + +- [backend/modelscope_studio/utils/dev/component.py:54-169](file://backend/modelscope_studio/utils/dev/component.py#L54-L169) +- [frontend/antd/button/Index.svelte:24-74](file://frontend/antd/button/Index.svelte#L24-L74) + +### Responsive Design and Internationalization Support + +- Responsive + - Grid and Flex provide multi-breakpoint configurations; it is recommended to set breakpoints and spacing separately for mobile and desktop. +- Internationalization + - Inject locales through ConfigProvider to achieve Chinese/English switching; note the correspondence between language packs and component text. + +**Section Source** + +- [docs/app.py:435-437](file://docs/app.py#L435-L437) + +### Code Examples and Scenario-based Applications + +- Example Organization + - The documentation site automatically scans the demos directory through Docs.py, rendering examples and code blocks; supports collapsible display and title annotation. +- Scenario Suggestions + - Forms: Use Form + FormItem + validation rules, combined with dynamic forms for conditional rendering. + - Data Tables: Combine Pagination and virtual scrolling to improve interaction smoothness with large data volumes. + - Navigation: Use Menu + Breadcrumb + Steps to build clear hierarchy and process guidance. + - Feedback: Use Message/Notification/Modal/Drawer to provide timely user feedback and operation confirmation. + - Thought Chain: Use ThoughtChain + ThoughtChainItem to build AI application thought process display. + - File Management: Use Folder + FileCard + Attachments to implement file management system. + +**Section Source** + +- [docs/helper/Docs.py:82-178](file://docs/helper/Docs.py#L82-L178) +- [docs/app.py:19-438](file://docs/app.py#L19-L438) + +### Parameter Mapping Supplementary Notes + +- Collapse Component Properties + - active_key: Currently expanded panel key + - default_active_key: Default expanded panel key + - accordion: Accordion mode + - bordered: Whether to have border + - collapsible: Collapsible trigger area + - destroy_inactive_panel: Destroy collapsed hidden panels + - expand_icon: Custom expand icon + - expand_icon_placement: Expand icon position, options are `start` or `end` + - ghost: Transparent borderless + - size: Size + +### Version Upgrade Notes + +- Gradio 6.0 Upgrade + - Supports new event system and component lifecycle management + - Improved component state management and data flow +- Ant Design 6.0 Upgrade + - More modern design system and visual specifications + - Enhanced accessibility support + - Improved theme customization capabilities +- Ant Design X 2.0 Upgrade + - Added rich interactive components + - Improved component API and slot system + - Enhanced TypeScript type support + +**Section Source** + +- [.changeset/pink-sails-itch.md:12-12](file://.changeset/pink-sails-itch.md#L12-L12) +- [.changeset/eleven-aliens-sell.md:12-12](file://.changeset/eleven-aliens-sell.md#L12-L12) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) diff --git a/.wiki/en/Ant Design Components/Components Overview.md b/.wiki/en/Ant Design Components/Components Overview.md new file mode 100644 index 00000000..1886a7a4 --- /dev/null +++ b/.wiki/en/Ant Design Components/Components Overview.md @@ -0,0 +1,384 @@ +# Components Overview + + +**Files referenced in this document** +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [docs/components/antd/overview/README.md](file://docs/components/antd/overview/README.md) +- [docs/README.md](file://docs/README.md) +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/components/pro/__init__.py](file://backend/modelscope_studio/components/pro/__init__.py) +- [docs/app.py](file://docs/app.py) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) +- [docs/components/antd/button/demos/basic.py](file://docs/components/antd/button/demos/basic.py) +- [docs/components/antd/form/demos/basic.py](file://docs/components/antd/form/demos/basic.py) +- [docs/components/antd/layout/demos/basic.py](file://docs/components/antd/layout/demos/basic.py) +- [frontend/svelte-preprocess-react/svelte-contexts/slot.svelte.ts](file://frontend/svelte-preprocess-react/svelte-contexts/slot.svelte.ts) +- [frontend/svelte-preprocess-react/component/import.ts](file://frontend/svelte-preprocess-react/component/import.ts) +- [frontend/svelte-preprocess-react/component/props.svelte.ts](file://frontend/svelte-preprocess-react/component/props.svelte.ts) +- [docs/components/base/fragment/README-zh_CN.md](file://docs/components/base/fragment/README-zh_CN.md) +- [CHANGELOG.md](file://CHANGELOG.md) +- [pnpm-lock.yaml](file://pnpm-lock.yaml) +- [package.json](file://package.json) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) + + +## Update Summary + +**Changes made** + +- Updated version information to reflect the upgrade from Ant Design 5.x to 6.3.5 +- Updated migration information from Gradio 5.x to 6.0 +- Updated component version compatibility notes +- Updated version-related information for theme customization and internationalization mechanisms + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Classification and Organization](#component-classification-and-organization) +6. [Usage Principles and Best Practices](#usage-principles-and-best-practices) +7. [Responsive Design and Internationalization](#responsive-design-and-internationalization) +8. [Theme Customization and Style System](#theme-customization-and-style-system) +9. [Typical Scenarios and Combined Usage](#typical-scenarios-and-combined-usage) +10. [Component Dependencies and Integration Patterns](#component-dependencies-and-integration-patterns) +11. [Performance Considerations](#performance-considerations) +12. [Troubleshooting Guide](#troubleshooting-guide) +13. [Conclusion](#conclusion) + +## Introduction + +This overview covers the overall presentation of the Ant Design component library in modelscope_studio, including features, design philosophy, overall architecture, component classification system, usage principles, responsive design and internationalization, theme customization, typical scenarios and combination methods, and inter-component dependencies and integration patterns. The component library is built on Gradio 6.0, providing richer page layouts and interaction capabilities, and adapts to Ant Design 6.3.5 styles and behaviors through a unified configuration container. + +**Update** The project has been upgraded from Gradio 5.x to 6.0, and Ant Design from 5.x to 6.3.5, bringing better performance and compatibility. + +**Version**: This document applies to ModelScope Studio 2.0+, supporting Gradio 6.0, Ant Design 6.3.5, and Ant Design X 2.0 + +## Project Structure + +- Backend Module Export: The Python layer exports all Ant Design components through module aggregation, facilitating direct on-demand import and usage. +- Frontend Implementation: Each Ant Design component is implemented in Svelte/React form, with typed properties and slot mechanism, achieving bridge with Gradio 6.0. +- Documentation and Examples: Accompanying documentation and demo scripts covering quick start, property constraints, event binding, slot rendering, function parameter passing, internationalization, and theme customization topics. + +```mermaid +graph TB +subgraph "Backend" +PY_INIT["backend/modelscope_studio/components/antd/__init__.py"] +PY_COMP["backend/modelscope_studio/components/antd/components.py"] +BASE_INIT["backend/modelscope_studio/components/base/__init__.py"] +PRO_INIT["backend/modelscope_studio/components/pro/__init__.py"] +VERSION["backend/modelscope_studio/version.py"] +end +subgraph "Frontend" +PKG["frontend/antd/package.json"] +CFG_TSX["frontend/antd/config-provider/config-provider.tsx"] +LOCALES["frontend/antd/config-provider/locales.ts"] +BUTTON_PKG["frontend/antd/button/package.json"] +FORM_PKG["frontend/antd/form/package.json"] +end +subgraph "Documentation and Examples" +OVERVIEW["docs/components/antd/overview/README.md"] +APP_PY["docs/app.py"] +DEMO_BTN["docs/components/antd/button/demos/basic.py"] +DEMO_FORM["docs/components/antd/form/demos/basic.py"] +DEMO_LAYOUT["docs/components/antd/layout/demos/basic.py"] +end +PY_INIT --> PY_COMP +PY_COMP --> PKG +PKG --> CFG_TSX +CFG_TSX --> LOCALES +PY_INIT --> OVERVIEW +APP_PY --> OVERVIEW +DEMO_BTN --> OVERVIEW +DEMO_FORM --> OVERVIEW +DEMO_LAYOUT --> OVERVIEW +BASE_INIT --> OVERVIEW +PRO_INIT --> OVERVIEW +VERSION --> OVERVIEW +BUTTON_PKG --> CFG_TSX +FORM_PKG --> CFG_TSX +``` + +**Diagram Source** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:313-465](file://frontend/antd/config-provider/locales.ts#L313-L465) +- [docs/components/antd/overview/README.md:1-75](file://docs/components/antd/overview/README.md#L1-L75) +- [docs/app.py:200-399](file://docs/app.py#L200-L399) +- [docs/components/antd/button/demos/basic.py:1-26](file://docs/components/antd/button/demos/basic.py#L1-L26) +- [docs/components/antd/form/demos/basic.py:1-94](file://docs/components/antd/form/demos/basic.py#L1-L94) +- [docs/components/antd/layout/demos/basic.py:1-88](file://docs/components/antd/layout/demos/basic.py#L1-L88) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/antd/button/package.json:1-15](file://frontend/antd/button/package.json#L1-L15) +- [frontend/antd/form/package.json:1-15](file://frontend/antd/form/package.json#L1-L15) + +**Section Source** + +- [docs/README.md:19-75](file://docs/README.md#L19-L75) +- [docs/components/antd/overview/README.md:1-75](file://docs/components/antd/overview/README.md#L1-L75) +- [docs/app.py:200-399](file://docs/app.py#L200-L399) +- [CHANGELOG.md:13](file://CHANGELOG.md#L13) + +## Core Components + +- Component Export: The backend exports all Ant Design components through module aggregation, forming a unified namespace for direct import and usage. +- Configuration Container: ConfigProvider provides global configuration for theme, language, popup container, etc., compatible with Ant Design 6.3.5 and injecting Gradio 6.0 style adaptation. +- Base Components: Application, AutoLoading, Fragment, and other base capabilities ensure correct component tree rendering and loading state feedback. +- Pro Components: Extended components for advanced scenarios (such as chatbot, editor, Web Sandbox, etc.). + +**Update** All components are now compatible with Ant Design 6.3.5 and Gradio 6.0 new features. + +**Section Source** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [pnpm-lock.yaml:2830](file://pnpm-lock.yaml#L2830-L2835) + +## Architecture Overview + +The overall architecture revolves around the closed loop of "backend component export + frontend bridge rendering + documentation and examples". The backend is responsible for component classes and property mapping, the frontend is responsible for converting properties and slots to React/JSX rendering, and injecting themes and internationalization through ConfigProvider; documentation and examples provide usage patterns and constraint explanations. + +**Update** The architecture is now fully adapted to Gradio 6.0's new event system and component lifecycle. + +```mermaid +graph TB +A["Backend Component Export
backend/modelscope_studio/components/antd/__init__.py"] --> B["Frontend Bridge Component
frontend/antd/*/*.tsx"] +B --> C["Configuration Container
frontend/antd/config-provider/config-provider.tsx"] +C --> D["Internationalization and Locale
frontend/antd/config-provider/locales.ts"] +E["Base Components
backend/modelscope_studio/components/base/__init__.py"] --> A +F["Pro Extension Components
backend/modelscope_studio/components/pro/__init__.py"] --> A +G["Documentation and Examples
docs/components/antd/*/demos/*.py"] --> A +G --> B +G --> C +H["Version Management
backend/modelscope_studio/version.py"] --> A +I["Dependency Lock
pnpm-lock.yaml"] --> B +``` + +**Diagram Source** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:313-465](file://frontend/antd/config-provider/locales.ts#L313-L465) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [docs/components/antd/button/demos/basic.py:1-26](file://docs/components/antd/button/demos/basic.py#L1-L26) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [pnpm-lock.yaml:2830](file://pnpm-lock.yaml#L2830-L2835) + +## Component Classification and Organization + +According to the navigation structure in the documentation, Ant Design components are divided into six major categories for easy retrieval and usage by functional domain: + +- General Components + - Includes: Button, Icon, Typography, etc. + - Examples: Button, Icon, Typography +- Layout Components + - Includes: Divider, Flex, Grid, Layout, Space, Splitter, etc. + - Examples: Grid, Flex, Splitter, Page Layout +- Navigation Components + - Includes: Anchor, Breadcrumb, Dropdown, Menu, Pagination, Steps, etc. + - Examples: Anchor, Breadcrumb, Dropdown, Navigation Menu, Pagination, Steps +- Data Entry Components + - Includes: AutoComplete, Cascader, Checkbox, ColorPicker, DatePicker, Form, Input, InputNumber, Mentions, Radio, Rate, Select, Slider, Switch, TimePicker, Transfer, TreeSelect, Upload, etc. + - Examples: Form, Input, Select, Time/Date, Switch, Slider, Upload +- Data Display Components + - Includes: Avatar, Badge, Calendar, Card, Carousel, Collapse, Descriptions, Empty, Image, List, Popover, QRCode, Segmented, Statistic, Table, Tabs, Tag, Timeline, Tooltip, Tour, Tree, etc. + - Examples: Card, Table, Tag, Timeline, Tree, Statistic +- Feedback Components + - Includes: Alert, Drawer, Message, Modal, Notification, etc. + - Examples: Alert, Drawer, Message, Modal, Notification + +**Update** All components have been adapted to Ant Design 6.3.5's new API and style specifications. + +The above classification and examples are from the documentation's navigation and example scripts, making it easy for developers to quickly locate components and reference usage. + +**Section Source** + +- [docs/app.py:200-399](file://docs/app.py#L200-L399) +- [docs/components/antd/button/demos/basic.py:1-26](file://docs/components/antd/button/demos/basic.py#L1-L26) +- [docs/components/antd/form/demos/basic.py:1-94](file://docs/components/antd/form/demos/basic.py#L1-L94) +- [docs/components/antd/layout/demos/basic.py:1-88](file://docs/components/antd/layout/demos/basic.py#L1-L88) + +## Usage Principles and Best Practices + +- Unified Entry: Import all components through the antd module to avoid scattered imports. +- Wrapper Container: All antd components must be placed between Application and ConfigProvider to ensure dependencies and styles work properly. +- Loading State Feedback: It is recommended to use AutoLoading to automatically display loading animations during requests to improve user experience. +- Event Binding: Events use Gradio 6.0's event binding form, with parameters stored in specific fields as arrays, note the destructure and handling. +- Slot Mechanism: Python cannot directly pass components as parameters; use Slot to wrap modules; if only strings or numbers, they can be passed directly as properties. +- Function Parameter Passing: Pass JS functions as strings, the frontend will automatically compile them into functions; functions returning ReactNode can be handled in two ways: rendered as regular nodes or generated through the global React object. +- Slot Compatibility: Some component slots only support modelscope_studio components; if you need to insert other Gradio components, wrap them with Fragment. + +**Update** The event system is fully adapted to Gradio 6.0's new event model, and the slot mechanism has been optimized accordingly. + +**Section Source** + +- [docs/components/antd/overview/README.md:13-75](file://docs/components/antd/overview/README.md#L13-L75) +- [docs/components/base/fragment/README-zh_CN.md:1-10](file://docs/components/base/fragment/README-zh_CN.md#L1-L10) + +## Responsive Design and Internationalization + +- Responsive Design: Components follow Ant Design 6.3.5's responsive specifications, combining Flex, Grid, and other layout components to achieve adaptive layouts. +- Internationalization: ConfigProvider supports multi-language switching, with built-in extensive language and region mapping, automatically loading corresponding language packs and date library languages to meet multi-language site requirements. + +```mermaid +sequenceDiagram +participant U as "User" +participant CFG as "ConfigProvider" +participant L as "locales.ts" +participant D as "dayjs" +U->>CFG : Set language identifier +CFG->>L : Parse language identifier and load corresponding language pack +L-->>CFG : Return Antd 6.3.5 language pack and dayjs language +CFG->>D : Set dayjs language +CFG-->>U : Apply language configuration +``` + +**Diagram Source** + +- [frontend/antd/config-provider/config-provider.tsx:85-105](file://frontend/antd/config-provider/config-provider.tsx#L85-L105) +- [frontend/antd/config-provider/locales.ts:313-465](file://frontend/antd/config-provider/locales.ts#L313-L465) + +**Section Source** + +- [frontend/antd/config-provider/config-provider.tsx:15-27](file://frontend/antd/config-provider/config-provider.tsx#L15-L27) +- [frontend/antd/config-provider/locales.ts:313-465](file://frontend/antd/config-provider/locales.ts#L313-L465) + +## Theme Customization and Style System + +- Theme Mode: Control dark/compact algorithms through ConfigProvider's themeMode, supporting dynamic switching. +- Theme Tokens: Support setting primary color and other tokens, combining with algorithms to achieve unified theme style. +- Style Injection: Use style provider to ensure component prefix and style isolation, avoiding conflicts. + +```mermaid +flowchart TD +Start(["Enter ConfigProvider"]) --> Parse["Parse themeMode and algorithm"] +Parse --> Merge["Merge algorithm and theme tokens"] +Merge --> Apply["Apply to Ant Design 6.3.5 theme"] +Apply --> Inject["Inject style provider"] +Inject --> End(["Complete theme rendering"]) +``` + +**Diagram Source** + +- [frontend/antd/config-provider/config-provider.tsx:88-143](file://frontend/antd/config-provider/config-provider.tsx#L88-L143) + +**Section Source** + +- [frontend/antd/config-provider/config-provider.tsx:53-151](file://frontend/antd/config-provider/config-provider.tsx#L53-L151) + +## Typical Scenarios and Combined Usage + +- Quick Start: Under Application and ConfigProvider wrapper, use Button, Icon, Typography, and other general components to build basic interfaces. +- Form Scenarios: Use Form and Form.Item combined with Input, Select, DatePicker, Upload, and other data entry components, combined with validation rules and submit callbacks. +- Page Layout: Use Layout, Grid, Flex, Space, and other layout components to build page skeletons, combined with Sider, Header, Content, Footer to achieve complex page structures. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant App as "Application" +participant Cfg as "ConfigProvider" +participant Btn as "Button" +participant Form as "Form" +participant Lay as "Layout" +Dev->>App : Create application context +App->>Cfg : Inject global configuration (theme/language) +Cfg->>Btn : Render button component +Cfg->>Form : Render form component +Cfg->>Lay : Render layout component +Btn-->>Dev : Trigger events and interactions +Form-->>Dev : Collect data and validate +Lay-->>Dev : Layout structure output +``` + +**Diagram Source** + +- [docs/components/antd/button/demos/basic.py:5-26](file://docs/components/antd/button/demos/basic.py#L5-L26) +- [docs/components/antd/form/demos/basic.py:16-94](file://docs/components/antd/form/demos/basic.py#L16-L94) +- [docs/components/antd/layout/demos/basic.py:42-88](file://docs/components/antd/layout/demos/basic.py#L42-L88) + +**Section Source** + +- [docs/components/antd/button/demos/basic.py:1-26](file://docs/components/antd/button/demos/basic.py#L1-L26) +- [docs/components/antd/form/demos/basic.py:1-94](file://docs/components/antd/form/demos/basic.py#L1-L94) +- [docs/components/antd/layout/demos/basic.py:1-88](file://docs/components/antd/layout/demos/basic.py#L1-L88) + +## Component Dependencies and Integration Patterns + +- Component Dependencies: Each component is exposed through backend export modules, with frontend managing versions and types as independent packages. +- Slots and Context: The frontend supports complex nesting and dynamic rendering through slot context and parameter mapping mechanisms. +- Initialization Flow: Before component loading, wait for initialization to complete to ensure global objects are available. +- Event and Property Mapping: The frontend uniformly maps properties and events to ensure consistency with Gradio 6.0's event model. + +**Update** Dependency relationships have been updated to reflect new version requirements for Gradio 6.0 and Ant Design 6.3.5. + +```mermaid +graph LR +PY["Backend Export Module"] --> FE["Frontend Component Implementation"] +FE --> CTX["Slot Context and Parameter Mapping"] +FE --> INIT["Initialization Flow"] +FE --> EVT["Event and Property Mapping"] +CTX --> REN["Render Pipeline"] +INIT --> REN +EVT --> REN +SUB["Sub-package Management"] --> FE +LOCK["Dependency Lock"] --> FE +``` + +**Diagram Source** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [frontend/svelte-preprocess-react/svelte-contexts/slot.svelte.ts:55-102](file://frontend/svelte-preprocess-react/svelte-contexts/slot.svelte.ts#L55-L102) +- [frontend/svelte-preprocess-react/component/import.ts:1-20](file://frontend/svelte-preprocess-react/component/import.ts#L1-L20) +- [frontend/svelte-preprocess-react/component/props.svelte.ts:258-312](file://frontend/svelte-preprocess-react/component/props.svelte.ts#L258-L312) +- [frontend/antd/button/package.json:1-15](file://frontend/antd/button/package.json#L1-L15) +- [pnpm-lock.yaml:2830](file://pnpm-lock.yaml#L2830-L2835) + +**Section Source** + +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/svelte-preprocess-react/svelte-contexts/slot.svelte.ts:55-102](file://frontend/svelte-preprocess-react/svelte-contexts/slot.svelte.ts#L55-L102) +- [frontend/svelte-preprocess-react/component/import.ts:1-20](file://frontend/svelte-preprocess-react/component/import.ts#L1-L20) +- [frontend/svelte-preprocess-react/component/props.svelte.ts:258-312](file://frontend/svelte-preprocess-react/component/props.svelte.ts#L258-L312) + +## Performance Considerations + +- On-demand Rendering: Reduce unnecessary component instantiation through slots and conditional rendering. +- Theme and Internationalization Lazy Loading: Language packs and theme algorithms are loaded on-demand, reducing initial overhead. +- Event and Property Mapping: Unified mapping reduces repeated calculations and DOM operations. +- Layout Component Optimization: Prefer modern layouts like Flex and Grid to reduce reflow and repaint. + +**Update** Performance optimization has been adjusted for Gradio 6.0's new architecture, providing better rendering performance. + +[This section is general guidance, no specific file references needed] + +## Troubleshooting Guide + +- Page preview unsuccessful: Confirm all components are wrapped in Application. +- Abnormal styles: Confirm ConfigProvider is correctly wrapped, and themeMode, locale settings are as expected. +- Events not responding: Check whether event binding uses Gradio 6.0 form, and whether parameters are correctly destructured. +- Slots not working: Confirm using Slot to wrap modules, or directly passing strings/numbers; if you need to insert other Gradio components, wrap with Fragment. +- Function parameter issues: Pass functions as strings, the frontend will automatically compile; functions returning ReactNode can choose slots or generate through global React object. + +**Update** Troubleshooting guide has been updated to reflect Gradio 6.0's new event system and component lifecycle changes. + +**Section Source** + +- [docs/components/antd/overview/README.md:13-75](file://docs/components/antd/overview/README.md#L13-L75) +- [docs/components/base/fragment/README-zh_CN.md:1-10](file://docs/components/base/fragment/README-zh_CN.md#L1-L10) + +## Conclusion + +modelscope_studio deeply integrates Ant Design 6.3.5 components with the Gradio 6.0 ecosystem, providing unified component export, configuration container, and documentation examples to help developers quickly build beautiful and maintainable interfaces. Through clear classification system, strict usage principles, and complete internationalization, theme, and slot mechanisms, the component library achieves a good balance between usability and extensibility. It is recommended to follow the "Application + ConfigProvider" wrapper principle in actual projects, make good use of slots and event mapping, and combine with layout components to achieve responsive and accessibility-friendly interfaces. + +**Update** The version upgrade brings better performance, more stable event system, and more modern theme support, providing developers with a better development experience. diff --git a/.wiki/en/Ant Design Components/Data Display Components/Avatar and Badge.md b/.wiki/en/Ant Design Components/Data Display Components/Avatar and Badge.md new file mode 100644 index 00000000..183344fe --- /dev/null +++ b/.wiki/en/Ant Design Components/Data Display Components/Avatar and Badge.md @@ -0,0 +1,328 @@ +# Avatar and Badge + + +**Files referenced in this document** +- [avatar.tsx](file://frontend/antd/avatar/avatar.tsx) +- [avatar group entry Index.svelte](file://frontend/antd/avatar/group/Index.svelte) +- [avatar.group.tsx](file://frontend/antd/avatar/group/avatar.group.tsx) +- [avatar.group.less](file://frontend/antd/avatar/group/avatar.group.less) +- [badge.tsx](file://frontend/antd/badge/badge.tsx) +- [badge ribbon entry Index.svelte](file://frontend/antd/badge/ribbon/Index.svelte) +- [ribbon.badge.tsx](file://frontend/antd/badge/ribbon/badge.ribbon.tsx) +- [avatar docs README.md](file://docs/components/antd/avatar/README.md) +- [badge docs README.md](file://docs/components/antd/badge/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document focuses on the Avatar and Badge component families, systematically covering size control, shape settings, Avatar.Group stacking and masking, Badge count display and dot marking, Badge.Ribbon ribbon effects, and other capabilities. It also provides placeholder handling, threshold settings, custom style solutions, as well as responsive and multi-layout adaptation recommendations. The document is based on actual implementations in the repository, with visual diagrams to help readers quickly understand and correctly use the components. + +## Project Structure + +- Avatar components are located in frontend/antd/avatar, containing two sub-modules: single avatar and avatar group. The avatar group dynamically imports its internal implementation via a composite Svelte entry file. +- Badge components are located in frontend/antd/badge, containing two sub-modules: basic badge and ribbon badge. The ribbon badge is also dynamically imported via a composite Svelte entry file. +- Documentation examples are in docs/components/antd/avatar and docs/components/antd/badge, providing demo entries for basic and combined usage. + +```mermaid +graph TB +subgraph "Avatar Components" +AV["avatar.tsx"] +AGI["avatar/group/Index.svelte"] +AGC["avatar/group/avatar.group.tsx"] +AGL["avatar/group/avatar.group.less"] +end +subgraph "Badge Components" +BD["badge.tsx"] +RBDI["badge/ribbon/Index.svelte"] +RBD["badge/ribbon/badge.ribbon.tsx"] +end +AV --> |"Wrap Ant Design"| AV +AGI --> |"Dynamic import"| AGC +AGC --> |"Render"| AV +AGC --> |"Styles"| AGL +BD --> |"Wrap Ant Design"| BD +RBDI --> |"Dynamic import"| RBD +RBD --> |"Wrap content"| RBD +``` + +**Diagram Source** + +- [avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [avatar group entry Index.svelte:1-62](file://frontend/antd/avatar/group/Index.svelte#L1-L62) +- [avatar.group.tsx:1-52](file://frontend/antd/avatar/group/avatar.group.tsx#L1-L52) +- [avatar.group.less:1-12](file://frontend/antd/avatar/group/avatar.group.less#L1-L12) +- [badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) +- [badge ribbon entry Index.svelte:1-62](file://frontend/antd/badge/ribbon/Index.svelte#L1-L62) +- [ribbon.badge.tsx:1-22](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L1-L22) + +**Section Source** + +- [avatar docs README.md:1-9](file://docs/components/antd/avatar/README.md#L1-L9) +- [badge docs README.md:1-9](file://docs/components/antd/badge/README.md#L1-L9) + +## Core Components + +- Avatar + - Supports icon, image and character display, with size and shape configuration; supports dynamic injection of icon and src via slot mechanism. + - Provides placeholder handling: when no icon or image is provided, child nodes can serve as fallback content. +- Avatar.Group + - Implements avatar stacking and masking effects; supports maximum count threshold and popup tooltip; controls overlap spacing via less variables. + - Supports slot-based customization of the popup layer title and content for "overflowed count". +- Badge + - Supports numeric count and text marking; both count and text can inject custom content via slots. + - Supports dot marking and overflow threshold (shows n+ when exceeding the threshold). +- Badge.Ribbon + - Overlays a "ribbon"-style badge on a target element, supporting text slots; typically used to emphasize status or identify features. + +**Section Source** + +- [avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [avatar.group.tsx:1-52](file://frontend/antd/avatar/group/avatar.group.tsx#L1-L52) +- [avatar.group.less:1-12](file://frontend/antd/avatar/group/avatar.group.less#L1-L12) +- [badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) +- [ribbon.badge.tsx:1-22](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L1-L22) + +## Architecture Overview + +The diagram below shows the call chain from the Svelte entry to specific Ant Design components, as well as key paths for slot and property forwarding. + +```mermaid +sequenceDiagram +participant U as "User Code" +participant S as "Svelte Composite Entry (Index)" +participant C as "Internal Component (tsx)" +participant A as "Ant Design Component" +U->>S : Pass properties and slots +S->>C : Dynamically import and forward properties/slots +C->>A : Forward properties/slots +A-->>U : Render result +``` + +**Diagram Source** + +- [avatar group entry Index.svelte:48-61](file://frontend/antd/avatar/group/Index.svelte#L48-L61) +- [avatar.group.tsx:12-49](file://frontend/antd/avatar/group/avatar.group.tsx#L12-L49) +- [badge ribbon entry Index.svelte:48-61](file://frontend/antd/badge/ribbon/Index.svelte#L48-L61) +- [ribbon.badge.tsx:6-18](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L6-L18) + +## Detailed Component Analysis + +### Avatar + +- Wrapping approach + - Uses sveltify to wrap Ant Design's Avatar as a Svelte component, while preserving slot capabilities for icon and src. + - When slots exist, slot content takes priority; otherwise falls back to property values; child nodes serve as default content when no slots are provided. +- Placeholder handling + - Through hidden containers and conditional rendering, ensures child nodes can still be rendered as placeholder content when no icon or image is provided. +- Shape and size + - Shape (e.g., circle/square) and size (e.g., small/medium/large) are controlled via Ant Design native properties, following Antd specifications. + +```mermaid +flowchart TD +Start(["Enter Avatar render"]) --> CheckIconSrc["Check if icon or src slot exists"] +CheckIconSrc --> HasSlot{"Slot exists?"} +HasSlot --> |Yes| UseSlot["Use slot content as icon/image"] +HasSlot --> |No| UseProp["Use property value as icon/image"] +UseSlot --> Render["Render Ant Design Avatar"] +UseProp --> Render +Render --> End(["Done"]) +``` + +**Diagram Source** + +- [avatar.tsx:6-25](file://frontend/antd/avatar/avatar.tsx#L6-L25) + +**Section Source** + +- [avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) + +### Avatar.Group + +- Stacking and masking + - Internally uses Ant Design's Group capability for avatar stacking; controls the starting margin of adjacent avatars via less variables to create visual overlap and layering. +- Threshold and popup layer + - Supports setting max.count as the threshold; when exceeded, shows hints like "n more". + - The popup layer title and content can be overridden via slots; if no slots are provided, falls back to property configuration. +- Sub-item rendering + - Maps child items to ReactSlot via useTargets and ReactSlot, ensuring each child avatar renders in order. + +```mermaid +flowchart TD +Enter(["Enter Avatar.Group"]) --> ComputeMax["Calculate max config
including count and popover"] +ComputeMax --> OverLimit{"Exceeds threshold?"} +OverLimit --> |Yes| Popover["Show popup layer (title/content can use slots)"] +OverLimit --> |No| RenderList["Render child avatars one by one"] +Popover --> RenderList +RenderList --> Exit(["Done"]) +``` + +**Diagram Source** + +- [avatar.group.tsx:12-49](file://frontend/antd/avatar/group/avatar.group.tsx#L12-L49) +- [avatar.group.less:1-12](file://frontend/antd/avatar/group/avatar.group.less#L1-L12) + +**Section Source** + +- [avatar group entry Index.svelte:1-62](file://frontend/antd/avatar/group/Index.svelte#L1-L62) +- [avatar.group.tsx:1-52](file://frontend/antd/avatar/group/avatar.group.tsx#L1-L52) +- [avatar.group.less:1-12](file://frontend/antd/avatar/group/avatar.group.less#L1-L12) + +### Badge + +- Count and text + - Both count and text support slot injection, enabling placement of complex content (such as icons, custom text) inside the badge. +- Dot marking + - Implements dot marking via Ant Design native capability; displays a pure dot when count is 0 and numbers are not shown. +- Threshold setting + - Supports setting a maximum value; displays n+ when exceeding the threshold. This capability is provided by the underlying Antd component and the component layer directly forwards the property. + +```mermaid +flowchart TD +Start(["Enter Badge render"]) --> CheckCountText["Check count and text slots"] +CheckCountText --> HasCount{"count has slot?"} +HasCount --> |Yes| UseCountSlot["Use slot count"] +HasCount --> |No| UseCountProp["Use property count"] +CheckCountText --> HasText{"text has slot?"} +HasText --> |Yes| UseTextSlot["Use slot text"] +HasText --> |No| UseTextProp["Use property text"] +UseCountSlot --> Render["Render Ant Design Badge"] +UseCountProp --> Render +UseTextSlot --> Render +UseTextProp --> Render +Render --> End(["Done"]) +``` + +**Diagram Source** + +- [badge.tsx:6-17](file://frontend/antd/badge/badge.tsx#L6-L17) + +**Section Source** + +- [badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) + +### Badge.Ribbon + +- Special effect + - Ribbon draws a "ribbon"-style badge on the parent container, commonly used to highlight status or mark new features; text content can be customized via slots. +- Use cases + - Suitable for adding prominent markings on cards, buttons, list items, and other containers; be careful to avoid conflicts with existing decorations. + +```mermaid +sequenceDiagram +participant U as "User Code" +participant S as "Ribbon Composite Entry" +participant C as "Internal Ribbon Component" +participant A as "Ant Design Ribbon" +U->>S : Pass properties and slots (text) +S->>C : Dynamically import and forward properties/slots +C->>A : Forward properties/slots +A-->>U : Render ribbon badge on container +``` + +**Diagram Source** + +- [badge ribbon entry Index.svelte:48-61](file://frontend/antd/badge/ribbon/Index.svelte#L48-L61) +- [ribbon.badge.tsx:6-18](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L6-L18) + +**Section Source** + +- [badge ribbon entry Index.svelte:1-62](file://frontend/antd/badge/ribbon/Index.svelte#L1-L62) +- [ribbon.badge.tsx:1-22](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L1-L22) + +## Dependency Analysis + +- Component wrapping + - All components bridge Ant Design counterparts as Svelte components via sveltify, maintaining consistent property and event forwarding. +- Slot mechanism + - Converts Svelte slots to React Slot via ReactSlot, ensuring compatibility with Antd component slot conventions. +- Dynamic import + - Composite entries use importComponent and import to dynamically import internal implementations, reducing initial bundle size and improving on-demand loading efficiency. +- Style coupling + - Avatar group controls overlap spacing and other style details via less variables, avoiding hardcoding and facilitating unified theme management. + +```mermaid +graph LR +Svelte["Svelte Composite Entry"] --> Sveltify["sveltify Wrapper"] +Sveltify --> Antd["Ant Design Component"] +Svelte --> ReactSlot["ReactSlot Bridge"] +Svelte --> DynamicImport["Dynamic Import Internal Implementation"] +Antd --> Less["less variables control styles"] +``` + +**Diagram Source** + +- [avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [avatar.group.tsx:1-52](file://frontend/antd/avatar/group/avatar.group.tsx#L1-L52) +- [badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) +- [ribbon.badge.tsx:1-22](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L1-L22) + +**Section Source** + +- [avatar group entry Index.svelte:1-62](file://frontend/antd/avatar/group/Index.svelte#L1-L62) +- [avatar.group.tsx:1-52](file://frontend/antd/avatar/group/avatar.group.tsx#L1-L52) +- [badge ribbon entry Index.svelte:1-62](file://frontend/antd/badge/ribbon/Index.svelte#L1-L62) +- [ribbon.badge.tsx:1-22](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L1-L22) + +## Performance Considerations + +- On-demand loading + - Composite entries use dynamic import strategy, loading internal implementations only when needed, reducing initial bundle size and first-screen rendering pressure. +- Slot rendering + - Slot content is injected at the rendering stage, avoiding unnecessary pre-processing overhead. +- Style variables + - Manage style details such as overlap spacing centrally via less variables, reducing repeated computation and style jitter. + +[This section provides general performance recommendations and does not require specific file references] + +## Troubleshooting Guide + +- Avatar not showing icon or image + - Check whether the icon or src property is correctly passed in; if using slots, confirm that the slot name and type match. + - If no icon/image is provided, the component falls back to child nodes as placeholder content; confirm that the child nodes are visible. +- Avatar group threshold invalid or popup layer not showing + - Confirm that max.count is a numeric type; when count is a number, the internal code automatically adds one to compensate for its own occupation. + - The popup layer title and content can be overridden via slots; if no slots are provided, falls back to property configuration. +- Badge threshold not working + - Confirm whether the threshold property is correctly forwarded to the underlying component; Antd natively supports n+ display logic. +- Ribbon badge position incorrect + - Confirm that Ribbon's parent container has a positioning context; if necessary, manually set relative positioning on the container to ensure stable overlay effect. + +**Section Source** + +- [avatar.tsx:6-25](file://frontend/antd/avatar/avatar.tsx#L6-L25) +- [avatar.group.tsx:18-40](file://frontend/antd/avatar/group/avatar.group.tsx#L18-L40) +- [badge.tsx:6-17](file://frontend/antd/badge/badge.tsx#L6-L17) +- [ribbon.badge.tsx:6-18](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L6-L18) + +## Conclusion + +This component system is built on Ant Design, with Svelte wrapping and slot bridging providing flexible avatar and badge capabilities. Avatar group stacking/masking, badge count and threshold, and ribbon badge highlighting effects can all be highly customized without breaking semantics. It is recommended to manage sizes, spacing, and colors uniformly via theme variables and layout specifications in actual projects to achieve a consistent user experience. + +[This section is a summary and does not require specific file references] + +## Appendix + +- Example entries + - Avatar component examples can be found under the demo tab in the docs directory. + - Badge component examples can be found under the demo tab in the docs directory. +- Related documentation + - Avatar component documentation overview: [avatar docs README.md:1-9](file://docs/components/antd/avatar/README.md#L1-L9) + - Badge component documentation overview: [badge docs README.md:1-9](file://docs/components/antd/badge/README.md#L1-L9) + +**Section Source** + +- [avatar docs README.md:1-9](file://docs/components/antd/avatar/README.md#L1-L9) +- [badge docs README.md:1-9](file://docs/components/antd/badge/README.md#L1-L9) diff --git a/.wiki/en/Ant Design Components/Data Display Components/Calendar and Card.md b/.wiki/en/Ant Design Components/Data Display Components/Calendar and Card.md new file mode 100644 index 00000000..e6da0038 --- /dev/null +++ b/.wiki/en/Ant Design Components/Data Display Components/Calendar and Card.md @@ -0,0 +1,359 @@ +# Calendar and Card + + +**Files referenced in this document** +- [frontend/antd/calendar/Index.svelte](file://frontend/antd/calendar/Index.svelte) +- [frontend/antd/calendar/calendar.tsx](file://frontend/antd/calendar/calendar.tsx) +- [frontend/antd/card/Index.svelte](file://frontend/antd/card/Index.svelte) +- [frontend/antd/card/card.tsx](file://frontend/antd/card/card.tsx) +- [frontend/antd/card/grid/Index.svelte](file://frontend/antd/card/grid/Index.svelte) +- [frontend/antd/card/grid/card.grid.tsx](file://frontend/antd/card/grid/card.grid.tsx) +- [frontend/antd/card/meta/Index.svelte](file://frontend/antd/card/meta/Index.svelte) +- [frontend/antd/card/meta/card.meta.tsx](file://frontend/antd/card/meta/card.meta.tsx) +- [frontend/antd/grid/col/col.tsx](file://frontend/antd/grid/col/col.tsx) +- [frontend/antd/grid/row/row.tsx](file://frontend/antd/grid/row/row.tsx) +- [frontend/antd/grid/context.ts](file://frontend/antd/grid/context.ts) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) + +## Introduction + +This document covers Calendar and Card components, providing complete instructions from architecture to implementation details. Key topics include: + +- Calendar component: scheduling, event marking, date selection, panel switching, special features of notification calendars (extended via slots and callbacks) +- Card component: basic structure, responsive layout with Card.Grid, content organization with Card.Meta, implementation methods for custom card content +- Localization: multilingual support and date localization based on ConfigProvider +- Interactions and callbacks: event callback handling, value change propagation +- Adaptability: adaptation strategies for different screen sizes and dynamic update mechanisms + +## Project Structure + +Calendar and Card components are located in the frontend Ant Design ecosystem, using Svelte + React wrappers (sveltify) to bridge Svelte components with Ant Design's React implementation. Each component provides: + +- Svelte entry file (Index.svelte): responsible for property forwarding, visibility control, slot collection, and async loading of React implementation +- React wrapper (\*.tsx): uses sveltify to wrap Ant Design components for Svelte use, handling function-type callbacks, slot rendering, and value formatting + +```mermaid +graph TB +subgraph "Calendar Component" +C_Index["calendar/Index.svelte"] +C_Tsx["calendar/calendar.tsx"] +end +subgraph "Card Component" +K_Index["card/Index.svelte"] +K_Tsx["card/card.tsx"] +end +subgraph "Card Sub-components" +G_Index["card/grid/Index.svelte"] +G_Tsx["card/grid/card.grid.tsx"] +M_Index["card/meta/Index.svelte"] +M_Tsx["card/meta/card.meta.tsx"] +end +subgraph "Grid System" +R_Tsx["grid/row/row.tsx"] +C_Tsx2["grid/col/col.tsx"] +Ctx["grid/context.ts"] +end +subgraph "Localization" +CP_Tsx["config-provider/config-provider.tsx"] +Locales["config-provider/locales.ts"] +end +C_Index --> C_Tsx +K_Index --> K_Tsx +G_Index --> G_Tsx +M_Index --> M_Tsx +R_Tsx --> C_Tsx2 +Ctx --> R_Tsx +CP_Tsx --> Locales +``` + +**Diagram Source** + +- [frontend/antd/calendar/Index.svelte:1-85](file://frontend/antd/calendar/Index.svelte#L1-L85) +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [frontend/antd/card/Index.svelte:1-68](file://frontend/antd/card/Index.svelte#L1-L68) +- [frontend/antd/card/card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) +- [frontend/antd/card/grid/Index.svelte:1-63](file://frontend/antd/card/grid/Index.svelte#L1-L63) +- [frontend/antd/card/grid/card.grid.tsx:1-7](file://frontend/antd/card/grid/card.grid.tsx#L1-L7) +- [frontend/antd/card/meta/Index.svelte:1-60](file://frontend/antd/card/meta/Index.svelte#L1-L60) +- [frontend/antd/card/meta/card.meta.tsx:1-32](file://frontend/antd/card/meta/card.meta.tsx#L1-L32) +- [frontend/antd/grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [frontend/antd/grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts:1-800](file://frontend/antd/config-provider/locales.ts#L1-L800) + +**Section Source** + +- [frontend/antd/calendar/Index.svelte:1-85](file://frontend/antd/calendar/Index.svelte#L1-L85) +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [frontend/antd/card/Index.svelte:1-68](file://frontend/antd/card/Index.svelte#L1-L68) +- [frontend/antd/card/card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) +- [frontend/antd/card/grid/Index.svelte:1-63](file://frontend/antd/card/grid/Index.svelte#L1-L63) +- [frontend/antd/card/grid/card.grid.tsx:1-7](file://frontend/antd/card/grid/card.grid.tsx#L1-L7) +- [frontend/antd/card/meta/Index.svelte:1-60](file://frontend/antd/card/meta/Index.svelte#L1-L60) +- [frontend/antd/card/meta/card.meta.tsx:1-32](file://frontend/antd/card/meta/card.meta.tsx#L1-L32) +- [frontend/antd/grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [frontend/antd/grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts:1-800](file://frontend/antd/config-provider/locales.ts#L1-L800) + +## Core Components + +- Calendar + - Supports date value formatting (second-level timestamp and dayjs conversion), disabled date filtering, cell render slots (cellRender/fullCellRender/headerRender), panel switching and selection event callbacks + - Value changes are synced upward via onValueChange for easy integration with Gradio and similar frameworks +- Card + - Provides slot-based rendering for title, extra content, cover image, action area and other regions; supports tab list and tab bar extension (tabProps.\* slots) + - Internally collects child items via context and dynamically composes them into Ant Design's Card component +- Card.Grid + - Serves as a grid container inside the card for holding child content and participating in responsive layout +- Card.Meta + - Provides slot-based rendering for title, description, and avatar, enabling flexible customization of card metadata +- Grid System (Row/Col) + - Row collects column items via context and maps children to Ant Design's Row/Col structure for responsive layout + +**Section Source** + +- [frontend/antd/calendar/calendar.tsx:10-15](file://frontend/antd/calendar/calendar.tsx#L10-L15) +- [frontend/antd/calendar/calendar.tsx:58-98](file://frontend/antd/calendar/calendar.tsx#L58-L98) +- [frontend/antd/card/card.tsx:36-146](file://frontend/antd/card/card.tsx#L36-L146) +- [frontend/antd/card/grid/card.grid.tsx:1-7](file://frontend/antd/card/grid/card.grid.tsx#L1-L7) +- [frontend/antd/card/meta/card.meta.tsx:5-29](file://frontend/antd/card/meta/card.meta.tsx#L5-L29) +- [frontend/antd/grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [frontend/antd/grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) + +## Architecture Overview + +The diagram below shows the bridging relationship between Calendar and Card components in Svelte and Ant Design, as well as key flows for slots and callbacks. + +```mermaid +sequenceDiagram +participant Svelte as "Svelte Component
Index.svelte" +participant Wrapper as "React Wrapper
sveltify" +participant Antd as "Ant Design Component" +participant Util as "Utility Functions
useFunction/renderParamsSlot" +Svelte->>Wrapper : Forward properties/visibility/slots +Wrapper->>Util : useFunction wraps callbacks +Wrapper->>Util : renderParamsSlot renders slots +Wrapper->>Antd : Render Antd component and pass props +Antd-->>Wrapper : Callback triggers onChange/onPanelChange/onSelect +Wrapper-->>Svelte : onValueChange syncs value +``` + +**Diagram Source** + +- [frontend/antd/calendar/Index.svelte:65-84](file://frontend/antd/calendar/Index.svelte#L65-L84) +- [frontend/antd/calendar/calendar.tsx:43-98](file://frontend/antd/calendar/calendar.tsx#L43-L98) +- [frontend/antd/card/Index.svelte:53-67](file://frontend/antd/card/Index.svelte#L53-L67) +- [frontend/antd/card/card.tsx:39-146](file://frontend/antd/card/card.tsx#L39-L146) + +## Detailed Component Analysis + +### Calendar + +- Properties and callbacks + - Input value and default value: supports second-level timestamps and dayjs objects, internally unified to dayjs + - Valid range: validRange is also formatted + - Callbacks: onChange/onPanelChange/onSelect convert dates to second-level timestamps before returning + - Slots: cellRender/fullCellRender/headerRender can inject custom rendering via slots +- Event marking and notification calendar + - Inject custom marks or badges via cellRender/fullCellRender slots + - onPanelChange can monitor month/year switching, combined with business logic to implement "notification calendar" scenarios (e.g., highlighting specific dates) +- Date selection and value sync + - onValueChange returns the currently selected date as a second-level timestamp to the parent for state management and persistence + +```mermaid +flowchart TD +Start(["Enter Calendar component"]) --> ParseValue["Parse input value
second-level timestamp -> dayjs"] +ParseValue --> ParseRange["Parse valid range
array -> dayjs[]"] +ParseRange --> RenderCalendar["Render Antd Calendar"] +RenderCalendar --> OnChange{"User selects date?"} +OnChange --> |Yes| ConvertSec["Convert date to second-level timestamp"] +ConvertSec --> CallCb["Trigger onChange/onSelect"] +CallCb --> OnValueChange["Trigger onValueChange to sync value"] +OnValueChange --> End(["Done"]) +OnChange --> |No| End +``` + +**Diagram Source** + +- [frontend/antd/calendar/calendar.tsx:47-98](file://frontend/antd/calendar/calendar.tsx#L47-L98) + +**Section Source** + +- [frontend/antd/calendar/Index.svelte:13-84](file://frontend/antd/calendar/Index.svelte#L13-L84) +- [frontend/antd/calendar/calendar.tsx:10-15](file://frontend/antd/calendar/calendar.tsx#L10-L15) +- [frontend/antd/calendar/calendar.tsx:47-98](file://frontend/antd/calendar/calendar.tsx#L47-L98) + +### Card + +- Basic structure + - Title, extra content, cover image, and action area can all be injected via slots + - Supports tab list tabList and tab bar extension (tabProps.\* slots), including indicator size, more menu, and left/right extra content +- Dynamic content and context + - Collects child items via useTabsItems and useTargets, dynamically injecting tabList and actions + - When Grid child items exist, controls placeholder grid visibility via containsGrid to ensure correct layout +- Custom content implementation + - Uses ReactSlot to render slot content, supporting complex nesting and conditional rendering + - The actions area preferentially uses collected targets, falling back to native props.actions + +```mermaid +classDiagram +class CardWrapper { ++props : AntdCardProps ++slots : Record
useTargets(children)"] +Extract --> Sort["Sort by index
slotIndex/subSlotIndex"] +Sort --> WrapCallbacks["Wrap callbacks
useFunction(afterChange/beforeChange)"] +WrapCallbacks --> Render["Render Ant Design Carousel"] +Render --> Children["Clone children
ReactSlot"] +Children --> End(["Done"]) +``` + +**Diagram Source** + +- [carousel.tsx:9-25](file://frontend/antd/carousel/carousel.tsx#L9-L25) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) + +**Section Source** + +- [carousel.tsx:8-29](file://frontend/antd/carousel/carousel.tsx#L8-L29) +- [Index.svelte:48-61](file://frontend/antd/carousel/Index.svelte#L48-L61) +- [**init**.py (carousel backend):45-94](file://backend/modelscope_studio/components/antd/carousel/__init__.py#L45-L94) +- [basic.py (carousel demo):40-73](file://docs/components/antd/carousel/demos/basic.py#L40-L73) + +### Collapse Component + +- Single Panel and Accordion + - Use accordion to enable/disable accordion mode; activeKey/defaultActiveKey controls currently expanded panels (supports multiple or single selection). +- Dynamic Panel Content Loading + - Use the items context and renderItems to convert slots into items; destroy_on_hidden/destroy_inactive_panel can control panel destruction when hidden to save resources. +- Collapse State Persistence + - State persistence is implemented via the controlled prop activeKey; the onChange callback can be used to record state changes. +- Controlled and Uncontrolled Modes + - Uncontrolled: use defaultActiveKey; controlled: use activeKey and listen to onChange for updates. +- Custom Panel Header + - The label slot is used for custom headers; the extra slot is used for additional actions on the right; the expandIcon slot or function can customize the expand icon. +- Animation Configuration + - Appearance props such as size, bordered, and ghost can be combined with animation and transition effects; specific animation behavior follows Ant Design's default implementation. + +```mermaid +sequenceDiagram +participant S as "Svelte Collapse" +participant P as "withItemsContextProvider" +participant R as "renderItems" +participant RP as "renderParamsSlot" +participant C as "Ant Design Collapse" +S->>P : "Inject items context" +P->>R : "Convert slots to items" +S->>RP : "Render expandIcon slot" +S->>C : "Pass items, onChange, expandIcon" +C-->>S : "Trigger onChange(key)" +S-->>S : "Update controlled state/persist" +``` + +**Diagram Source** + +- [collapse.tsx:11-49](file://frontend/antd/collapse/collapse.tsx#L11-L49) +- [context.ts:1-7](file://frontend/antd/collapse/context.ts#L1-L7) +- [renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) +- [renderParamsSlot.tsx:5-49](file://frontend/utils/renderParamsSlot.tsx#L5-L49) + +**Section Source** + +- [collapse.tsx:10-50](file://frontend/antd/collapse/collapse.tsx#L10-L50) +- [collapse.item/Index.svelte:60-88](file://frontend/antd/collapse/item/Index.svelte#L60-L88) +- [context.ts:1-7](file://frontend/antd/collapse/context.ts#L1-L7) +- [**init**.py (collapse backend):54-98](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L54-L98) + +## Dependency Analysis + +- Carousel + - carousel.tsx depends on useFunction and useTargets; Index.svelte handles props and visibility. +- Collapse + - collapse.tsx depends on useFunction, renderItems, renderParamsSlot, and the items context; collapse.item/Index.svelte handles slot cloning and forwarding. +- Backend Mapping + - The backend Python components map parameters to frontend components, avoiding duplicated API definitions. + +```mermaid +graph LR +CF["carousel.tsx"] --> UF["useFunction.ts"] +CF --> UT["useTargets.ts"] +CI["Index.svelte(Carousel)"] --> CF +DF["collapse.tsx"] --> UF +DF --> RI["renderItems.tsx"] +DF --> RPS["renderParamsSlot.tsx"] +DI["Index.svelte(Collapse)"] --> DF +DII["collapse.item/Index.svelte"] --> DF +``` + +**Diagram Source** + +- [carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [Index.svelte:1-66](file://frontend/antd/carousel/Index.svelte#L1-L66) +- [Index.svelte:1-66](file://frontend/antd/collapse/Index.svelte#L1-L66) +- [collapse.item/Index.svelte:1-95](file://frontend/antd/collapse/item/Index.svelte#L1-L95) + +**Section Source** + +- [carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [Index.svelte:1-66](file://frontend/antd/carousel/Index.svelte#L1-L66) +- [Index.svelte:1-66](file://frontend/antd/collapse/Index.svelte#L1-L66) +- [collapse.item/Index.svelte:1-95](file://frontend/antd/collapse/item/Index.svelte#L1-L95) + +## Performance Considerations + +- Carousel + - Child item sorting and target extraction are performed inside useMemo to avoid unnecessary re-renders. + - ReactSlot is used for cloning and rendering; be mindful of the number and complexity of child items. +- Collapse + - Use destroy_on_hidden/destroy_inactive_panel to control panel destruction and reduce memory usage. + - renderItems performs recursive rendering of nested slots; avoid excessively deep nesting. +- General + - useFunction wraps callbacks to ensure stable function references and reduce side effects. + +[This section provides general guidance and does not directly analyze specific files; therefore no "Section Source" is included.] + +## Troubleshooting Guide + +- Carousel children not displayed + - Check that children are passed correctly; verify the useTargets filter logic and slotIndex configuration. +- Carousel callbacks not triggered + - Confirm that afterChange/beforeChange are wrapped with useFunction; check Ant Design version compatibility. +- Collapse items not taking effect + - Confirm that items are injected via slots or passed explicitly; check renderItems key generation and slot key names. +- Expand icon not displayed + - If using the expandIcon slot, ensure the slot exists and renderParamsSlot renders correctly; otherwise check that the expandIcon function is passed in. + +**Section Source** + +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) +- [renderParamsSlot.tsx:5-49](file://frontend/utils/renderParamsSlot.tsx#L5-L49) + +## Conclusion + +- Both Carousel and Collapse follow a unified architecture of "Svelte wrapper + Ant Design component + utility functions", offering good extensibility and maintainability. +- Carousel focuses on autoplay, transition animations, and indicator configuration; Collapse emphasizes controlled/uncontrolled modes, dynamic loading, and state persistence. +- It is recommended to combine demo scripts and backend parameter mappings to quickly implement feature requirements in real projects. + +[This section is a summary and does not directly analyze specific files; therefore no "Section Source" is included.] + +## Appendix + +- Parameter Reference + - Carousel: autoplay, autoplaySpeed, adaptiveHeight, dotPosition, dotPlacement, dots, draggable, fade, infinite, speed, easing, effect, afterChange, beforeChange, wait_for_animate, root_class_name. + - Collapse: accordion, activeKey/defaultActiveKey, bordered, collapsible, destroy_on_hidden, destroy_inactive_panel, expand_icon, expand_icon_position, expand_icon_placement, ghost, items, size, root_class_name. + +**Section Source** + +- [**init**.py (carousel backend):45-94](file://backend/modelscope_studio/components/antd/carousel/__init__.py#L45-L94) +- [**init**.py (collapse backend):54-98](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L54-L98) +- [basic.py (carousel demo):40-73](file://docs/components/antd/carousel/demos/basic.py#L40-L73) diff --git a/.wiki/en/Ant Design Components/Data Display Components/Data Display Components.md b/.wiki/en/Ant Design Components/Data Display Components/Data Display Components.md new file mode 100644 index 00000000..9f05e7d7 --- /dev/null +++ b/.wiki/en/Ant Design Components/Data Display Components/Data Display Components.md @@ -0,0 +1,664 @@ +# Data Display Components + + +**Files referenced in this document** +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [frontend/antd/avatar/avatar.tsx](file://frontend/antd/avatar/avatar.tsx) +- [frontend/antd/badge/badge.tsx](file://frontend/antd/badge/badge.tsx) +- [frontend/antd/calendar/calendar.tsx](file://frontend/antd/calendar/calendar.tsx) +- [frontend/antd/card/card.tsx](file://frontend/antd/card/card.tsx) +- [frontend/antd/carousel/carousel.tsx](file://frontend/antd/carousel/carousel.tsx) +- [frontend/antd/collapse/collapse.tsx](file://frontend/antd/collapse/collapse.tsx) +- [frontend/antd/descriptions/descriptions.tsx](file://frontend/antd/descriptions/descriptions.tsx) +- [frontend/antd/empty/empty.tsx](file://frontend/antd/empty/empty.tsx) +- [frontend/antd/image/image.tsx](file://frontend/antd/image/image.tsx) +- [frontend/antd/list/list.tsx](file://frontend/antd/list/list.tsx) +- [frontend/antd/popover/popover.tsx](file://frontend/antd/popover/popover.tsx) +- [frontend/antd/qr_code/qr-code.tsx](file://frontend/antd/qr_code/qr-code.tsx) +- [frontend/antd/segmented/segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [frontend/antd/statistic/statistic.tsx](file://frontend/antd/statistic/statistic.tsx) +- [frontend/antd/table/table.tsx](file://frontend/antd/table/table.tsx) +- [frontend/antd/tabs/tabs.tsx](file://frontend/antd/tabs/tabs.tsx) +- [frontend/antd/tag/tag.tsx](file://frontend/antd/tag/tag.tsx) +- [frontend/antd/timeline/timeline.tsx](file://frontend/antd/timeline/timeline.tsx) +- [frontend/antd/tooltip/tooltip.tsx](file://frontend/antd/tooltip/tooltip.tsx) +- [frontend/antd/tour/tour.tsx](file://frontend/antd/tour/tour.tsx) +- [frontend/antd/tree/tree.tsx](file://frontend/antd/tree/tree.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document covers Ant Design data display components, systematically covering Avatar, Badge, Calendar, Card, Carousel, Collapse, Descriptions, Empty, Image, List, Popover, QRCode, Segmented, Statistic, Table, Tabs, Tag, Timeline, Tooltip, Tour, and Tree components and their implementation and usage in this repository. Key topics include: + +- Data rendering: how to map child nodes to Ant Design component children/items via slots and items. +- Interaction behavior: unified handling of event callbacks (such as onChange/onSelect) and function wrapping (useFunction). +- Animation effects: provided by Ant Design natively; the component layer does not add additional animation wrapping. +- Large data optimization: recommended to adopt virtual scrolling, pagination, lazy loading, and other strategies, combined with component extensibility for secondary wrapping. +- Theme customization and style overrides: achieved through Ant Design's theme variable and CSS variable system. +- Responsive and mobile adaptation: follows Ant Design's grid and breakpoint strategies, combined with Svelte component size control. + +## Project Structure + +This repository uses a dual-layer wrapping pattern of "backend Python module + frontend Svelte package": + +- The backend module is responsible for exporting each component class for unified reference in a Python environment. +- The frontend Svelte package bridges Ant Design React components as Svelte components via sveltify, supporting declarative rendering of slots and items. + +```mermaid +graph TB +subgraph "Backend" +PY_API["Python Export Module
__init__.py / components.py"] +end +subgraph "Frontend" +PKG["Svelte Package
package.json"] +AVATAR["Avatar
avatar.tsx"] +BADGE["Badge
badge.tsx"] +CALENDAR["Calendar
calendar.tsx"] +CARD["Card
card.tsx"] +CAROUSEL["Carousel
carousel.tsx"] +COLLAPSE["Collapse
collapse.tsx"] +DESC["Descriptions
descriptions.tsx"] +EMPTY["Empty
empty.tsx"] +IMAGE["Image
image.tsx"] +LIST["List
list.tsx"] +POPOVER["Popover
popover.tsx"] +QRCODE["QRCode
qr-code.tsx"] +SEG["Segmented
segmented.tsx"] +STAT["Statistic
statistic.tsx"] +TABLE["Table
table.tsx"] +TABS["Tabs
tabs.tsx"] +TAG["Tag
tag.tsx"] +TIME["Timeline
timeline.tsx"] +TT["Tooltip
tooltip.tsx"] +TOUR["Tour
tour.tsx"] +TREE["Tree
tree.tsx"] +end +PY_API --> AVATAR +PY_API --> BADGE +PY_API --> CALENDAR +PY_API --> CARD +PY_API --> CAROUSEL +PY_API --> COLLAPSE +PY_API --> DESC +PY_API --> EMPTY +PY_API --> IMAGE +PY_API --> LIST +PY_API --> POPOVER +PY_API --> QRCODE +PY_API --> SEG +PY_API --> STAT +PY_API --> TABLE +PY_API --> TABS +PY_API --> TAG +PY_API --> TIME +PY_API --> TT +PY_API --> TOUR +PY_API --> TREE +PKG --> AVATAR +PKG --> BADGE +PKG --> CALENDAR +PKG --> CARD +PKG --> CAROUSEL +PKG --> COLLAPSE +PKG --> DESC +PKG --> EMPTY +PKG --> IMAGE +PKG --> LIST +PKG --> POPOVER +PKG --> QRCODE +PKG --> SEG +PKG --> STAT +PKG --> TABLE +PKG --> TABS +PKG --> TAG +PKG --> TIME +PKG --> TT +PKG --> TOUR +PKG --> TREE +``` + +Diagram Source + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) + +Section Source + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) + +## Core Components + +This section outlines the bridging approach and key features of each component on the frontend: + +- Unified bridging: all components wrap Ant Design React components as Svelte components via sveltify, supporting declarative rendering of slots and items. +- Function callbacks: use useFunction to wrap callbacks such as onChange/onSelect to ensure correct execution in the Svelte context. +- Date and range: format and convert date-type props to ensure consistency with timestamps passed in from the parent. +- Sub-item rendering: achieve unified mapping of items and children via renderItems and useTargets. + +Section Source + +- [frontend/antd/avatar/avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [frontend/antd/badge/badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [frontend/antd/card/card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) +- [frontend/antd/carousel/carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [frontend/antd/collapse/collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) + +## Architecture Overview + +The diagram below shows the overall flow from backend export to frontend component bridging, as well as utility functions and contexts shared between components. + +```mermaid +sequenceDiagram +participant Py as "Backend Export Module" +participant Svelte as "Svelte Component" +participant AD as "Ant Design React" +participant Util as "Utility Functions" +Py->>Svelte : Export component class +Svelte->>Util : useFunction/useTargets/renderItems +Svelte->>AD : sveltify wrapping and pass props/slots +AD-->>Svelte : Render result and callback triggers +Svelte-->>Py : Complete data display via slots/items +``` + +Diagram Source + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [frontend/antd/avatar/avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [frontend/antd/card/card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) +- [frontend/antd/carousel/carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [frontend/antd/collapse/collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) + +## Detailed Component Analysis + +### Avatar + +- Data rendering: supports rendering icon and src via slots; if not provided, falls back to children. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design; component layer does not add additional wrapping. + +```mermaid +flowchart TD +Start(["Enter Avatar"]) --> CheckSlots["Check slots: icon / src"] +CheckSlots --> HasSlots{"Slots exist?"} +HasSlots --> |Yes| RenderSlots["Render slot content"] +HasSlots --> |No| Fallback["Fall back to children"] +RenderSlots --> Render["Render Ant Design Avatar"] +Fallback --> Render +Render --> End(["Done"]) +``` + +Diagram Source + +- [frontend/antd/avatar/avatar.tsx:6-25](file://frontend/antd/avatar/avatar.tsx#L6-L25) + +Section Source + +- [frontend/antd/avatar/avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) + +### Badge + +- Data rendering: count and text support custom slots. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +```mermaid +flowchart TD +Start(["Enter Badge"]) --> CountSlot["count has slot?"] +CountSlot --> |Yes| RenderCount["Render count slot"] +CountSlot --> |No| UseCount["Use props.count"] +TextSlot["text has slot?"] +TextSlot --> |Yes| RenderText["Render text slot"] +TextSlot --> |No| UseText["Use props.text"] +RenderCount --> Render["Render Ant Design Badge"] +UseCount --> Render +RenderText --> Render +UseText --> Render +Render --> End(["Done"]) +``` + +Diagram Source + +- [frontend/antd/badge/badge.tsx:6-18](file://frontend/antd/badge/badge.tsx#L6-L18) + +Section Source + +- [frontend/antd/badge/badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) + +### Calendar + +- Data rendering: value/defaultValue/validRange are formatted with dayjs; cellRender/fullCellRender/headerRender support slots. +- Interaction behavior: onChange/onPanelChange/onSelect callbacks are uniformly wrapped via useFunction; internally converts dates to second-level timestamps before returning to the parent. +- Animation effects: provided by Ant Design. + +```mermaid +sequenceDiagram +participant UI as "User Interface" +participant Comp as "Calendar Component" +participant Util as "useFunction/formatDayjs" +participant AD as "Ant Design Calendar" +UI->>Comp : Pass value/defaultValue/validRange +Comp->>Util : Format date +Comp->>AD : Render and bind callbacks +AD-->>Comp : onChange/onPanelChange/onSelect triggered +Comp->>UI : Convert to second-level timestamp and callback +``` + +Diagram Source + +- [frontend/antd/calendar/calendar.tsx:17-99](file://frontend/antd/calendar/calendar.tsx#L17-L99) + +Section Source + +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) + +### Card + +- Data rendering: title/extra/cover/tabBarExtraContent support slots; actions are auto-collected via useTargets; tabList is rendered via renderItems. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +```mermaid +flowchart TD +Start(["Enter Card"]) --> Actions["Collect actions slots"] +Actions --> Tabs["Parse tabList and tabProps"] +Tabs --> Slots["Parse title/extra/cover and other slots"] +Slots --> Render["Render Ant Design Card"] +Render --> End(["Done"]) +``` + +Diagram Source + +- [frontend/antd/card/card.tsx:37-147](file://frontend/antd/card/card.tsx#L37-L147) + +Section Source + +- [frontend/antd/card/card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) + +### Carousel + +- Data rendering: children are collected via useTargets, then cloned and rendered as ReactSlot. +- Interaction behavior: afterChange/beforeChange are wrapped via useFunction. +- Animation effects: provided by Ant Design. + +```mermaid +sequenceDiagram +participant Comp as "Carousel Component" +participant Util as "useTargets/useFunction" +participant AD as "Ant Design Carousel" +Comp->>Util : Collect children and clone +Comp->>AD : Render and bind callbacks +AD-->>Comp : Before/after switch callbacks +Comp-->>Comp : Execute wrapped callbacks +``` + +Diagram Source + +- [frontend/antd/carousel/carousel.tsx:8-29](file://frontend/antd/carousel/carousel.tsx#L8-L29) + +Section Source + +- [frontend/antd/carousel/carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) + +### Collapse + +- Data rendering: items are rendered via renderItems; expandIcon supports slots. +- Interaction behavior: onChange is wrapped via useFunction. +- Animation effects: provided by Ant Design. + +```mermaid +flowchart TD +Start(["Enter Collapse"]) --> Items["Parse items or slots.default/items"] +Items --> ExpandIcon["expandIcon has slot?"] +ExpandIcon --> |Yes| RenderIcon["Render slot"] +ExpandIcon --> |No| UseIcon["Use props.expandIcon"] +RenderIcon --> Render["Render Ant Design Collapse"] +UseIcon --> Render +Render --> End(["Done"]) +``` + +Diagram Source + +- [frontend/antd/collapse/collapse.tsx:11-50](file://frontend/antd/collapse/collapse.tsx#L11-L50) + +Section Source + +- [frontend/antd/collapse/collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) + +### Descriptions + +- Data rendering: title/extra support slots; items are rendered via renderItems. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +```mermaid +flowchart TD +Start(["Enter Descriptions"]) --> Resolve["Resolve items or slots.default/items"] +Resolve --> Render["Render Ant Design Descriptions"] +Render --> End(["Done"]) +``` + +Diagram Source + +- [frontend/antd/descriptions/descriptions.tsx:10-38](file://frontend/antd/descriptions/descriptions.tsx#L10-L38) + +Section Source + +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) + +### Empty + +- Data rendering: description/image support slots; image supports default value and custom. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +```mermaid +flowchart TD +Start(["Enter Empty"]) --> Desc["description has slot?"] +Desc --> |Yes| RenderDesc["Render slot"] +Desc --> |No| UseDesc["Use props.description"] +Image["image has slot?"] +Image --> |Yes| RenderImg["Render slot"] +Image --> |No| CheckDefault["Determine default or custom"] +RenderDesc --> Render["Render Ant Design Empty"] +UseDesc --> Render +RenderImg --> Render +CheckDefault --> Render +Render --> End(["Done"]) +``` + +Diagram Source + +- [frontend/antd/empty/empty.tsx:6-49](file://frontend/antd/empty/empty.tsx#L6-L49) + +Section Source + +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) + +### Image + +- Data rendering: supports preview group and slots. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +Section Source + +- [frontend/antd/image/image.tsx:1-200](file://frontend/antd/image/image.tsx#L1-L200) + +### List + +- Data rendering: supports custom item rendering and action areas. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +Section Source + +- [frontend/antd/list/list.tsx:1-200](file://frontend/antd/list/list.tsx#L1-L200) + +### Popover + +- Data rendering: supports slots for trigger and content areas. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +Section Source + +- [frontend/antd/popover/popover.tsx:1-200](file://frontend/antd/popover/popover.tsx#L1-L200) + +### QRCode + +- Data rendering: supports content and style configuration. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +Section Source + +- [frontend/antd/qr_code/qr-code.tsx:1-200](file://frontend/antd/qr_code/qr-code.tsx#L1-L200) + +### Segmented + +- Data rendering: supports options and slots. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +Section Source + +- [frontend/antd/segmented/segmented.tsx:1-200](file://frontend/antd/segmented/segmented.tsx#L1-L200) + +### Statistic + +- Data rendering: supports custom titles and values. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +Section Source + +- [frontend/antd/statistic/statistic.tsx:1-200](file://frontend/antd/statistic/statistic.tsx#L1-L200) + +### Table + +- Data rendering: supports complex structures including column definitions, expandable rows, and row selection. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +Section Source + +- [frontend/antd/table/table.tsx:1-200](file://frontend/antd/table/table.tsx#L1-L200) + +### Tabs + +- Data rendering: supports slots for tab items and extra content. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +Section Source + +- [frontend/antd/tabs/tabs.tsx:1-200](file://frontend/antd/tabs/tabs.tsx#L1-L200) + +### Tag + +- Data rendering: supports checkable tags and slots. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +Section Source + +- [frontend/antd/tag/tag.tsx:1-200](file://frontend/antd/tag/tag.tsx#L1-L200) + +### Timeline + +- Data rendering: supports timeline items and slots. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +Section Source + +- [frontend/antd/timeline/timeline.tsx:1-200](file://frontend/antd/timeline/timeline.tsx#L1-L200) + +### Tooltip + +- Data rendering: supports slots for trigger and content areas. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +Section Source + +- [frontend/antd/tooltip/tooltip.tsx:1-200](file://frontend/antd/tooltip/tooltip.tsx#L1-L200) + +### Tour + +- Data rendering: supports steps and slots. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +Section Source + +- [frontend/antd/tour/tour.tsx:1-200](file://frontend/antd/tour/tour.tsx#L1-L200) + +### Tree + +- Data rendering: supports directory tree and node rendering. +- Interaction behavior: no interaction events. +- Animation effects: provided by Ant Design. + +Section Source + +- [frontend/antd/tree/tree.tsx:1-200](file://frontend/antd/tree/tree.tsx#L1-L200) + +## Dependency Analysis + +- Component coupling: all components depend on Ant Design React version; unified wrapping via sveltify reduces the complexity of directly using React. +- Utility functions: tools such as useFunction/useTargets/renderItems/renderParamsSlot run throughout multiple components, improving reusability and consistency. +- Context: some components (such as Collapse/Descriptions/Tabs) introduce an items context for unified declaration and rendering of items. + +```mermaid +graph LR +Util["Utility Functions
useFunction/useTargets/renderItems"] --> AV["Avatar"] +Util --> BG["Badge"] +Util --> CA["Calendar"] +Util --> CR["Card"] +Util --> CL["Carousel"] +Util --> CP["Collapse"] +Util --> DS["Descriptions"] +Util --> EM["Empty"] +Util --> IM["Image"] +Util --> LI["List"] +Util --> PP["Popover"] +Util --> QC["QRCode"] +Util --> SG["Segmented"] +Util --> ST["Statistic"] +Util --> TB["Table"] +Util --> TS["Tabs"] +Util --> TG["Tag"] +Util --> TM["Timeline"] +Util --> TT["Tooltip"] +Util --> TR["Tree"] +``` + +Diagram Source + +- [frontend/antd/avatar/avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [frontend/antd/badge/badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [frontend/antd/card/card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) +- [frontend/antd/carousel/carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [frontend/antd/collapse/collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) +- [frontend/antd/image/image.tsx:1-200](file://frontend/antd/image/image.tsx#L1-L200) +- [frontend/antd/list/list.tsx:1-200](file://frontend/antd/list/list.tsx#L1-L200) +- [frontend/antd/popover/popover.tsx:1-200](file://frontend/antd/popover/popover.tsx#L1-L200) +- [frontend/antd/qr_code/qr-code.tsx:1-200](file://frontend/antd/qr_code/qr-code.tsx#L1-L200) +- [frontend/antd/segmented/segmented.tsx:1-200](file://frontend/antd/segmented/segmented.tsx#L1-L200) +- [frontend/antd/statistic/statistic.tsx:1-200](file://frontend/antd/statistic/statistic.tsx#L1-L200) +- [frontend/antd/table/table.tsx:1-200](file://frontend/antd/table/table.tsx#L1-L200) +- [frontend/antd/tabs/tabs.tsx:1-200](file://frontend/antd/tabs/tabs.tsx#L1-L200) +- [frontend/antd/tag/tag.tsx:1-200](file://frontend/antd/tag/tag.tsx#L1-L200) +- [frontend/antd/timeline/timeline.tsx:1-200](file://frontend/antd/timeline/timeline.tsx#L1-L200) +- [frontend/antd/tooltip/tooltip.tsx:1-200](file://frontend/antd/tooltip/tooltip.tsx#L1-L200) +- [frontend/antd/tree/tree.tsx:1-200](file://frontend/antd/tree/tree.tsx#L1-L200) + +Section Source + +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) + +## Performance Considerations + +- Large data display recommendations + - Virtual scrolling: prioritize container components with virtual scrolling capabilities (such as List/Table), rendering only visible area elements. + - Pagination and lazy loading: use pagination or scroll-to-bottom loading for long lists to reduce one-time rendering pressure. + - Event throttling: use throttle/debounce for high-frequency interactions (such as scrolling, zooming) to avoid frequent re-renders. + - Rendering optimization: move complex computations to the backend or cache them; the frontend only does lightweight rendering. +- Animation and transitions + - Ant Design components have built-in smooth transitions; the component layer does not add additional animations to avoid performance degradation from overlapping. +- Theming and styles + - Use Ant Design's theme variables and CSS variable system to reduce repeated style computations. + - Avoid dynamically generating large amounts of inline styles within components; prefer class names and CSS Modules. + +## Troubleshooting Guide + +- Date parameter anomaly + - Symptom: calendar component date display or callback timestamp is inconsistent. + - Diagnosis: confirm whether value/defaultValue/validRange passed in are valid timestamps or values parseable by dayjs; check whether the formatting logic is effective. +- Callback not triggered + - Symptom: callbacks such as onChange/onSelect are not executed. + - Diagnosis: confirm whether useFunction correctly wraps the callback; check the priority relationship between slots and props. +- Slots not working + - Symptom: title/extra/actions, etc. are not rendered as expected. + - Diagnosis: confirm that slot names are consistent with component conventions; check whether renderItems and useTargets are used correctly. +- Style override not working + - Symptom: custom styles do not take effect. + - Diagnosis: confirm CSS scope and !important usage; prefer theme variables and controlled style objects. + +Section Source + +- [frontend/antd/calendar/calendar.tsx:17-99](file://frontend/antd/calendar/calendar.tsx#L17-L99) +- [frontend/antd/card/card.tsx:37-147](file://frontend/antd/card/card.tsx#L37-L147) +- [frontend/antd/carousel/carousel.tsx:8-29](file://frontend/antd/carousel/carousel.tsx#L8-L29) +- [frontend/antd/collapse/collapse.tsx:11-50](file://frontend/antd/collapse/collapse.tsx#L11-L50) +- [frontend/antd/descriptions/descriptions.tsx:10-38](file://frontend/antd/descriptions/descriptions.tsx#L10-L38) +- [frontend/antd/empty/empty.tsx:6-49](file://frontend/antd/empty/empty.tsx#L6-L49) + +## Conclusion + +This repository seamlessly integrates Ant Design React components into the Svelte ecosystem through unified sveltify bridging and utility functions, achieving: + +- Declarative data rendering (slots/items) +- Consistent interaction callbacks (useFunction) +- Easy-to-extend theming and style overrides +- Good performance and maintainability + +For large data scenarios, it is recommended to combine virtual scrolling, pagination, and lazy loading strategies to further improve user experience and performance. + +## Appendix + +- Component list and corresponding file paths + - Avatar: [frontend/antd/avatar/avatar.tsx](file://frontend/antd/avatar/avatar.tsx) + - Badge: [frontend/antd/badge/badge.tsx](file://frontend/antd/badge/badge.tsx) + - Calendar: [frontend/antd/calendar/calendar.tsx](file://frontend/antd/calendar/calendar.tsx) + - Card: [frontend/antd/card/card.tsx](file://frontend/antd/card/card.tsx) + - Carousel: [frontend/antd/carousel/carousel.tsx](file://frontend/antd/carousel/carousel.tsx) + - Collapse: [frontend/antd/collapse/collapse.tsx](file://frontend/antd/collapse/collapse.tsx) + - Descriptions: [frontend/antd/descriptions/descriptions.tsx](file://frontend/antd/descriptions/descriptions.tsx) + - Empty: [frontend/antd/empty/empty.tsx](file://frontend/antd/empty/empty.tsx) + - Image: [frontend/antd/image/image.tsx](file://frontend/antd/image/image.tsx) + - List: [frontend/antd/list/list.tsx](file://frontend/antd/list/list.tsx) + - Popover: [frontend/antd/popover/popover.tsx](file://frontend/antd/popover/popover.tsx) + - QRCode: [frontend/antd/qr_code/qr-code.tsx](file://frontend/antd/qr_code/qr-code.tsx) + - Segmented: [frontend/antd/segmented/segmented.tsx](file://frontend/antd/segmented/segmented.tsx) + - Statistic: [frontend/antd/statistic/statistic.tsx](file://frontend/antd/statistic/statistic.tsx) + - Table: [frontend/antd/table/table.tsx](file://frontend/antd/table/table.tsx) + - Tabs: [frontend/antd/tabs/tabs.tsx](file://frontend/antd/tabs/tabs.tsx) + - Tag: [frontend/antd/tag/tag.tsx](file://frontend/antd/tag/tag.tsx) + - Timeline: [frontend/antd/timeline/timeline.tsx](file://frontend/antd/timeline/timeline.tsx) + - Tooltip: [frontend/antd/tooltip/tooltip.tsx](file://frontend/antd/tooltip/tooltip.tsx) + - Tour: [frontend/antd/tour/tour.tsx](file://frontend/antd/tour/tour.tsx) + - Tree: [frontend/antd/tree/tree.tsx](file://frontend/antd/tree/tree.tsx) +- Backend exports + - [backend/modelscope_studio/components/antd/**init**.py](file://backend/modelscope_studio/components/antd/__init__.py) + - [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- Frontend package info + - [frontend/antd/package.json](file://frontend/antd/package.json) diff --git a/.wiki/en/Ant Design Components/Data Display Components/Descriptions and Empty.md b/.wiki/en/Ant Design Components/Data Display Components/Descriptions and Empty.md new file mode 100644 index 00000000..79aced65 --- /dev/null +++ b/.wiki/en/Ant Design Components/Data Display Components/Descriptions and Empty.md @@ -0,0 +1,350 @@ +# Descriptions and Empty + + +**Files Referenced in This Document** +- [frontend/antd/descriptions/descriptions.tsx](file://frontend/antd/descriptions/descriptions.tsx) +- [frontend/antd/descriptions/item/Index.svelte](file://frontend/antd/descriptions/item/Index.svelte) +- [frontend/antd/descriptions/context.ts](file://frontend/antd/descriptions/context.ts) +- [frontend/antd/empty/empty.tsx](file://frontend/antd/empty/empty.tsx) +- [frontend/antd/grid/row/row.tsx](file://frontend/antd/grid/row/row.tsx) +- [frontend/antd/grid/col/col.tsx](file://frontend/antd/grid/col/col.tsx) +- [frontend/antd/grid/context.ts](file://frontend/antd/grid/context.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) +- [docs/components/antd/descriptions/README.md](file://docs/components/antd/descriptions/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document focuses on two commonly used UI components: **Descriptions** and **Empty**. It provides an in-depth analysis from the perspectives of system architecture, component relationships, data flow and processing logic, integration points and error handling, and performance characteristics. Based on the existing implementation in the repository, it also provides actionable usage recommendations and best practices. Topics covered include: + +- Descriptions: key-value pair display, responsive layout, label alignment, and custom configuration of description items +- Empty: default icons, custom icons, helper text, and combining action buttons +- Descriptions in form detail pages, multi-language support for labels, and internationalization of empty state +- Grid-based layout for Descriptions and user experience optimization with Empty during data load failures + +## Project Structure + +This project uses a layered and component-based frontend structure. Descriptions and Empty are located under the antd frontend component directory, and use common utilities and context mechanisms to enable flexible slot and child item management. + +```mermaid +graph TB +subgraph "Descriptions" +DRoot["descriptions.tsx"] +DItem["item/Index.svelte"] +DContext["context.ts"] +end +subgraph "Empty" +ERoot["empty.tsx"] +end +subgraph "Grid System" +GRow["grid/row/row.tsx"] +GCol["grid/col/col.tsx"] +GContext["grid/context.ts"] +end +subgraph "Common Utilities" +Ctx["utils/createItemsContext.tsx"] +Locales["config-provider/locales.ts"] +end +DRoot --> DContext +DItem --> DContext +DContext --> Ctx +GRow --> GContext +GCol --> GContext +GContext --> Ctx +ERoot --> Locales +``` + +Diagram Source + +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [frontend/antd/descriptions/item/Index.svelte:1-83](file://frontend/antd/descriptions/item/Index.svelte#L1-L83) +- [frontend/antd/descriptions/context.ts:1-7](file://frontend/antd/descriptions/context.ts#L1-L7) +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) +- [frontend/antd/grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [frontend/antd/grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) + +Section Source + +- [docs/components/antd/descriptions/README.md:1-9](file://docs/components/antd/descriptions/README.md#L1-L9) + +## Core Components + +- Descriptions + - Responsible for displaying a set of key-value pairs in a read-only grouped format, with support for titles, extra areas, and slot-based content injection. + - Collects internal description items via context and item handlers, and ultimately renders them as an Ant Design Descriptions component. +- Descriptions.Item + - A child item of Descriptions, responsible for receiving visibility, style, ID, class name, and other props, and passing child content to the underlying component via slots. +- Empty + - Provides an empty state placeholder with default, simple, or custom icons; supports custom description text and style functions to improve the experience when data is empty or fails to load. +- Grid System (Grid.Row/Col) + - Uses a context mechanism to collect column children and map them to Ant Design's Row/Col, enabling a grid-based layout for Descriptions. + +Section Source + +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [frontend/antd/descriptions/item/Index.svelte:1-83](file://frontend/antd/descriptions/item/Index.svelte#L1-L83) +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) +- [frontend/antd/grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [frontend/antd/grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +## Architecture Overview + +Both Descriptions and Empty work based on a unified "slot and child item context" mechanism: + +- The context provider is responsible for collecting structured information (props, slots, elements, etc.) from child items and transforming them into the data structures required by Ant Design during the rendering phase. +- Slots allow users to inject custom content in the form of ReactSlot or Svelte Slot, such as titles, extra areas, and description item content. +- When rendering, the Empty component selects the appropriate icon based on the passed image type or slot, and merges style functions with inline styles. + +```mermaid +sequenceDiagram +participant U as "User Code" +participant D as "Descriptions(React)" +participant Ctx as "ItemsContextProvider" +participant Item as "Descriptions.Item(Svelte)" +participant AD as "Antd.Descriptions" +U->>D : Render Descriptions and pass props/slots +D->>Ctx : Wrap with context provider +U->>Item : Place multiple Items inside Descriptions +Item->>Ctx : Register child items via ItemHandler +Ctx-->>D : Aggregate items list +D->>AD : Pass items, title, extra to Antd.Descriptions +AD-->>U : Rendering complete +``` + +Diagram Source + +- [frontend/antd/descriptions/descriptions.tsx:10-38](file://frontend/antd/descriptions/descriptions.tsx#L10-L38) +- [frontend/antd/descriptions/context.ts:1-7](file://frontend/antd/descriptions/context.ts#L1-L7) +- [frontend/antd/descriptions/item/Index.svelte:56-76](file://frontend/antd/descriptions/item/Index.svelte#L56-L76) +- [frontend/utils/createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) + +## Detailed Component Analysis + +### Descriptions Component + +- Key-Value Pair Display + - Child items are collected via context and ultimately generate the items array required by Ant Design Descriptions; supports directly passing items or auto-aggregating from child items. +- Responsive Layout + - Can be combined with the Grid System (Grid.Row/Col) for responsive layout; column children inside a Row are mapped to Antd Col for adaptive arrangement at breakpoints. +- Label Alignment + - The component itself does not directly control label alignment, but can pass through props for Antd Descriptions to handle; alignment is transparently forwarded at the Svelte layer. +- Custom Configuration of Description Items + - Supports visible for controlling display, elem_id/elem_classes/elem_style for setting DOM attributes and styles, additionalProps for additional attributes, and as_item for custom render types. +- Slots, Title, and Extra Area + - Supports title and extra slots for injecting custom titles and extra action areas; falls back to props if not provided. + +```mermaid +classDiagram +class Descriptions { ++props : "Antd Descriptions Props" ++slots : "title, extra, default" ++items : "Array or child item collection" ++render() +} +class DescriptionsItem { ++visible : "Visibility flag" ++elem_id : "DOM ID" ++elem_classes : "CSS classes" ++elem_style : "Inline styles" ++additionalProps : "Additional props" ++as_item : "Render type" ++slots : "children etc." ++itemIndex : "Index" ++itemSlotKey : "Slot key" +} +class ItemsContext { ++items : "Child items grouped by slot" ++setItem() ++initial : "Initialization flag" +} +Descriptions --> ItemsContext : "uses" +DescriptionsItem --> ItemsContext : "registers/collects" +``` + +Diagram Source + +- [frontend/antd/descriptions/descriptions.tsx:10-38](file://frontend/antd/descriptions/descriptions.tsx#L10-L38) +- [frontend/antd/descriptions/item/Index.svelte:18-76](file://frontend/antd/descriptions/item/Index.svelte#L18-L76) +- [frontend/antd/descriptions/context.ts:1-7](file://frontend/antd/descriptions/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:40-95](file://frontend/utils/createItemsContext.tsx#L40-L95) + +Section Source + +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [frontend/antd/descriptions/item/Index.svelte:1-83](file://frontend/antd/descriptions/item/Index.svelte#L1-L83) +- [frontend/antd/descriptions/context.ts:1-7](file://frontend/antd/descriptions/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +### Empty Component + +- Default and Custom Icons + - Supports three built-in icon types as well as custom images; the image slot takes priority when present. +- Helper Text + - The description slot has higher priority than props.description, making it easy to dynamically render localized text or complex content. +- Style and Layout + - Supports passing style functions or objects; internally sets the image style to inline-block to ensure consistent alignment of icons and text. +- Combining Action Buttons + - Interactive elements such as buttons can be combined within the description slot to create a complete "empty state + action" flow. + +```mermaid +flowchart TD +Start(["Enter Empty render"]) --> CheckImage["Check if image slot exists"] +CheckImage --> |Yes| UseSlotImage["Use slot image"] +CheckImage --> |No| SwitchImage["Select type based on props.image"] +SwitchImage --> |Built-in constant| UseAntdDefault["Use Antd default icon"] +SwitchImage --> |Simple built-in| UseAntdSimple["Use Antd simple icon"] +SwitchImage --> |Other| UseCustom["Use custom image"] +UseSlotImage --> RenderDesc["Render description slot or props.description"] +UseAntdDefault --> RenderDesc +UseAntdSimple --> RenderDesc +UseCustom --> RenderDesc +RenderDesc --> MergeStyles["Merge style function and object
ensure icon is inline-block"] +MergeStyles --> End(["Rendering complete"]) +``` + +Diagram Source + +- [frontend/antd/empty/empty.tsx:9-49](file://frontend/antd/empty/empty.tsx#L9-L49) + +Section Source + +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) + +### Grid-Based Layout (Grid.Row/Col) + +- Row maps collected column children to Antd Col and renders them inside the Row to achieve responsive grid layout. +- Col receives column props and slots via ItemHandler and forwards them to Antd Col. +- When combined with Descriptions, description items can be nested inside Row/Col to form a "grid-based Descriptions". + +```mermaid +sequenceDiagram +participant U as "User Code" +participant R as "Grid.Row(React)" +participant Ctx as "Grid ItemsContext" +participant C as "Grid.Col(React)" +participant AD as "Antd.Row/Col" +U->>R : Render Row +R->>Ctx : Use context provider +U->>C : Place multiple Col inside Row +C->>Ctx : Register column children via ItemHandler +Ctx-->>R : Aggregate column items +R->>AD : Render Row and map Col +AD-->>U : Grid layout complete +``` + +Diagram Source + +- [frontend/antd/grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [frontend/antd/grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) + +Section Source + +- [frontend/antd/grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [frontend/antd/grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) + +## Dependency Analysis + +- Descriptions Dependencies + - Uses the context capability provided by createItemsContext to bridge Svelte slots and React components, enabling items collection and rendering. + - Wraps the component with withItemsContextProvider to ensure child item registration and updates. +- Empty Dependencies + - Depends on Ant Design's Empty component and built-in icon constants; style function and object merging ensures consistent alignment of icons and text. +- Internationalization Dependencies + - Provides multi-language environments through the config-provider's locales, supporting localization switching for both Antd and dayjs. + +```mermaid +graph LR +D["Descriptions"] --> Ctx["createItemsContext"] +DItem["Descriptions.Item"] --> Ctx +E["Empty"] --> AD["Antd.Empty"] +E --> Locales["locales.ts"] +subgraph "Context Utilities" +Ctx +end +subgraph "Antd Components" +AD +end +subgraph "Internationalization" +Locales +end +``` + +Diagram Source + +- [frontend/antd/descriptions/descriptions.tsx:1-10](file://frontend/antd/descriptions/descriptions.tsx#L1-L10) +- [frontend/antd/descriptions/item/Index.svelte:1-15](file://frontend/antd/descriptions/item/Index.svelte#L1-L15) +- [frontend/antd/empty/empty.tsx:1-9](file://frontend/antd/empty/empty.tsx#L1-L9) +- [frontend/antd/config-provider/locales.ts:1-10](file://frontend/antd/config-provider/locales.ts#L1-L10) + +Section Source + +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) + +## Performance Considerations + +- Child Item Collection and Rendering + - Both Descriptions and the Grid System collect child items via context, avoiding unnecessary re-renders; only the corresponding component's recalculation is triggered when items update. +- Slots and Styles + - Slot content is rendered lazily, mounting only when visible; style function and object merging occurs at render time — it is recommended to reuse style objects as much as possible to reduce overhead. +- Icons and Descriptions + - Icon selection and style merging logic for the Empty component is simple with low performance overhead; it is recommended to use built-in icons in scenarios with many empty states to reduce resource loading. + +## Troubleshooting Guide + +- Descriptions shows no content + - Check whether withItemsContextProvider is correctly wrapping Descriptions, and that Descriptions.Item is placed inside it. + - Confirm that child items have been registered via ItemHandler and that the items list is not empty. +- Description items not taking effect + - Check whether visible, elem_id, elem_classes, elem_style, additionalProps, and other props are passed correctly. + - Confirm that the children slot is correctly bound and rendered. +- Empty state icon not displayed + - If passing an image slot, ensure the slot content is valid; otherwise check whether props.image is a built-in constant or a valid custom value. + - Confirm that the object returned by the style function contains the correct image styles. +- Grid layout issues + - Check whether Grid.Row/Col children are correctly registered; confirm that column props and slots are properly forwarded. + +Section Source + +- [frontend/antd/descriptions/descriptions.tsx:10-38](file://frontend/antd/descriptions/descriptions.tsx#L10-L38) +- [frontend/antd/descriptions/item/Index.svelte:56-76](file://frontend/antd/descriptions/item/Index.svelte#L56-L76) +- [frontend/antd/empty/empty.tsx:9-49](file://frontend/antd/empty/empty.tsx#L9-L49) +- [frontend/antd/grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [frontend/antd/grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) + +## Conclusion + +The Descriptions and Empty components achieve flexible content injection and rendering through a unified context and slot mechanism. Descriptions supports key-value pair display and grid-based layout; Empty provides placeholder solutions with both default and custom icons, and can be combined with action buttons to optimize user experience. Combined with internationalization tools, both can operate stably in multi-language environments. It is recommended to prioritize using Descriptions for displaying read-only information in form detail pages, and to use the Empty component to improve usability when data is empty or fails to load. + +## Appendix + +- Usage Scenario Recommendations + - Form detail pages: Use Descriptions to display read-only fields, optionally combined with the Grid System for responsive layout. + - Data load failures: Use the Empty component to display prompts and retry buttons to improve user confidence. +- Multi-language Support + - Switch Antd and dayjs localization through the config-provider's locales to ensure text and formatting in Descriptions and Empty match the target language. +- Best Practices + - Use slots and props appropriately; avoid creating new objects frequently in render functions. + - For scenarios with many empty states, prefer built-in icons to reduce resource overhead. + - In grid-based layouts, divide column widths and breakpoints carefully to ensure readability across different devices. diff --git a/.wiki/en/Ant Design Components/Data Display Components/Image and List.md b/.wiki/en/Ant Design Components/Data Display Components/Image and List.md new file mode 100644 index 00000000..a1dac268 --- /dev/null +++ b/.wiki/en/Ant Design Components/Data Display Components/Image and List.md @@ -0,0 +1,324 @@ +# Image and List + + +**Files Referenced in This Document** +- [frontend/antd/image/image.tsx](file://frontend/antd/image/image.tsx) +- [frontend/antd/image/preview-group/image.preview-group.tsx](file://frontend/antd/image/preview-group/image.preview-group.tsx) +- [frontend/antd/image/preview-group/Index.svelte](file://frontend/antd/image/preview-group/Index.svelte) +- [frontend/antd/list/list.tsx](file://frontend/antd/list/list.tsx) +- [frontend/antd/list/item/list.item.tsx](file://frontend/antd/list/item/list.item.tsx) +- [frontend/antd/list/item/Index.svelte](file://frontend/antd/list/item/Index.svelte) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/utils/hooks/useTargets.ts](file://frontend/utils/hooks/useTargets.ts) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document focuses on the **Image** and **List** component families, systematically reviewing their encapsulation approach at the frontend layer, capability boundaries, and extension points. Based on the existing repository implementation, it provides actionable usage recommendations and best practices. Key topics include: + +- Image component: batch viewing via preview groups, lazy loading, error handling, and the availability and limitations of image cropping; current state and extension paths for zoom controls, rotation, and download support. +- List component: basic list structure, list item metadata (meta), vertical list layout, and dynamic data binding; current state and extension paths for virtual scrolling, infinite loading, and data filtering; adaptive display and responsive layout design across different devices. + +## Project Structure + +The frontend uses a Svelte + Ant Design combination pattern for Image and List components: + +- Component entry points are exported via Svelte files, with sveltify internally bridging Ant Design's React components into a Svelte-compatible form. +- Preview groups and list items are lazy-loaded via importComponent, combined with the slots mechanism for flexible rendering extensions. +- Utility functions and hooks provide general capabilities: function wrapping, parameterized slot rendering, and target node extraction. + +```mermaid +graph TB +subgraph "Image Component" +IMG_TS["image.tsx
Wraps Ant Design Image"] +PG_IDX["preview-group/Index.svelte
Preview group entry"] +PG_IMPL["preview-group/image.preview-group.tsx
Preview group implementation"] +end +subgraph "List Component" +LIST_TS["list.tsx
Wraps Ant Design List"] +ITEM_IDX["item/Index.svelte
List item entry"] +ITEM_IMPL["item/list.item.tsx
List item implementation"] +end +subgraph "Utilities and Hooks" +USE_FN["useFunction.ts
Function wrapping"] +USE_TGT["useTargets.ts
Target node extraction"] +RENDER_SLOT["renderParamsSlot.tsx
Parameterized slot rendering"] +end +IMG_TS --> PG_IMPL +PG_IDX --> PG_IMPL +LIST_TS --> ITEM_IMPL +ITEM_IDX --> ITEM_IMPL +IMG_TS --> USE_FN +PG_IMPL --> USE_FN +LIST_TS --> USE_FN +ITEM_IMPL --> USE_FN +LIST_TS --> RENDER_SLOT +ITEM_IMPL --> RENDER_SLOT +ITEM_IMPL --> USE_TGT +``` + +**Diagram Source** + +- [frontend/antd/image/image.tsx:1-89](file://frontend/antd/image/image.tsx#L1-L89) +- [frontend/antd/image/preview-group/Index.svelte:1-72](file://frontend/antd/image/preview-group/Index.svelte#L1-L72) +- [frontend/antd/image/preview-group/image.preview-group.tsx:1-55](file://frontend/antd/image/preview-group/image.preview-group.tsx#L1-L55) +- [frontend/antd/list/list.tsx:1-36](file://frontend/antd/list/list.tsx#L1-L36) +- [frontend/antd/list/item/Index.svelte:1-60](file://frontend/antd/list/item/Index.svelte#L1-L60) +- [frontend/antd/list/item/list.item.tsx:1-29](file://frontend/antd/list/item/list.item.tsx#L1-L29) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/hooks/useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +**Section Source** + +- [frontend/antd/image/image.tsx:1-89](file://frontend/antd/image/image.tsx#L1-L89) +- [frontend/antd/image/preview-group/Index.svelte:1-72](file://frontend/antd/image/preview-group/Index.svelte#L1-L72) +- [frontend/antd/image/preview-group/image.preview-group.tsx:1-55](file://frontend/antd/image/preview-group/image.preview-group.tsx#L1-L55) +- [frontend/antd/list/list.tsx:1-36](file://frontend/antd/list/list.tsx#L1-L36) +- [frontend/antd/list/item/Index.svelte:1-60](file://frontend/antd/list/item/Index.svelte#L1-L60) +- [frontend/antd/list/item/list.item.tsx:1-29](file://frontend/antd/list/item/list.item.tsx#L1-L29) + +## Core Components + +- Image: Wraps Ant Design's Image component via sveltify, supporting placeholders, preview configuration, and slot extensions. The preview group provides batch viewing capability, with support for custom masks, close icons, and toolbars. +- List: Wraps Ant Design's List component via sveltify, supporting headers/footers, load-more, and custom render items. List items support extra areas and action collections, with useTargets automatically extracting child nodes carrying specific slotKeys. + +**Section Source** + +- [frontend/antd/image/image.tsx:14-86](file://frontend/antd/image/image.tsx#L14-L86) +- [frontend/antd/image/preview-group/image.preview-group.tsx:13-52](file://frontend/antd/image/preview-group/image.preview-group.tsx#L13-L52) +- [frontend/antd/list/list.tsx:8-33](file://frontend/antd/list/list.tsx#L8-L33) +- [frontend/antd/list/item/list.item.tsx:6-26](file://frontend/antd/list/item/list.item.tsx#L6-L26) + +## Architecture Overview + +The following diagram shows the call chain and slot extension points of the Image and List components at the frontend layer: + +```mermaid +sequenceDiagram +participant U as "User" +participant IMG as "Image Component
image.tsx" +participant PG as "Preview Group
image.preview-group.tsx" +participant LIST as "List Component
list.tsx" +participant ITEM as "ListItem Component
list.item.tsx" +U->>IMG : "Click image" +IMG->>PG : "Trigger preview group" +PG-->>U : "Batch view / toolbar / mask" +U->>LIST : "Render list" +LIST->>ITEM : "Render each item" +ITEM-->>U : "Extra area / action collection" +``` + +**Diagram Source** + +- [frontend/antd/image/image.tsx:24-85](file://frontend/antd/image/image.tsx#L24-L85) +- [frontend/antd/image/preview-group/image.preview-group.tsx:18-51](file://frontend/antd/image/preview-group/image.preview-group.tsx#L18-L51) +- [frontend/antd/list/list.tsx:11-32](file://frontend/antd/list/list.tsx#L11-L32) +- [frontend/antd/list/item/list.item.tsx:9-25](file://frontend/antd/list/item/list.item.tsx#L9-L25) + +## Detailed Component Analysis + +### Image Component + +- Batch Viewing (Preview Group) + - The preview group achieves on-demand loading via lazy imports and conditional rendering, reducing the initial load burden. + - Supports custom masks, close icons, and toolbars; toolbar and image rendering can be injected via slots or function callbacks. + - The mount location of the preview container can be customized via getContainer, making it easy to embed in a specific DOM container. +- Lazy Loading and Error Handling + - The current implementation does not explicitly declare lazy loading and error handling logic; if needed, these can be enhanced at the business layer using native browser attributes or third-party libraries. +- Image Cropping + - This implementation does not expose cropping-related parameters; if cropping is needed, resources can be pre-processed at the business layer or a dedicated cropping library can be introduced. +- Zoom Controls, Rotation, and Download Support + - The current implementation does not have built-in zoom, rotation, or download buttons; corresponding controls can be added via the custom toolbar slot in combination with external libraries. +- Slots and Function Wrapping + - useFunction is used to stabilize passed-in functions; renderParamsSlot supports passing parameters to slot render functions, improving flexibility. + +```mermaid +flowchart TD +Start(["Enter Image render"]) --> CheckPreview["Detect if preview is enabled"] +CheckPreview --> |Yes| BuildPreview["Build preview config
merge slots and functions"] +CheckPreview --> |No| SkipPreview["Disable preview"] +BuildPreview --> SlotsCheck{"Custom slots present?"} +SlotsCheck --> |Yes| RenderSlots["Render custom slots"] +SlotsCheck --> |No| UseDefault["Use default preview behavior"] +RenderSlots --> End(["Done"]) +UseDefault --> End +SkipPreview --> End +``` + +**Diagram Source** + +- [frontend/antd/image/image.tsx:24-85](file://frontend/antd/image/image.tsx#L24-L85) +- [frontend/antd/image/preview-group/image.preview-group.tsx:18-51](file://frontend/antd/image/preview-group/image.preview-group.tsx#L18-L51) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/renderParamsSlot.tsx:5-50](file://frontend/utils/renderParamsSlot.tsx#L5-L50) + +**Section Source** + +- [frontend/antd/image/image.tsx:14-86](file://frontend/antd/image/image.tsx#L14-L86) +- [frontend/antd/image/preview-group/image.preview-group.tsx:13-52](file://frontend/antd/image/preview-group/image.preview-group.tsx#L13-L52) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +### List Component + +- Basic List Structure and Dynamic Data Binding + - Wraps Ant Design List via sveltify, supporting headers/footers, load-more, and custom render items. + - Render items can be passed via slots or injected as functions, enabling flexible data binding and view rendering. +- List Item and Metadata (meta) + - List items support "extra areas" and "action collections"; action collections are automatically extracted from child nodes carrying specific slotKeys using useTargets, ensuring controllable order and indexing. +- Vertical List Layout + - Uses Ant Design's default vertical layout strategy, suitable for most scenarios; for horizontal or grid layouts, use styles or layout components at the business layer. + +```mermaid +classDiagram +class List_tsx { ++slots : footer/header/loadMore/renderItem ++render() : ReactNode +} +class ListItem_tsx { ++slots : extra/actions ++useTargets(children, slotKey) ++render() : ReactNode +} +List_tsx --> ListItem_tsx : "Renders each item" +``` + +**Diagram Source** + +- [frontend/antd/list/list.tsx:8-33](file://frontend/antd/list/list.tsx#L8-L33) +- [frontend/antd/list/item/list.item.tsx:6-26](file://frontend/antd/list/item/list.item.tsx#L6-L26) +- [frontend/utils/hooks/useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) + +**Section Source** + +- [frontend/antd/list/list.tsx:8-33](file://frontend/antd/list/list.tsx#L8-L33) +- [frontend/antd/list/item/list.item.tsx:6-26](file://frontend/antd/list/item/list.item.tsx#L6-L26) +- [frontend/utils/hooks/useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) + +### Preview Group + +- Batch Viewing and Visibility Control + - The preview group entry uses Svelte lazy imports and visibility checks to render the actual component only when needed, reducing initial overhead. + - Supports controlling preview visibility change events via props, enabling synchronization with parent state. +- Slots and Container Mounting + - Supports custom masks and close icons; container mounting location is customized via getContainer, making it easy to embed in a specified container. + +```mermaid +sequenceDiagram +participant IDX as "Preview Group Entry
Index.svelte" +participant CMP as "Preview Group Implementation
image.preview-group.tsx" +IDX->>IDX : "Check visibility" +IDX->>CMP : "Lazy import and render" +CMP-->>IDX : "Output preview group" +``` + +**Diagram Source** + +- [frontend/antd/image/preview-group/Index.svelte:55-71](file://frontend/antd/image/preview-group/Index.svelte#L55-L71) +- [frontend/antd/image/preview-group/image.preview-group.tsx:18-51](file://frontend/antd/image/preview-group/image.preview-group.tsx#L18-L51) + +**Section Source** + +- [frontend/antd/image/preview-group/Index.svelte:14-71](file://frontend/antd/image/preview-group/Index.svelte#L14-L71) +- [frontend/antd/image/preview-group/image.preview-group.tsx:18-52](file://frontend/antd/image/preview-group/image.preview-group.tsx#L18-L52) + +## Dependency Analysis + +- Components and Utility Functions + - Both Image and List components depend on useFunction for function stabilization, ensuring callbacks are not recreated when props change. + - List items depend on useTargets to extract child nodes with specific slotKeys, enabling automatic assembly of action collections. + - renderParamsSlot provides parameterized slot rendering, supporting parameter passing to slots with forced cloning to ensure rendering consistency across multiple renders. +- Inter-Component Coupling + - Image preview group and Image component are decoupled: the preview group exists as an independent component and collaborates with the Image component via props and slots. + - List items and the List component are decoupled: list items use lazy imports and slots for independent rendering, reducing coupling. + +```mermaid +graph LR +IMG["image.tsx"] --> UF["useFunction.ts"] +PG["image.preview-group.tsx"] --> UF +LIST["list.tsx"] --> UF +ITEM["list.item.tsx"] --> UF +ITEM --> UT["useTargets.ts"] +LIST --> RS["renderParamsSlot.tsx"] +ITEM --> RS +``` + +**Diagram Source** + +- [frontend/antd/image/image.tsx:3-4](file://frontend/antd/image/image.tsx#L3-L4) +- [frontend/antd/image/preview-group/image.preview-group.tsx:3-4](file://frontend/antd/image/preview-group/image.preview-group.tsx#L3-L4) +- [frontend/antd/list/list.tsx:4-5](file://frontend/antd/list/list.tsx#L4-L5) +- [frontend/antd/list/item/list.item.tsx:3-4](file://frontend/antd/list/item/list.item.tsx#L3-L4) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/hooks/useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +**Section Source** + +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/hooks/useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +## Performance Considerations + +- On-Demand Loading and Lazy Imports + - Both preview groups and list items use lazy import strategies, rendering only when visible, which helps reduce initial load and memory usage. +- Function Stabilization + - useFunction memoizes callbacks to avoid recreation due to prop changes, reducing re-render costs. +- Slot Rendering Optimization + - renderParamsSlot enforces cloning and parameter forwarding, ensuring deterministic and reusable slot rendering while reducing unnecessary repeated computation. + +**Section Source** + +- [frontend/antd/image/preview-group/Index.svelte:55-71](file://frontend/antd/image/preview-group/Index.svelte#L55-L71) +- [frontend/antd/list/item/Index.svelte:46-59](file://frontend/antd/list/item/Index.svelte#L46-L59) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/renderParamsSlot.tsx:23-49](file://frontend/utils/renderParamsSlot.tsx#L23-L49) + +## Troubleshooting Guide + +- Preview group not displayed + - Check the visibility props and the entry component's visibility logic to confirm that the preview group has been lazy-loaded and rendered. + - If using a custom mask or close icon, confirm that the slot is correctly passed in and has not been overridden. +- Toolbar/image rendering not working + - Confirm that passed-in functions are wrapped with useFunction to prevent failures due to function reference changes. + - If using slots, confirm that parameter passing to renderParamsSlot is correct. +- List item action collection is empty + - Check whether child nodes carry the correct slotKey and index information to ensure useTargets can extract them correctly. +- Performance issues + - If frequent re-renders occur, check whether callbacks or slot content are being changed frequently in the parent component; it is recommended to use useFunction or stabilization strategies. + +**Section Source** + +- [frontend/antd/image/preview-group/Index.svelte:55-71](file://frontend/antd/image/preview-group/Index.svelte#L55-L71) +- [frontend/antd/image/preview-group/image.preview-group.tsx:18-51](file://frontend/antd/image/preview-group/image.preview-group.tsx#L18-L51) +- [frontend/antd/list/item/list.item.tsx:10-21](file://frontend/antd/list/item/list.item.tsx#L10-L21) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/renderParamsSlot.tsx:23-49](file://frontend/utils/renderParamsSlot.tsx#L23-L49) + +## Conclusion + +- The Image component achieves batch viewing and flexible slot extensions via the preview group; the current implementation does not have built-in lazy loading, error handling, cropping, zoom, rotation, or download features, but offers good extensibility. +- The List component provides basic structure and dynamic binding capabilities; list item action collections are automatically assembled via useTargets, making it suitable for combining with styles and layout at the business layer to achieve responsive and adaptive display. +- In terms of performance, components generally adopt lazy import and function stabilization strategies, helping to maintain good runtime efficiency in complex scenarios. + +## Appendix + +- Extension Recommendations + - Image: Introduce lazy loading and error handling strategies at the business layer; for cropping, zoom, rotation, and download, combine external libraries with custom toolbar slots. + - List: Introduce virtual scrolling and infinite loading at the business layer; data filtering can be achieved through external state and render conditions; responsive layout can be adapted for multiple devices via style and breakpoint strategies. diff --git a/.wiki/en/Ant Design Components/Data Display Components/Popover and QRCode.md b/.wiki/en/Ant Design Components/Data Display Components/Popover and QRCode.md new file mode 100644 index 00000000..33d4eecc --- /dev/null +++ b/.wiki/en/Ant Design Components/Data Display Components/Popover and QRCode.md @@ -0,0 +1,332 @@ +# Popover and QRCode + + +**Files Referenced in This Document** +- [popover.tsx](file://frontend/antd/popover/popover.tsx) +- [Index.svelte (Popover)](file://frontend/antd/popover/Index.svelte) +- [__init__.py (AntdPopover)](file://backend/modelscope_studio/components/antd/popover/__init__.py) +- [README-zh_CN.md (Popover docs)](file://docs/components/antd/popover/README-zh_CN.md) +- [README.md (Popover docs)](file://docs/components/antd/popover/README.md) +- [qr-code.tsx](file://frontend/antd/qr-code/qr-code.tsx) +- [Index.svelte (QRCode)](file://frontend/antd/qr-code/Index.svelte) +- [__init__.py (AntdQRCode)](file://backend/modelscope_studio/components/antd/qr_code/__init__.py) +- [README-zh_CN.md (QRCode docs)](file://docs/components/antd/qr_code/README-zh_CN.md) +- [README.md (QRCode docs)](file://docs/components/antd/qr_code/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document provides a comprehensive explanation of the **Popover** and **QRCode** components, from underlying implementation to usage at the application layer. Topics covered include: + +- Popover: trigger modes, position control, content customization, animation integration, nested usage, delayed display, accessibility support, and more +- QRCode: encoded content, size and margin, color and background, error correction level, icon overlay, dynamic refresh, custom styles, and print optimization +- Complex layout positioning strategies and mobile scanning experience recommendations + +## Project Structure + +Both components follow a unified layered design of "backend component class + frontend Svelte wrapper + React encapsulation": + +- The backend component class handles parameter validation, event binding, example values, and render switches +- The frontend Svelte layer handles prop forwarding, slot processing, and visibility control +- The React encapsulation layer bridges with Ant Design components and supports slot and function callback conversion + +```mermaid +graph TB +subgraph "Backend" +BPY["AntdPopover.__init__"] +BQRY["AntdQRCode.__init__"] +end +subgraph "Frontend Svelte" +PIdx["Popover/Index.svelte"] +QIdx["QRCode/Index.svelte"] +end +subgraph "React Encapsulation" +PR["Popover/popover.tsx"] +QR["QRCode/qr-code.tsx"] +end +subgraph "Ant Design" +ADPop["antd.Popover"] +ADQR["antd.QRCode"] +end +BPY --> PIdx +BQRY --> QIdx +PIdx --> PR +QIdx --> QR +PR --> ADPop +QR --> ADQR +``` + +Diagram Source + +- [**init**.py (AntdPopover):10-124](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L124) +- [Index.svelte (Popover):10-72](file://frontend/antd/popover/Index.svelte#L10-L72) +- [popover.tsx:7-34](file://frontend/antd/popover/popover.tsx#L7-L34) +- [**init**.py (AntdQRCode):10-96](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L10-L96) +- [Index.svelte (QRCode):10-63](file://frontend/antd/qr-code/Index.svelte#L10-L63) +- [qr-code.tsx:6-20](file://frontend/antd/qr-code/qr-code.tsx#L6-L20) + +Section Source + +- [**init**.py (AntdPopover):10-124](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L124) +- [Index.svelte (Popover):10-72](file://frontend/antd/popover/Index.svelte#L10-L72) +- [popover.tsx:7-34](file://frontend/antd/popover/popover.tsx#L7-L34) +- [**init**.py (AntdQRCode):10-96](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L10-L96) +- [Index.svelte (QRCode):10-63](file://frontend/antd/qr-code/Index.svelte#L10-L63) +- [qr-code.tsx:6-20](file://frontend/antd/qr-code/qr-code.tsx#L6-L20) + +## Core Components + +- Popover + - Supports multiple trigger modes: hover, focus, click, context menu + - Supports 12 placement positions: top/bottom/left/right and four corners + - Supports title and content slots for injecting arbitrary content + - Supports open state change event binding + - Supports custom container mount point and delayed display control +- QRCode + - Supports canvas/svg output types + - Supports foreground color, background color, border, icon overlay, and margin + - Supports four error correction levels: L/M/Q/H + - Supports status render slot and refresh event binding + +Section Source + +- [**init**.py (AntdPopover):43-59](file://backend/modelscope_studio/components/antd/popover/__init__.py#L43-L59) +- [**init**.py (AntdQRCode):29-40](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L29-L40) + +## Architecture Overview + +The following diagram shows the call chain from the backend component class to the frontend Svelte wrapper, then to the React encapsulation layer and Ant Design. + +```mermaid +sequenceDiagram +participant Backend as "Backend Component Class" +participant Svelte as "Svelte Wrapper" +participant ReactWrap as "React Encapsulation" +participant AntD as "Ant Design" +Backend->>Svelte : Pass parameters and events +Svelte->>ReactWrap : Forward props/slots/visibility +ReactWrap->>AntD : Render and bind events +AntD-->>ReactWrap : Interaction results/state changes +ReactWrap-->>Svelte : Return callbacks/state +Svelte-->>Backend : Trigger events/update state +``` + +Diagram Source + +- [**init**.py (AntdPopover):14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) +- [Index.svelte (Popover):24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- [popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) +- [**init**.py (AntdQRCode):15-19](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L15-L19) +- [Index.svelte (QRCode):22-45](file://frontend/antd/qr-code/Index.svelte#L22-L45) +- [qr-code.tsx:6-20](file://frontend/antd/qr-code/qr-code.tsx#L6-L20) + +## Detailed Component Analysis + +### Popover Component + +- Trigger Modes + - Supports hover/focus/click/contextMenu and their combinations + - Entry/leave delays can be controlled via delay parameters +- Position Control + - Supports top/left/right/bottom and all nine grid positions + - Supports overflow auto-adjustment and arrow configuration +- Content Customization + - Supports title/content slots for rendering arbitrary content + - Supports overlay style and inner style +- Animation and Events + - Provides the open_change event for listening to open state changes + - Supports custom container mount points for precise positioning in complex layouts +- Nested Usage + - Avoid z-index conflicts by customizing the container mount point + - Be careful to avoid focus issues caused by multiple layered popovers activating simultaneously +- Delayed Display + - Control the display timing using entry/leave delay parameters +- Accessibility Support + - Recommended to combine with aria-\* attributes and keyboard navigation + - Pay attention to semantic labels and description text in nested scenarios + +```mermaid +classDiagram +class AntdPopover { ++EVENTS ++SLOTS ++placement ++trigger ++mouse_enter_delay ++mouse_leave_delay ++overlay_style ++overlay_inner_style ++get_popup_container ++open_change +} +class PopoverWrapper { ++slots ++afterOpenChange ++getPopupContainer ++children +} +AntdPopover --> PopoverWrapper : "prop forwarding" +``` + +Diagram Source + +- [**init**.py (AntdPopover):14-105](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L105) +- [popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) + +Section Source + +- [**init**.py (AntdPopover):23-105](file://backend/modelscope_studio/components/antd/popover/__init__.py#L23-L105) +- [Index.svelte (Popover):24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- [popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) +- [README-zh_CN.md (Popover docs):1-8](file://docs/components/antd/popover/README-zh_CN.md#L1-L8) +- [README.md (Popover docs):1-8](file://docs/components/antd/popover/README.md#L1-L8) + +### QRCode Component + +- Encoded Content and Size + - value: the encoded content of the QR code + - size: overall size; margin_size: outer margin; bordered: whether to show a border +- Color and Style + - color: foreground color; bg_color: background color; type: canvas/svg output +- Error Correction and Enhancement + - error_level: four correction levels L/M/Q/H + - boost_level: enhance recognition capability (boolean) +- Icon Overlay and Status + - icon: center icon URL; icon_size: icon size or size configuration + - status: active/expired/loading/scanned states + - statusRender: status render slot +- Dynamic Updates and Events + - refresh event: used to trigger QR code regeneration +- Custom Styles and Print Optimization + - Theme adaptation via styles and class names + - For print scenarios, it is recommended to use fixed sizes and high-contrast colors + +```mermaid +classDiagram +class AntdQRCode { ++EVENTS ++SLOTS ++value ++size ++color ++bg_color ++type ++bordered ++error_level ++boost_level ++icon ++icon_size ++margin_size ++status ++statusRender ++refresh +} +class QRWrapper { ++slots ++statusRender ++value +} +AntdQRCode --> QRWrapper : "prop forwarding" +``` + +Diagram Source + +- [**init**.py (AntdQRCode):15-77](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L15-L77) +- [qr-code.tsx:6-20](file://frontend/antd/qr-code/qr-code.tsx#L6-L20) + +Section Source + +- [**init**.py (AntdQRCode):24-77](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L24-L77) +- [Index.svelte (QRCode):22-45](file://frontend/antd/qr-code/Index.svelte#L22-L45) +- [qr-code.tsx:6-20](file://frontend/antd/qr-code/qr-code.tsx#L6-L20) +- [README-zh_CN.md (QRCode docs):1-8](file://docs/components/antd/qr_code/README-zh_CN.md#L1-L8) +- [README.md (QRCode docs):1-8](file://docs/components/antd/qr_code/README.md#L1-L8) + +## Dependency Analysis + +- Backend Component Class and Frontend Wrapper + - The backend class defines parameters and events; the frontend Svelte layer is responsible for the final assembly of props and slots +- React Encapsulation and Ant Design + - The React encapsulation layer converts slots into renderable nodes and safely passes callback functions to Ant Design components +- Event Binding + - Popover: open_change + - QRCode: refresh + +```mermaid +graph LR +BE["Backend Component Class"] --> FE["Svelte Wrapper"] +FE --> WR["React Encapsulation"] +WR --> AD["Ant Design Component"] +``` + +Diagram Source + +- [**init**.py (AntdPopover):14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) +- [Index.svelte (Popover):24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- [popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) +- [**init**.py (AntdQRCode):15-19](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L15-L19) +- [Index.svelte (QRCode):22-45](file://frontend/antd/qr-code/Index.svelte#L22-L45) +- [qr-code.tsx:6-20](file://frontend/antd/qr-code/qr-code.tsx#L6-L20) + +Section Source + +- [**init**.py (AntdPopover):14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) +- [Index.svelte (Popover):24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- [popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) +- [**init**.py (AntdQRCode):15-19](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L15-L19) +- [Index.svelte (QRCode):22-45](file://frontend/antd/qr-code/Index.svelte#L22-L45) +- [qr-code.tsx:6-20](file://frontend/antd/qr-code/qr-code.tsx#L6-L20) + +## Performance Considerations + +- Popover + - Set trigger modes and delays appropriately to avoid frequent re-renders + - For complex content, consider lazy loading or on-demand rendering + - The container mount point should be as close to the target element as possible to reduce DOM nesting depth +- QRCode + - Canvas output may create memory pressure at large sizes; consider using svg or reducing the size if necessary + - Icon overlay increases rendering overhead; lightweight icons are recommended + - The status render slot should only be enabled when needed to avoid unnecessary computation + +## Troubleshooting Guide + +- Popover + - Open state not taking effect: check open_change event binding and the open parameter + - Content not displayed: confirm that the title/content slots are correctly passed + - Positioning issues: check whether get_popup_container returns a valid container +- QRCode + - Cannot refresh: confirm that the refresh event is successfully bound + - Styles not taking effect: check whether color/bg_color and type settings are correct + - Scanning difficulties: increase error_level or enable boost_level + +Section Source + +- [**init**.py (AntdPopover):14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) +- [Index.svelte (Popover):24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- [**init**.py (AntdQRCode):15-19](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L15-L19) +- [Index.svelte (QRCode):22-45](file://frontend/antd/qr-code/Index.svelte#L22-L45) + +## Conclusion + +- Both Popover and QRCode follow a consistent three-layer encapsulation pattern, offering good extensibility and controllability +- Popover focuses on interaction and layout; QRCode focuses on data encoding and visual presentation +- It is recommended to combine the strategies and notes in this document when optimizing for complex layouts and mobile scenarios + +## Appendix + +- Demo Entry References + - Popover demo: [README-zh_CN.md (Popover docs)](file://docs/components/antd/popover/README-zh_CN.md#L7) + - QRCode demo: [README-zh_CN.md (QRCode docs)](file://docs/components/antd/qr_code/README-zh_CN.md#L7) diff --git a/.wiki/en/Ant Design Components/Data Display Components/Segmented and Statistic.md b/.wiki/en/Ant Design Components/Data Display Components/Segmented and Statistic.md new file mode 100644 index 00000000..6ff7a19b --- /dev/null +++ b/.wiki/en/Ant Design Components/Data Display Components/Segmented and Statistic.md @@ -0,0 +1,312 @@ +# Segmented and Statistic + + +**Files Referenced in This Document** +- [frontend/antd/segmented/segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js](file://backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js) +- [backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js](file://backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js) +- [frontend/antd/statistic/statistic.tsx](file://frontend/antd/statistic/statistic.tsx) +- [backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js](file://backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx](file://frontend/antd/statistic/countdown/statistic.countdown.tsx) +- [frontend/antd/statistic/timer/statistic.timer.tsx](file://frontend/antd/statistic/timer/statistic.timer.tsx) +- [docs/components/antd/segmented/README-zh_CN.md](file://docs/components/antd/segmented/README-zh_CN.md) +- [docs/components/antd/statistic/README-zh_CN.md](file://docs/components/antd/statistic/README-zh_CN.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document focuses on two frontend components: **Segmented** and **Statistic**. The former is used for selecting among multiple mutually exclusive options; the latter is used for displaying numeric values, titles, prefixes/suffixes, and supports countdown and timer functionality. This document systematically explains the design and usage of these two components from the perspectives of architecture, data flow, processing logic, integration points, error handling, and performance characteristics, with visual diagrams for better understanding. + +## Project Structure + +- Components are composed of a frontend adaptation layer (React wrapper + Svelte pre-processing) and a backend template rendering layer (Svelte runtime bridge). +- Segmented injects option collections via context, supporting combined use with "option" groups; the Statistic component supports flexible extension through slots and function-based formatters. +- The documentation side provides basic demo entry points for quick onboarding. + +```mermaid +graph TB +subgraph "Frontend Adaptation Layer" +S_Tsx["segmented.tsx
React wrapper + render options"] +ST_Tsx["statistic.tsx
React wrapper + slots/formatter"] +CD_Tsx["countdown.tsx
React wrapper + countdown"] +TM_Tsx["timer.tsx
React wrapper + timer"] +end +subgraph "Backend Template Rendering Layer" +S_JS["segmented-Ds7q4Ezu.js
Svelte runtime bridge"] +SO_JS["segmented.option-CS0TqVwO.js
Option item implementation"] +ST_JS["statistic-DvxTRiyV.js
Svelte runtime bridge"] +end +subgraph "External Dependencies" +Antd["Ant Design Component Library"] +end +S_Tsx --> S_JS +ST_Tsx --> ST_JS +CD_Tsx --> Antd +TM_Tsx --> Antd +SO_JS --> S_JS +``` + +**Diagram Source** + +- [frontend/antd/segmented/segmented.tsx:1-47](file://frontend/antd/segmented/segmented.tsx#L1-L47) +- [backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js:695-719](file://backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js#L695-L719) +- [backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js:441-447](file://backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js#L441-L447) +- [frontend/antd/statistic/statistic.tsx:1-34](file://frontend/antd/statistic/statistic.tsx#L1-L34) +- [backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js:685-715](file://backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js#L685-L715) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:1-27](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L1-L27) +- [frontend/antd/statistic/timer/statistic.timer.tsx:1-29](file://frontend/antd/statistic/timer/statistic.timer.tsx#L1-L29) + +**Section Source** + +- [docs/components/antd/segmented/README-zh_CN.md:1-8](file://docs/components/antd/segmented/README-zh_CN.md#L1-L8) +- [docs/components/antd/statistic/README-zh_CN.md:1-9](file://docs/components/antd/statistic/README-zh_CN.md#L1-L9) + +## Core Components + +- Segmented + - Supports passing an options array via props or injecting option collections via "option" slots. + - Provides a combination of the onValueChange callback and the native onChange event. + - Supports disabled state and block-level display (achieved by hiding children). +- Statistic + - Supports combined use of title, prefix, suffix, and formatter as both slots and props. + - Supports custom formatter functions and ReactSlot slot rendering. +- Statistic Sub-components + - Countdown: accepts timestamps or millisecond values and automatically converts them to milliseconds. + - Timer: a timer display based on the current time. + +**Section Source** + +- [frontend/antd/segmented/segmented.tsx:10-44](file://frontend/antd/segmented/segmented.tsx#L10-L44) +- [frontend/antd/statistic/statistic.tsx:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:6-24](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L6-L24) +- [frontend/antd/statistic/timer/statistic.timer.tsx:10-26](file://frontend/antd/statistic/timer/statistic.timer.tsx#L10-L26) + +## Architecture Overview + +The following diagram shows the complete call chain from the Svelte template to the React wrapper and then to the Ant Design component, and how slots and context participate in rendering. + +```mermaid +sequenceDiagram +participant Svelte as "Svelte Template" +participant Bridge as "Svelte Runtime Bridge" +participant ReactWrap as "React Wrapper Layer" +participant Antd as "Ant Design Component" +Svelte->>Bridge : "Generate nodes/slot mappings" +Bridge->>ReactWrap : "Create React elements and inject context/slots" +ReactWrap->>Antd : "Pass props/slots/event callbacks" +Antd-->>ReactWrap : "Render result" +ReactWrap-->>Bridge : "Bridge DOM/Portal" +Bridge-->>Svelte : "Complete mount/update" +``` + +**Diagram Source** + +- [backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js:695-719](file://backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js#L695-L719) +- [backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js:685-715](file://backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js#L685-L715) +- [backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js:441-447](file://backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js#L441-L447) + +## Detailed Component Analysis + +### Segmented Analysis + +- Option Configuration and "Option Group" Combination + - Injects "options/default" slot groups via context; options takes priority, falling back to default. + - Uses useMemo to cache the option list and avoid unnecessary re-renders. +- Controlled and Uncontrolled Modes + - Externally, value/onChange can be passed directly for controlled mode; onValueChange is also provided as an internal value change callback. +- Disabled State and Block-Level Display + - Structural consistency is maintained by hiding children, without affecting the outer layout. +- Dynamic Updates and Style Customization + - Option items achieve dynamic slot and context injection via the bridge runtime, with style and event forwarding support. + +```mermaid +flowchart TD +Start(["Enter Segmented render"]) --> CheckSlots["Check slots: options vs default"] +CheckSlots --> HasOptions{"Has options?"} +HasOptions --> |Yes| UseOptions["Use options option set"] +HasOptions --> |No| UseDefault["Use default option set"] +UseOptions --> Resolve["Render as Antd options array"] +UseDefault --> Resolve +Resolve --> Wrap["Wrap as Antd Segmented and bind onChange/onValueChange"] +Wrap --> End(["Rendering complete"]) +``` + +**Diagram Source** + +- [frontend/antd/segmented/segmented.tsx:15-44](file://frontend/antd/segmented/segmented.tsx#L15-L44) +- [backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js:695-719](file://backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js#L695-L719) + +**Section Source** + +- [frontend/antd/segmented/segmented.tsx:10-44](file://frontend/antd/segmented/segmented.tsx#L10-L44) +- [backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js:695-719](file://backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js#L695-L719) +- [backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js:441-447](file://backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js#L441-L447) + +### Statistic Analysis + +- Value Display, Unit Settings, and Formatting + - Supports dual-channel (slot + prop) for title/prefix/suffix; formatter supports both function and slot forms. +- Countdown and Timer + - Both countdown and timer convert value to milliseconds to ensure consistency with what the Antd component expects. +- Combining Slots and Function-Based Formatters + - When slots.formatter is present, the slot render takes priority; otherwise it falls back to the function-based formatter. + +```mermaid +sequenceDiagram +participant User as "User Code" +participant Stat as "Statistic Wrapper Layer" +participant Slots as "Slot System" +participant Antd as "Antd Statistic" +User->>Stat : "Pass value/title/prefix/suffix/formatter" +Stat->>Slots : "Detect slots.formatter/title/prefix/suffix" +alt slots.formatter exists +Slots-->>Stat : "Return slot render function" +else slots.formatter does not exist +Stat-->>Stat : "Use formatter function" +end +Stat->>Antd : "Pass props and render functions" +Antd-->>User : "Render statistic value" +``` + +**Diagram Source** + +- [frontend/antd/statistic/statistic.tsx:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) +- [backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js:685-715](file://backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js#L685-L715) + +**Section Source** + +- [frontend/antd/statistic/statistic.tsx:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:6-24](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L6-L24) +- [frontend/antd/statistic/timer/statistic.timer.tsx:10-26](file://frontend/antd/statistic/timer/statistic.timer.tsx#L10-L26) + +### Component Class Relationship Diagram (Code Level) + +```mermaid +classDiagram +class SegmentedWrapper { ++props : GetProps
frontend/antd/table/table.tsx"] +CtxT["Table Context
frontend/antd/table/context.ts"] +Col["Column Handler
frontend/antd/table/column/table.column.tsx"] +ColG["Column Group Handler
frontend/antd/table/column-group/table.column-group.tsx"] +Exp["Expandable Handler
frontend/antd/table/expandable/table.expandable.tsx"] +RSel["Row Selection Handler
frontend/antd/table/row-selection/table.row-selection.tsx"] +end +subgraph "Tabs Component" +Tabs["Tabs Container
frontend/antd/tabs/tabs.tsx"] +CtxTabs["Tabs Context
frontend/antd/tabs/context.ts"] +TabsItem["Tab Item Handler
frontend/antd/tabs/item/tabs.item.tsx"] +end +T --> CtxT +T --> Col +T --> ColG +T --> Exp +T --> RSel +Tabs --> CtxTabs +Tabs --> TabsItem +``` + +**Diagram Source** + +- [table.tsx:28-276](file://frontend/antd/table/table.tsx#L28-L276) +- [context.ts](file://frontend/antd/table/context.ts) +- [table.column.tsx:20-97](file://frontend/antd/table/column/table.column.tsx#L20-L97) +- [table.column-group.tsx:7-19](file://frontend/antd/table/column-group/table.column-group.tsx#L7-L19) +- [table.expandable.tsx:7-11](file://frontend/antd/table/expandable/table.expandable.tsx#L7-L11) +- [table.row-selection.tsx:13-35](file://frontend/antd/table/row-selection/table.row-selection.tsx#L13-L35) +- [tabs.tsx:12-118](file://frontend/antd/tabs/tabs.tsx#L12-L118) +- [tabs.context.ts](file://frontend/antd/tabs/context.ts) +- [tabs.item.tsx:7-11](file://frontend/antd/tabs/item/tabs.item.tsx#L7-L11) + +**Section Source** + +- [table.tsx:28-276](file://frontend/antd/table/table.tsx#L28-L276) +- [tabs.tsx:12-118](file://frontend/antd/tabs/tabs.tsx#L12-L118) + +## Core Components + +- Table Container: handles unified processing and slot rendering for columns, rowSelection, expandable, sticky, showSorterTooltip, pagination, loading, footer, title, and other props. +- Column Handler: enhances column configuration with support for filter dropdown menus, custom popup rendering, menu expand icons, and overflow indicators. +- Column Group Handler: groups a set of columns as a logical unit, facilitating header merging and style control. +- Expandable Handler: injects expandable configuration into the table. +- Row Selection Handler: injects custom selection items (e.g., "Select All", "Invert Selection") into rowSelection. +- Tabs Container: handles unified processing and slot rendering for items, indicator, renderTabBar, more, tabBarExtraContent, addIcon, removeIcon, and other props. +- Tab Item Handler: injects individual tab items into Tabs' items. + +**Section Source** + +- [table.tsx:28-276](file://frontend/antd/table/table.tsx#L28-L276) +- [table.column.tsx:20-97](file://frontend/antd/table/column/table.column.tsx#L20-L97) +- [table.column-group.tsx:7-19](file://frontend/antd/table/column-group/table.column-group.tsx#L7-L19) +- [table.expandable.tsx:7-11](file://frontend/antd/table/expandable/table.expandable.tsx#L7-L11) +- [table.row-selection.tsx:13-35](file://frontend/antd/table/row-selection/table.row-selection.tsx#L13-L35) +- [tabs.tsx:12-118](file://frontend/antd/tabs/tabs.tsx#L12-L118) +- [tabs.item.tsx:7-11](file://frontend/antd/tabs/item/tabs.item.tsx#L7-L11) + +## Architecture Overview + +The following diagram shows the dependency relationships and division of responsibilities between the Table and Tabs containers and their item handlers. + +```mermaid +classDiagram +class Table { ++props : columns,rowSelection,expandable,sticky,showSorterTooltip,pagination,loading,footer,title ++slots : title,footer,loading.tip,loading.indicator,pagination.showQuickJumper.goButton,pagination.itemRender,showSorterTooltip.title,summary +} +class TableColumn { ++enhancement : filterDropdownProps.menu +} +class TableColumnGroup +class TableExpandable +class TableRowSelection +class Tabs { ++props : items,indicator,more,renderTabBar,tabBarExtraContent,addIcon,removeIcon ++slots : renderTabBar,tabBarExtraContent.left,right,more.icon +} +class TabsItem +Table --> TableColumn : "uses" +Table --> TableColumnGroup : "uses" +Table --> TableExpandable : "uses" +Table --> TableRowSelection : "uses" +Tabs --> TabsItem : "uses" +``` + +**Diagram Source** + +- [table.tsx:28-276](file://frontend/antd/table/table.tsx#L28-L276) +- [table.column.tsx:20-97](file://frontend/antd/table/column/table.column.tsx#L20-L97) +- [table.column-group.tsx:7-19](file://frontend/antd/table/column-group/table.column-group.tsx#L7-L19) +- [table.expandable.tsx:7-11](file://frontend/antd/table/expandable/table.expandable.tsx#L7-L11) +- [table.row-selection.tsx:13-35](file://frontend/antd/table/row-selection/table.row-selection.tsx#L13-L35) +- [tabs.tsx:12-118](file://frontend/antd/tabs/tabs.tsx#L12-L118) +- [tabs.item.tsx:7-11](file://frontend/antd/tabs/item/tabs.item.tsx#L7-L11) + +## Detailed Component Analysis + +### Table Component + +- Column Definition (column) + - Supports directly passing columns or injecting via TableColumn; + - Recognizes and converts special placeholders (such as EXPAND_COLUMN, SELECTION_COLUMN); + - Enhances filterDropdownProps with support for menu items, dropdown rendering, popup rendering, menu expand icons, and overflow indicators. +- Column Group (column_group) + - Groups a set of columns as a logical unit for header merging and style control; + - Only the default slot is allowed. +- Expandable Rows (expandable) + - Injects expandable configuration via TableExpandable; + - Supports custom rendering of expanded content. +- Row Selection (row_selection) + - Injects rowSelection via TableRowSelection; + - Supports custom selection items via selections (e.g., "Select All", "Invert Selection"). +- Sorting, Filtering, and Pagination + - Supports slot-based title for showSorterTooltip; + - Supports slot-based jump button and page item rendering for pagination; + - Supports tip and indicator slots for loading; + - Supports container getter function for sticky; + - Supports slot-based rendering for footer and summary. +- Large Datasets and Virtual Scrolling + - It is recommended to combine external virtual scrolling solutions (e.g., fixed height + scrollable container) to reduce DOM node count; + - Use onScroll with pagination/infinite scrolling to avoid rendering large numbers of rows at once. +- Responsive Design + - Use sticky and column width settings to prioritize key columns on small screens; + - Use the column's responsive configuration or a custom breakpoint strategy. + +```mermaid +sequenceDiagram +participant U as "User" +participant T as "Table Container" +participant C as "Column/Expandable/RowSelection Handler" +participant R as "Ant Design Table" +U->>T : Provide columns/rowSelection/expandable/pagination props +T->>C : Inject child items and enhance configuration +C-->>T : Return enhanced configuration +T->>R : Forward props and render slots +R-->>U : Render table UI +``` + +**Diagram Source** + +- [table.tsx:66-271](file://frontend/antd/table/table.tsx#L66-L271) +- [table.column.tsx:28-93](file://frontend/antd/table/column/table.column.tsx#L28-L93) +- [table.expandable.tsx:9-10](file://frontend/antd/table/expandable/table.expandable.tsx#L9-L10) +- [table.row-selection.tsx:21-32](file://frontend/antd/table/row-selection/table.row-selection.tsx#L21-L32) + +**Section Source** + +- [table.tsx:28-276](file://frontend/antd/table/table.tsx#L28-L276) +- [table.column.tsx:20-97](file://frontend/antd/table/column/table.column.tsx#L20-L97) +- [table.column-group.tsx:7-19](file://frontend/antd/table/column-group/table.column-group.tsx#L7-L19) +- [table.expandable.tsx:7-11](file://frontend/antd/table/expandable/table.expandable.tsx#L7-L11) +- [table.row-selection.tsx:13-35](file://frontend/antd/table/row-selection/table.row-selection.tsx#L13-L35) + +### Tabs Component + +- Tab Items + - Inject individual tab items via TabsItem; + - Supports basic props such as disabled, closable, and closeIcon. +- Position Control and Dynamic Add/Remove + - Control tab addition/removal via the dynamic items array; + - indicator controls the bottom bar style with size function support; + - addIcon/removeIcon support slot-based icons. +- Lazy Content Loading + - It is recommended to render only the active panel's content on activation, avoiding rendering all panels at once; + - Load data and components on demand in the onChange event. +- Tab Icons and Close Button + - Customize icons via addIcon/removeIcon slots; + - closable and closeIcon control whether tabs can be closed and the close icon appearance. +- Drag-to-Reorder + - Can be implemented using an external drag library combined with onChange; + - Be careful to maintain consistency between items order and activeKey. +- More Menu and Extra Content + - more.icon supports a slot-based icon; + - tabBarExtraContent supports slot-based content on both the left and right sides. + +```mermaid +sequenceDiagram +participant U as "User" +participant Tabs as "Tabs Container" +participant Item as "TabsItem Handler" +participant AD as "Ant Design Tabs" +U->>Tabs : Provide items/addIcon/removeIcon/more/tabBarExtraContent +Tabs->>Item : Inject tab items and enhance configuration +Item-->>Tabs : Return enhanced tab items +Tabs->>AD : Forward props and render slots +AD-->>U : Render tabs UI +``` + +**Diagram Source** + +- [tabs.tsx:26-115](file://frontend/antd/tabs/tabs.tsx#L26-L115) +- [tabs.item.tsx:9-10](file://frontend/antd/tabs/item/tabs.item.tsx#L9-L10) + +**Section Source** + +- [tabs.tsx:12-118](file://frontend/antd/tabs/tabs.tsx#L12-L118) +- [tabs.item.tsx:7-11](file://frontend/antd/tabs/item/tabs.item.tsx#L7-L11) + +### Navigation Strategies in Complex Layouts + +- Responsive Navigation + - On narrow screens, enable the Tabs more menu to move less-used tabs into a dropdown; + - Use sticky or fixed headers to keep navigation always visible. +- Nested Usage + - When nesting child tabs or subtables inside tabs, be mindful of hierarchy and interaction conflicts; + - Use independent contexts and namespaces to avoid event bubbling and state pollution. +- Navigation Consistency + - Use onChange and activeKey uniformly to manage the current active state; + - For asynchronously loaded data, display a skeleton screen first, then switch to real content. + +## Dependency Analysis + +- Table Side + - The Table container depends on context providers (Column, Expandable, RowSelection) to collect child items; + - TableColumn enhances filterDropdownProps and reuses the menu context; + - TableRowSelection injects selections. +- Tabs Side + - The Tabs container relies on the Items context to collect tab items; + - TabsItem injects individual tab items. + +```mermaid +graph LR +subgraph "Table Dependencies" +CTX["Table Context"] +COL["Column Handler"] +COLG["Column Group Handler"] +EXP["Expandable Handler"] +SEL["Row Selection Handler"] +TBL["Table Container"] +TBL --> CTX +TBL --> COL +TBL --> COLG +TBL --> EXP +TBL --> SEL +end +subgraph "Tabs Dependencies" +CTXS["Tabs Context"] +ITEM["Tab Item Handler"] +TABS["Tabs Container"] +TABS --> CTXS +TABS --> ITEM +end +``` + +**Diagram Source** + +- [context.ts](file://frontend/antd/table/context.ts) +- [table.tsx:41-275](file://frontend/antd/table/table.tsx#L41-L275) +- [tabs.context.ts](file://frontend/antd/tabs/context.ts) +- [tabs.tsx:24-117](file://frontend/antd/tabs/tabs.tsx#L24-L117) + +**Section Source** + +- [table.tsx:41-275](file://frontend/antd/table/table.tsx#L41-L275) +- [tabs.tsx:24-117](file://frontend/antd/tabs/tabs.tsx#L24-L117) + +## Performance Considerations + +- Table + - Large datasets: use fixed height + virtual scrolling (e.g., external library) to reduce DOM node count; + - Pagination/infinite scrolling: combine with backend pagination to avoid rendering everything at once; + - Column rendering: only render necessary columns, hide non-critical ones; + - Event binding: use throttle/debounce for onRow/onHeaderRow. +- Tabs + - Lazy content loading: only render on activation; + - Dynamic add/remove: batch update items to avoid frequent re-renders; + - Icons and slots: use lightweight components and avoid complex computations. + +## Troubleshooting Guide + +- Slots not taking effect + - Confirm that slot key names match container declarations (such as pagination.showQuickJumper.goButton, more.icon, etc.); + - Check that slots are correctly wrapped inside child items. +- Props not taking effect + - Confirm that function-type props are wrapped with useFunction; + - Check that object-type props (such as sticky, showSorterTooltip, pagination) are correctly merged. +- Style anomalies + - Check whether getPopupContainer/getContainer returns the correct mount node; + - Confirm that the ReactSlot render target container inside slots exists and is visible. + +**Section Source** + +- [table.tsx:76-108](file://frontend/antd/table/table.tsx#L76-L108) +- [tabs.tsx:36-39](file://frontend/antd/tabs/tabs.tsx#L36-L39) + +## Conclusion + +This document systematically reviews the capability boundaries and extension points of the Table and Tabs components from an architectural and implementation perspective. Through the collaboration of container components and item handlers, prop forwarding, slot rendering, and configuration enhancement are achieved. Combined with large dataset handling, virtual scrolling, lazy loading, and responsive strategies, they can provide a stable and maintainable navigation experience in complex layouts. + +## Appendix + +- Key Implementation Points + - Table: slotting and function wrapping for columns, rowSelection, expandable, sticky, showSorterTooltip, pagination, loading, footer, and title; + - Tabs: slotting and function wrapping for items, indicator, renderTabBar, more, tabBarExtraContent, addIcon, and removeIcon. +- Extension Recommendations + - Table: introduce virtual scrolling with pagination integration; customize column groups and expandable content based on business scenarios; + - Tabs: combine with routing and state management to implement dynamic add/remove and persistence; support drag-to-reorder and the more menu. diff --git a/.wiki/en/Ant Design Components/Data Display Components/Tag and Timeline.md b/.wiki/en/Ant Design Components/Data Display Components/Tag and Timeline.md new file mode 100644 index 00000000..1e987675 --- /dev/null +++ b/.wiki/en/Ant Design Components/Data Display Components/Tag and Timeline.md @@ -0,0 +1,438 @@ +# Tag and Timeline + + +**Files Referenced in This Document** +- [frontend/antd/tag/tag.tsx](file://frontend/antd/tag/tag.tsx) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx) +- [frontend/antd/tag/checkable-tag/Index.svelte](file://frontend/antd/tag/checkable-tag/Index.svelte) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx) +- [frontend/antd/tag/checkable-tag-group/Index.svelte](file://frontend/antd/tag/checkable-tag-group/Index.svelte) +- [frontend/antd/tag/checkable-tag-group/context.ts](file://frontend/antd/tag/checkable-tag-group/context.ts) +- [frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx](file://frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx) +- [frontend/antd/tag/checkable-tag-group/option/Index.svelte](file://frontend/antd/tag/checkable-tag-group/option/Index.svelte) +- [frontend/antd/timeline/timeline.tsx](file://frontend/antd/timeline/timeline.tsx) +- [frontend/antd/timeline/item/Index.svelte](file://frontend/antd/timeline/item/Index.svelte) +- [frontend/antd/timeline/context.ts](file://frontend/antd/timeline/context.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/hooks/useTargets.ts](file://frontend/utils/hooks/useTargets.ts) +- [docs/components/antd/tag/demos/checkable_tag.py](file://docs/components/antd/tag/demos/checkable_tag.py) +- [docs/components/antd/timeline/demos/basic.py](file://docs/components/antd/timeline/demos/basic.py) + + +## Update Summary + +**Changes Made** + +- Added the CheckableTagGroup component system, including the CheckableTagGroup main component and CheckableTagGroupOption child component +- Updated Timeline component documentation to reflect the simplified implementation of the Timeline.Item component +- Enhanced batch operation capabilities and dynamic option management for tag groups +- Improved context management and option handling mechanisms for CheckableTagGroup + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document focuses on the **Tag** and **Timeline** components, systematically explaining their design philosophy, data flow, interaction behavior, and extensibility. Key topics include: + +- Tag: interaction states for regular and checkable tags, color configuration, dynamic tag management, click events, delete functionality, and batch operation recommendations. +- **New**: CheckableTagGroup component system supporting batch tag selection, dynamic option management, and grouped operations. +- Timeline: time nodes (Items), direction control, node customization, and style customization; as well as implementation paths for reversed display, custom icons, and line style adjustments. + +## Project Structure + +- The component layer uses a pattern of "frontend Svelte wrapper + backend Python component bridge"; the frontend adapts Ant Design's React components into Svelte components via sveltify, and introduces the Items context and slot rendering mechanism where necessary. +- The utility layer provides general capabilities such as items context, slot rendering, and target element resolution, supporting dynamic item management for complex container components (such as Timeline). + +```mermaid +graph TB +subgraph "Tag Component" +TAG["Tag
frontend/antd/tag/tag.tsx"] +CTAG["CheckableTag
frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx"] +CTAG_IDX["CheckableTag Wrapper
frontend/antd/tag/checkable-tag/Index.svelte"] +CTAG_GROUP["CheckableTagGroup
frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx"] +CTAG_GROUP_IDX["CheckableTagGroup Wrapper
frontend/antd/tag/checkable-tag-group/Index.svelte"] +CTAG_OPTION["CheckableTagGroupOption
frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx"] +CTAG_OPTION_IDX["CheckableTagGroupOption Wrapper
frontend/antd/tag/checkable-tag-group/option/Index.svelte"] +end +subgraph "Timeline Component" +TL["Timeline
frontend/antd/timeline/timeline.tsx"] +TL_ITEM["Timeline.Item
frontend/antd/timeline/item/Index.svelte"] +TL_CTX["Timeline Context
frontend/antd/timeline/context.ts"] +end +subgraph "Utility Library" +CREATE_ITEMS["createItemsContext
frontend/utils/createItemsContext.tsx"] +RENDER_ITEMS["renderItems
frontend/utils/renderItems.tsx"] +USE_TARGETS["useTargets
frontend/utils/hooks/useTargets.ts"] +end +TAG --> USE_TARGETS +CTAG --> USE_TARGETS +CTAG_GROUP --> CTAG_GROUP_IDX +CTAG_GROUP_IDX --> CTAG_GROUP +CTAG_OPTION --> CTAG_OPTION_IDX +CTAG_OPTION_IDX --> CTAG_OPTION +TL --> TL_CTX +TL_CTX --> CREATE_ITEMS +TL --> RENDER_ITEMS +TL_ITEM --> TL_CTX +``` + +**Diagram Source** + +- [frontend/antd/tag/tag.tsx:1-35](file://frontend/antd/tag/tag.tsx#L1-L35) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:1-35](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L1-L35) +- [frontend/antd/tag/checkable-tag/Index.svelte:1-77](file://frontend/antd/tag/checkable-tag/Index.svelte#L1-L77) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:1-51](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L1-L51) +- [frontend/antd/tag/checkable-tag-group/Index.svelte:1-79](file://frontend/antd/tag/checkable-tag-group/Index.svelte#L1-L79) +- [frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx:1-14](file://frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx#L1-L14) +- [frontend/antd/tag/checkable-tag-group/option/Index.svelte:1-74](file://frontend/antd/tag/checkable-tag-group/option/Index.svelte#L1-L74) +- [frontend/antd/timeline/timeline.tsx:1-50](file://frontend/antd/timeline/timeline.tsx#L1-L50) +- [frontend/antd/timeline/item/Index.svelte:1-65](file://frontend/antd/timeline/item/Index.svelte#L1-L65) +- [frontend/antd/timeline/context.ts:1-7](file://frontend/antd/timeline/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/hooks/useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) + +**Section Source** + +- [frontend/antd/tag/tag.tsx:1-35](file://frontend/antd/tag/tag.tsx#L1-L35) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:1-35](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L1-L35) +- [frontend/antd/tag/checkable-tag/Index.svelte:1-77](file://frontend/antd/tag/checkable-tag/Index.svelte#L1-L77) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:1-51](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L1-L51) +- [frontend/antd/tag/checkable-tag-group/Index.svelte:1-79](file://frontend/antd/tag/checkable-tag-group/Index.svelte#L1-L79) +- [frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx:1-14](file://frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx#L1-L14) +- [frontend/antd/tag/checkable-tag-group/option/Index.svelte:1-74](file://frontend/antd/tag/checkable-tag-group/option/Index.svelte#L1-L74) +- [frontend/antd/timeline/timeline.tsx:1-50](file://frontend/antd/timeline/timeline.tsx#L1-L50) +- [frontend/antd/timeline/item/Index.svelte:1-65](file://frontend/antd/timeline/item/Index.svelte#L1-L65) +- [frontend/antd/timeline/context.ts:1-7](file://frontend/antd/timeline/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/hooks/useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) + +## Core Components + +- Tag + - Regular tag: supports text and icons, closeIcon slot, and value field fallback rendering. + - CheckableTag: two-way binding for checked state, supports label text fallback, icon slot, and change callback. + - **New**: CheckableTagGroup: supports batch tag selection, dynamic option management, and grouped operations. +- Timeline + - Supports dynamic items injection and default slot fallback; supports pending/pendingDot slots; internally collects child items via the Items context and renders them. + +**Section Source** + +- [frontend/antd/tag/tag.tsx:7-32](file://frontend/antd/tag/tag.tsx#L7-L32) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:7-32](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L7-L32) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:8-48](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L8-L48) +- [frontend/antd/timeline/timeline.tsx:9-47](file://frontend/antd/timeline/timeline.tsx#L9-L47) + +## Architecture Overview + +Both Tag and Timeline bridge Ant Design's React components into the Svelte ecosystem via sveltify, while leveraging slots and context to achieve flexible dynamic rendering and prop forwarding. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Svelte as "Svelte Wrapper Layer" +participant Utils as "Utility Library" +participant Antd as "Ant Design Component" +Dev->>Svelte : Pass props and slots +Svelte->>Utils : Parse slots/target elements/context +Utils-->>Svelte : Return processed props and render functions +Svelte->>Antd : Render final component tree +Antd-->>Dev : Output UI result +``` + +**Diagram Source** + +- [frontend/antd/tag/tag.tsx:12-32](file://frontend/antd/tag/tag.tsx#L12-L32) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:13-32](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L13-L32) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:14-46](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L14-L46) +- [frontend/antd/timeline/timeline.tsx:15-46](file://frontend/antd/timeline/timeline.tsx#L15-L46) + +## Detailed Component Analysis + +### Tag Component + +- Regular Tag + - Key points: supports icon/closeIcon slots; when target child nodes are present, child nodes take rendering priority over the children + value fallback. + - Use cases: category labels, status badges, closable temporary tags. +- CheckableTag + - Key points: supports checked/value props and onValueChange callback; supports label text fallback; onChange is triggered in the callback chain. + - Use cases: multi-select filtering, preference settings, category checkboxes. +- **New**: CheckableTagGroup + - Key points: supports an options array or default slot fallback; injects context via ItemHandler, recording each child item's props, slots, and nested children. + - Use cases: batch tag selection, category filtering, multi-option group management. + +```mermaid +classDiagram +class Tag { ++props : All Ant Design Tag supported props ++slots : icon, closeIcon ++value? : string +} +class CheckableTag { ++props : Ant Design Tag.CheckableTag props ++slots : icon ++onValueChange(checked) ++label? : string +} +class CheckableTagGroup { ++props : Ant Design Tag.CheckableTagGroup props ++slots : options, default ++onValueChange(value) ++options? : array +} +class CheckableTagGroupOption { ++props : Single tag option props ++slots : default ++itemIndex : number ++itemSlotKey : string +} +Tag --> "uses" useTargets +CheckableTag --> "uses" useTargets +CheckableTagGroup --> "uses" createItemsContext +CheckableTagGroupOption --> "uses" ItemHandler +``` + +**Diagram Source** + +- [frontend/antd/tag/tag.tsx:7-32](file://frontend/antd/tag/tag.tsx#L7-L32) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:7-32](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L7-L32) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:8-48](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L8-L48) +- [frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx:7-13](file://frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx#L7-L13) +- [frontend/utils/hooks/useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [frontend/antd/tag/checkable-tag-group/context.ts:3-4](file://frontend/antd/tag/checkable-tag-group/context.ts#L3-L4) + +**Section Source** + +- [frontend/antd/tag/tag.tsx:7-32](file://frontend/antd/tag/tag.tsx#L7-L32) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:7-32](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L7-L32) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:8-48](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L8-L48) +- [frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx:7-13](file://frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx#L7-L13) +- [frontend/utils/hooks/useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [frontend/antd/tag/checkable-tag-group/context.ts:3-4](file://frontend/antd/tag/checkable-tag-group/context.ts#L3-L4) + +#### Interaction and State + +- Regular Tag + - Click events: handled by Antd native events; onClick and other events can be forwarded via props. + - Delete: achievable by combining the closeIcon slot with the closeIcon prop. +- CheckableTag + - Checked state: two-way binding via value/checked; onValueChange callback for state synchronization. + - Batch operations: manage the value of multiple CheckableTags in a parent container and update them in bulk. +- **New**: CheckableTagGroup + - Checked state: supports single-select and multi-select modes; onValueChange returns a selected value array or a single value. + - Dynamic options: dynamically add/remove tag options via the options prop or default slot. + - Group management: supports nested tag groups and batch operations at the group level. + +**Section Source** + +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:23-26](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L23-L26) +- [frontend/antd/tag/checkable-tag/Index.svelte:69-71](file://frontend/antd/tag/checkable-tag/Index.svelte#L69-L71) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:39-42](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L39-L42) +- [frontend/antd/tag/checkable-tag-group/Index.svelte:71-73](file://frontend/antd/tag/checkable-tag-group/Index.svelte#L71-L73) + +#### Color Configuration and Dynamic Management + +- Color: supports preset color palettes and custom hex values via the color prop. +- Dynamic: combining backend component bridging and frontend prop forwarding enables runtime dynamic switching of colors and text. +- **New**: Tag group color: supports setting a unified color theme for the entire tag group while preserving per-tag color overrides. + +**Section Source** + +- [docs/components/antd/tag/demos/checkable_tag.py:10-15](file://docs/components/antd/tag/demos/checkable_tag.py#L10-L15) + +#### Application in Search Results + +- Recommendation: add Tags to search result entries as category/status identifiers; use CheckableTag for multi-dimensional filtering; use closeIcon to remove filter conditions in one click. +- **New**: Use CheckableTagGroup for advanced filtering: supports multi-dimensional tag combination filtering, batch operations, and saving filter conditions. + +### Timeline Component + +- Timeline Body + - Supports an items array or default slot fallback; pending/pendingDot slots can customize the "in progress" state. + - Internally collects child items via the Items context, then uses renderItems to convert them into the data structure required by Antd. +- **Updated**: Timeline Item (Timeline.Item) + - **Simplified implementation**: removed complex prop handling logic, directly forwarding all props and slots. + - Injects context via ItemHandler, recording each child item's props, slots, and nested children. + - Supports a custom dot slot to replace the timeline node icon. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant TL as "Timeline" +participant Ctx as "Items Context" +participant Item as "Timeline.Item" +participant Render as "renderItems" +Dev->>TL : Set items or fill default slot +TL->>Ctx : Wrap with withItemsContextProvider +TL->>Item : Render child items and inject context +Item->>Ctx : ItemHandler records props/slots/children +TL->>Render : Use renderItems to convert to Antd data structure +Render-->>TL : Return items array +TL-->>Dev : Render timeline +``` + +**Diagram Source** + +- [frontend/antd/timeline/timeline.tsx:13-46](file://frontend/antd/timeline/timeline.tsx#L13-L46) +- [frontend/antd/timeline/context.ts:3-4](file://frontend/antd/timeline/context.ts#L3-L4) +- [frontend/utils/createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) +- [frontend/utils/renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) +- [frontend/antd/timeline/item/Index.svelte:49-64](file://frontend/antd/timeline/item/Index.svelte#L49-L64) + +**Section Source** + +- [frontend/antd/timeline/timeline.tsx:13-46](file://frontend/antd/timeline/timeline.tsx#L13-L46) +- [frontend/antd/timeline/context.ts:3-4](file://frontend/antd/timeline/context.ts#L3-L4) +- [frontend/utils/createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) +- [frontend/utils/renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) +- [frontend/antd/timeline/item/Index.svelte:49-64](file://frontend/antd/timeline/item/Index.svelte#L49-L64) + +#### Direction Control and Style Customization + +- Direction control: use the mode prop (such as alternate) to control alternating display of timeline nodes. +- Style customization: supports the color prop for node coloring; the dot slot allows custom node icons; pending/pendingDot slots customize the "in progress" state. + +**Section Source** + +- [docs/components/antd/timeline/demos/basic.py:18-38](file://docs/components/antd/timeline/demos/basic.py#L18-L38) + +#### Reversed Display and Timeline Style Adjustments + +- Reversed display: reverse order can be achieved via mode or external layout; for complete reversal, reverse the items array before passing it in at the parent layer. +- Line styles: Antd Timeline's default styles can be adjusted via theme variables or overriding class names; custom styles can also be wrapped in a parent container. + +#### Custom Node Icons + +- Custom icons: inject any icon component via the dot slot in Timeline.Item to achieve personalized visual node expression. + +**Section Source** + +- [docs/components/antd/timeline/demos/basic.py:27-37](file://docs/components/antd/timeline/demos/basic.py#L27-L37) + +#### Visualization in Project Progress + +- Recommendations: express milestones, task nodes, version releases, and other events as Timeline.Items; use color to mark priority/status; use dot slot for status icons; use pending/pendingDot slots to highlight the current phase. + +## Dependency Analysis + +- Tag Component + - useTargets: resolves target elements among child nodes to determine whether to fall back to children + value. + - **New**: createItemsContext: provides context support for tag groups to manage option lists and state. +- Timeline Component + - createItemsContext: provides the Items context responsible for collecting and merging child items. + - renderItems: converts the Item structure in context into the items array required by Antd. + - useItems: reads the collected items in Timeline and passes them to Antd Timeline. + +```mermaid +graph LR +USE_TARGETS["useTargets"] --> TAG["Tag"] +USE_TARGETS --> CTAG["CheckableTag"] +CREATE_ITEMS["createItemsContext"] --> CTAG_GROUP["CheckableTagGroup"] +CREATE_ITEMS --> TL["Timeline"] +TL --> RENDER_ITEMS["renderItems"] +TL --> TL_ITEM["Timeline.Item"] +CTAG_GROUP --> CTAG_OPTION["CheckableTagGroupOption"] +CTAG_OPTION --> CREATE_ITEMS +TL_ITEM --> CREATE_ITEMS +``` + +**Diagram Source** + +- [frontend/utils/hooks/useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [frontend/antd/tag/tag.tsx:12-32](file://frontend/antd/tag/tag.tsx#L12-L32) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:13-32](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L13-L32) +- [frontend/antd/tag/checkable-tag-group/context.ts:1-7](file://frontend/antd/tag/checkable-tag-group/context.ts#L1-L7) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:6-6](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L6-L6) +- [frontend/antd/timeline/timeline.tsx:7-7](file://frontend/antd/timeline/timeline.tsx#L7-L7) +- [frontend/utils/createItemsContext.tsx:97-106](file://frontend/utils/createItemsContext.tsx#L97-L106) +- [frontend/antd/timeline/item/Index.svelte:13-13](file://frontend/antd/timeline/item/Index.svelte#L13-L13) + +**Section Source** + +- [frontend/utils/hooks/useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [frontend/antd/tag/tag.tsx:12-32](file://frontend/antd/tag/tag.tsx#L12-L32) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:13-32](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L13-L32) +- [frontend/antd/tag/checkable-tag-group/context.ts:1-7](file://frontend/antd/tag/checkable-tag-group/context.ts#L1-L7) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:6-6](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L6-L6) +- [frontend/antd/timeline/timeline.tsx:7-7](file://frontend/antd/timeline/timeline.tsx#L7-L7) +- [frontend/utils/createItemsContext.tsx:97-106](file://frontend/utils/createItemsContext.tsx#L97-L106) +- [frontend/antd/timeline/item/Index.svelte:13-13](file://frontend/antd/timeline/item/Index.svelte#L13-L13) + +## Performance Considerations + +- Rendering Optimization + - useTargets only recalculates sorting and filtering of child nodes when children change, avoiding unnecessary re-renders. + - renderItems controls context update frequency via memoizedEqualValue and useMemoizedFn. + - **New**: CheckableTagGroup ensures option cloning via clone: true parameter to avoid state pollution. +- Context Stability + - withItemsContextProvider and useItems keep context references stable via useMemo and useRef, reducing subtree re-renders. + - **New**: Tag group context provides stable option management via createItemsContext. +- Slot Clone Strategy + - renderItems supports clone/forceClone parameters to control node cloning on demand, balancing performance with scope isolation. + +**Section Source** + +- [frontend/utils/hooks/useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [frontend/utils/createItemsContext.tsx:113-156](file://frontend/utils/createItemsContext.tsx#L113-L156) +- [frontend/utils/renderItems.tsx:62-94](file://frontend/utils/renderItems.tsx#L62-L94) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:33-36](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L33-L36) + +## Troubleshooting Guide + +- Tag not displaying value + - Check whether children contain recognizable target nodes; if target nodes are present, they will take rendering priority over the value fallback. + - Reference path: [frontend/antd/tag/tag.tsx:22-29](file://frontend/antd/tag/tag.tsx#L22-L29) +- CheckableTag not triggering onValueChange + - Confirm that onValueChange is correctly passed; onChange is triggered before onValueChange, ensure the callback chain is complete. + - Reference path: [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:23-26](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L23-L26) +- **New**: CheckableTagGroup options not displayed + - Confirm that CheckableTagGroupOption is correctly used and content is injected via slots; check that the tag group context is active. + - Reference path: [frontend/antd/tag/checkable-tag-group/option/Index.svelte:55-73](file://frontend/antd/tag/checkable-tag-group/option/Index.svelte#L55-L73) +- **New**: Tag group value not updating + - Confirm that the onValueChange callback correctly handles the return value; check the tag group's value prop binding. + - Reference path: [frontend/antd/tag/checkable-tag-group/Index.svelte:71-73](file://frontend/antd/tag/checkable-tag-group/Index.svelte#L71-L73) +- Timeline not displaying any nodes + - Confirm that Timeline.Item is correctly used and content is injected via slots; check that the Items context is active. + - Reference path: [frontend/antd/timeline/item/Index.svelte:49-64](file://frontend/antd/timeline/item/Index.svelte#L49-L64) +- Custom dot not taking effect + - Ensure the dot slot is correctly declared inside Timeline.Item; check that slotKey matches the context. + - Reference path: [frontend/antd/timeline/item/Index.svelte:58-63](file://frontend/antd/timeline/item/Index.svelte#L58-L63) + +**Section Source** + +- [frontend/antd/tag/tag.tsx:22-29](file://frontend/antd/tag/tag.tsx#L22-L29) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:23-26](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L23-L26) +- [frontend/antd/tag/checkable-tag-group/option/Index.svelte:55-73](file://frontend/antd/tag/checkable-tag-group/option/Index.svelte#L55-L73) +- [frontend/antd/tag/checkable-tag-group/Index.svelte:71-73](file://frontend/antd/tag/checkable-tag-group/Index.svelte#L71-L73) +- [frontend/antd/timeline/item/Index.svelte:49-64](file://frontend/antd/timeline/item/Index.svelte#L49-L64) +- [frontend/antd/timeline/item/Index.svelte:58-63](file://frontend/antd/timeline/item/Index.svelte#L58-L63) + +## Conclusion + +- The Tag component achieves flexible content fallback and icon extension through slot and target element resolution; CheckableTag provides a concise two-way binding and callback mechanism, suitable for multi-select and filtering scenarios. +- **New**: CheckableTagGroup provides powerful batch tag selection capabilities through a complete context system and option management, suitable for complex filtering and grouping scenarios. +- The Timeline component uses the Items context and renderItems to convert complex nested structures into the array form required by Antd, offering good extensibility and customization capabilities. +- In real business scenarios, combining backend component bridging and frontend prop forwarding can achieve linked display of dynamic tags and progress timelines. + +## Appendix + +- Example References + - CheckableTag demo: [docs/components/antd/tag/demos/checkable_tag.py:1-19](file://docs/components/antd/tag/demos/checkable_tag.py#L1-L19) + - Timeline basic demo: [docs/components/antd/timeline/demos/basic.py:1-41](file://docs/components/antd/timeline/demos/basic.py#L1-L41) +- **New**: CheckableTagGroup Examples + - Tag group basic usage: supports options array and dynamic option management + - Tag group batch operations: supports multi-select mode and batch state management + - Tag group nested usage: supports integrating tag group components in forms and filters diff --git a/.wiki/en/Ant Design Components/Data Display Components/Tooltip and Tour.md b/.wiki/en/Ant Design Components/Data Display Components/Tooltip and Tour.md new file mode 100644 index 00000000..1c61e6cf --- /dev/null +++ b/.wiki/en/Ant Design Components/Data Display Components/Tooltip and Tour.md @@ -0,0 +1,304 @@ +# Tooltip and Tour + + +**Files Referenced in This Document** +- [tooltip.tsx](file://frontend/antd/tooltip/tooltip.tsx) +- [tour.tsx](file://frontend/antd/tour/tour.tsx) +- [context.ts](file://frontend/antd/tour/context.ts) +- [Index.svelte (Tour)](file://frontend/antd/tour/Index.svelte) +- [Index.svelte (Tour Step)](file://frontend/antd/tour/step/Index.svelte) +- [tour.step.tsx](file://frontend/antd/tour/step/tour.step.tsx) +- [README.md (Tooltip docs)](file://docs/components/antd/tooltip/README.md) +- [README.md (Tour docs)](file://docs/components/antd/tour/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document covers the encapsulation and usage of the **Tooltip** and **Tour** Ant Design components in this repository. Key topics include: + +- Tooltip: trigger modes, position offset, delayed display, multi-line text support, nested usage, HTML content support, and accessibility optimization +- Tour: step configuration, path planning, focus areas, user interaction control, conditional logic, user preference memory, and guided flow customization + +## Project Structure + +This project uses Svelte + React preprocessing (svelte-preprocess-react) to expose Ant Design's React components to the Svelte ecosystem as Svelte components. Tooltip and Tour encapsulations are located under frontend/antd, and Tour's Step subcomponent is located at frontend/antd/tour/step. + +```mermaid +graph TB +subgraph "Ant Design Encapsulation Layer" +T["Tooltip
tooltip.tsx"] +TR["Tour
tour.tsx"] +TS["Tour Step
step/tour.step.tsx"] +end +subgraph "Svelte Wrapper Layer" +TI["Tour Wrapper
tour/Index.svelte"] +TSI["Tour Step Wrapper
step/Index.svelte"] +end +subgraph "Context and Utilities" +CTX["Items Context
tour/context.ts"] +U1["useFunction hook"] +U2["renderItems / renderParamsSlot utilities"] +end +T --> |"calls Antd Tooltip"| T +TR --> |"calls Antd Tour"| TR +TR --> CTX +TR --> U1 +TR --> U2 +TI --> TR +TSI --> TS +``` + +Diagram Source + +- [tooltip.tsx:1-29](file://frontend/antd/tooltip/tooltip.tsx#L1-L29) +- [tour.tsx:1-87](file://frontend/antd/tour/tour.tsx#L1-L87) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) +- [Index.svelte (Tour):1-60](file://frontend/antd/tour/Index.svelte#L1-L60) +- [Index.svelte (Tour Step):1-82](file://frontend/antd/tour/step/Index.svelte#L1-L82) +- [tour.step.tsx:1-14](file://frontend/antd/tour/step/tour.step.tsx#L1-L14) + +Section Source + +- [tooltip.tsx:1-29](file://frontend/antd/tooltip/tooltip.tsx#L1-L29) +- [tour.tsx:1-87](file://frontend/antd/tour/tour.tsx#L1-L87) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) +- [Index.svelte (Tour):1-60](file://frontend/antd/tour/Index.svelte#L1-L60) +- [Index.svelte (Tour Step):1-82](file://frontend/antd/tour/step/Index.svelte#L1-L82) +- [tour.step.tsx:1-14](file://frontend/antd/tour/step/tour.step.tsx#L1-L14) + +## Core Components + +- Tooltip: a lightweight wrapper for Ant Design Tooltip that preserves the title prop and slot-based title rendering capability, and safely injects callback functions into the React component via useFunction. +- Tour: an enhanced wrapper for Ant Design Tour that supports injecting steps, close icons, indicators, and action areas via slots; internally uses the Items context and render utilities to parse the step list; and provides onChange/onClose callback bridging. + +Section Source + +- [tooltip.tsx:7-26](file://frontend/antd/tooltip/tooltip.tsx#L7-L26) +- [tour.tsx:11-84](file://frontend/antd/tour/tour.tsx#L11-L84) + +## Architecture Overview + +The following diagram shows the call chain and data flow for Tooltip and Tour in this repository: + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant SvelteUI as "Svelte Component Wrapper Layer" +participant TourComp as "Tour Component" +participant TourStep as "Tour Step Component" +participant Ctx as "Items Context" +participant Antd as "Ant Design Tour/Tooltip" +Dev->>SvelteUI : Render Tour or Tooltip +SvelteUI->>TourComp : Pass props and slots +TourComp->>Ctx : Read steps/default slot items +TourComp->>Antd : Render Tour and pass steps and callbacks +TourComp->>TourStep : Render each step item +TourStep->>Antd : Render individual TourStep +Dev->>TourComp : Trigger onChange/onClose +TourComp-->>Dev : Callback notification +``` + +Diagram Source + +- [tour.tsx:17-83](file://frontend/antd/tour/tour.tsx#L17-L83) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) +- [Index.svelte (Tour):46-59](file://frontend/antd/tour/Index.svelte#L46-L59) +- [Index.svelte (Tour Step):61-81](file://frontend/antd/tour/step/Index.svelte#L61-L81) +- [tour.step.tsx:7-11](file://frontend/antd/tour/step/tour.step.tsx#L7-L11) + +## Detailed Component Analysis + +### Tooltip Component + +- Trigger Modes + - Supports standard mouse-hover triggering via Ant Design Tooltip's native behavior. + - Dynamic content rendering can be achieved via slot-based titles, making it easy to embed HTML structures or complex components in the title. +- Position Offset + - Fine-tuned using Ant Design Tooltip's native offset parameters to meet different layout requirements. +- Delayed Display + - Use Ant Design Tooltip's delay parameters to avoid flickering or accidental triggers from frequent interactions. +- Multi-line Text Support + - Naturally supports multi-line text and rich text via the slot-based title and Ant Design Tooltip's line-break mechanism. +- Nested Usage + - Other interactive elements (such as buttons or links) can be nested inside Tooltip to achieve composite interactions. +- HTML Content Support + - HTML fragments can be rendered in Tooltip by injecting React nodes into the title via a slot. +- Accessibility Optimization + - Maintain native semantic tags and keyboard reachability; ensure that the title content is readable and understandable. + +```mermaid +flowchart TD +Start(["Enter Tooltip render"]) --> CheckSlot["Check if title slot exists"] +CheckSlot --> |Yes| RenderSlot["Render slot content as title"] +CheckSlot --> |No| UseProp["Use title prop as title"] +RenderSlot --> PassProps["Forward to Antd Tooltip"] +UseProp --> PassProps +PassProps --> End(["Rendering complete"]) +``` + +Diagram Source + +- [tooltip.tsx:17-19](file://frontend/antd/tooltip/tooltip.tsx#L17-L19) + +Section Source + +- [tooltip.tsx:7-26](file://frontend/antd/tooltip/tooltip.tsx#L7-L26) + +### Tour Component + +- Step Configuration + - Supports directly passing a steps array, or injecting steps/default items via slots; internally, render utilities uniformly parse them into the step format required by Ant Design Tour. +- Path Planning + - Step navigation is implemented via Ant Design Tour's built-in navigation logic; the current step index can be obtained via onChange, and combined with business logic to implement conditional decisions and path changes. +- Focus Areas + - Each step can bind a target element selector or function for locating the focus area; dynamic target element computation is supported. +- User Interaction Control + - Provides closeIcon, indicatorsRender, and actionsRender slots for customizing the close icon, indicators, and action area. + - Use the onClose callback to perform cleanup or record user preferences on close. +- Conditional Logic + - In onChange, determine whether to allow the next step or skip certain steps based on the current step and business state. +- User Preference Memory + - Persist user preferences (e.g., "don't show again") in onClose, and decide whether to show the Tour on next initialization based on preferences. +- Guided Flow Customization + - Combine slots and callbacks to implement custom guide text, styles, and interaction behavior. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Tour as "Tour Component" +participant Steps as "Steps List" +participant Ctx as "Items Context" +participant Antd as "Antd Tour" +Dev->>Tour : Pass steps or slot items +Tour->>Ctx : Read steps/default +Tour->>Steps : Use render utilities to parse into Antd steps +Tour->>Antd : Render Tour and pass step list +Dev->>Tour : Trigger onChange/onClose +Tour-->>Dev : Return current step index/close event +``` + +Diagram Source + +- [tour.tsx:33-48](file://frontend/antd/tour/tour.tsx#L33-L48) +- [tour.tsx:49-78](file://frontend/antd/tour/tour.tsx#L49-L78) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) + +Section Source + +- [tour.tsx:11-84](file://frontend/antd/tour/tour.tsx#L11-L84) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) + +#### Tour Step Component + +- Role + - Serves as the container for a single step, responsible for mapping externally passed props and slots to Ant Design TourStep. +- Key Points + - Supports target functions or selectors for locating focus areas. + - Supports bridging interactive props such as next_button_click/prev_button_click. + - Integrates with the Items context via ItemHandler for step item registration and management. + +```mermaid +classDiagram +class TourStep { ++props : TourStepProps ++target : string|function ++itemIndex : number ++slots : object +} +class ItemHandler { ++register(item) ++unregister(id) +} +TourStep --> ItemHandler : "register/manage step items" +``` + +Diagram Source + +- [tour.step.tsx:7-11](file://frontend/antd/tour/step/tour.step.tsx#L7-L11) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) + +Section Source + +- [Index.svelte (Tour Step):1-82](file://frontend/antd/tour/step/Index.svelte#L1-L82) +- [tour.step.tsx:1-14](file://frontend/antd/tour/step/tour.step.tsx#L1-L14) + +## Dependency Analysis + +- Tooltip depends on Ant Design Tooltip, adapted from React component to Svelte via sveltify. +- Tour depends on Ant Design Tour, and also introduces the Items context and render utilities to convert slots into step arrays. +- The Svelte wrapper layer handles prop and slot forwarding, class name and visibility control, and async loading of the underlying component. + +```mermaid +graph LR +A["tooltip.tsx"] --> AD1["Antd Tooltip"] +B["tour.tsx"] --> AD2["Antd Tour"] +B --> C["context.ts"] +D["tour/Index.svelte"] --> B +E["step/Index.svelte"] --> F["step/tour.step.tsx"] +``` + +Diagram Source + +- [tooltip.tsx:1-29](file://frontend/antd/tooltip/tooltip.tsx#L1-L29) +- [tour.tsx:1-87](file://frontend/antd/tour/tour.tsx#L1-L87) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) +- [Index.svelte (Tour):1-60](file://frontend/antd/tour/Index.svelte#L1-L60) +- [Index.svelte (Tour Step):1-82](file://frontend/antd/tour/step/Index.svelte#L1-L82) +- [tour.step.tsx:1-14](file://frontend/antd/tour/step/tour.step.tsx#L1-L14) + +Section Source + +- [tooltip.tsx:1-29](file://frontend/antd/tooltip/tooltip.tsx#L1-L29) +- [tour.tsx:1-87](file://frontend/antd/tour/tour.tsx#L1-L87) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) +- [Index.svelte (Tour):1-60](file://frontend/antd/tour/Index.svelte#L1-L60) +- [Index.svelte (Tour Step):1-82](file://frontend/antd/tour/step/Index.svelte#L1-L82) +- [tour.step.tsx:1-14](file://frontend/antd/tour/step/tour.step.tsx#L1-L14) + +## Performance Considerations + +- Use useMemo to cache the step array and avoid unnecessary re-renders. +- Render Tour and Step only when visible to reduce DOM overhead. +- Use slots and dynamic rendering judiciously to avoid rendering too many complex nodes at once. +- In onChange/onClose, avoid heavy synchronous operations; use async processing where necessary. + +## Troubleshooting Guide + +- Title not displayed or empty + - Check whether title is correctly passed or whether the title slot is used; confirm that the slot content has been correctly rendered. +- Steps not taking effect + - Confirm that the steps or slot items are correctly injected; check whether the Items context is correctly provided. +- Target element cannot be focused + - Check the target selector or function return value; ensure the element is rendered on the page and accessible. +- Callbacks not triggered + - Confirm that onChange/onClose are correctly passed; check whether useFunction is correctly wrapping the callbacks. + +Section Source + +- [tour.tsx:33-48](file://frontend/antd/tour/tour.tsx#L33-L48) +- [tour.tsx:49-78](file://frontend/antd/tour/tour.tsx#L49-L78) +- [Index.svelte (Tour):46-59](file://frontend/antd/tour/Index.svelte#L46-L59) +- [Index.svelte (Tour Step):69-73](file://frontend/antd/tour/step/Index.svelte#L69-L73) + +## Conclusion + +The encapsulation of Tooltip and Tour in this repository follows the principles of "lightweight, extensible, and easy to integrate": while preserving Ant Design's native capabilities, it enhances step configuration, interaction customization, and rendering flexibility through slots and context mechanisms. In practice, it is recommended to configure step paths, target areas, and user preferences based on business scenarios to achieve a better user experience. + +## Appendix + +- Demo and Documentation Entry Points + - Tooltip documentation demo entry: [Tooltip docs:1-8](file://docs/components/antd/tooltip/README.md#L1-L8) + - Tour documentation demo entry: [Tour docs:1-8](file://docs/components/antd/tour/README.md#L1-L8) diff --git a/.wiki/en/Ant Design Components/Data Display Components/Tree.md b/.wiki/en/Ant Design Components/Data Display Components/Tree.md new file mode 100644 index 00000000..7d277088 --- /dev/null +++ b/.wiki/en/Ant Design Components/Data Display Components/Tree.md @@ -0,0 +1,348 @@ +# Tree + + +**Files Referenced in This Document** +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [Index.svelte](file://frontend/antd/tree/Index.svelte) +- [context.ts](file://frontend/antd/tree/context.ts) +- [tree.tree-node.tsx](file://frontend/antd/tree/tree-node/tree.tree-node.tsx) +- [directory-tree/Index.svelte](file://frontend/antd/tree/directory-tree/Index.svelte) +- [folder.tsx](file://frontend/antdx/folder/folder.tsx) +- [context.ts (folder context)](file://frontend/antdx/folder/context.ts) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document systematically reviews the design and implementation of the **Tree** component, covering its basic structure, node expand/collapse, DirectoryTree special capabilities, asynchronous data source loading, selection modes and multi-select/half-select, disabled configuration, search filtering, node dragging, right-click context menu, batch operations, virtual scrolling and large dataset optimization, dynamic CRUD operations, as well as typical applications and performance strategies in file management, organizational structures, and classification systems. + +## Project Structure + +The Tree component is composed of a Svelte frontend wrapper layer and a React component bridge layer, and supports declarative nesting and data injection for tree nodes via an "item context" mechanism. DirectoryTree, as a specialized form of Tree, reuses the same bridge layer and enables the directory tree component. + +```mermaid +graph TB +subgraph "Frontend Wrapper Layer" +T_Index["Tree/Index.svelte"] +DT_Index["DirectoryTree/Index.svelte"] +TN_Node["TreeNode/tree.tree-node.tsx"] +end +subgraph "Bridge and Context" +Bridge["Tree/tree.tsx"] +Ctx["Tree/context.ts"] +end +subgraph "External Dependencies" +AntD["Ant Design Tree/DirectoryTree"] +end +T_Index --> Bridge +DT_Index --> Bridge +TN_Node --> Ctx +Bridge --> AntD +``` + +Diagram Source + +- [Index.svelte:1-80](file://frontend/antd/tree/Index.svelte#L1-L80) +- [directory-tree/Index.svelte:1-83](file://frontend/antd/tree/directory-tree/Index.svelte#L1-L83) +- [tree.tree-node.tsx:1-22](file://frontend/antd/tree/tree-node/tree.tree-node.tsx#L1-L22) +- [tree.tsx:1-150](file://frontend/antd/tree/tree.tsx#L1-L150) +- [context.ts:1-7](file://frontend/antd/tree/context.ts#L1-L7) + +Section Source + +- [Index.svelte:1-80](file://frontend/antd/tree/Index.svelte#L1-L80) +- [directory-tree/Index.svelte:1-83](file://frontend/antd/tree/directory-tree/Index.svelte#L1-L83) +- [tree.tsx:1-150](file://frontend/antd/tree/tree.tsx#L1-L150) +- [context.ts:1-7](file://frontend/antd/tree/context.ts#L1-L7) + +## Core Components + +- Tree Wrapper: responsible for bridging Ant Design's Tree/DirectoryTree to the Svelte ecosystem, supporting slot extension, event forwarding, async loading, dragging, and title rendering. +- Tree Node: injects child nodes via ItemHandler as "default" slots, forming a tree structure. +- DirectoryTree: enables directory tree mode on top of Tree, providing folder-style interaction and behavior. +- Item Context: uniformly manages the collection and injection of "items" such as tree nodes and directory icons. + +Section Source + +- [tree.tsx:14-148](file://frontend/antd/tree/tree.tsx#L14-L148) +- [tree.tree-node.tsx:7-18](file://frontend/antd/tree/tree-node/tree.tree-node.tsx#L7-L18) +- [directory-tree/Index.svelte:65-82](file://frontend/antd/tree/directory-tree/Index.svelte#L65-L82) +- [context.ts:3-4](file://frontend/antd/tree/context.ts#L3-L4) + +## Architecture Overview + +The following diagram shows the call chain from Svelte to React, as well as the switching logic between DirectoryTree and regular Tree. + +```mermaid +sequenceDiagram +participant Svelte as "Svelte Wrapper Layer" +participant Bridge as "Tree Bridge Layer" +participant AntD as "Ant Design Component Library" +Svelte->>Bridge : Pass props and slots +Bridge->>Bridge : Parse treeData/slots/events +alt Directory Tree Mode +Bridge->>AntD : Use DirectoryTree +else Regular Tree Mode +Bridge->>AntD : Use Tree +end +AntD-->>Bridge : Render results and callbacks +Bridge-->>Svelte : Event forwarding/data return +``` + +Diagram Source + +- [tree.tsx:52-115](file://frontend/antd/tree/tree.tsx#L52-L115) +- [Index.svelte:67-78](file://frontend/antd/tree/Index.svelte#L67-L78) +- [directory-tree/Index.svelte:66-81](file://frontend/antd/tree/directory-tree/Index.svelte#L66-L81) + +## Detailed Component Analysis + +### Basic Structure and Data Model + +- Data Source Origins + - Explicit treeData: directly pass the tree node array required by AntD. + - Slot treeData/default: collect child nodes via item context, automatically converting to treeData. +- Key Fields + - Identification and hierarchy: key/value/title etc. used for identification and display. + - Expanded state: expandedKeys controls initial expansion; onExpand callback responds to user actions. + - Selection and checking: selectedKeys/checkedKeys support single/multi-select; half-select is calculated via internal algorithm. + - Disabled: disabled field disables node interaction. +- Slot Extensions + - switcherIcon/switcherLoadingIcon: custom expand/loading icons. + - showLine.showLeafIcon: custom connection line leaf icon. + - icon: node icon. + - draggable.icon/nodeDraggable: drag icon and node-level draggable toggle. + - titleRender: custom title render function. + +Section Source + +- [tree.tsx:56-126](file://frontend/antd/tree/tree.tsx#L56-L126) +- [context.ts:3-4](file://frontend/antd/tree/context.ts#L3-L4) + +### Expand/Collapse and Async Loading + +- Expand/Collapse + - Get the current expanded set via onExpand, and implement hierarchical expansion combined with treeData's children. +- Async Loading + - Provide lazy loading hooks via loadData/onLoadData, requesting child node data on demand. + - DirectoryTree mode also supports async loading, suitable for large directory scenarios. + +```mermaid +flowchart TD +Start(["User clicks expand"]) --> CheckLoaded{"Child nodes already loaded?"} +CheckLoaded --> |No| Load["Trigger onLoadData/loadData request"] +Load --> Update["Update treeData child nodes"] +CheckLoaded --> |Yes| Render["Render child nodes directly"] +Update --> Render +Render --> End(["Done"]) +``` + +Diagram Source + +- [tree.tsx:114-114](file://frontend/antd/tree/tree.tsx#L114-L114) +- [tree.tsx:137-139](file://frontend/antd/tree/tree.tsx#L137-L139) + +Section Source + +- [tree.tsx:38-42](file://frontend/antd/tree/tree.tsx#L38-L42) +- [tree.tsx:114-114](file://frontend/antd/tree/tree.tsx#L114-L114) + +### DirectoryTree Special Features + +- Mode Switching + - Toggle between Tree and DirectoryTree via the directory prop. +- Event Mapping + - dragStart/dragEnter/dragOver/dragLeave/dragEnd: drag lifecycle events. + - rightClick: right-click context menu trigger. + - loadData: directory tree specific lazy loading hook. +- Folder Style + - More aligned with file system browsing experience, supporting directory hierarchy and icon mapping. + +Section Source + +- [tree.tsx:52-52](file://frontend/antd/tree/tree.tsx#L52-L52) +- [directory-tree/Index.svelte:18-25](file://frontend/antd/tree/directory-tree/Index.svelte#L18-L25) +- [directory-tree/Index.svelte:50-58](file://frontend/antd/tree/directory-tree/Index.svelte#L50-L58) + +### Selection Modes, Multi-select and Half-select + +- Single-select/Multi-select + - Implement single or multi-select via selectedKeys/onChange. +- Multi-select Linkage + - Checking parent nodes affects child nodes; unchecking affects parent node state. +- Half-select State + - When some child nodes are checked, the parent node shows a half-selected state for quick identification of partial selection. +- Disabled Nodes + - The disabled field prevents nodes from being selected or checked. + +Section Source + +- [tree.tsx:134-142](file://frontend/antd/tree/tree.tsx#L134-L142) + +### Search Filtering + +- Filter Function + - filterTreeNode accepts a node and input value, returning a boolean to decide whether to display. +- Practical Recommendations + - Combine expanded state and highlight matching items to improve discoverability. + +Section Source + +- [tree.tsx:132-132](file://frontend/antd/tree/tree.tsx#L132-L132) + +### Node Dragging + +- Drag Toggle + - draggable can be a boolean or object; nodeDraggable supports node-level draggable control. +- Icon Customization + - draggable.icon customizes the drag handle icon. +- Event Forwarding + - dragStart/dragEnd etc. events are triggered by the underlying component for business layer integration. + +Section Source + +- [tree.tsx:102-112](file://frontend/antd/tree/tree.tsx#L102-L112) +- [tree.tsx:48-50](file://frontend/antd/tree/tree.tsx#L48-L50) + +### Right-click Context Menu and Batch Operations + +- Right-click Context Menu + - rightClick event can be used to pop up a context menu. +- Batch Operations + - Combine multi-select and right-click context menu for batch actions like copy, move, and delete. +- Safety + - Intercept disabled nodes to prevent accidental operations. + +Section Source + +- [directory-tree/Index.svelte:23-23](file://frontend/antd/tree/directory-tree/Index.svelte#L23-L23) +- [tree.tsx:134-142](file://frontend/antd/tree/tree.tsx#L134-L142) + +### Dynamic CRUD Operations + +- Add/Modify + - Update treeData or maintain selectedKeys/checkedKeys in controlled mode. +- Delete + - Remove the corresponding node and synchronize cleanup of selection state. +- Query + - Link filterTreeNode with search input for instant filtering. + +Section Source + +- [tree.tsx:59-79](file://frontend/antd/tree/tree.tsx#L59-L79) + +### Virtual Scrolling and Large Dataset Optimization + +- Virtual Scrolling + - Enabling virtual scrolling in super-large trees can significantly reduce DOM count and improve rendering performance. +- Other Optimizations + - Lazy loading (loadData/onLoadData) renders only visible levels. + - Use disabled and hidden nodes judiciously to reduce rendering burden. + - Avoid frequent recalculation of treeData; use shallow comparison and caching where possible. + +Section Source + +- [tree.tsx:114-114](file://frontend/antd/tree/tree.tsx#L114-L114) + +### Application Scenarios and Best Practices + +- File Management + - DirectoryTree + dragging + right-click context menu + async loading to build a file browser-like experience. +- Organizational Structure + - Departments/teams as nodes, supporting collapse and search for easy navigation. +- Classification Systems + - Multi-level classification tree, combined with half-select and batch operations to improve editing efficiency. + +Section Source + +- [directory-tree/Index.svelte:65-82](file://frontend/antd/tree/directory-tree/Index.svelte#L65-L82) +- [tree.tsx:52-52](file://frontend/antd/tree/tree.tsx#L52-L52) + +## Dependency Analysis + +- Component Coupling + - Tree/Index.svelte and DirectoryTree/Index.svelte both depend on the Tree bridge layer. + - Tree nodes inject into the context via ItemHandler, forming a tree structure. +- External Dependencies + - Ant Design Tree/DirectoryTree provides core interaction and rendering. +- Slots and Events + - High customizability is achieved through slots and event forwarding. + +```mermaid +graph LR +T_Index["Tree/Index.svelte"] --> Bridge["Tree/tree.tsx"] +DT_Index["DirectoryTree/Index.svelte"] --> Bridge +TN_Node["TreeNode/tree.tree-node.tsx"] --> Ctx["Tree/context.ts"] +Bridge --> AntD["Ant Design Tree/DirectoryTree"] +``` + +Diagram Source + +- [Index.svelte:10-10](file://frontend/antd/tree/Index.svelte#L10-L10) +- [directory-tree/Index.svelte:10-10](file://frontend/antd/tree/directory-tree/Index.svelte#L10-L10) +- [tree.tsx:1-11](file://frontend/antd/tree/tree.tsx#L1-L11) +- [tree.tree-node.tsx:5-5](file://frontend/antd/tree/tree-node/tree.tree-node.tsx#L5-L5) +- [context.ts:3-4](file://frontend/antd/tree/context.ts#L3-L4) + +Section Source + +- [Index.svelte:1-80](file://frontend/antd/tree/Index.svelte#L1-L80) +- [directory-tree/Index.svelte:1-83](file://frontend/antd/tree/directory-tree/Index.svelte#L1-L83) +- [tree.tsx:1-150](file://frontend/antd/tree/tree.tsx#L1-L150) +- [tree.tree-node.tsx:1-22](file://frontend/antd/tree/tree-node/tree.tree-node.tsx#L1-L22) +- [context.ts:1-7](file://frontend/antd/tree/context.ts#L1-L7) + +## Performance Considerations + +- Rendering Optimization + - Use virtual scrolling and lazy loading to avoid rendering a large number of nodes at once. +- Data Structure + - Keep treeData flat and stable in reference to reduce unnecessary re-renders. +- Event Throttling + - Throttle/debounce high-frequency events (such as drag and scroll). +- Selection and Half-select + - Use checkedKeys and half-select state judiciously to avoid recursive calculations layer by layer. + +## Troubleshooting Guide + +- Cannot expand nodes + - Check whether treeData's children are correctly set or whether async loading is implemented. +- Drag not working + - Confirm that draggable is an object and includes nodeDraggable or that draggable.icon is correctly injected. +- Right-click context menu not appearing + - Confirm that the rightClick event is bound and works in directory tree mode. +- Selection state anomaly + - Check whether selectedKeys/checkedKeys are updated synchronously with treeData. + +Section Source + +- [tree.tsx:102-112](file://frontend/antd/tree/tree.tsx#L102-L112) +- [tree.tsx:134-142](file://frontend/antd/tree/tree.tsx#L134-L142) +- [directory-tree/Index.svelte:23-23](file://frontend/antd/tree/directory-tree/Index.svelte#L23-L23) + +## Conclusion + +This Tree component provides complete encapsulation of Ant Design Tree/DirectoryTree through the combination of a Svelte wrapper layer and React bridge layer, with good extensibility and customizability. Combined with async loading, virtual scrolling, and rich interaction capabilities, it is suitable for complex scenarios such as file management, organizational structures, and classification systems. + +## Appendix + +- Relationship Between DirectoryTree and Folder Component + - DirectoryTree is used for the directory mode of the tree; the folder component (antdx/folder) provides richer file system capabilities (such as icon mapping and content services), and the two can be used complementarily. + +Section Source + +- [directory-tree/Index.svelte:65-82](file://frontend/antd/tree/directory-tree/Index.svelte#L65-L82) +- [folder.tsx:48-86](file://frontend/antdx/folder/folder.tsx#L48-L86) +- [context.ts (folder context):3-13](file://frontend/antdx/folder/context.ts#L3-L13) diff --git a/.wiki/en/Ant Design Components/Data Entry Components/Color and File Components.md b/.wiki/en/Ant Design Components/Data Entry Components/Color and File Components.md new file mode 100644 index 00000000..d9f7205d --- /dev/null +++ b/.wiki/en/Ant Design Components/Data Entry Components/Color and File Components.md @@ -0,0 +1,364 @@ +# Color and File Components + + +**Files referenced in this document** +- [color-picker.tsx](file://frontend/antd/color-picker/color-picker.tsx) +- [context.ts (ColorPicker)](file://frontend/antd/color-picker/context.ts) +- [upload.tsx](file://frontend/antd/upload/upload.tsx) +- [upload.ts (utility functions)](file://frontend/utils/upload.ts) +- [slider.tsx](file://frontend/antd/slider/slider.tsx) +- [context.ts (Slider)](file://frontend/antd/slider/context.ts) +- [form.tsx](file://frontend/antd/form/form.tsx) +- [README.md (ColorPicker docs)](file://docs/components/antd/color_picker/README.md) +- [README.md (Upload docs)](file://docs/components/antd/upload/README.md) +- [README.md (Slider docs)](file://docs/components/antd/slider/README.md) +- [README.md (Form docs)](file://docs/components/antd/form/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document focuses on color, file, and advanced input components: ColorPicker, Upload, Slider, and Form. Content covers: + +- Color format conversion (RGB, HEX, HSB), gradient color handling and preset palettes +- Upload configuration, drag-and-drop upload, file preview, progress display and error handling +- Overall form design patterns, field validation, dynamic forms and nested forms +- Accessibility and keyboard navigation support +- Performance optimization strategies such as large file handling, concurrent uploads, and error retry +- Data flow management and best practices for complex form scenarios + +## Project Structure + +These components are located in the frontend Svelte + Ant Design ecosystem, bridging Ant Design components for Svelte use via sveltify, and encapsulating state and callbacks where necessary to adapt to the Gradio data domain. + +```mermaid +graph TB +subgraph "Antd Component Layer" +CP["ColorPicker"] +UP["Upload"] +SL["Slider"] +FM["Form"] +end +subgraph "Utilities and Context" +CTX_CP["ColorPicker Context"] +CTX_SL["Slider Context"] +UT["Upload Utility Functions
URL Parsing and Assembly"] +end +CP --> CTX_CP +SL --> CTX_SL +UP --> UT +``` + +Diagram Source + +- [color-picker.tsx:1-106](file://frontend/antd/color-picker/color-picker.tsx#L1-L106) +- [upload.tsx:1-282](file://frontend/antd/upload/upload.tsx#L1-L282) +- [slider.tsx:1-97](file://frontend/antd/slider/slider.tsx#L1-L97) +- [form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) + +Section Source + +- [color-picker.tsx:1-106](file://frontend/antd/color-picker/color-picker.tsx#L1-L106) +- [upload.tsx:1-282](file://frontend/antd/upload/upload.tsx#L1-L282) +- [slider.tsx:1-97](file://frontend/antd/slider/slider.tsx#L1-L97) +- [form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) + +## Core Components + +- ColorPicker + - Supports RGB/HEX/HSB three color format outputs + - Gradient color parsing and multi-point color mapping + - Preset palette rendering and custom panel/text slots +- Upload + - Custom request hook and progress formatting + - File list normalization, maximum count control + - Drag-and-drop/click upload, preview and icon rendering slots +- Slider + - Tick mark rendering (supports label slots) + - Step and tooltip container customization +- Form + - Value domain binding and change notification + - Manually trigger reset/submit/validate actions + - Required mark and feedback icon slots + +Section Source + +- [color-picker.tsx:11-103](file://frontend/antd/color-picker/color-picker.tsx#L11-L103) +- [upload.tsx:21-279](file://frontend/antd/upload/upload.tsx#L21-L279) +- [slider.tsx:37-94](file://frontend/antd/slider/slider.tsx#L37-L94) +- [form.tsx:15-76](file://frontend/antd/form/form.tsx#L15-L76) + +## Architecture Overview + +Components use a "bridge + decoration" architecture: with Ant Design native components as the core, wrapped via sveltify and injected with value change callbacks, slot rendering, and context injection to achieve seamless integration with the Gradio data domain. + +```mermaid +sequenceDiagram +participant U as "User" +participant C as "ColorPicker" +participant A as "Antd ColorPicker" +participant F as "Format Conversion Logic" +U->>C : Select color/drag gradient +C->>A : Trigger onChange(...) +A-->>C : Return color object/gradient info +C->>F : Convert to RGB/HEX/HSB according to value_format +F-->>C : Output unified format array or string +C-->>U : Callback onValueChange(...) +``` + +Diagram Source + +- [color-picker.tsx:71-95](file://frontend/antd/color-picker/color-picker.tsx#L71-L95) + +Section Source + +- [color-picker.tsx:1-106](file://frontend/antd/color-picker/color-picker.tsx#L1-L106) + +## Detailed Component Analysis + +### ColorPicker + +- Key features + - Color format conversion: one of RGB/HEX/HSB, output according to value_format + - Gradient color handling: iterate through gradient points, convert each to the specified format and return as array + - Preset palette: supports passing presets or injecting via context + - Slot extension: slot-based rendering for panelRender and showText +- Key flow + +```mermaid +flowchart TD +Start(["Start"]) --> IsGrad{"Is gradient color?"} +IsGrad --> |Yes| Iterate["Iterate through gradient points"] +Iterate --> Convert["Convert color according to value_format"] +Convert --> EmitGrad["Callback onValueChange(array)"] +IsGrad --> |No| Single["Single color conversion"] +Single --> EmitSingle["Callback onValueChange(string)"] +EmitGrad --> End(["End"]) +EmitSingle --> End +``` + +Diagram Source + +- [color-picker.tsx:71-95](file://frontend/antd/color-picker/color-picker.tsx#L71-L95) + +- Context and preset palette + - Inject marks/presets and other item sets via createItemsContext + - Preset palette prefers externally passed values; otherwise renders from context + +- Accessibility and keyboard navigation + - Based on Ant Design native component, follows its accessibility specifications + - Recommended to supplement aria-label, aria-describedby and other attributes on the business side + +Section Source + +- [color-picker.tsx:1-106](file://frontend/antd/color-picker/color-picker.tsx#L1-L106) +- [context.ts (ColorPicker):1-7](file://frontend/antd/color-picker/context.ts#L1-L7) +- [README.md (ColorPicker docs):1-9](file://docs/components/antd/color_picker/README.md#L1-L9) + +### Upload + +- Key features + - Custom upload: upload(files) -> Promise
Exports Antd* component aliases"] +end +subgraph "Frontend" +B["frontend/antd/*/*.tsx
Component wrappers: sveltify + hooks"] +C["frontend/antd/form/*
Form/FormItem/Rule/Provider"] +D["utils/*
hooks/renderItems/renderParamsSlot etc."] +end +A --> B +B --> D +C --> B +``` + +Diagram Source + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [frontend/antd/auto-complete/auto-complete.tsx:1-151](file://frontend/antd/auto-complete/auto-complete.tsx#L1-L151) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/form/item/form.item.tsx](file://frontend/antd/form/item/form.item.tsx) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) +- [frontend/antd/form/provider/form.provider.tsx](file://frontend/antd/form/provider/form.provider.tsx) + +Section Source + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) + +## Core Components + +This section gives an overview of the components covered in this document and their responsibilities: + +- Form system: Form, FormItem, FormItem.Rule, FormProvider +- Input types: Input, Input.TextArea, Input.Search, Input.Password, Input.OTP, InputNumber +- Selection types: Select, Select.Option, Cascader, TreeSelect, Transfer +- Date/time types: DatePicker, TimePicker +- Slider and rating: Slider, Rate +- Toggle and selection: Switch, Radio, Checkbox +- Color: ColorPicker +- Mentions: Mentions (supports keyword mentions and dynamic rendering of options, including the Option sub-component) + +Section Source + +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/form/item/form.item.tsx](file://frontend/antd/form/item/form.item.tsx) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) +- [frontend/antd/form/provider/form.provider.tsx](file://frontend/antd/form/provider/form.provider.tsx) +- [frontend/antd/input/input.tsx](file://frontend/antd/input/input.tsx) +- [frontend/antd/input/otp/input.otp.tsx](file://frontend/antd/input/otp/input.otp.tsx) +- [frontend/antd/input/password/input.password.tsx](file://frontend/antd/input/password/input.password.tsx) +- [frontend/antd/input/search/input.search.tsx](file://frontend/antd/input/search/input.search.tsx) +- [frontend/antd/input/textarea/input.textarea.tsx](file://frontend/antd/input/textarea/input.textarea.tsx) +- [frontend/antd/input-number/input-number.tsx](file://frontend/antd/input-number/input-number.tsx) +- [frontend/antd/select/select.tsx](file://frontend/antd/select/select.tsx) +- [frontend/antd/select/option/select.option.tsx](file://frontend/antd/select/option/select.option.tsx) +- [frontend/antd/cascader/cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [frontend/antd/tree-select/tree-select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [frontend/antd/transfer/transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [frontend/antd/date-picker/date-picker.tsx](file://frontend/antd/date-picker/date-picker.tsx) +- [frontend/antd/time-picker/time-picker.tsx](file://frontend/antd/time-picker/time-picker.tsx) +- [frontend/antd/slider/slider.tsx](file://frontend/antd/slider/slider.tsx) +- [frontend/antd/rate/rate.tsx](file://frontend/antd/rate/rate.tsx) +- [frontend/antd/switch/switch.tsx](file://frontend/antd/switch/switch.tsx) +- [frontend/antd/radio/radio.tsx](file://frontend/antd/radio/radio.tsx) +- [frontend/antd/checkbox/checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [frontend/antd/color-picker/color-picker.tsx](file://frontend/antd/color-picker/color-picker.tsx) + +## Architecture Overview + +Frontend components universally use sveltify to wrap Ant Design native components, and complete the following via hooks: + +- Value change bridging: useValueChange bridges onChange and onValueChange to ensure the external side consistently receives value +- Function parameterization: useFunction wraps incoming functions as stable references to avoid closure traps +- Slot rendering: renderItems/renderParamsSlot support flexible combinations of children and slots +- Context injection: withItemsContextProvider injects items into child components (such as Option/Marks/Preset) + +```mermaid +sequenceDiagram +participant U as "User" +participant C as "Wrapped Component (e.g. AutoComplete)" +participant R as "React/antd Component" +participant H as "hooks(onValueChange/useFunction)" +participant P as "Parent Component (Form/Page)" +U->>C : Trigger interaction +C->>R : Call native component event +R-->>C : Callback value +C->>H : onValueChange(value) +H-->>C : Update internal state +C-->>P : onValueChange(value) +Note over C,P : Parent component can combine Form/FormItem for validation and linked fields +``` + +Diagram Source + +- [frontend/antd/auto-complete/auto-complete.tsx:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) +- [frontend/antd/cascader/cascader.tsx:39-204](file://frontend/antd/cascader/cascader.tsx#L39-L204) +- [frontend/antd/checkbox/checkbox.tsx:4-19](file://frontend/antd/checkbox/checkbox.tsx#L4-L19) +- [frontend/antd/color-picker/color-picker.tsx:24-103](file://frontend/antd/color-picker/color-picker.tsx#L24-L103) +- [frontend/antd/date-picker/date-picker.tsx:40-231](file://frontend/antd/date-picker/date-picker.tsx#L40-L231) +- [frontend/antd/radio/radio.tsx:6-29](file://frontend/antd/radio/radio.tsx#L6-L29) +- [frontend/antd/rate/rate.tsx:12-42](file://frontend/antd/rate/rate.tsx#L12-L42) +- [frontend/antd/slider/slider.tsx:37-94](file://frontend/antd/slider/slider.tsx#L37-L94) +- [frontend/antd/switch/switch.tsx:6-39](file://frontend/antd/switch/switch.tsx#L6-L39) +- [frontend/antd/time-picker/time-picker.tsx:37-198](file://frontend/antd/time-picker/time-picker.tsx#L37-L198) + +## Component Details + +### AutoComplete + +- Data binding: receives string value via onValueChange; onChange passes through native callback +- Slots: supports children, dropdownRender, popupRender, notFoundContent, allowClear.clearIcon +- Options: supports rendering via options or slots.children +- Filtering: filterOption can customize filter logic or use default behavior + +```mermaid +flowchart TD +Start(["Start"]) --> Bind["Bind onValueChange"] +Bind --> Render["Render options/slots"] +Render --> UserInput["User input"] +UserInput --> Filter{"Custom filter?"} +Filter -- Yes --> UseFn["Use filterOption function"] +Filter -- No --> Default["Default filtering"] +UseFn --> Change["Trigger onChange and update value"] +Default --> Change +Change --> End(["End"]) +``` + +Diagram Source + +- [frontend/antd/auto-complete/auto-complete.tsx:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) + +Section Source + +- [frontend/antd/auto-complete/auto-complete.tsx:1-151](file://frontend/antd/auto-complete/auto-complete.tsx#L1-L151) + +### Cascader + +- Data binding: onValueChange receives an array (path value); onChange passes through +- Slots: suffixIcon, prefix, removeIcon, expandIcon, displayRender, tagRender, dropdownRender, popupRender, showSearch.render, maxTagPlaceholder +- Search: showSearch supports object configuration and slot rendering +- Dynamic loading: onLoadData corresponds to native loadData + +```mermaid +sequenceDiagram +participant U as "User" +participant C as "Cascader" +participant R as "Antd Cascader" +U->>C : Expand/select node +C->>R : Render panel/search +R-->>C : Return selected value +C-->>U : onValueChange(path array) +``` + +Diagram Source + +- [frontend/antd/cascader/cascader.tsx:19-204](file://frontend/antd/cascader/cascader.tsx#L19-L204) + +Section Source + +- [frontend/antd/cascader/cascader.tsx:1-207](file://frontend/antd/cascader/cascader.tsx#L1-L207) + +### Checkbox + +- Data binding: onValueChange receives a boolean value +- Events: onChange passes through native event + +Section Source + +- [frontend/antd/checkbox/checkbox.tsx:1-22](file://frontend/antd/checkbox/checkbox.tsx#L1-L22) + +### ColorPicker + +- Data binding: onValueChange receives a string or gradient color array; value_format controls the output format (rgb/hex/hsb) +- Slots: panelRender, showText +- Gradient: when isGradient(), outputs each color segment according to value_format + +Section Source + +- [frontend/antd/color-picker/color-picker.tsx:1-106](file://frontend/antd/color-picker/color-picker.tsx#L1-L106) + +### DatePicker + +- Data binding: onValueChange receives a second-level timestamp (including array scenario); onChange/onPanelChange passes through +- Internal format: unified dayjs conversion, external output as second-level timestamp +- Slots: renderExtraFooter, cellRender, panelRender, prevIcon/prefix/nextIcon/suffixIcon/superNextIcon/superPrevIcon, allowClear.clearIcon +- Presets: presets are rendered via renderItems + +```mermaid +flowchart TD +In(["Input date"]) --> Parse["dayjs parse"] +Parse --> Normalize["Normalize to second-level timestamp"] +Normalize --> Emit["onValueChange/onChange"] +Emit --> Out(["Output to parent component"]) +``` + +Diagram Source + +- [frontend/antd/date-picker/date-picker.tsx:14-38](file://frontend/antd/date-picker/date-picker.tsx#L14-L38) +- [frontend/antd/date-picker/date-picker.tsx:126-170](file://frontend/antd/date-picker/date-picker.tsx#L126-L170) + +Section Source + +- [frontend/antd/date-picker/date-picker.tsx:1-234](file://frontend/antd/date-picker/date-picker.tsx#L1-L234) + +### Form / FormItem / FormItem.Rule / FormProvider + +- Form: container that provides Provider injection and layout capability +- FormItem: field container holding label, help, required, validateStatus, etc. +- FormItem.Rule: validation rules supporting required, regex, custom functions, async validation +- FormProvider: global configuration and context + +```mermaid +classDiagram +class Form { ++provider() ++submit() ++resetFields() +} +class FormItem { ++label ++help ++required ++validateStatus +} +class FormItemRule { ++rules ++trigger +} +class FormProvider { ++config +} +Form --> FormItem : "contains" +FormItem --> FormItemRule : "uses" +Form --> FormProvider : "injects" +``` + +Diagram Source + +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/form/item/form.item.tsx](file://frontend/antd/form/item/form.item.tsx) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) +- [frontend/antd/form/provider/form.provider.tsx](file://frontend/antd/form/provider/form.provider.tsx) + +Section Source + +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/form/item/form.item.tsx](file://frontend/antd/form/item/form.item.tsx) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) +- [frontend/antd/form/provider/form.provider.tsx](file://frontend/antd/form/provider/form.provider.tsx) + +### Input / TextArea / Search / Password / OTP + +- Unified pattern: all receive the latest value via onValueChange; onChange passes through native event +- Extensions: Search, Password, OTP each provide specific behavior and styles + +Section Source + +- [frontend/antd/input/input.tsx](file://frontend/antd/input/input.tsx) +- [frontend/antd/input/otp/input.otp.tsx](file://frontend/antd/input/otp/input.otp.tsx) +- [frontend/antd/input/password/input.password.tsx](file://frontend/antd/input/password/input.password.tsx) +- [frontend/antd/input/search/input.search.tsx](file://frontend/antd/input/search/input.search.tsx) +- [frontend/antd/input/textarea/input.textarea.tsx](file://frontend/antd/input/textarea/input.textarea.tsx) + +### InputNumber + +- Data binding: onValueChange receives a numeric value; onChange passes through +- Use cases: step control, range, precision control + +Section Source + +- [frontend/antd/input-number/input-number.tsx](file://frontend/antd/input-number/input-number.tsx) + +### Select / Option + +- Data binding: onValueChange receives string/number/array; onChange passes through +- Sub-items: Option is injected via renderItems, supporting disabled, grouping, etc. + +Section Source + +- [frontend/antd/select/select.tsx](file://frontend/antd/select/select.tsx) +- [frontend/antd/select/option/select.option.tsx](file://frontend/antd/select/option/select.option.tsx) + +### Slider / Marks + +- Data binding: onValueChange receives number or number[]; onChange passes through +- Marks: rendered via slots.children or slots.label + +Section Source + +- [frontend/antd/slider/slider.tsx:1-97](file://frontend/antd/slider/slider.tsx#L1-L97) + +### Radio + +- Data binding: onValueChange receives a boolean value; onChange passes through +- Theme: style variables injected via token.lineWidth + +Section Source + +- [frontend/antd/radio/radio.tsx:1-32](file://frontend/antd/radio/radio.tsx#L1-L32) + +### Rate + +- Data binding: onValueChange receives a numeric value; onChange passes through +- Slots: character supports custom rating icons + +Section Source + +- [frontend/antd/rate/rate.tsx:1-45](file://frontend/antd/rate/rate.tsx#L1-L45) + +### Switch + +- Data binding: onValueChange receives a boolean value; onChange passes through +- Slots: checkedChildren, unCheckedChildren + +Section Source + +- [frontend/antd/switch/switch.tsx:1-42](file://frontend/antd/switch/switch.tsx#L1-L42) + +### TimePicker + +- Data binding: onValueChange receives a second-level timestamp; onChange/onPanelChange/onCalendarChange passes through +- Internal format: unified dayjs conversion + +Section Source + +- [frontend/antd/time-picker/time-picker.tsx:1-201](file://frontend/antd/time-picker/time-picker.tsx#L1-L201) + +### Transfer + +- Data binding: onValueChange receives target list key values; onChange passes through +- Use cases: multi-select move, sorting, search + +Section Source + +- [frontend/antd/transfer/transfer.tsx](file://frontend/antd/transfer/transfer.tsx) + +### TreeSelect + +- Data binding: onValueChange receives string/array; onChange passes through +- Sub-items: TreeNode is injected via renderItems + +Section Source + +- [frontend/antd/tree-select/tree-select.tsx](file://frontend/antd/tree-select/tree-select.tsx) + +### Upload + +- Data binding: onValueChange receives a file list; onChange passes through +- Use cases: drag and drop, preview, size/type restrictions + +Section Source + +- [frontend/antd/upload/upload.tsx](file://frontend/antd/upload/upload.tsx) + +## Dependency Analysis + +- Inter-component coupling: most components are decoupled through hooks and utility functions, reducing coupling to specific implementations +- Slots and context: withItemsContextProvider and renderItems allow child components to be uniformly injected and rendered +- Event bridging: useValueChange aligns onChange with onValueChange, ensuring parent components subscribe consistently + +```mermaid +graph LR +Utils["utils/*
hooks/renderItems/renderParamsSlot"] --> Auto["AutoComplete"] +Utils --> Cascader +Utils --> ColorPicker +Utils --> DatePicker +Utils --> Slider +Utils --> TimePicker +Form["Form/FormItem/Rule/Provider"] --> Auto +Form --> Cascader +Form --> DatePicker +Form --> TimePicker +``` + +Diagram Source + +- [frontend/antd/auto-complete/auto-complete.tsx:1-151](file://frontend/antd/auto-complete/auto-complete.tsx#L1-L151) +- [frontend/antd/cascader/cascader.tsx:1-207](file://frontend/antd/cascader/cascader.tsx#L1-L207) +- [frontend/antd/color-picker/color-picker.tsx:1-106](file://frontend/antd/color-picker/color-picker.tsx#L1-L106) +- [frontend/antd/date-picker/date-picker.tsx:1-234](file://frontend/antd/date-picker/date-picker.tsx#L1-L234) +- [frontend/antd/slider/slider.tsx:1-97](file://frontend/antd/slider/slider.tsx#L1-L97) +- [frontend/antd/time-picker/time-picker.tsx:1-201](file://frontend/antd/time-picker/time-picker.tsx#L1-L201) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/form/item/form.item.tsx](file://frontend/antd/form/item/form.item.tsx) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) +- [frontend/antd/form/provider/form.provider.tsx](file://frontend/antd/form/provider/form.provider.tsx) + +## Performance and Large Data Optimization + +- List rendering + - Use virtual scrolling: in Select/Cascader/TreeSelect, prioritize virtualization solutions to reduce the number of DOM nodes + - Lazy loading: Cascader's onLoadData only requests data when expanded, avoiding loading everything at once +- Input performance + - Debounce/throttle: add debounce to AutoComplete's filterOption or search-type inputs + - Batch updates: use batch submission in Form to reduce re-render counts +- Date and time + - Use dayjs internally, output second-level timestamps externally to avoid repeated parsing + - Render presets and panels with memoization to reduce unnecessary recalculations +- Graphics and colors + - ColorPicker computes output in gradient scenarios according to value_format, avoiding repeated formatting + +## Accessibility and Keyboard Navigation + +- Semantic labels: Radio/Checkbox/Switch, etc. provide clear aria attributes and label associations +- Keyboard navigation: DatePicker/TimePicker/Select/Slider support standard operations such as Tab/Enter/arrow keys +- Focus management: getPopupContainer mounts the overlay inside a container to avoid focus loss +- Screen readers: FormItem provides help/status text to assist in describing errors and prompt information + +## Complex Form Design Patterns and Data Flow + +- Multi-step forms: use FormProvider global configuration combined with onPanelChange and linked fields +- Conditional rendering: dynamically show/hide sections based on field values, combined with FormItem's required and Rule +- Dynamic fields: inject Option/TreeNode/Mark via renderItems to implement dynamic add/edit/delete +- Linked fields and computation: trigger side effects in onValueChange (such as calculating total price, filling in address), and update other fields via Form.setFieldsValue + +```mermaid +sequenceDiagram +participant F as "Form" +participant I1 as "FormItem A" +participant I2 as "FormItem B" +F->>I1 : User input +I1-->>F : onValueChange(newValueA) +F->>I2 : setFieldsValue(linked field) +I2-->>F : onValueChange(newValueB) +F-->>F : Validate and submit +``` + +Diagram Source + +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/form/item/form.item.tsx](file://frontend/antd/form/item/form.item.tsx) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) + +## Troubleshooting Guide + +- Event not triggered + - Check whether onValueChange is passed in correctly; confirm whether onChange has been overridden +- Value not updating + - In controlled mode, confirm whether the parent component calls setState in time; check the dependencies of useValueChange +- Slot not working + - Confirm whether slots.key is consistent with the component's contract; check renderParamsSlot's key +- Validation not working + - Check FormItem.Rule's trigger and rules configuration; confirm the timing of Form.validateFields call +- Date anomaly + - Confirm that the input is a second-level timestamp; check the dayjs conversion chain and defaultValue/defaultPickerValue + +Section Source + +- [frontend/antd/auto-complete/auto-complete.tsx:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) +- [frontend/antd/date-picker/date-picker.tsx:126-170](file://frontend/antd/date-picker/date-picker.tsx#L126-L170) +- [frontend/antd/time-picker/time-picker.tsx:109-143](file://frontend/antd/time-picker/time-picker.tsx#L109-L143) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) + +## Conclusion + +This project achieves high consistency and strong extensibility for Ant Design components on the frontend through unified wrapping patterns and hooks utilities. With a clear practical path centered on data binding, validation rules, formatting options, and complex form design, it is recommended to combine virtual scrolling, lazy loading, and debounce strategies in actual business scenarios to continuously optimize performance, while improving accessibility and keyboard navigation to enhance the user experience. diff --git a/.wiki/en/Ant Design Components/Data Entry Components/DateTime Components.md b/.wiki/en/Ant Design Components/Data Entry Components/DateTime Components.md new file mode 100644 index 00000000..e599c10b --- /dev/null +++ b/.wiki/en/Ant Design Components/Data Entry Components/DateTime Components.md @@ -0,0 +1,463 @@ +# DateTime Components + + +**Files referenced in this document** +- [frontend/antd/date-picker/date-picker.tsx](file://frontend/antd/date-picker/date-picker.tsx) +- [frontend/antd/date-picker/context.ts](file://frontend/antd/date-picker/context.ts) +- [frontend/antd/date-picker/preset/date-picker.preset.tsx](file://frontend/antd/date-picker/preset/date-picker.preset.tsx) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx) +- [frontend/antd/time-picker/time-picker.tsx](file://frontend/antd/time-picker/time-picker.tsx) +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx) +- [frontend/antd/calendar/calendar.tsx](file://frontend/antd/calendar/calendar.tsx) +- [frontend/antd/statistic/statistic.tsx](file://frontend/antd/statistic/statistic.tsx) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx](file://frontend/antd/statistic/countdown/statistic.countdown.tsx) +- [frontend/antd/statistic/timer/statistic.timer.tsx](file://frontend/antd/statistic/timer/statistic.timer.tsx) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document systematically covers the "date and time" related components and capabilities in the ModelScope Studio frontend, including: + +- DatePicker and DateRangePicker +- TimePicker and TimeRangePicker +- Calendar +- Countdown and Timer within Statistic +- Date formatting, timezone and time unit conversion, range selection, quick options (presets), and disabled date/time +- Localization (ConfigProvider) and internationalization configuration (locales) +- Validation rules and business scenario applications +- Accessibility and keyboard navigation +- Handling patterns and best practices for complex date/time scenarios + +## Project Structure + +The frontend implementation around date/time components is primarily located in the antd-prefixed directory, using Svelte + React wrapping (sveltify) to bridge Ant Design components, with ConfigProvider providing unified theming and internationalization. + +```mermaid +graph TB +subgraph "Date/Time Components" +DP["DatePicker"] +DRP["DateRangePicker"] +TP["TimePicker"] +TRP["TimeRangePicker"] +CAL["Calendar"] +STAT["Statistic"] +CD["Statistic.Countdown"] +TM["Statistic.Timer"] +end +subgraph "Bridge Layer" +Sveltify["sveltify Wrapper"] +Slots["Slot Rendering
renderParamsSlot/ReactSlot"] +Hooks["Utility Hooks
useFunction/useMemo"] +end +subgraph "Internationalization and Theming" +CP["ConfigProvider
Theme/Popup Container/Empty State"] +LOCALES["locales.ts
Multilingual Mapping and On-demand Loading"] +end +DP --> Sveltify +DRP --> Sveltify +TP --> Sveltify +TRP --> Sveltify +CAL --> Sveltify +STAT --> Sveltify +CD --> Sveltify +TM --> Sveltify +Sveltify --> Slots +Sveltify --> Hooks +CP --> LOCALES +CP --> Sveltify +``` + +Diagram Source + +- [frontend/antd/date-picker/date-picker.tsx:40-231](file://frontend/antd/date-picker/date-picker.tsx#L40-L231) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:29-245](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L29-L245) +- [frontend/antd/time-picker/time-picker.tsx:37-198](file://frontend/antd/time-picker/time-picker.tsx#L37-L198) +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx:26-207](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx#L26-L207) +- [frontend/antd/calendar/calendar.tsx:17-99](file://frontend/antd/calendar/calendar.tsx#L17-L99) +- [frontend/antd/statistic/statistic.tsx:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:6-24](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L6-L24) +- [frontend/antd/statistic/timer/statistic.timer.tsx:10-26](file://frontend/antd/statistic/timer/statistic.timer.tsx#L10-L26) +- [frontend/antd/config-provider/config-provider.tsx:53-151](file://frontend/antd/config-provider/config-provider.tsx#L53-L151) +- [frontend/antd/config-provider/locales.ts:89-863](file://frontend/antd/config-provider/locales.ts#L89-L863) + +Section Source + +- [frontend/antd/date-picker/date-picker.tsx:1-234](file://frontend/antd/date-picker/date-picker.tsx#L1-L234) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:1-248](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L1-L248) +- [frontend/antd/time-picker/time-picker.tsx:1-201](file://frontend/antd/time-picker/time-picker.tsx#L1-L201) +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx:1-211](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx#L1-L211) +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [frontend/antd/statistic/statistic.tsx:1-34](file://frontend/antd/statistic/statistic.tsx#L1-L34) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:1-27](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L1-L27) +- [frontend/antd/statistic/timer/statistic.timer.tsx:1-29](file://frontend/antd/statistic/timer/statistic.timer.tsx#L1-L29) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) + +## Core Components + +- DatePicker: supports date and time selection, range selection, preset shortcuts, disabled date/time, panel switch callbacks, custom popup containers, etc. +- TimePicker: supports time selection, range selection, disabled time, panel switching, and calendar linked callbacks. +- Calendar: provides a full month view, supports custom cell rendering, header rendering, and valid range restriction. +- Statistic: basic statistic display; both Countdown and Timer accept values in seconds and internally auto-convert to milliseconds to pass to the underlying component. + +Section Source + +- [frontend/antd/date-picker/date-picker.tsx:40-170](file://frontend/antd/date-picker/date-picker.tsx#L40-L170) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:29-177](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L29-L177) +- [frontend/antd/time-picker/time-picker.tsx:37-143](file://frontend/antd/time-picker/time-picker.tsx#L37-L143) +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx:26-146](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx#L26-L146) +- [frontend/antd/calendar/calendar.tsx:17-94](file://frontend/antd/calendar/calendar.tsx#L17-L94) +- [frontend/antd/statistic/statistic.tsx:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:6-21](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L6-L21) +- [frontend/antd/statistic/timer/statistic.timer.tsx:10-23](file://frontend/antd/statistic/timer/statistic.timer.tsx#L10-L23) + +## Architecture Overview + +Components are uniformly wrapped through sveltify around Ant Design components, using dayjs for date parsing and formatting. They expose a unified second-level timestamp interface externally, then internally convert to milliseconds to pass to the underlying component. ConfigProvider handles theme algorithms, popup containers, empty state rendering, and internationalization (Antd language packs and dayjs language packs). + +```mermaid +sequenceDiagram +participant U as "User" +participant C as "Component (e.g. DatePicker)" +participant F as "Formatting function (formatDayjs/formatDate)" +participant D as "dayjs" +participant A as "Antd Component" +U->>C : Select date/time +C->>F : Input value (may be seconds/milliseconds/string) +F->>D : Parse to dayjs object +D-->>F : dayjs instance +F-->>C : Format to second-level timestamp +C->>A : Pass millisecond value and callback parameters +A-->>C : Callback triggered (onChange/onPanelChange) +C-->>U : Trigger onValueChange/onChange (second-level timestamp) +``` + +Diagram Source + +- [frontend/antd/date-picker/date-picker.tsx:14-38](file://frontend/antd/date-picker/date-picker.tsx#L14-L38) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:14-27](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L14-L27) +- [frontend/antd/time-picker/time-picker.tsx:11-35](file://frontend/antd/time-picker/time-picker.tsx#L11-L35) +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx:11-24](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx#L11-L24) + +## Detailed Component Analysis + +### DatePicker + +- Data flow and formatting + - Input supports number (seconds), string, dayjs objects; internally unified to dayjs. + - Output is uniformly a second-level timestamp for easy backend or cross-component passing. +- Key capabilities + - showTime supports object form, and defaultValue will also be formatted. + - disabledDate/disabledTime customize disabled logic. + - presets shortcuts: injected via context, supports dynamic rendering and formatting. + - cellRender/panelRender slot-based rendering. + - getPopupContainer customizes popup container. +- Event callbacks + - onValueChange: unified value change callback (second-level). + - onChange/onPanelChange: both native callback and secondary wrapped callback are available. + +```mermaid +flowchart TD +Start(["Start"]) --> Parse["Parse input to dayjs"] +Parse --> ShowTime{"Time enabled?"} +ShowTime --> |Yes| FormatST["Format default time"] +ShowTime --> |No| SkipST["Skip default time"] +FormatST --> Presets["Merge/format preset items"] +SkipST --> Presets +Presets --> Render["Render component and bind callbacks"] +Render --> End(["End"]) +``` + +Diagram Source + +- [frontend/antd/date-picker/date-picker.tsx:91-161](file://frontend/antd/date-picker/date-picker.tsx#L91-L161) + +Section Source + +- [frontend/antd/date-picker/date-picker.tsx:1-234](file://frontend/antd/date-picker/date-picker.tsx#L1-L234) +- [frontend/antd/date-picker/context.ts:1-7](file://frontend/antd/date-picker/context.ts#L1-L7) +- [frontend/antd/date-picker/preset/date-picker.preset.tsx:1-14](file://frontend/antd/date-picker/preset/date-picker.preset.tsx#L1-L14) + +### DateRangePicker + +- Data flow + - Input/output are both two-element arrays [start, end], with elements as second-level timestamps. + - Default value, current value, and panel value are all formatted and mapped as arrays using dayjs. +- Key capabilities + - showTime's defaultValue supports array mapping. + - presets also support array formatting. + - separator supports slot-based separator. +- Event callbacks + - onValueChange, onChange, onPanelChange, onCalendarChange all return second-level arrays. + +```mermaid +sequenceDiagram +participant U as "User" +participant RP as "DateRangePicker" +participant F as "formatDates" +participant A as "Antd.RangePicker" +U->>RP : Select start and end dates +RP->>F : Input [start, end] (may be dayjs/seconds) +F-->>RP : Return [start, end] (seconds) +RP->>A : Pass millisecond values and callbacks +A-->>RP : Callback triggered +RP-->>U : onValueChange/onChange (second-level array) +``` + +Diagram Source + +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:21-27](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L21-L27) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:165-177](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L165-L177) + +Section Source + +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:1-248](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L1-L248) + +### TimePicker + +- Data flow + - Input supports number (seconds), string, dayjs; uniformly formatted to dayjs. + - Output is a second-level value (number or string), ensuring consistency via onValueChange. +- Key capabilities + - disabledTime/disabledDate controls available time slots. + - cellRender/panelRender supports slots. + - onCalendarChange and onPanelChange. +- Event callbacks + - onValueChange receives second-level values; onChange/onPanelChange are also formatted before callback. + +```mermaid +flowchart TD +S(["Start"]) --> V["Validate/format input to dayjs"] +V --> DT{"Disabled time?"} +DT --> |Yes| Block["Block selection"] +DT --> |No| RenderT["Render TimePicker"] +RenderT --> Evt["Trigger onChange/onPanelChange/onCalendarChange"] +Evt --> Out["Format to seconds and callback onValueChange"] +Out --> End(["End"]) +``` + +Diagram Source + +- [frontend/antd/time-picker/time-picker.tsx:88-143](file://frontend/antd/time-picker/time-picker.tsx#L88-L143) + +Section Source + +- [frontend/antd/time-picker/time-picker.tsx:1-201](file://frontend/antd/time-picker/time-picker.tsx#L1-L201) + +### TimeRangePicker + +- Data flow + - Input/output are [start, end] arrays with elements as second-level timestamps. + - Default value, current value, and panel value are all formatted as array mappings. +- Key capabilities + - disabledTime/disabledDate controls available time slots. + - separator supports slot-based separator. +- Event callbacks + - onValueChange, onChange, onPanelChange, onCalendarChange all return second-level arrays. + +Section Source + +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx:1-211](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx#L1-L211) + +### Calendar + +- Data flow + - Input/output are uniformly second-level timestamps; internally converted to milliseconds for Antd Calendar. +- Key capabilities + - validRange restricts the valid range. + - cellRender/fullCellRender/headerRender support slots. + - onSelect/onPanelChange/onChange uniformly callback second-level values. +- Note + - disabledDate is not directly exposed; it can be controlled by passing values from external logic. + +Section Source + +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) + +### Statistic / Countdown / Timer + +- Statistic + - Supports slot-based title/prefix/suffix/formatter. +- Statistic.Countdown + - Input value supports seconds or milliseconds; internally converts seconds to milliseconds. + - Supports slot-based title/prefix/suffix. +- Statistic.Timer + - Input value supports seconds or milliseconds; internally converts seconds to milliseconds. + - Supports slot-based title/prefix/suffix. + +```mermaid +sequenceDiagram +participant U as "User" +participant CD as "Countdown" +participant TM as "Timer" +participant A as "Antd.Statistic" +U->>CD : Set target time (seconds) +CD->>CD : Convert seconds to milliseconds +CD->>A : Render countdown +A-->>U : Display remaining time +U->>TM : Set initial value (seconds) +TM->>TM : Convert seconds to milliseconds +TM->>A : Render timer +A-->>U : Display elapsed time +``` + +Diagram Source + +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:11-21](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L11-L21) +- [frontend/antd/statistic/timer/statistic.timer.tsx:13-23](file://frontend/antd/statistic/timer/statistic.timer.tsx#L13-L23) + +Section Source + +- [frontend/antd/statistic/statistic.tsx:1-34](file://frontend/antd/statistic/statistic.tsx#L1-L34) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:1-27](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L1-L27) +- [frontend/antd/statistic/timer/statistic.timer.tsx:1-29](file://frontend/antd/statistic/timer/statistic.timer.tsx#L1-L29) + +## Dependency Analysis + +- Components to utilities + - Uses dayjs for date parsing and formatting. + - Uses useFunction/useMemo to stabilize callbacks and computations. + - Uses renderParamsSlot/ReactSlot for slot-based rendering. +- Components to context + - DatePicker presets are injected and consumed via createItemsContext. +- Internationalization and theming + - ConfigProvider is responsible for: + - Theme algorithms (dark/compact). + - Popup containers and target container functions. + - Empty state rendering. + - Internationalization: Antd language packs and dayjs language packs loaded on demand. + - locales.ts provides mapping from language codes to language packs with async loading. + +```mermaid +graph LR +DP["DatePicker"] --> Dayjs["dayjs"] +DRP["DateRangePicker"] --> Dayjs +TP["TimePicker"] --> Dayjs +TRP["TimeRangePicker"] --> Dayjs +CAL["Calendar"] --> Dayjs +DP --> Hooks["useFunction/useMemo"] +DRP --> Hooks +TP --> Hooks +TRP --> Hooks +CAL --> Hooks +DP --> Slots["renderParamsSlot/ReactSlot"] +DRP --> Slots +TP --> Slots +TRP --> Slots +CAL --> Slots +CP["ConfigProvider"] --> LOCALES["locales.ts"] +CP --> Theme["Theme Algorithm/Container/Empty State"] +``` + +Diagram Source + +- [frontend/antd/date-picker/date-picker.tsx:1-11](file://frontend/antd/date-picker/date-picker.tsx#L1-L11) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:1-7](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L1-L7) +- [frontend/antd/time-picker/time-picker.tsx:1-6](file://frontend/antd/time-picker/time-picker.tsx#L1-L6) +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx:1-6](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx#L1-L6) +- [frontend/antd/calendar/calendar.tsx:1-6](file://frontend/antd/calendar/calendar.tsx#L1-L6) +- [frontend/antd/config-provider/config-provider.tsx:1-11](file://frontend/antd/config-provider/config-provider.tsx#L1-L11) +- [frontend/antd/config-provider/locales.ts:1-10](file://frontend/antd/config-provider/locales.ts#L1-L10) + +Section Source + +- [frontend/antd/date-picker/date-picker.tsx:1-234](file://frontend/antd/date-picker/date-picker.tsx#L1-L234) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:1-248](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L1-L248) +- [frontend/antd/time-picker/time-picker.tsx:1-201](file://frontend/antd/time-picker/time-picker.tsx#L1-L201) +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx:1-211](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx#L1-L211) +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) + +## Performance Considerations + +- Formatting and caching + - Use useMemo to cache formatted dayjs values to avoid repeated computation. + - useFunction stabilizes callback references to reduce unnecessary re-renders. +- On-demand loading + - ConfigProvider async-loads Antd and dayjs language resources when locale changes, reducing initial bundle size. +- Rendering optimization + - Slot-based rendering only mounts when needed, reducing irrelevant node overhead. +- Recommendations + - For wide range selection or frequent updates, apply throttle/debounce at the parent level as much as possible. + - When there are many preset items, consider lazy loading and virtualized rendering. + +## Troubleshooting Guide + +- Date not displayed or displayed incorrectly + - Check whether the input is a second-level timestamp; the component internally converts it to milliseconds. + - Confirm that the dayjs language has been correctly set (ConfigProvider sets it automatically). +- Internationalization not taking effect + - Confirm that the locale parameter format conforms to the specification (e.g., zh_CN, en_US); locales.ts contains the corresponding mapping. + - If the language pack fails to load, check network and build configuration. +- Preset items not displayed + - Confirm that preset items have been injected via context, and ensure the value format is dayjs. +- Disabled logic not working + - disabledDate/disabledTime should be functions; ensure stable references by wrapping with useFunction. +- Callback not triggered + - Confirm that using onValueChange and onChange simultaneously does not cause state inconsistency. + - Check whether getPopupContainer correctly returns the container. + +Section Source + +- [frontend/antd/config-provider/config-provider.tsx:96-105](file://frontend/antd/config-provider/config-provider.tsx#L96-L105) +- [frontend/antd/date-picker/date-picker.tsx:86-90](file://frontend/antd/date-picker/date-picker.tsx#L86-L90) +- [frontend/antd/time-picker/time-picker.tsx:83-87](file://frontend/antd/time-picker/time-picker.tsx#L83-L87) + +## Conclusion + +This date/time component system is built on Ant Design and provides complete capabilities from dates and times to calendar, countdown, and timer through a unified formatting and slot-based mechanism. With ConfigProvider's theming and internationalization support, it can meet complex business requirements in multi-language and multi-theme scenarios. It is recommended to follow the "unified second-level timestamp" data contract in actual use, combined with useMemo/useFunction for performance optimization, and extend UI expressiveness through slot-based customization. + +## Appendix + +### Localization and Internationalization Configuration + +- ConfigProvider + - Supports themeMode to switch dark/compact algorithms. + - Supports getPopupContainer/getTargetContainer to customize containers. + - Supports renderEmpty for custom empty state. + - The locale parameter supports language codes; locales.ts provides mapping and async loading. +- locales.ts + - Provides 80+ language code mappings with on-demand loading of Antd and dayjs language packs. + - Default language is en_US; dayjs default language is en. + +Section Source + +- [frontend/antd/config-provider/config-provider.tsx:53-151](file://frontend/antd/config-provider/config-provider.tsx#L53-L151) +- [frontend/antd/config-provider/locales.ts:89-863](file://frontend/antd/config-provider/locales.ts#L89-L863) + +### Accessibility and Keyboard Navigation + +- Recommendations + - Use standard semantic labels and native interactions to ensure keyboard accessibility. + - Mount popup layers inside focusable containers via getPopupContainer. + - Preserve focus management and accessibility attributes in custom cellRender/headerRender. + - For countdown/timer, provide clear titles and unit hints for screen reader recognition. + +### Complex Scenario Handling Patterns and Best Practices + +- Cross-timezone scenarios + - Recommended to uniformly store and transmit UTC second-level timestamps, and perform localized display in the presentation layer based on ConfigProvider's dayjs language and locale settings. +- Range selection + - Use DateRangePicker/TimeRangePicker and validate start/end order and validity at the parent level. +- Preset shortcuts + - Inject preset items via DatePickerPreset, ensure values are in dayjs format to avoid display anomalies from format inconsistencies. +- Validation rules + - Combine disabledDate/disabledTime with min/max date restrictions to form a "disable + validate" dual safeguard. +- Performance + - In large list/high-frequency update scenarios, prioritize useMemo/useCallback to stabilize props and callbacks to reduce re-renders. diff --git a/.wiki/en/Ant Design Components/Data Entry Components/Input Components.md b/.wiki/en/Ant Design Components/Data Entry Components/Input Components.md new file mode 100644 index 00000000..a19ce6e3 --- /dev/null +++ b/.wiki/en/Ant Design Components/Data Entry Components/Input Components.md @@ -0,0 +1,516 @@ +# Input Components + + +**Files referenced in this document** +- [input.tsx](file://frontend/antd/input/input.tsx) +- [input-number.tsx](file://frontend/antd/input-number/input-number.tsx) +- [auto-complete.tsx](file://frontend/antd/auto-complete/auto-complete.tsx) +- [mentions.tsx](file://frontend/antd/mentions/mentions.tsx) +- [input.password.tsx](file://frontend/antd/input/password/input.password.tsx) +- [input.search.tsx](file://frontend/antd/input/search/input.search.tsx) +- [input.textarea.tsx](file://frontend/antd/input/textarea/input.textarea.tsx) +- [input.otp.tsx](file://frontend/antd/input/otp/input.otp.tsx) +- [context.ts](file://frontend/antd/auto-complete/context.ts) +- [hooks/useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [renderItems.ts](file://frontend/utils/renderItems.ts) +- [renderParamsSlot.ts](file://frontend/utils/renderParamsSlot.ts) +- [omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) + +## Introduction + +This section covers the usage and extension of "input-type data entry components", including: Input, InputNumber, AutoComplete, Mentions, InputPassword, InputSearch, InputTextarea, and InputOTP. The document focuses on: + +- How input validation, formatting, debounce, and character limiting are implemented within components, and best practices +- Accessibility and keyboard navigation support +- Integration patterns with form validation +- Performance optimization strategies for large-scale data input scenarios + +## Project Structure + +Input components are all located in the frontend Ant Design wrapper layer, using a unified pattern of "sveltify wrapping + React Slot + Hooks value synchronization" to ensure alignment with Ant Design component properties while providing more flexible slot-based and functional callback capabilities. + +```mermaid +graph TB +subgraph "Antd Input Component Wrappers" +A["Input
Text Input"] +B["InputNumber
Numeric Input"] +C["AutoComplete
Auto Complete"] +D["Mentions
Mentions"] +E["InputPassword
Password Input"] +F["InputSearch
Search Input"] +G["InputTextarea
Multiline Textarea"] +H["InputOTP
One-Time Password Input"] +end +subgraph "Common Utilities and Hooks" +U1["useValueChange
Value Change Sync"] +U2["useFunction
Function Wrapping"] +U3["renderItems
Option Rendering"] +U4["renderParamsSlot
Parameterized Slots"] +U5["omitUndefinedProps
Property Trimming"] +end +A --> U1 +A --> U2 +A --> U4 +A --> U5 +B --> U1 +B --> U2 +B --> U4 +C --> U1 +C --> U2 +C --> U3 +C --> U4 +C --> U5 +C -.-> X["AutoComplete Context"] +D --> U1 +D --> U2 +D --> U3 +D --> U4 +D --> U5 +E --> U1 +E --> U2 +E --> U4 +E --> U5 +F --> U1 +F --> U2 +F --> U4 +F --> U5 +G --> U1 +G --> U2 +G --> U4 +G --> U5 +H --> U1 +H --> U2 +H --> U4 +``` + +Diagram Source + +- [input.tsx:10-116](file://frontend/antd/input/input.tsx#L10-L116) +- [input-number.tsx:7-89](file://frontend/antd/input-number/input-number.tsx#L7-L89) +- [auto-complete.tsx:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) +- [mentions.tsx:11-77](file://frontend/antd/mentions/mentions.tsx#L11-L77) +- [input.password.tsx:10-126](file://frontend/antd/input/password/input.password.tsx#L10-L126) +- [input.search.tsx:10-123](file://frontend/antd/input/search/input.search.tsx#L10-L123) +- [input.textarea.tsx:10-88](file://frontend/antd/input/textarea/input.textarea.tsx#L10-L88) +- [input.otp.tsx:7-54](file://frontend/antd/input/otp/input.otp.tsx#L7-L54) +- [context.ts](file://frontend/antd/auto-complete/context.ts) +- [hooks/useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [renderItems.ts](file://frontend/utils/renderItems.ts) +- [renderParamsSlot.ts](file://frontend/utils/renderParamsSlot.ts) +- [omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +Section Source + +- [input.tsx:1-119](file://frontend/antd/input/input.tsx#L1-L119) +- [input-number.tsx:1-92](file://frontend/antd/input-number/input-number.tsx#L1-L92) +- [auto-complete.tsx:1-151](file://frontend/antd/auto-complete/auto-complete.tsx#L1-L151) +- [mentions.tsx:1-80](file://frontend/antd/mentions/mentions.tsx#L1-L80) +- [input.password.tsx:1-129](file://frontend/antd/input/password/input.password.tsx#L1-L129) +- [input.search.tsx:1-126](file://frontend/antd/input/search/input.search.tsx#L1-L126) +- [input.textarea.tsx:1-91](file://frontend/antd/input/textarea/input.textarea.tsx#L1-L91) +- [input.otp.tsx:1-57](file://frontend/antd/input/otp/input.otp.tsx#L1-L57) + +## Core Components + +This section outlines the key responsibilities and common design of each component: + +- Value synchronization and callbacks: through the unified useValueChange hook, the controlled value is decoupled from the onValueChange callback, ensuring consistent updates between input events and external state. +- Function wrapping: useFunction converts incoming functions (such as formatter, parser, filterOption) into stable references, avoiding unnecessary re-renders. +- Slot system: ReactSlot and renderParamsSlot support slot-based custom rendering (such as prefix/suffix, clear icon, dropdown items, separators, etc.) and allow parameter passing. +- Property trimming: omitUndefinedProps only passes valid configuration, preventing undefined properties from affecting rendering or behavior. +- Option rendering: renderItems converts option nodes from slots into the options array required by Ant Design, supporting both default and custom option sets. + +Section Source + +- [input.tsx:39-42](file://frontend/antd/input/input.tsx#L39-L42) +- [input-number.tsx:32-35](file://frontend/antd/input-number/input-number.tsx#L32-L35) +- [auto-complete.tsx:63-66](file://frontend/antd/auto-complete/auto-complete.tsx#L63-L66) +- [mentions.tsx:34-37](file://frontend/antd/mentions/mentions.tsx#L34-L37) +- [hooks/useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [renderItems.ts](file://frontend/utils/renderItems.ts) +- [renderParamsSlot.ts](file://frontend/utils/renderParamsSlot.ts) +- [omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +## Architecture Overview + +The unified architecture of input components consists of "wrapper layer + utility layer + AntD native components", forming clear responsibility boundaries and reuse paths. + +```mermaid +sequenceDiagram +participant U as "User" +participant S as "Svelte Component (Wrapper)" +participant H as "Hooks/Utilities" +participant R as "AntD Native Component" +U->>S : Input/select/keypress +S->>H : Trigger value sync/function wrapping/slot rendering +H-->>S : Return stable value/function/render result +S->>R : Render native component (with value/callbacks/slots) +R-->>S : Trigger onChange/callback +S->>H : Update controlled value (onValueChange) +H-->>S : Complete sync +S-->>U : UI update +``` + +Diagram Source + +- [input.tsx:47-54](file://frontend/antd/input/input.tsx#L47-L54) +- [input-number.tsx:39-46](file://frontend/antd/input-number/input-number.tsx#L39-L46) +- [auto-complete.tsx:76-104](file://frontend/antd/auto-complete/auto-complete.tsx#L76-L104) +- [mentions.tsx:44-61](file://frontend/antd/mentions/mentions.tsx#L44-L61) +- [hooks/useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) + +## Detailed Component Analysis + +### Input + +- Key features + - Controlled value: synchronizes props.value with internal state via useValueChange; triggers onValueChange on onChange. + - Character counting: showCount supports functional formatter; count supports combined configuration of strategy/exceedFormatter/show, using useMemo and omitUndefinedProps to trim invalid fields. + - Slot-based decoration: addonBefore/After, prefix/suffix, allowClear.clearIcon can inject custom nodes via slots. +- Input validation and formatting + - No built-in regex validation; recommended to combine with form validators or perform validation within onValueChange. + - formatter/parser are passed in from the parent; not covered here. +- Debounce and character limits + - No built-in debounce; throttle/debounce can be self-implemented in onValueChange. + - maxLength is natively supported by AntD and used together with showCount. +- Accessibility and keyboard navigation + - Preserves native input behavior, following browser default keyboard interactions. +- Integration with form validation + - Recommended to perform real-time validation in onValueChange and update state via setFieldError/setFieldValue exposed by the form context. +- Performance optimization + - Use useMemo to cache count configuration to reduce re-renders. + - Only render the corresponding decoration node when slots exist, avoiding empty branch overhead. + +Section Source + +- [input.tsx:39-84](file://frontend/antd/input/input.tsx#L39-L84) +- [input.tsx:85-112](file://frontend/antd/input/input.tsx#L85-L112) + +### InputNumber + +- Key features + - Controlled value and callbacks: same as above, using useValueChange to sync values. + - Formatting/parsing: formatter/parser are passed in as functions, wrapped with useFunction for stable references. + - Control icons: controls.upIcon/controls.downIcon support slot injection. + - Decoration and prefix/suffix: addonBefore/After, prefix/suffix support slots. +- Input validation and formatting + - No built-in validation; recommended to perform range and format validation in onChange or onValueChange. + - formatter/parser are used for display and parsing to prevent users from entering non-numeric characters. +- Debounce and character limits + - No built-in debounce; can be implemented in onValueChange. +- Accessibility and keyboard navigation + - Preserves native numeric input behavior, supports up/down arrows to increment/decrement. +- Integration with form validation + - Perform numeric range and precision validation in onValueChange and sync form state. +- Performance optimization + - formatter/parser and control icons are rendered on demand, reducing unnecessary overhead. + +Section Source + +- [input-number.tsx:32-35](file://frontend/antd/input-number/input-number.tsx#L32-L35) +- [input-number.tsx:47-64](file://frontend/antd/input-number/input-number.tsx#L47-L64) +- [input-number.tsx:79-84](file://frontend/antd/input-number/input-number.tsx#L79-L84) + +### AutoComplete + +- Key features + - Value sync: useValueChange syncs value with onValueChange. + - Option rendering: prefers passed-in options; otherwise extracts from slots and converts using renderItems. + - Dropdown rendering: dropdownRender/popupRender support both slot and function forms. + - Filter logic: filterOption supports functions or boolean values; getPopupContainer specifies the popup container. + - Clear and decoration: allowClear.clearIcon, notFoundContent, addonBefore/After, prefix/suffix support slots. +- Input validation and formatting + - No built-in validation; control candidate set via filterOption and validateSearch. + - Recommended to perform secondary validation in onChange/onValueChange. +- Debounce and character limits + - No built-in debounce; can be implemented in onValueChange. +- Accessibility and keyboard navigation + - Supports keyboard up/down selection, Enter to confirm, Tab to switch. +- Integration with form validation + - Use the form context to set error messages in onValueChange. +- Performance optimization + - Use useMemo to cache options; only render decoration nodes when slots exist. + +```mermaid +flowchart TD +Start(["Input event"]) --> Filter["Apply filterOption/validateSearch"] +Filter --> HasOptions{"Matching items?"} +HasOptions -- Yes --> RenderList["Render candidate list
dropdownRender/popupRender"] +HasOptions -- No --> NotFound["Render notFoundContent"] +RenderList --> Select["User selects/Enter to confirm"] +NotFound --> Select +Select --> Sync["useValueChange syncs value"] +Sync --> End(["Done"]) +``` + +Diagram Source + +- [auto-complete.tsx:89-100](file://frontend/antd/auto-complete/auto-complete.tsx#L89-L100) +- [auto-complete.tsx:114-135](file://frontend/antd/auto-complete/auto-complete.tsx#L114-L135) +- [mentions.tsx:48-57](file://frontend/antd/mentions/mentions.tsx#L48-L57) + +Section Source + +- [auto-complete.tsx:63-66](file://frontend/antd/auto-complete/auto-complete.tsx#L63-L66) +- [auto-complete.tsx:89-100](file://frontend/antd/auto-complete/auto-complete.tsx#L89-L100) +- [auto-complete.tsx:114-135](file://frontend/antd/auto-complete/auto-complete.tsx#L114-L135) +- [context.ts](file://frontend/antd/auto-complete/context.ts) + +### Mentions + +- Key features + - Value sync: useValueChange syncs value with onValueChange. + - Option rendering: prefers options; otherwise uses slot renderItems. + - Filter and validation: filterOption, validateSearch support functional forms. + - Popup container: getPopupContainer specifies the container. + - Clear and placeholder: allowClear.clearIcon, notFoundContent support slots. +- Input validation and formatting + - No built-in validation; control input and candidates via validateSearch and filterOption. +- Debounce and character limits + - No built-in debounce; can be implemented in onValueChange. +- Accessibility and keyboard navigation + - Supports keyboard selection and confirmation. +- Integration with form validation + - Perform format and content validation in onValueChange. +- Performance optimization + - useMemo caches options; renders decoration nodes on demand. + +Section Source + +- [mentions.tsx:34-37](file://frontend/antd/mentions/mentions.tsx#L34-L37) +- [mentions.tsx:48-57](file://frontend/antd/mentions/mentions.tsx#L48-L57) +- [mentions.tsx:62-71](file://frontend/antd/mentions/mentions.tsx#L62-L71) + +### InputPassword + +- Key features + - Controlled value: useValueChange syncs value with onValueChange. + - Show/hide toggle: iconRender supports slots and functions. + - Character counting: showCount/formatter and count configuration support functional forms and trimming. + - Decoration and clear: addonBefore/After, prefix/suffix, allowClear.clearIcon support slots. +- Input validation and formatting + - No built-in validation; recommended to perform strength and length validation in onValueChange. +- Debounce and character limits + - No built-in debounce; can be implemented in onValueChange. +- Accessibility and keyboard navigation + - Preserves native password input behavior. +- Integration with form validation + - Perform password policy validation in onValueChange. +- Performance optimization + - Use useMemo to cache count configuration and iconRender. + +Section Source + +- [input.password.tsx:42-45](file://frontend/antd/input/password/input.password.tsx#L42-L45) +- [input.password.tsx:65-79](file://frontend/antd/input/password/input.password.tsx#L65-L79) +- [input.password.tsx:80-94](file://frontend/antd/input/password/input.password.tsx#L80-L94) +- [input.password.tsx:95-122](file://frontend/antd/input/password/input.password.tsx#L95-L122) + +### InputSearch + +- Key features + - Controlled value: useValueChange syncs value with onValueChange. + - Character counting: showCount/formatter and count configuration support functional forms and trimming. + - Search button: enterButton supports slots and text. + - Decoration and clear: addonBefore/After, prefix/suffix, allowClear.clearIcon support slots. +- Input validation and formatting + - No built-in validation; recommended to perform length and content validation in onValueChange. +- Debounce and character limits + - No built-in debounce; can be implemented in onValueChange. +- Accessibility and keyboard navigation + - Supports Enter to trigger search. +- Integration with form validation + - Perform search term validation in onValueChange. +- Performance optimization + - Use useMemo to cache count configuration and enterButton. + +Section Source + +- [input.search.tsx:40-43](file://frontend/antd/input/search/input.search.tsx#L40-L43) +- [input.search.tsx:70-78](file://frontend/antd/input/search/input.search.tsx#L70-L78) +- [input.search.tsx:85-91](file://frontend/antd/input/search/input.search.tsx#L85-L91) +- [input.search.tsx:92-118](file://frontend/antd/input/search/input.search.tsx#L92-L118) + +### InputTextarea + +- Key features + - Controlled value: useValueChange syncs value with onValueChange. + - Character counting: showCount/formatter and count configuration support functional forms and trimming. + - Clear: allowClear.clearIcon supports slots. +- Input validation and formatting + - No built-in validation; recommended to perform length and content validation in onValueChange. +- Debounce and character limits + - No built-in debounce; can be implemented in onValueChange. +- Accessibility and keyboard navigation + - Supports multiline input and scrolling. +- Integration with form validation + - Perform content and length validation in onValueChange. +- Performance optimization + - Use useMemo to cache count configuration. + +Section Source + +- [input.textarea.tsx:32-35](file://frontend/antd/input/textarea/input.textarea.tsx#L32-L35) +- [input.textarea.tsx:62-76](file://frontend/antd/input/textarea/input.textarea.tsx#L62-L76) +- [input.textarea.tsx:77-83](file://frontend/antd/input/textarea/input.textarea.tsx#L77-L83) + +### InputOTP + +- Key features + - Controlled value: useValueChange syncs value with onValueChange. + - Separator: separator supports slots and functions. + - Formatting: formatter supports functions. +- Input validation and formatting + - No built-in validation; recommended to perform length and character type validation in onValueChange. +- Debounce and character limits + - No built-in debounce; can be implemented in onValueChange. +- Accessibility and keyboard navigation + - Supports cell-by-cell input and automatic focus movement. +- Integration with form validation + - Perform OTP validation in onValueChange. +- Performance optimization + - Use useMemo to cache formatter and separator. + +Section Source + +- [input.otp.tsx:25-28](file://frontend/antd/input/otp/input.otp.tsx#L25-L28) +- [input.otp.tsx:38-44](file://frontend/antd/input/otp/input.otp.tsx#L38-L44) +- [input.otp.tsx:46-49](file://frontend/antd/input/otp/input.otp.tsx#L46-L49) + +## Dependency Analysis + +- Component to utility layer + - All input components depend on useValueChange for controlled value synchronization. + - useFunction is used for stable function references to avoid re-renders. + - renderItems/renderParamsSlot are used for slot options and parameterized rendering. + - omitUndefinedProps is used to trim invalid properties. +- Differences between components + - AutoComplete/Mentions rely on context and slot option rendering. + - InputNumber/InputPassword/InputSearch/InputTextarea/InputOTP functionalize and cache configurations such as showCount/count/formatter. + +```mermaid +graph LR +subgraph "Components" +I["Input"] +N["InputNumber"] +AC["AutoComplete"] +M["Mentions"] +P["InputPassword"] +S["InputSearch"] +T["InputTextarea"] +O["InputOTP"] +end +subgraph "Utilities" +V["useValueChange"] +F["useFunction"] +RI["renderItems"] +RP["renderParamsSlot"] +OD["omitUndefinedProps"] +end +I --> V +I --> F +I --> RP +I --> OD +N --> V +N --> F +N --> RP +AC --> V +AC --> F +AC --> RI +AC --> RP +AC --> OD +M --> V +M --> F +M --> RI +M --> RP +M --> OD +P --> V +P --> F +P --> RP +P --> OD +S --> V +S --> F +S --> RP +S --> OD +T --> V +T --> F +T --> RP +T --> OD +O --> V +O --> F +O --> RP +``` + +Diagram Source + +- [input.tsx:39-84](file://frontend/antd/input/input.tsx#L39-L84) +- [input-number.tsx:32-84](file://frontend/antd/input-number/input-number.tsx#L32-L84) +- [auto-complete.tsx:63-100](file://frontend/antd/auto-complete/auto-complete.tsx#L63-L100) +- [mentions.tsx:34-57](file://frontend/antd/mentions/mentions.tsx#L34-L57) +- [input.password.tsx:42-94](file://frontend/antd/input/password/input.password.tsx#L42-L94) +- [input.search.tsx:40-84](file://frontend/antd/input/search/input.search.tsx#L40-L84) +- [input.textarea.tsx:32-76](file://frontend/antd/input/textarea/input.textarea.tsx#L32-L76) +- [input.otp.tsx:25-44](file://frontend/antd/input/otp/input.otp.tsx#L25-L44) +- [hooks/useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [renderItems.ts](file://frontend/utils/renderItems.ts) +- [renderParamsSlot.ts](file://frontend/utils/renderParamsSlot.ts) +- [omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +## Performance Considerations + +- Controlled value synchronization + - Use useValueChange to uniformly manage the controlled value, avoiding redundant renders caused by inconsistencies between external and internal state. +- Function reference stabilization + - useFunction wraps incoming functions to reduce re-renders caused by prop changes. +- Slot rendering optimization + - Only render the corresponding node when slots exist, avoiding empty branch overhead. +- Configuration caching + - Use useMemo to cache configurations such as showCount/count/formatter to reduce rendering cost. +- Large data input handling + - Avoid heavy computation in onValueChange; if necessary, split into microtasks or use Web Worker. + - For high-frequency inputs (such as search, auto-complete), it is recommended to add debounce/throttle strategies upstream. + - For long text input, prefer TextArea and enable necessary character limits and counting hints. + +## Troubleshooting Guide + +- Input value not syncing + - Check whether onValueChange is correctly passed in and has not been overridden. + - Confirm whether the value in useValueChange is consistent with props.value. +- Slot not working + - Confirm that the slot key name matches the slots supported by the component (such as allowClear.clearIcon, prefix, suffix, enterButton, separator, etc.). + - Check whether the renderParamsSlot key is correct. +- Options not displayed + - AutoComplete/Mentions require providing options or providing options via slots; check the children name and structure in renderItems. +- Formatting anomaly + - Functions such as formatter/parser/filterOption must return the expected type; use useFunction to wrap them for stable references. +- Count configuration invalid + - Confirm that when showCount is an object, provide formatter; use omitUndefinedProps to trim invalid fields in count configuration. + +Section Source + +- [hooks/useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [renderItems.ts](file://frontend/utils/renderItems.ts) +- [renderParamsSlot.ts](file://frontend/utils/renderParamsSlot.ts) +- [omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +## Conclusion + +Input components achieve deep compatibility with Ant Design and flexible extensibility through a unified wrapping pattern. With the help of tools such as useValueChange, useFunction, renderItems, renderParamsSlot, and omitUndefinedProps, the components provide powerful slot-based and functional capabilities while ensuring performance. In actual business scenarios, it is recommended to combine with the form validation system to implement input validation, formatting, and debounce strategies in onValueChange, and to employ caching and asynchronous processing for large-scale data input scenarios, to achieve better user experience and stability. diff --git a/.wiki/en/Ant Design Components/Data Entry Components/Selection Components.md b/.wiki/en/Ant Design Components/Data Entry Components/Selection Components.md new file mode 100644 index 00000000..21a22c7a --- /dev/null +++ b/.wiki/en/Ant Design Components/Data Entry Components/Selection Components.md @@ -0,0 +1,673 @@ +# Selection Components + + +**Files referenced in this document** +- [select.tsx](file://frontend/antd/select/select.tsx) +- [option.tsx](file://frontend/antd/select/option/option.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [group.tsx](file://frontend/antd/checkbox/group/checkbox.group.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [radio.group.tsx](file://frontend/antd/radio/group/radio.group.tsx) +- [switch.tsx](file://frontend/antd/switch/switch.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [option.tsx](file://frontend/antd/segmented/option/segmented.option.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [tree.node.tsx](file://frontend/antd/tree/tree-node/tree.node.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [tree.node.tsx](file://frontend/antd/tree-select/tree-node/tree.node.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [panel.tsx](file://frontend/antd/cascader/panel/panel.tsx) +- [option.tsx](file://frontend/antd/cascader/option/option.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) +- [context.ts](file://frontend/antd/select/context.ts) +- [context.ts](file://frontend/antd/checkbox/context.ts) +- [context.ts](file://frontend/antd/radio/context.ts) +- [context.ts](file://frontend/antd/segmented/context.ts) +- [context.ts](file://frontend/antd/tree/context.ts) +- [context.ts](file://frontend/antd/tree-select/context.ts) +- [context.ts](file://frontend/antd/cascader/context.ts) +- [context.ts](file://frontend/antd/rate/context.ts) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance and Virtual Scrolling](#performance-and-virtual-scrolling) +8. [Accessibility and Keyboard Navigation](#accessibility-and-keyboard-navigation) +9. [Troubleshooting Guide](#troubleshooting-guide) +10. [Conclusion](#conclusion) + +## Introduction + +This document systematically covers the "selection-type" components in the frontend component library: Select, Checkbox, Radio, Switch, Segmented, TreeSelect, Cascader, Transfer, Tree, and Rate. The document covers data binding, option configuration, multi-select mode, and disabled state, combined with design patterns and data flow management for complex scenarios. It also provides accessibility and keyboard navigation recommendations, as well as virtual scrolling and performance optimization strategies for large option sets. + +## Project Structure + +Selection components are primarily located in the frontend Ant Design component directory, organized by functional module: each component is stored in its own directory containing the entry component file and sub-components (such as Option, Group, Panel, etc.), with shared state and configuration managed uniformly through a context file (context.ts). + +```mermaid +graph TB +subgraph "Selection Component Directory" +S["select.tsx"] +C["checkbox.tsx"] +R["radio.tsx"] +SW["switch.tsx"] +SG["segmented.tsx"] +TS["tree-select.tsx"] +CA["cascader.tsx"] +T["tree.tsx"] +TR["transfer.tsx"] +RA["rate.tsx"] +end +subgraph "Sub-components" +SO["option.tsx (select)"] +CO["checkbox.group.tsx"] +RO["radio.group.tsx"] +SGO["segmented.option.tsx"] +TSN["tree.node.tsx (tree-select)"] +TN["tree.node.tsx (tree)"] +CAP["panel.tsx (cascader)"] +CAO["option.tsx (cascader)"] +end +subgraph "Context" +SC["context.ts (select)"] +CC["context.ts (checkbox)"] +RC["context.ts (radio)"] +SGC["context.ts (segmented)"] +TSC["context.ts (tree-select)"] +CAC["context.ts (cascader)"] +TC["context.ts (tree)"] +RAC["context.ts (rate)"] +end +S --> SO +S --> SC +C --> CO +C --> CC +R --> RO +R --> RC +SG --> SGO +SG --> SGC +TS --> TSN +TS --> TSC +T --> TN +T --> TC +CA --> CAP +CA --> CAO +CA --> CAC +TR --> TR +RA --> RAC +``` + +Diagram Source + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [switch.tsx](file://frontend/antd/switch/switch.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) + +Section Source + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [switch.tsx](file://frontend/antd/switch/switch.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) + +## Core Components + +This section outlines the key capabilities and common features of each component: + +- Data binding: controlled/uncontrolled modes, linked to external state via properties such as value/checked. +- Option configuration: declaratively define option sets through child item components (Option/Segmented.Option/Tree.Node, etc.). +- Multi-select mode: Checkbox supports multi-select; Select/Cascader/TreeSelect can be configured for multi-select; Transfer provides a left-right list interaction. +- Disabled state: supports both global disable and per-item disable, ensuring unavailable options do not respond to interaction. +- Controlled updates: onChange callback returns the current selected value, driving upstream state synchronization. + +Section Source + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [switch.tsx](file://frontend/antd/switch/switch.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) + +## Architecture Overview + +Selection components follow a unified "container-item-context" architecture: + +- Container components are responsible for rendering, state management, and event dispatching; +- Item components carry the display and interaction of specific options; +- Context files centrally handle shared logic such as default values, disabled states, and multi-select strategies. + +```mermaid +classDiagram +class Select { ++value ++mode ++disabled ++onChange() +} +class Option { ++label ++value ++disabled +} +class Checkbox { ++checked ++disabled ++onChange() +} +class CheckboxGroup { ++options[] ++value[] ++disabled ++onChange() +} +class Radio { ++checked ++disabled ++onChange() +} +class RadioGroup { ++options[] ++value ++disabled ++onChange() +} +class Switch { ++checked ++disabled ++onChange() +} +class Segmented { ++value ++disabled ++onChange() +} +class SegmentedOption { ++label ++value ++disabled +} +class Tree { ++treeData[] ++expandedKeys[] ++selectedKeys[] ++multiple ++onChange() +} +class TreeNode { ++title ++key ++disabled +} +class TreeSelect { ++treeData[] ++value ++treeDefaultExpandAll ++onChange() +} +class Cascader { ++options[] ++value[] ++onChange() +} +class CascaderPanel { ++options[] ++onChange() +} +class Transfer { ++dataSource[] ++targetKeys[] ++onChange() +} +class Rate { ++value ++allowHalf ++disabled ++onChange() +} +Select --> Option : "contains" +Checkbox --> CheckboxGroup : "combines" +Radio --> RadioGroup : "combines" +Segmented --> SegmentedOption : "contains" +Tree --> TreeNode : "contains" +TreeSelect --> TreeNode : "contains" +Cascader --> CascaderPanel : "contains" +``` + +Diagram Source + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [option.tsx](file://frontend/antd/select/option/option.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [group.tsx](file://frontend/antd/checkbox/group/checkbox.group.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [radio.group.tsx](file://frontend/antd/radio/group/radio.group.tsx) +- [switch.tsx](file://frontend/antd/switch/switch.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [option.tsx](file://frontend/antd/segmented/option/segmented.option.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [tree.node.tsx](file://frontend/antd/tree/tree-node/tree.node.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [tree.node.tsx](file://frontend/antd/tree-select/tree-node/tree.node.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [panel.tsx](file://frontend/antd/cascader/panel/panel.tsx) +- [option.tsx](file://frontend/antd/cascader/option/option.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) + +## Detailed Component Analysis + +### Select + +- Data binding: supports controlled value and uncontrolled default value; onChange returns the selected value or value array (multi-select). +- Option configuration: declare label/value/disabled via Option child items; supports search filtering and tag backfilling. +- Multi-select mode: when multi-select is enabled, supports tag-style display and clearing individual tags. +- Disabled state: both container and individual items can be disabled; when disabled, cannot be expanded or toggled. +- Context: context.ts centrally handles default values, disabled states, multi-select strategies, and controlled validation. + +```mermaid +sequenceDiagram +participant U as "User" +participant S as "Select" +participant O as "Option" +participant C as "Context" +U->>S : Expand dropdown +S->>C : Read default value/disabled state +U->>O : Click an option +O-->>S : Trigger selection callback +S->>S : Update internal state +S-->>U : Close dropdown and display selected item +S->>C : Trigger onChange(value) +``` + +Diagram Source + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [option.tsx](file://frontend/antd/select/option/option.tsx) +- [context.ts](file://frontend/antd/select/context.ts) + +Section Source + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [option.tsx](file://frontend/antd/select/option/option.tsx) +- [context.ts](file://frontend/antd/select/context.ts) + +### Checkbox + +- Data binding: single Checkbox is a controlled checked value; Checkbox.Group receives value[] and syncs via onChange. +- Option configuration: Group's options[] supports passing label/value/disabled directly; child Checkbox items can also be used. +- Multi-select mode: Group defaults to multi-select; supports select all/deselect all and indeterminate state. +- Disabled state: Group-level disable affects all child items; child items can also be individually disabled. +- Context: context.ts is responsible for default values, disabled states, and multi-select strategies. + +```mermaid +flowchart TD +Start(["Enter Checkbox.Group"]) --> LoadOptions["Load options[] or child items"] +LoadOptions --> Render["Render child Checkboxes"] +Render --> Interact{"User interaction?"} +Interact --> |Check/Uncheck| UpdateValue["Update value[]"] +UpdateValue --> Callback["Trigger onChange(value[])"] +Callback --> End(["Done"]) +``` + +Diagram Source + +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [group.tsx](file://frontend/antd/checkbox/group/checkbox.group.tsx) +- [context.ts](file://frontend/antd/checkbox/context.ts) + +Section Source + +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [group.tsx](file://frontend/antd/checkbox/group/checkbox.group.tsx) +- [context.ts](file://frontend/antd/checkbox/context.ts) + +### Radio + +- Data binding: single Radio is a controlled checked value; Radio.Group receives value and syncs via onChange. +- Option configuration: Group's options[] supports label/value/disabled; child Radio items can also be used. +- Multi-select mode: Group is single-select; supports clear and disable. +- Disabled state: Group-level disable affects all child items; child items can also be individually disabled. +- Context: context.ts is responsible for default values, disabled states, and single-select strategies. + +```mermaid +sequenceDiagram +participant U as "User" +participant RG as "Radio.Group" +participant R as "Radio" +participant C as "Context" +U->>R : Click option +R-->>RG : Trigger selection callback +RG->>C : Apply default value/disabled state +RG-->>U : Update selected state and callback onChange(value) +``` + +Diagram Source + +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [radio.group.tsx](file://frontend/antd/radio/group/radio.group.tsx) +- [context.ts](file://frontend/antd/radio/context.ts) + +Section Source + +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [radio.group.tsx](file://frontend/antd/radio/group/radio.group.tsx) +- [context.ts](file://frontend/antd/radio/context.ts) + +### Switch + +- Data binding: controlled checked value; onChange returns the new boolean value. +- Disabled state: disabled disables interaction; supports loading state. +- Use case: suitable for binary selection, such as "enable/disable" or "yes/no". + +Section Source + +- [switch.tsx](file://frontend/antd/switch/switch.tsx) + +### Segmented + +- Data binding: controlled value; onChange returns the selected value. +- Option configuration: supports options[] or child Segmented.Option items; can disable individual items. +- Use case: a compact alternative to Radio.Group, suitable for a small number of discrete options. + +```mermaid +classDiagram +class Segmented { ++value ++options[] ++disabled ++onChange() +} +class SegmentedOption { ++label ++value ++disabled +} +Segmented --> SegmentedOption : "contains" +``` + +Diagram Source + +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [option.tsx](file://frontend/antd/segmented/option/segmented.option.tsx) +- [context.ts](file://frontend/antd/segmented/context.ts) + +Section Source + +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [option.tsx](file://frontend/antd/segmented/option/segmented.option.tsx) +- [context.ts](file://frontend/antd/segmented/context.ts) + +### Tree + +- Data binding: controlled selectedKeys/expandedKeys; onChange returns the selected key set. +- Option configuration: treeData[] supports title/key/children/disabled; supports drag-and-drop, search, and batch selection. +- Multi-select mode: when multiple=true, multi-select is supported; supports both controlled and uncontrolled modes. +- Disabled state: node-level disabled; supports batch disable. + +```mermaid +sequenceDiagram +participant U as "User" +participant T as "Tree" +participant TN as "TreeNode" +participant C as "Context" +U->>TN : Click node +TN-->>T : Trigger selection/expansion +T->>C : Apply multi-select/disable strategy +T-->>U : Update selectedKeys/expandedKeys and callback +``` + +Diagram Source + +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [tree.node.tsx](file://frontend/antd/tree/tree-node/tree.node.tsx) +- [context.ts](file://frontend/antd/tree/context.ts) + +Section Source + +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [tree.node.tsx](file://frontend/antd/tree/tree-node/tree.node.tsx) +- [context.ts](file://frontend/antd/tree/context.ts) + +### TreeSelect + +- Data binding: controlled value; onChange returns the selected key. +- Option configuration: treeData[] with option declaration similar to Select; supports search filtering and tag backfilling. +- Multi-select mode: supports multi-select and parent-child linkage strategies (e.g., leaves only). +- Disabled state: supports global and node-level disable. + +```mermaid +flowchart TD +Open["Expand TreeSelect"] --> Filter["Enter search keyword"] +Filter --> List["Render matching nodes"] +List --> Select["Click node to select"] +Select --> Update["Update value and close panel"] +Update --> Callback["Trigger onChange(value)"] +``` + +Diagram Source + +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [tree.node.tsx](file://frontend/antd/tree-select/tree-node/tree.node.tsx) +- [context.ts](file://frontend/antd/tree-select/context.ts) + +Section Source + +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [tree.node.tsx](file://frontend/antd/tree-select/tree-node/tree.node.tsx) +- [context.ts](file://frontend/antd/tree-select/context.ts) + +### Cascader + +- Data binding: controlled value[]; onChange returns the full path value array. +- Option configuration: options[] supports label/value/children; supports async loading of child levels. +- Multi-select mode: typically single path selection; multiple path selection can be achieved through extensions. +- Disabled state: supports disabling the entire tree and node-level disable. + +```mermaid +sequenceDiagram +participant U as "User" +participant C as "Cascader" +participant P as "CascaderPanel" +participant O as "Option" +participant Ctx as "Context" +U->>C : Open cascade +C->>Ctx : Read default value/disabled state +U->>P : Select level 1 +P-->>C : Notify change +U->>P : Select level 2... +P-->>C : Notify change +C-->>U : Complete path selection and callback onChange(value[]) +``` + +Diagram Source + +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [panel.tsx](file://frontend/antd/cascader/panel/panel.tsx) +- [option.tsx](file://frontend/antd/cascader/option/option.tsx) +- [context.ts](file://frontend/antd/cascader/context.ts) + +Section Source + +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [panel.tsx](file://frontend/antd/cascader/panel/panel.tsx) +- [option.tsx](file://frontend/antd/cascader/option/option.tsx) +- [context.ts](file://frontend/antd/cascader/context.ts) + +### Transfer + +- Data binding: controlled targetKeys[]; onChange returns the target list key set. +- Option configuration: dataSource[] supports title/key; supports search filtering and batch operations. +- Multi-select mode: bidirectional movement from left to right; supports select all/deselect all. +- Disabled state: supports global disable and button disable. + +```mermaid +flowchart TD +Start(["Open Transfer"]) --> SearchLeft["Left side search"] +SearchLeft --> Move["Click move button"] +Move --> UpdateTarget["Update targetKeys[]"] +UpdateTarget --> Callback["Trigger onChange(targetKeys)"] +Callback --> End(["Done"]) +``` + +Diagram Source + +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) + +Section Source + +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) + +### Rate + +- Data binding: controlled value; onChange returns the rating value. +- Option configuration: supports allowHalf half-star, count total, tooltips text. +- Disabled state: disabled disables interaction; supports read-only mode. +- Use case: quick expression of satisfaction or level rating. + +```mermaid +sequenceDiagram +participant U as "User" +participant RA as "Rate" +participant C as "Context" +U->>RA : Mouse hover/click +RA->>C : Apply disabled/read-only strategy +RA-->>U : Update value and callback onChange(value) +``` + +Diagram Source + +- [rate.tsx](file://frontend/antd/rate/rate.tsx) +- [context.ts](file://frontend/antd/rate/context.ts) + +Section Source + +- [rate.tsx](file://frontend/antd/rate/rate.tsx) +- [context.ts](file://frontend/antd/rate/context.ts) + +## Dependency Analysis + +- Low inter-component coupling: container components combine declaratively with child item components, avoiding tight coupling. +- Centralized context: each component's context.ts aggregates default values, disabled states, and multi-select strategies, reducing duplicate logic. +- Clear event chain: from user interaction to container update to callback, forming a stable data flow. + +```mermaid +graph LR +Select["Select"] --> Option["Option"] +Checkbox["Checkbox"] --> CheckboxGroup["Checkbox.Group"] +Radio["Radio"] --> RadioGroup["Radio.Group"] +Segmented["Segmented"] --> SegmentedOption["Segmented.Option"] +Tree["Tree"] --> TreeNode["TreeNode"] +TreeSelect["TreeSelect"] --> TreeNode +Cascader["Cascader"] --> Panel["Cascader.Panel"] +Cascader --> Option +Transfer["Transfer"] +Rate["Rate"] +``` + +Diagram Source + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) + +Section Source + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) + +## Performance and Virtual Scrolling + +- Recommendations for large option sets: + - Use virtual scrolling: for long lists (such as Select/Tree/Transfer), use virtual scroll rendering to only render visible area nodes, significantly reducing DOM count and reflow cost. + - Lazy loading and pagination: for TreeSelect/Cascader, support async loading of child nodes to reduce initial rendering pressure. + - Caching and debounce: debounce search filtering and onChange callbacks to avoid frequent redraws. + - Controlled update optimization: merge multiple state changes in the parent form to reduce unnecessary re-renders. +- Specific implementation points: + - Select: enable virtual scrolling and search filtering for the Option list. + - Tree/TreeSelect: enable virtual scrolling and lazy loading for node rendering. + - Transfer: enable virtual scrolling and batch operation optimization for left and right lists. + +[This section provides general performance guidance and does not require specific file references] + +## Accessibility and Keyboard Navigation + +- Keyboard support: + - Use Tab/Shift+Tab to navigate between options; + - Use Enter/Space to confirm selection; + - Use arrow keys to move among multiple options (such as Tree/Select/Cascader). +- Screen reader friendly: + - Provide semantic labels for each option; + - Disabled and error states provide aria-\* attributes and hint text; + - Provide value reading and tooltips for Rate. +- Recommendations: + - Provide aria-expanded/aria-controls for container components; + - Provide aria-disabled for disabled options; + - Provide aria-required for required fields. + +[This section provides general accessibility guidance and does not require specific file references] + +## Troubleshooting Guide + +- Common issues and diagnosis: + - Selected value not updated: check whether the controlled value and onChange are correctly passed in; confirm consistency of value/checked between container and child items. + - Multi-select not working: confirm the structure of Group's options[] and the type of value[]; check disabled state and indeterminate state. + - Disable not working: verify the disabled attribute hierarchy (container vs. child items); check the disable strategy in context. + - Performance stuttering: enable virtual scrolling for long lists; reduce unnecessary re-renders and deep nesting. +- Debugging recommendations: + - Print the current value in onChange to verify data flow; + - Use browser developer tools to observe DOM count and reflow; + - For TreeSelect/Cascader, check whether async loading is correctly triggered. + +Section Source + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) + +## Conclusion + +Selection components in this project implement a unified container-item-context architecture with good extensibility and maintainability. Through controlled data binding, clear option configuration, and comprehensive disable strategies, they can meet diverse needs ranging from simple binary selection to complex tree/cascading selection. Combined with virtual scrolling and accessibility design, they can maintain a good experience in large-scale data and accessible scenarios. diff --git a/.wiki/en/Ant Design Components/Feedback Components/Alert.md b/.wiki/en/Ant Design Components/Feedback Components/Alert.md new file mode 100644 index 00000000..162b23f6 --- /dev/null +++ b/.wiki/en/Ant Design Components/Feedback Components/Alert.md @@ -0,0 +1,287 @@ +# Alert + + +**Files referenced in this document** +- [frontend/antd/alert/alert.tsx](file://frontend/antd/alert/alert.tsx) +- [frontend/antd/alert/Index.svelte](file://frontend/antd/alert/Index.svelte) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx) +- [frontend/antd/alert/error-boundary/Index.svelte](file://frontend/antd/alert/error-boundary/Index.svelte) +- [backend/modelscope_studio/components/antd/alert/__init__.py](file://backend/modelscope_studio/components/antd/alert/__init__.py) +- [backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py) +- [frontend/antd/alert/package.json](file://frontend/antd/alert/package.json) +- [docs/components/antd/alert/README-zh_CN.md](file://docs/components/antd/alert/README-zh_CN.md) +- [docs/components/antd/alert/README.md](file://docs/components/antd/alert/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +The Alert component is used to convey information or status feedback that requires user attention, commonly used in form validation hints, operation result feedback, system notifications, and similar scenarios. This component is a wrapper around Ant Design's Alert, providing typed variants (success, info, warning, error), closability, icon and description slots, and error boundary wrapping, ensuring stable presentation even in complex rendering scenarios. + +## Project Structure + +The Alert component is composed of a frontend Svelte wrapper layer and a backend Gradio component layer, with a standalone error boundary version provided to enhance stability. + +```mermaid +graph TB +subgraph "Frontend" +A_Index["frontend/antd/alert/Index.svelte"] +A_Alert["frontend/antd/alert/alert.tsx"] +EB_Index["frontend/antd/alert/error-boundary/Index.svelte"] +EB_Boundary["frontend/antd/alert/error-boundary/alert.error-boundary.tsx"] +Pkg["frontend/antd/alert/package.json"] +end +subgraph "Backend" +Py_Component["backend/modelscope_studio/components/antd/alert/__init__.py"] +Py_EB["backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py"] +end +A_Index --> A_Alert +EB_Index --> EB_Boundary +A_Index --> Py_Component +EB_Index --> Py_EB +Pkg --> A_Index +Pkg --> EB_Index +``` + +Diagram sources + +- [frontend/antd/alert/Index.svelte:10-47](file://frontend/antd/alert/Index.svelte#L10-L47) +- [frontend/antd/alert/alert.tsx:7-43](file://frontend/antd/alert/alert.tsx#L7-L43) +- [frontend/antd/alert/error-boundary/Index.svelte:10-47](file://frontend/antd/alert/error-boundary/Index.svelte#L10-L47) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:6-32](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L6-L32) +- [backend/modelscope_studio/components/antd/alert/**init**.py:11-71](file://backend/modelscope_studio/components/antd/alert/__init__.py#L11-L71) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:10-55](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L10-L55) +- [frontend/antd/alert/package.json:1-15](file://frontend/antd/alert/package.json#L1-L15) + +Section sources + +- [frontend/antd/alert/Index.svelte:1-66](file://frontend/antd/alert/Index.svelte#L1-L66) +- [frontend/antd/alert/alert.tsx:1-46](file://frontend/antd/alert/alert.tsx#L1-L46) +- [frontend/antd/alert/error-boundary/Index.svelte:1-70](file://frontend/antd/alert/error-boundary/Index.svelte#L1-L70) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-35](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L35) +- [backend/modelscope_studio/components/antd/alert/**init**.py:1-89](file://backend/modelscope_studio/components/antd/alert/__init__.py#L1-L89) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:1-73](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L1-L73) +- [frontend/antd/alert/package.json:1-15](file://frontend/antd/alert/package.json#L1-L15) + +## Core Components + +- Frontend main component: Responsible for wrapping Ant Design's Alert into a Svelte-consumable form, supporting slots (action, closable.closeIcon, description, icon, message), and passing through props and event callbacks. +- Error boundary component: Wraps Alert with an error boundary to ensure that exceptions in the subtree do not crash the entire interface, while retaining slot capabilities for message and description. +- Backend Gradio component: Provides typed parameters (type), slot mapping, event binding (close), and style/class injection capabilities; the error boundary version likewise provides corresponding events and slots. + +Section sources + +- [frontend/antd/alert/alert.tsx:7-43](file://frontend/antd/alert/alert.tsx#L7-L43) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:6-32](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L6-L32) +- [backend/modelscope_studio/components/antd/alert/**init**.py:11-71](file://backend/modelscope_studio/components/antd/alert/__init__.py#L11-L71) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:10-55](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L10-L55) + +## Architecture Overview + +The following sequence diagram illustrates the call chain from the backend Gradio component through the frontend Svelte wrapper layer to the Ant Design component, including the error boundary wrapping path. + +```mermaid +sequenceDiagram +participant Py as "Backend Component
AntdAlert/AntdAlertErrorBoundary" +participant Svelte as "Frontend Wrapper
Index.svelte" +participant ReactComp as "React Component
alert.tsx / alert.error-boundary.tsx" +participant AntD as "Ant Design Alert" +Py->>Svelte : Render request with props + slots +Svelte->>ReactComp : Pass props and slots +ReactComp->>AntD : Render Alert or ErrorBoundary-wrapped Alert +AntD-->>ReactComp : Visual presentation and interactions (close button, action buttons, etc.) +ReactComp-->>Svelte : Callback afterClose and other events +Svelte-->>Py : Event report (e.g., close) +``` + +Diagram sources + +- [backend/modelscope_studio/components/antd/alert/**init**.py:11-71](file://backend/modelscope_studio/components/antd/alert/__init__.py#L11-L71) +- [frontend/antd/alert/Index.svelte:10-47](file://frontend/antd/alert/Index.svelte#L10-L47) +- [frontend/antd/alert/alert.tsx:12-42](file://frontend/antd/alert/alert.tsx#L12-L42) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:17-29](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L17-L29) + +## Detailed Component Analysis + +### Types and Semantics + +- Supported types (type): success, info, warning, error. Each corresponds to a different visual emphasis and semantic meaning, helping users quickly identify the status. +- Semantic guidelines: + - success: Positive feedback for completed operations or finished workflows + - info: General hints or supplementary notes + - warning: Potential issues or operations requiring attention + - error: Failures, exceptions, or issues requiring immediate action + +Section sources + +- [backend/modelscope_studio/components/antd/alert/**init**.py:37-37](file://backend/modelscope_studio/components/antd/alert/__init__.py#L37-L37) + +### Slots and Customization Points + +- Supported slots: + - action: Custom action area (e.g., a "View Details" button) + - closable.closeIcon: Custom close icon + - description: Auxiliary description text / rich content + - icon: Custom icon + - message: Title / main message body +- Prop passthrough: All other props are passed directly to Ant Design Alert, including closable, show_icon, banner, after_close, etc. + +Section sources + +- [backend/modelscope_studio/components/antd/alert/**init**.py:22-23](file://backend/modelscope_studio/components/antd/alert/__init__.py#L22-L23) +- [frontend/antd/alert/alert.tsx:11-43](file://frontend/antd/alert/alert.tsx#L11-L43) + +### Events and Interactions + +- close event: Fired when the user clicks the close button; the backend can bind handling logic via an event listener. +- after_close callback: Fired after the animation ends; can be used to clean up resources or switch states. +- Keyboard operation: Follows Ant Design behavior by default — typically Tab to navigate to the close button, Enter/Space to trigger closing. + +Section sources + +- [backend/modelscope_studio/components/antd/alert/**init**.py:16-20](file://backend/modelscope_studio/components/antd/alert/__init__.py#L16-L20) +- [frontend/antd/alert/alert.tsx:13-13](file://frontend/antd/alert/alert.tsx#L13-L13) + +### Error Boundary + +- Purpose: Captures errors in the Alert subtree to prevent a single slot or content rendering exception from crashing the entire page. +- Use case: When the message/description slots contain dynamic rendering or external data, it is recommended to use the error boundary version. +- Events: Also supports the close event for unified handling of close behavior. + +```mermaid +flowchart TD +Start(["Enter Alert Error Boundary"]) --> RenderMsg["Render message slot"] +RenderMsg --> MsgOK{"Render successful?"} +MsgOK --> |Yes| RenderDesc["Render description slot"] +MsgOK --> |No| Fallback["Display fallback content / empty state"] +RenderDesc --> DescOK{"Render successful?"} +DescOK --> |Yes| Ready["Display normally"] +DescOK --> |No| Fallback +Fallback --> End(["End"]) +Ready --> End +``` + +Diagram sources + +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:17-29](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L17-L29) + +Section sources + +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:6-32](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L6-L32) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:10-55](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L10-L55) + +### Styles and Class Names + +- Supports injecting base styles and identifiers via elem_id, elem_classes, elem_style. +- Primary class name prefixes: + - ms-gr-antd-alert: Main Alert component + - ms-gr-antd-alert-error-boundary: Error boundary version +- Can be combined with Ant Design's own type, show_icon, closable, and other props to control appearance. + +Section sources + +- [frontend/antd/alert/Index.svelte:53-53](file://frontend/antd/alert/Index.svelte#L53-L53) +- [frontend/antd/alert/error-boundary/Index.svelte:56-56](file://frontend/antd/alert/error-boundary/Index.svelte#L56-L56) + +### Accessibility and Keyboard Support + +- Accessibility: Follows Ant Design's default accessibility design to ensure screen readers can read the message and description. +- Keyboard: Tab to navigate to the close button, Enter/Space to close; it is recommended to provide explicit accessible names in the action slot. + +Section sources + +- [frontend/antd/alert/alert.tsx:17-40](file://frontend/antd/alert/alert.tsx#L17-L40) + +### Typical Use Cases + +- Form validation hints: Use info/warning/error types, provide specific error information in the description, and offer a "View Details" action. +- Operation feedback: After a successful operation, use the success type to show a brief message with an icon. +- System notifications: Use banner mode with closable to improve visibility and controllability. +- Dynamic content: When message/description comes from external data or async rendering, prefer the error boundary version. + +Section sources + +- [docs/components/antd/alert/README-zh_CN.md:1-8](file://docs/components/antd/alert/README-zh_CN.md#L1-L8) +- [docs/components/antd/alert/README.md:1-8](file://docs/components/antd/alert/README.md#L1-L8) + +## Dependency Analysis + +- Frontend export: package.json points both the Gradio and default entries to Index.svelte, ensuring the backend loads it as expected. +- Component coupling: The frontend wrapper is tightly coupled to the Ant Design component, but maintains high extensibility through slots and prop passthrough. +- Backend integration: The backend component resolves the frontend directory via resolve_frontend_dir; events and slots are declared in the Python layer and executed at runtime by the frontend. + +```mermaid +graph LR +PyMain["Python Component
AntdAlert"] --> FEIndex["Svelte Wrapper
Index.svelte"] +PyEB["Python Component
AntdAlertErrorBoundary"] --> FEIndexEB["Svelte Wrapper
error-boundary/Index.svelte"] +FEIndex --> ReactComp["React Component
alert.tsx"] +FEIndexEB --> ReactCompEB["React Component
alert.error-boundary.tsx"] +ReactComp --> AntD["Ant Design Alert"] +ReactCompEB --> AntDEB["Ant Design ErrorBoundary(Alert)"] +``` + +Diagram sources + +- [frontend/antd/alert/package.json:4-12](file://frontend/antd/alert/package.json#L4-L12) +- [backend/modelscope_studio/components/antd/alert/**init**.py:71-71](file://backend/modelscope_studio/components/antd/alert/__init__.py#L71-L71) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:55-55](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L55-L55) + +Section sources + +- [frontend/antd/alert/package.json:1-15](file://frontend/antd/alert/package.json#L1-L15) +- [backend/modelscope_studio/components/antd/alert/**init**.py:71-71](file://backend/modelscope_studio/components/antd/alert/__init__.py#L71-L71) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:55-55](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L55-L55) + +## Performance Considerations + +- Avoid frequent re-renders: Use stable values for message/description/icon and other slots; cache computed results in the parent layer when necessary. +- Control slot complexity: Split complex subtrees into components and use them inside the error boundary to reduce overall rendering pressure. +- Use banner judiciously: Banner mode takes up more space; enable it only for critical alerts. +- Event throttling: Avoid heavy synchronous operations in after_close and close event callbacks; use microtasks or debouncing when necessary. + +## Troubleshooting Guide + +- Slots not working + - Check that slot names are correct (action, closable.closeIcon, description, icon, message). + - Confirm the frontend wrapper has passed slots through to the React component. +- Close event not fired + - Confirm the backend event listener has registered the close event. + - When closable is an object containing a closeIcon slot, check that it is correctly passed through. +- Error boundary not catching exceptions + - Confirm the error boundary version of the component is being used. + - Check that exceptions in the message/description slots are properly wrapped. +- Styles not applied + - Check that elem_id, elem_classes, elem_style are correctly passed in. + - Confirm the class name prefix ms-gr-antd-alert or ms-gr-antd-alert-error-boundary has been applied. + +Section sources + +- [frontend/antd/alert/alert.tsx:11-43](file://frontend/antd/alert/alert.tsx#L11-L43) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:12-29](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L12-L29) +- [backend/modelscope_studio/components/antd/alert/**init**.py:16-23](file://backend/modelscope_studio/components/antd/alert/__init__.py#L16-L23) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:14-21](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L14-L21) + +## Conclusion + +The Alert component in this project provides a complete set of capabilities: typed variants, slot support, closability, and error boundary protection. Through a clear separation of responsibilities between the frontend and backend, and a stable export convention, it satisfies both standard alerting needs and maintains robustness in complex rendering scenarios. When dynamic or external content is involved, it is recommended to use the error boundary version and combine the event and style system to deliver a consistent user experience. + +## Appendix + +- Example entry reference: The demo provided in the documentation is named `basic`; the demonstration effect can be viewed on the corresponding documentation page. + +Section sources + +- [docs/components/antd/alert/README-zh_CN.md:5-7](file://docs/components/antd/alert/README-zh_CN.md#L5-L7) +- [docs/components/antd/alert/README.md:5-7](file://docs/components/antd/alert/README.md#L5-L7) diff --git a/.wiki/en/Ant Design Components/Feedback Components/Drawer.md b/.wiki/en/Ant Design Components/Feedback Components/Drawer.md new file mode 100644 index 00000000..2a458f3c --- /dev/null +++ b/.wiki/en/Ant Design Components/Feedback Components/Drawer.md @@ -0,0 +1,348 @@ +# Drawer + + +**Files referenced in this document** +- [frontend/antd/drawer/drawer.tsx](file://frontend/antd/drawer/drawer.tsx) +- [frontend/antd/drawer/Index.svelte](file://frontend/antd/drawer/Index.svelte) +- [backend/modelscope_studio/components/antd/drawer/__init__.py](file://backend/modelscope_studio/components/antd/drawer/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [docs/components/antd/drawer/README.md](file://docs/components/antd/drawer/README.md) +- [docs/components/antd/drawer/README-zh_CN.md](file://docs/components/antd/drawer/README-zh_CN.md) +- [docs/components/antd/watermark/demos/modal_or_drawer.py](file://docs/components/antd/watermark/demos/modal_or_drawer.py) +- [frontend/antd/layout/layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +Drawer is a panel that slides out from the edge of the screen, commonly used for sidebar navigation, detail panels, settings panels, and similar scenarios. This component is implemented based on Ant Design Drawer and bridged through the Gradio ecosystem, supporting position configuration (left, right, top, bottom), size control, mask behavior, keyboard interaction, and rich slot extension capabilities. This document systematically describes its layout design, interaction patterns, use cases, and best practices, with directly referenceable example paths. + +## Project Structure + +The Drawer component consists of a Svelte frontend wrapper and a Python backend component, working together through Gradio's bridging mechanism. The overall structure is as follows: + +```mermaid +graph TB +subgraph "Backend" +PyInit["AntdDrawer Initialization
Parameter and Event Definitions"] +PySlots["Supported Slot List"] +PyEntry["Register to Component Entry"] +end +subgraph "Frontend" +SvelteIndex["Index.svelte
Conditional Rendering and Prop Passthrough"] +ReactWrapper["drawer.tsx
sveltify Wrapper and Slot Handling"] +AntdDrawer["Ant Design Drawer
Native Component"] +end +PyInit --> PySlots +PyInit --> PyEntry +SvelteIndex --> ReactWrapper +ReactWrapper --> AntdDrawer +``` + +Diagram sources + +- [frontend/antd/drawer/Index.svelte:10-61](file://frontend/antd/drawer/Index.svelte#L10-L61) +- [frontend/antd/drawer/drawer.tsx:14-57](file://frontend/antd/drawer/drawer.tsx#L14-L57) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:10-108](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L10-L108) +- [backend/modelscope_studio/components/antd/components.py:38](file://backend/modelscope_studio/components/antd/components.py#L38) + +Section sources + +- [frontend/antd/drawer/Index.svelte:1-65](file://frontend/antd/drawer/Index.svelte#L1-L65) +- [frontend/antd/drawer/drawer.tsx:1-60](file://frontend/antd/drawer/drawer.tsx#L1-L60) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:1-126](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L1-L126) +- [backend/modelscope_studio/components/antd/components.py:38](file://backend/modelscope_studio/components/antd/components.py#L38) + +## Core Components + +- Backend component: AntdDrawer (Python) + - Supported parameters cover key behaviors such as position, size, mask, keyboard, push, and rendering strategy + - Defines the close event binding mechanism + - Exposes multiple slots to support custom title, footer, extra actions, close icon, etc. +- Frontend wrapper: Index.svelte and drawer.tsx + - Conditional rendering: Loads and mounts the Drawer only when `visible` is true + - Prop passthrough: Merges Gradio props and additional props and passes them to the underlying component + - Slot handling: Supports closeIcon, closable.closeIcon, extra, footer, title, drawerRender slots +- Base layout component: Base (layout.base.tsx) + - Provides the base wrapper for Ant Design Layout, making it easy to build page layouts in conjunction with Drawer + +Section sources + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:10-108](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L10-L108) +- [frontend/antd/drawer/Index.svelte:13-42](file://frontend/antd/drawer/Index.svelte#L13-L42) +- [frontend/antd/drawer/drawer.tsx:14-57](file://frontend/antd/drawer/drawer.tsx#L14-L57) +- [frontend/antd/layout/layout.base.tsx:6-37](file://frontend/antd/layout/layout.base.tsx#L6-L37) + +## Architecture Overview + +The Drawer call chain starts from the backend AntdDrawer, goes through the conditional rendering in the frontend Index.svelte, then uses sveltify in drawer.tsx to bridge the React component to the Svelte environment, and finally renders as an Ant Design Drawer. This flow ensures two-way binding of props and events while preserving all capabilities of Ant Design Drawer. + +```mermaid +sequenceDiagram +participant User as "User" +participant Backend as "AntdDrawer (Backend)" +participant FrontIndex as "Index.svelte (Frontend)" +participant Wrapper as "drawer.tsx (Bridge)" +participant AD as "Antd Drawer (React)" +User->>Backend : Set open/visible and other parameters +Backend->>FrontIndex : Render request +FrontIndex->>FrontIndex : Check visible +FrontIndex->>Wrapper : Pass props and slots +Wrapper->>AD : sveltify wrapper and render +AD-->>User : Display drawer and fire event callbacks +``` + +Diagram sources + +- [frontend/antd/drawer/Index.svelte:48-61](file://frontend/antd/drawer/Index.svelte#L48-L61) +- [frontend/antd/drawer/drawer.tsx:24-56](file://frontend/antd/drawer/drawer.tsx#L24-L56) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:14-18](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L14-L18) + +## Detailed Component Analysis + +### Parameters and Slots Overview + +- Key parameters (excerpt) + - Position and size: placement (left/right/top/bottom), width, height, size (default/large) + - Behavior control: open, keyboard, mask, maskClosable, closable, destroyOnClose, destroyOnHidden, forceRender + - Layout and rendering: getContainer, push, resizable, drawerRender, as_item, visible, elem_id/elem_classes/elem_style +- Slots + - closeIcon, closable.closeIcon, extra, footer, title, drawerRender + +Section sources + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:26-107](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L26-L107) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:20-24](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L20-L24) +- [frontend/antd/drawer/drawer.tsx:14-57](file://frontend/antd/drawer/drawer.tsx#L14-L57) + +### Open/Close Mechanism and Events + +- Visibility control: Index.svelte controls whether the Drawer is rendered via `visible` +- Event binding: The backend defines the close event listener for updating state on close +- Callback functions: Callbacks such as afterOpenChange are converted into safely passable functions via useFunction + +```mermaid +flowchart TD +Start(["Start"]) --> CheckVisible["Check visible"] +CheckVisible --> |false| Skip["Do not render"] +CheckVisible --> |true| Render["Render Drawer component"] +Render --> BindEvents["Bind close and other events"] +BindEvents --> Open["Display drawer"] +Open --> UserAction{"User action?"} +UserAction --> |Click mask / Press ESC| Close["Trigger close"] +Close --> UpdateState["Update open/visible state"] +UpdateState --> Destroy{"Destroy strategy?"} +Destroy --> |Yes| Unmount["Unmount component"] +Destroy --> |No| Hide["Hide but keep DOM"] +Unmount --> End(["End"]) +Hide --> End +Skip --> End +``` + +Diagram sources + +- [frontend/antd/drawer/Index.svelte:48-61](file://frontend/antd/drawer/Index.svelte#L48-L61) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:14-18](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L14-L18) +- [frontend/antd/drawer/drawer.tsx:24-26](file://frontend/antd/drawer/drawer.tsx#L24-L26) + +### Position Configuration and Size Control + +- Position: placement supports left, right, top, bottom +- Size: width/height or size (default/large) controls the drawer dimensions +- Push and container: push can be used with a layout to push content; getContainer specifies the mount container + +Section sources + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:47-50](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L47-L50) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:42-56](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L42-L56) +- [frontend/antd/drawer/drawer.tsx:52-54](file://frontend/antd/drawer/drawer.tsx#L52-L54) + +### Mask Behavior and Keyboard Interaction + +- Mask: `mask` controls whether the mask is displayed; `maskClosable` controls whether clicking the mask closes the drawer +- Keyboard: `keyboard` controls whether ESC closes the drawer +- Auto focus: `autoFocus` can automatically focus the drawer on open + +Section sources + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:44-46](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L44-L46) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:31-32](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L31-L32) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:91](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L91) + +### Animation and Rendering Strategy + +- Animation: Driven by Ant Design Drawer's built-in animation; no additional configuration needed +- Rendering strategy: destroyOnClose, destroyOnHidden, forceRender control the destruction timing and forced rendering + +Section sources + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:36-39](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L36-L39) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:87-89](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L87-L89) + +### Slot and Style Customization + +- Slot mapping: closeIcon, closable.closeIcon, extra, footer, title, drawerRender +- Styles: elem_id, elem_classes, elem_style, styles, class_names, root_style, root_class_name +- Custom rendering: drawerRender can receive parameters and return custom rendered content + +Section sources + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:20-24](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L20-L24) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:33-35](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L33-L35) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:57-60](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L57-L60) +- [frontend/antd/drawer/drawer.tsx:41-51](file://frontend/antd/drawer/drawer.tsx#L41-L51) + +### Coordination with Page Layout and Responsive Adaptation + +- Layout collaboration: Can be combined with Ant Design Layout (Header/Footer/Content/Sider) +- Responsive: Combined with Flex/Grid and other layout components, adjust drawer width or switch placement based on screen size + +Section sources + +- [frontend/antd/layout/layout.base.tsx:6-37](file://frontend/antd/layout/layout.base.tsx#L6-L37) + +### Accessibility and Mobile Optimization + +- Accessibility: The keyboard and focus strategies should be combined with auto-focus and semantic labeling +- Mobile: On small-screen devices, prefer using `bottom` or a smaller `width` to avoid covering main content + +Section sources + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:91](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L91) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:31-32](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L31-L32) + +### Common Use Cases and Example Paths + +- Sidebar navigation: Place menu items in the left drawer; update routes or data when a menu item is clicked +- Detail panel: Display detailed content in the right drawer, supporting scrolling and a bottom action area +- Settings panel: Provide settings in the top or bottom drawer, supporting quick toggling and saving +- Example references: + - Drawer basic usage and extra actions: [docs/components/antd/drawer/README.md](file://docs/components/antd/drawer/README.md) + - Drawer vs. Modal comparison demo: [docs/components/antd/watermark/demos/modal_or_drawer.py](file://docs/components/antd/watermark/demos/modal_or_drawer.py) + +Section sources + +- [docs/components/antd/drawer/README.md:1-9](file://docs/components/antd/drawer/README.md#L1-L9) +- [docs/components/antd/watermark/demos/modal_or_drawer.py:19-26](file://docs/components/antd/watermark/demos/modal_or_drawer.py#L19-L26) + +## Dependency Analysis + +- Component inheritance and context + - AntdDrawer inherits from ModelScopeLayoutComponent, with the general characteristics of a layout component + - AppContext is used to ensure the application context is available +- Component registration + - AntdDrawer is exported from the component entry for unified import and usage + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++bool visible ++str elem_id ++any elem_classes ++dict elem_style ++bool skip_api +} +class AntdDrawer { ++dict additional_props ++str after_open_change ++bool auto_focus ++dict body_style ++str close_icon ++any class_names ++any closable ++bool destroy_on_close ++bool destroy_on_hidden ++bool draggable ++str extra ++str footer ++bool force_render ++any get_container ++num height ++bool keyboard ++bool mask ++bool mask_closable ++str placement ++any push ++bool resizable ++str size ++any styles ++str title ++bool loading ++bool open ++num width ++int z_index ++str drawer_render ++dict root_style ++str root_class_name ++str as_item ++dict _internal ++bool visible ++str elem_id ++any elem_classes ++dict elem_style ++bool render +} +ModelScopeLayoutComponent <|-- AntdDrawer +``` + +Diagram sources + +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:10-108](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L10-L108) + +Section sources + +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [backend/modelscope_studio/components/antd/components.py:38](file://backend/modelscope_studio/components/antd/components.py#L38) + +## Performance Considerations + +- Conditional rendering: Render the Drawer only when `visible` is true to reduce unnecessary DOM overhead +- Rendering strategy: Use destroyOnClose/destroyOnHidden appropriately to balance memory usage and interaction smoothness +- Slots and custom rendering: Avoid heavy computations in drawerRender; use caching or async processing when necessary + +## Troubleshooting Guide + +- Drawer not showing + - Check if visible/open is true + - Confirm the conditional rendering logic in Index.svelte +- Slots not working + - Confirm slot names are correct (closeIcon, closable.closeIcon, extra, footer, title, drawerRender) + - Confirm the slot mapping logic in drawer.tsx +- Close event not fired + - Check the backend event binding and callback function passing +- Mask not working or clicking does not close + - Check mask and maskClosable configuration +- Keyboard close not working + - Check keyboard configuration and auto-focus strategy + +Section sources + +- [frontend/antd/drawer/Index.svelte:48-61](file://frontend/antd/drawer/Index.svelte#L48-L61) +- [frontend/antd/drawer/drawer.tsx:41-51](file://frontend/antd/drawer/drawer.tsx#L41-L51) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:14-18](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L14-L18) + +## Conclusion + +The Drawer component, through its integrated frontend-backend design, preserves the native capabilities of Ant Design Drawer while providing more flexible parameter and slot extensions. With conditional rendering and event binding mechanisms, it can efficiently adapt to various interaction scenarios, including sidebar navigation, detail panels, and settings panels. At the layout level, it can work in conjunction with Ant Design Layout; for accessibility and mobile experience, it is recommended to combine keyboard and size strategies to enhance the user experience. + +## Appendix + +- Example references + - Drawer basic usage and extra actions: [docs/components/antd/drawer/README.md](file://docs/components/antd/drawer/README.md) + - Drawer vs. Modal comparison demo: [docs/components/antd/watermark/demos/modal_or_drawer.py](file://docs/components/antd/watermark/demos/modal_or_drawer.py) +- Related documentation + - Ant Design Drawer official documentation: [Ant Design Drawer](https://ant.design/components/drawer/) diff --git a/.wiki/en/Ant Design Components/Feedback Components/Feedback Components.md b/.wiki/en/Ant Design Components/Feedback Components/Feedback Components.md new file mode 100644 index 00000000..6fa5d009 --- /dev/null +++ b/.wiki/en/Ant Design Components/Feedback Components/Feedback Components.md @@ -0,0 +1,437 @@ +# Feedback Components + + +**Files referenced in this document** +- [alert.tsx](file://frontend/antd/alert/alert.tsx) +- [drawer.tsx](file://frontend/antd/drawer/drawer.tsx) +- [message.tsx](file://frontend/antd/message/message.tsx) +- [modal.tsx](file://frontend/antd/modal/modal.tsx) +- [notification.tsx](file://frontend/antd/notification/notification.tsx) +- [popconfirm.tsx](file://frontend/antd/popconfirm/popconfirm.tsx) +- [progress.tsx](file://frontend/antd/progress/progress.tsx) +- [result.tsx](file://frontend/antd/result/result.tsx) +- [skeleton.tsx](file://frontend/antd/skeleton/skeleton.tsx) +- [spin.tsx](file://frontend/antd/spin/spin.tsx) +- [watermark.tsx](file://frontend/antd/watermark/watermark.tsx) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [useTargets.ts](file://frontend/utils/hooks/useTargets.ts) +- [renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document systematically covers the frontend wrappers and usage of Ant Design feedback components, including: Alert, Drawer, Message, Modal, Notification, Popconfirm, Progress, Result, Skeleton, Spin, and Watermark. It focuses on each component's trigger mechanism, display timing, interaction logic, animation and transition state management, error and exception handling strategies, accessibility and keyboard operation support, as well as feedback design patterns for complex interaction scenarios. + +## Project Structure + +All feedback components reside in the frontend directory and follow a unified wrapping pattern: bridging native Ant Design components to Svelte-style components via `sveltify`; implementing slot-based rendering via ReactSlot and renderParamsSlot; and ensuring correct propagation and ordering of callbacks and slot targets through utility hooks such as useFunction and useTargets. + +```mermaid +graph TB +subgraph "Ant Design Feedback Components" +A1["Alert
frontend/antd/alert/alert.tsx"] +A2["Drawer
frontend/antd/drawer/drawer.tsx"] +A3["Message
frontend/antd/message/message.tsx"] +A4["Modal
frontend/antd/modal/modal.tsx"] +A5["Notification
frontend/antd/notification/notification.tsx"] +A6["Popconfirm
frontend/antd/popconfirm/popconfirm.tsx"] +A7["Progress
frontend/antd/progress/progress.tsx"] +A8["Result
frontend/antd/result/result.tsx"] +A9["Skeleton
frontend/antd/skeleton/skeleton.tsx"] +A10["Spin
frontend/antd/spin/spin.tsx"] +A11["Watermark
frontend/antd/watermark/watermark.tsx"] +end +subgraph "Utilities and Hooks" +U1["useFunction
frontend/utils/hooks/useFunction.ts"] +U2["useTargets
frontend/utils/hooks/useTargets.ts"] +U3["renderParamsSlot
frontend/utils/renderParamsSlot.tsx"] +end +A1 --> U1 +A2 --> U1 +A3 --> U1 +A4 --> U1 +A5 --> U1 +A6 --> U1 +A7 --> U1 +A8 --> U2 +A9 --> U1 +A10 --> U2 +A11 --> U1 +A2 --> U3 +A4 --> U3 +``` + +Diagram sources + +- [alert.tsx:1-46](file://frontend/antd/alert/alert.tsx#L1-L46) +- [drawer.tsx:1-60](file://frontend/antd/drawer/drawer.tsx#L1-L60) +- [message.tsx:1-79](file://frontend/antd/message/message.tsx#L1-L79) +- [modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) +- [notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [popconfirm.tsx:1-65](file://frontend/antd/popconfirm/popconfirm.tsx#L1-L65) +- [progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) +- [skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +Section sources + +- [alert.tsx:1-46](file://frontend/antd/alert/alert.tsx#L1-L46) +- [drawer.tsx:1-60](file://frontend/antd/drawer/drawer.tsx#L1-L60) +- [message.tsx:1-79](file://frontend/antd/message/message.tsx#L1-L79) +- [modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) +- [notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [popconfirm.tsx:1-65](file://frontend/antd/popconfirm/popconfirm.tsx#L1-L65) +- [progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) +- [skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +## Core Components + +- Unified wrapping: All feedback components wrap native Ant Design components via `sveltify`, preserving their APIs while extending slot capabilities. +- Slot system: ReactSlot renders named slots (e.g., title, description, icon, footer), with some components supporting parameterized slot rendering (renderParamsSlot). +- Callback adaptation: useFunction wraps incoming functions as stable references, avoiding side effects or duplicate subscriptions caused by re-rendering. +- Target selection: useTargets extracts deliverable target nodes from children, supporting complex layouts and conditional rendering. +- Context holder: Message/Notification obtain context holders via useMessage/useNotification, enabling mounting and destruction of global messages and notifications. + +Section sources + +- [alert.tsx:7-43](file://frontend/antd/alert/alert.tsx#L7-L43) +- [drawer.tsx:14-57](file://frontend/antd/drawer/drawer.tsx#L14-L57) +- [message.tsx:9-76](file://frontend/antd/message/message.tsx#L9-L76) +- [modal.tsx:8-104](file://frontend/antd/modal/modal.tsx#L8-L104) +- [notification.tsx:8-103](file://frontend/antd/notification/notification.tsx#L8-L103) +- [popconfirm.tsx:7-62](file://frontend/antd/popconfirm/popconfirm.tsx#L7-L62) +- [progress.tsx:5-21](file://frontend/antd/progress/progress.tsx#L5-L21) +- [result.tsx:7-30](file://frontend/antd/result/result.tsx#L7-L30) +- [skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [spin.tsx:7-35](file://frontend/antd/spin/spin.tsx#L7-L35) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [renderParamsSlot.tsx:5-50](file://frontend/utils/renderParamsSlot.tsx#L5-L50) + +## Architecture Overview + +The runtime architecture of feedback components revolves around "prop passthrough + slot rendering + callback adaptation". For components that need global mounting (Message/Notification), context holders are obtained via useMessage/useNotification and injected into the DOM upon component mount. For container-type components (Drawer/Modal), the mount target is determined via getContainer or a string selector. For content-type components (Alert/Result/Spin), slots control the title, description, icon, extra content, and more. + +```mermaid +graph TB +C["Application-layer Component"] --> F1["useFunction
Stable Function Reference"] +C --> F2["useTargets
Resolve Slot Targets"] +C --> F3["renderParamsSlot
Parameterized Slot Rendering"] +subgraph "Global Feedback" +M["Message
useMessage"] --> D1["DOM Mount Point"] +N["Notification
useNotification"] --> D2["DOM Mount Point"] +end +subgraph "Container Feedback" +DR["Drawer"] --> G1["getContainer / String"] +MD["Modal"] --> G2["getContainer / String"] +end +subgraph "Content Feedback" +AL["Alert"] +RS["Result"] +SP["Spin"] +end +``` + +Diagram sources + +- [message.tsx:30-33](file://frontend/antd/message/message.tsx#L30-L33) +- [notification.tsx:31-36](file://frontend/antd/notification/notification.tsx#L31-L36) +- [drawer.tsx:52-54](file://frontend/antd/drawer/drawer.tsx#L52-L54) +- [modal.tsx:96-98](file://frontend/antd/modal/modal.tsx#L96-L98) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [renderParamsSlot.tsx:5-50](file://frontend/utils/renderParamsSlot.tsx#L5-L50) + +## Component Details + +### Alert + +- Trigger mechanism: Triggered by business state changes or user actions; can be closed via `closable`, which fires the `afterClose` callback. +- Display timing: Shown or hidden based on the data source after page initialization; supports dynamic switching of message/description/icon/action slots. +- Interaction logic: Clicking the close button triggers an animated collapse; the `afterClose` callback can be used for resource cleanup or navigation. +- Animation & transitions: Built-in Ant Design animations; slots allow custom icons and action buttons. +- Error handling: Falls back to prop-provided content when slot content is empty; releases resources after closing. +- Accessibility & keyboard: Follows Ant Design default accessibility; it is recommended to provide explicit ARIA labels for the close button. + +Section sources + +- [alert.tsx:7-43](file://frontend/antd/alert/alert.tsx#L7-L43) + +### Drawer + +- Trigger mechanism: Triggered by a button click or route change via `visible`; supports `afterOpenChange` to manage state after opening/closing. +- Display timing: Animates in on first open; animates out on close. +- Interaction logic: Supports custom `closeIcon`, `extra`, `footer`, `title`; `closable.closeIcon` can replace the default close icon. +- Animation & transitions: Controlled by Ant Design's slide-in/slide-out animation; `drawerRender` supports custom rendering logic. +- Error handling: When `getContainer` is a string, it is wrapped via `useFunction`; falls back to the default container on exception. +- Accessibility & keyboard: Maintains native focus order; it is recommended to provide explicit action buttons in the footer. + +Section sources + +- [drawer.tsx:8-57](file://frontend/antd/drawer/drawer.tsx#L8-L57) + +### Message + +- Trigger mechanism: Controlled by the `visible` prop; internally uses `messageApi.open` to open the message. +- Display timing: An effect watches for `visible=true` to open the message; `onClose` is triggered when the `duration` expires or the message is manually closed. +- Interaction logic: `onVisible(false)` and `onClose` are synchronized callbacks; supports deduplication via `key` and `destroy`. +- Animation & transitions: Built-in Ant Design animations; content/icon slots can customize content and icons. +- Error handling: The effect cleanup phase calls `destroy`; ensures the message is only opened once on exception. +- Accessibility & keyboard: Automatically mounted to the context holder; it is recommended to provide readable text and concise descriptions. + +Section sources + +- [message.tsx:19-76](file://frontend/antd/message/message.tsx#L19-L76) + +### Modal + +- Trigger mechanism: `visible` controls display; `afterOpenChange`/`afterClose` manage lifecycle after opening/closing. +- Display timing: Animates in on first open; animates out on close. +- Interaction logic: ok/cancel text and icons can all be customized via slots; `footer` supports a function or a default value. +- Animation & transitions: Built-in Ant Design animations; `modalRender` supports custom rendering. +- Error handling: When `getContainer` is a string, it is wrapped as a function; when `footer` equals `DEFAULT_FOOTER`, it falls back to `undefined`. +- Accessibility & keyboard: Maintains default focus and ESC closing; it is recommended to provide clear confirm/cancel semantics. + +Section sources + +- [modal.tsx:22-104](file://frontend/antd/modal/modal.tsx#L22-L104) + +### Notification + +- Trigger mechanism: `visible` controls display; `open`/`destroy` returned by `useNotification` control the message lifecycle. +- Display timing: An effect watches for `visible=true` to open; `onClose` is triggered when `duration` expires or the notification is manually closed. +- Interaction logic: `onVisible(false)`/`onClose` are synchronized callbacks; supports `placement`, `stack`, `top`/`bottom` positioning. +- Animation & transitions: Built-in Ant Design animations; supports description/icon/actions/btn slots. +- Error handling: The effect cleanup phase calls `destroy`; ensures the notification is only opened once on exception. +- Accessibility & keyboard: It is recommended to provide readable titles and descriptions; supports hover-to-pause and progress bar. + +Section sources + +- [notification.tsx:18-103](file://frontend/antd/notification/notification.tsx#L18-L103) + +### Popconfirm + +- Trigger mechanism: A user click triggers the bubble popup; `afterOpenChange` manages the popup open state. +- Display timing: Pops up immediately after clicking the target element; closes after confirm/cancel. +- Interaction logic: ok/cancel text and icons can all be customized via slots; title/description supports clone rendering. +- Animation & transitions: Bubble animation controlled by Ant Design; `getPopupContainer` supports specifying a mount container. +- Error handling: Falls back to props when slot content is empty; keeps interaction available on exception. +- Accessibility & keyboard: Maintains default focus and ESC closing; it is recommended to provide clear confirm/cancel semantics. + +Section sources + +- [popconfirm.tsx:7-62](file://frontend/antd/popconfirm/popconfirm.tsx#L7-L62) + +### Progress + +- Trigger mechanism: Value changes drive progress updates; `format` and `rounding` support custom formatting. +- Display timing: Value changes are reflected immediately; supports both static and dynamic modes. +- Interaction logic: `format` and `rounding` are wrapped as stable references via `useFunction`. +- Animation & transitions: Built-in Ant Design animations; supports percentage, status, and custom text. +- Error handling: Out-of-bounds values are handled by Ant Design; keeps the component stable on exception. +- Accessibility & keyboard: No interactive input; it is recommended to provide readable text. + +Section sources + +- [progress.tsx:5-21](file://frontend/antd/progress/progress.tsx#L5-L21) + +### Result + +- Trigger mechanism: Displayed after a business operation completes; supports title/subTitle/icon/extra slots. +- Display timing: Rendered immediately once data is ready; children serve as additional content. +- Interaction logic: useTargets resolves slot targets; falls back to children when no slots are provided. +- Animation & transitions: Built-in Ant Design animations; supports multiple status icons and text. +- Error handling: Falls back to props when slot content is empty; keeps content visible on exception. +- Accessibility & keyboard: It is recommended to provide readable titles and descriptions. + +Section sources + +- [result.tsx:7-30](file://frontend/antd/result/result.tsx#L7-L30) + +### Skeleton + +- Trigger mechanism: Displays a skeleton before data loads; switches to real content once loading is complete. +- Display timing: Shown immediately on component mount; switches automatically when real content is ready. +- Interaction logic: No interaction; supports animation and shape configuration. +- Animation & transitions: Built-in Ant Design skeleton animation. +- Error handling: Keeps the skeleton stable on exception; it is recommended to provide a timeout fallback. +- Accessibility & keyboard: No interaction; it is recommended to provide ARIA hints for the loading state. + +Section sources + +- [skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) + +### Spin + +- Trigger mechanism: Shown when an async task starts; hidden when the task ends. +- Display timing: Shown immediately on component mount; wraps real content when children are empty. +- Interaction logic: useTargets resolves slot targets; tip/indicator supports slots. +- Animation & transitions: Built-in Ant Design spinning animation; supports custom indicator and tip text. +- Error handling: Falls back to props when slot content is empty; keeps the loading state on exception. +- Accessibility & keyboard: It is recommended to provide an ARIA label and loading state hint. + +Section sources + +- [spin.tsx:7-35](file://frontend/antd/spin/spin.tsx#L7-L35) + +### Watermark + +- Trigger mechanism: Watermark is generated after page load; supports dynamic updates to text and size. +- Display timing: Takes effect immediately on component mount; suitable for full-screen or localized watermarks. +- Interaction logic: No interaction; supports multi-line text and opacity configuration. +- Animation & transitions: No animation; suitable as a background decoration. +- Error handling: Keeps the watermark stable on exception; it is recommended to provide a fallback solution. +- Accessibility & keyboard: No interaction; does not affect accessibility. + +Section sources + +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) + +## Dependency Analysis + +- Inter-component coupling: Feedback components are independent of one another, sharing only utility hooks. Container-type components share getContainer and renderParamsSlot; global-type components share the context holder. +- External dependencies: Native Ant Design components and styles; React Slot rendering; Svelte Preprocess React bridge. +- Circular dependencies: No circular dependencies found; utility hooks are pure functional wrappers. +- Interface contracts: All components maintain compatibility with the Ant Design API via `sveltify`; slot key names and rendering strategies are consistent. + +```mermaid +graph LR +subgraph "Utility Layer" +UF["useFunction"] +UT["useTargets"] +RPS["renderParamsSlot"] +end +subgraph "Feedback Components" +MSG["Message"] +NOTI["Notification"] +MOD["Modal"] +DRW["Drawer"] +ALERT["Alert"] +POP["Popconfirm"] +PROG["Progress"] +RES["Result"] +SKEL["Skeleton"] +SPIN["Spin"] +WM["Watermark"] +end +UF --> MSG +UF --> NOTI +UF --> MOD +UF --> DRW +UF --> ALERT +UF --> POP +UF --> PROG +UT --> RES +UT --> SPIN +RPS --> MOD +RPS --> DRW +``` + +Diagram sources + +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [renderParamsSlot.tsx:5-50](file://frontend/utils/renderParamsSlot.tsx#L5-L50) +- [message.tsx:29-33](file://frontend/antd/message/message.tsx#L29-L33) +- [notification.tsx:31-36](file://frontend/antd/notification/notification.tsx#L31-L36) +- [modal.tsx:34-35](file://frontend/antd/modal/modal.tsx#L34-L35) +- [drawer.tsx:27-28](file://frontend/antd/drawer/drawer.tsx#L27-L28) +- [alert.tsx:13-20](file://frontend/antd/alert/alert.tsx#L13-L20) +- [popconfirm.tsx:18-20](file://frontend/antd/popconfirm/popconfirm.tsx#L18-L20) +- [progress.tsx:10-12](file://frontend/antd/progress/progress.tsx#L10-L12) +- [result.tsx:11-12](file://frontend/antd/result/result.tsx#L11-L12) +- [spin.tsx:13-14](file://frontend/antd/spin/spin.tsx#L13-L14) + +Section sources + +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [renderParamsSlot.tsx:5-50](file://frontend/utils/renderParamsSlot.tsx#L5-L50) +- [message.tsx:29-33](file://frontend/antd/message/message.tsx#L29-L33) +- [notification.tsx:31-36](file://frontend/antd/notification/notification.tsx#L31-L36) +- [modal.tsx:34-35](file://frontend/antd/modal/modal.tsx#L34-L35) +- [drawer.tsx:27-28](file://frontend/antd/drawer/drawer.tsx#L27-L28) +- [alert.tsx:13-20](file://frontend/antd/alert/alert.tsx#L13-L20) +- [popconfirm.tsx:18-20](file://frontend/antd/popconfirm/popconfirm.tsx#L18-L20) +- [progress.tsx:10-12](file://frontend/antd/progress/progress.tsx#L10-L12) +- [result.tsx:11-12](file://frontend/antd/result/result.tsx#L11-L12) +- [spin.tsx:13-14](file://frontend/antd/spin/spin.tsx#L13-L14) + +## Performance Considerations + +- Stable function references: useFunction wraps callbacks as useMemo references, reducing unnecessary re-renders and side effects. +- Slot rendering optimization: ReactSlot and renderParamsSlot clone and render only when necessary, avoiding full re-layouts. +- Lifecycle management: Message/Notification proactively call `destroy` in the effect cleanup phase to prevent memory leaks. +- Container mounting: When `getContainer` for Drawer/Modal is a string, a wrapper function is used to avoid repeated bindings. +- Conditional rendering: Spin/Result use useTargets and conditional branches to render real content only when slots are present, reducing DOM overhead. + +## Troubleshooting Guide + +- Slots not working + - Check that slot key names match the component declarations; confirm that ReactSlot is correctly wrapping them. + - Reference paths: [alert.tsx:17-40](file://frontend/antd/alert/alert.tsx#L17-L40), [result.tsx:17-27](file://frontend/antd/result/result.tsx#L17-L27), [spin.tsx:20-32](file://frontend/antd/spin/spin.tsx#L20-L32) +- Callbacks not fired or firing repeatedly + - Use useFunction to wrap callbacks to ensure stable references; check the effect dependency array. + - Reference paths: [message.tsx:35-68](file://frontend/antd/message/message.tsx#L35-L68), [notification.tsx:38-95](file://frontend/antd/notification/notification.tsx#L38-L95) +- Global message not displayed + - Confirm the context holder has been rendered; verify that `visible` and `key` are configured correctly; set a reasonable `duration`. + - Reference paths: [message.tsx:30-33](file://frontend/antd/message/message.tsx#L30-L33), [notification.tsx:31-36](file://frontend/antd/notification/notification.tsx#L31-L36) +- Container mount exception + - When `getContainer` is a string, ensure it is wrapped as a function; check selector validity. + - Reference paths: [drawer.tsx:52-54](file://frontend/antd/drawer/drawer.tsx#L52-L54), [modal.tsx:96-98](file://frontend/antd/modal/modal.tsx#L96-L98) +- Animation stuttering or flickering + - Check if slot content is changing frequently; avoid heavy DOM operations during animations. + - Reference paths: [progress.tsx:10-12](file://frontend/antd/progress/progress.tsx#L10-L12), [spin.tsx:13-14](file://frontend/antd/spin/spin.tsx#L13-L14) + +Section sources + +- [alert.tsx:17-40](file://frontend/antd/alert/alert.tsx#L17-L40) +- [result.tsx:17-27](file://frontend/antd/result/result.tsx#L17-L27) +- [spin.tsx:20-32](file://frontend/antd/spin/spin.tsx#L20-L32) +- [message.tsx:30-33](file://frontend/antd/message/message.tsx#L30-L33) +- [notification.tsx:31-36](file://frontend/antd/notification/notification.tsx#L31-L36) +- [drawer.tsx:52-54](file://frontend/antd/drawer/drawer.tsx#L52-L54) +- [modal.tsx:96-98](file://frontend/antd/modal/modal.tsx#L96-L98) +- [progress.tsx:10-12](file://frontend/antd/progress/progress.tsx#L10-L12) + +## Conclusion + +This repository provides a systematic wrapper for Ant Design feedback components, unifying slot rendering, callback adaptation, and lifecycle management. Through stable function references, conditional rendering, and context holders, it achieves a highly available and maintainable feedback system. It is recommended to select the appropriate component and trigger strategy based on your business scenario in practice, and to pay attention to accessibility and performance details. + +## Appendix + +- Best practices + - Use `visible` and `key` to manage the uniqueness and lifecycle of global messages. + - Provide clear confirm/cancel semantics and keyboard support for important operations. + - In complex layouts, prefer renderParamsSlot and useTargets to manage slot targets. + - Provide clear text and visual cues for loading states and error states. +- Complex interaction scenarios + - Multi-step flows: Use Result to display the final state; Progress to show progress; Spin to wrap critical areas. + - Global notifications: Place Notification in the top-right or bottom-right corner, supporting stacking and pause-on-hover. + - Modal confirmation: Use Modal/Popconfirm for critical deletions and dangerous operations to provide a second confirmation. + - Drawer navigation: Use Drawer as a secondary panel for long lists or settings pages; pay attention to getContainer and z-index management. diff --git a/.wiki/en/Ant Design Components/Feedback Components/Interactive Feedback.md b/.wiki/en/Ant Design Components/Feedback Components/Interactive Feedback.md new file mode 100644 index 00000000..a711d684 --- /dev/null +++ b/.wiki/en/Ant Design Components/Feedback Components/Interactive Feedback.md @@ -0,0 +1,301 @@ +# Interactive Feedback + + +**Files referenced in this document** +- [frontend/antd/popconfirm/popconfirm.tsx](file://frontend/antd/popconfirm/popconfirm.tsx) +- [frontend/antd/popover/popover.tsx](file://frontend/antd/popover/popover.tsx) +- [frontend/antd/popconfirm/Index.svelte](file://frontend/antd/popconfirm/Index.svelte) +- [frontend/antd/popover/Index.svelte](file://frontend/antd/popover/Index.svelte) +- [backend/modelscope_studio/components/antd/popconfirm/__init__.py](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py) +- [backend/modelscope_studio/components/antd/popover/__init__.py](file://backend/modelscope_studio/components/antd/popover/__init__.py) +- [docs/components/antd/popconfirm/README-zh_CN.md](file://docs/components/antd/popconfirm/README-zh_CN.md) +- [docs/components/antd/popover/README-zh_CN.md](file://docs/components/antd/popover/README-zh_CN.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document focuses on two types of components in the interactive feedback component group: Popconfirm (Bubble Confirmation) and Popover (Bubble Card). It provides a systematic explanation from design philosophy, interaction patterns, confirmation flow, content delivery, trigger and positioning strategies, props and events, style customization, and common use cases, along with source-traceable reference paths to help developers quickly understand and correctly use these components. + +## Project Structure + +These two components use a "Svelte wrapper layer + React component library bridge" pattern on the frontend, with the backend exposing a Python API through Gradio component wrapping. Their organization is as follows: + +- Frontend layer: Svelte components handle prop passthrough, slot rendering, and event mapping; the TypeScript bridge layer adapts Ant Design's React components for use in Svelte. +- Backend layer: Python component classes define props, events, slots, and default values, and declare frontend directory mappings so the runtime can load the corresponding frontend components. + +```mermaid +graph TB +subgraph "Frontend" +IDX_PCF["Index.svelte
popconfirm"] --> BRG_PCF["popconfirm.tsx
Bridge Layer"] +IDX_POV["Index.svelte
popover"] --> BRG_POV["popover.tsx
Bridge Layer"] +end +subgraph "Backend" +PY_PCF["AntdPopconfirm
Python Component"] --> FE_DIR_PCF["resolve_frontend_dir('popconfirm')"] +PY_POV["AntdPopover
Python Component"] --> FE_DIR_POV["resolve_frontend_dir('popover')"] +end +BRG_PCF --> ANT_PCF["Ant Design Popconfirm"] +BRG_POV --> ANT_POV["Ant Design Popover"] +PY_PCF --> IDX_PCF +PY_POV --> IDX_POV +``` + +Diagram sources + +- [frontend/antd/popconfirm/Index.svelte:1-76](file://frontend/antd/popconfirm/Index.svelte#L1-L76) +- [frontend/antd/popover/Index.svelte:1-76](file://frontend/antd/popover/Index.svelte#L1-L76) +- [frontend/antd/popconfirm/popconfirm.tsx:1-65](file://frontend/antd/popconfirm/popconfirm.tsx#L1-L65) +- [frontend/antd/popover/popover.tsx:1-37](file://frontend/antd/popover/popover.tsx#L1-L37) +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:138-138](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L138-L138) +- [backend/modelscope_studio/components/antd/popover/**init**.py:106-106](file://backend/modelscope_studio/components/antd/popover/__init__.py#L106-L106) + +Section sources + +- [frontend/antd/popconfirm/Index.svelte:1-76](file://frontend/antd/popconfirm/Index.svelte#L1-L76) +- [frontend/antd/popover/Index.svelte:1-76](file://frontend/antd/popover/Index.svelte#L1-L76) +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:138-138](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L138-L138) +- [backend/modelscope_studio/components/antd/popover/**init**.py:106-106](file://backend/modelscope_studio/components/antd/popover/__init__.py#L106-L106) + +## Core Components + +- Popconfirm + - Design philosophy: Provides a second confirmation for dangerous or irreversible operations to reduce accidental operation risk. + - Key interactions: Supports hover/focus/click/contextMenu triggers; provides confirm/cancel dual buttons with text/icon slots. + - Confirmation flow: Clicking confirm fires the callback; cancel closes the popup; supports controlled `open` state and controlled event callbacks. +- Popover + - Design philosophy: Provides contextual information hints or lightweight action entry points for target elements without changing the page layout. + - Key interactions: Supports hover/focus/click/contextMenu triggers; title and content can be slotted, with automatic collision avoidance and positioning. + +Section sources + +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:10-27](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L10-L27) +- [backend/modelscope_studio/components/antd/popover/**init**.py:10-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L18) + +## Architecture Overview + +The following diagram shows the call chain and data flow from the frontend Svelte to the backend Python component. + +```mermaid +sequenceDiagram +participant Py as "Python Component
AntdPopconfirm/AntdPopover" +participant Idx as "Svelte Wrapper Layer
Index.svelte" +participant Br as "Bridge Layer
popconfirm.tsx / popover.tsx" +participant AD as "Ant Design Component" +Py->>Idx : "Instantiate and pass props/events/slots" +Idx->>Br : "Render bridge component, pass through props and slots" +Br->>AD : "Call Ant Design component, inject events and container" +AD-->>Br : "State change (openChange)" +Br-->>Idx : "Callback fired" +Idx-->>Py : "Event report (e.g., open_change/popup_click)" +``` + +Diagram sources + +- [frontend/antd/popconfirm/Index.svelte:24-55](file://frontend/antd/popconfirm/Index.svelte#L24-L55) +- [frontend/antd/popover/Index.svelte:24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- [frontend/antd/popconfirm/popconfirm.tsx:17-62](file://frontend/antd/popconfirm/popconfirm.tsx#L17-L62) +- [frontend/antd/popover/popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:14-27](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L14-L27) +- [backend/modelscope_studio/components/antd/popover/**init**.py:14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) + +## Detailed Component Analysis + +### Popconfirm + +- Design philosophy and interaction pattern + - Targeting "high-risk operations", reduces accidental trigger cost through a second confirmation. + - Supports multiple trigger modes; the popup provides confirm/cancel buttons with an optional icon. +- Props and events + - Key props: title, description, confirm text/button props, cancel text/button props, trigger type, positioning and collision avoidance, container mount point, delay, z-index, etc. + - Key events: open_change, cancel, confirm, popup_click. + - Key slots: title, description, okText, okButtonProps.icon, cancelText, cancelButtonProps.icon. +- Callbacks and state + - Get open/close state changes via `afterOpenChange`. + - Customize the mount container via `getPopupContainer` for positioning and z-index control in complex layouts. +- Use cases + - Delete confirmation, edit confirmation, batch operation confirmation, etc. + +```mermaid +flowchart TD +Start(["User trigger"]) --> Trigger{"Trigger type"} +Trigger --> |click/hover/focus/contextMenu| Open["Open confirmation popup"] +Open --> Action{"User choice"} +Action --> |Confirm| Confirm["Fire confirm callback"] +Action --> |Cancel| Cancel["Fire cancel callback"] +Confirm --> Close["Close popup"] +Cancel --> Close +Close --> End(["End"]) +``` + +Diagram sources + +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:14-27](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L14-L27) +- [frontend/antd/popconfirm/popconfirm.tsx:17-62](file://frontend/antd/popconfirm/popconfirm.tsx#L17-L62) + +Section sources + +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:10-137](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L10-L137) +- [frontend/antd/popconfirm/popconfirm.tsx:7-62](file://frontend/antd/popconfirm/popconfirm.tsx#L7-L62) +- [frontend/antd/popconfirm/Index.svelte:24-75](file://frontend/antd/popconfirm/Index.svelte#L24-L75) + +### Popover + +- Design philosophy and interaction pattern + - Provides non-intrusive information display and lightweight action entry points. + - Supports title and content slots, with automatic collision avoidance and multi-directional positioning. +- Props and events + - Key props: title, content, trigger type, placement, arrow, color, container mount point, delay, z-index, etc. + - Key events: open_change. + - Key slots: title, content. +- Use cases + - Information hints, action menus, supplementary explanations, etc. + +```mermaid +sequenceDiagram +participant U as "User" +participant P as "Popover" +participant C as "Content Slot" +participant D as "Positioning and Collision Avoidance" +U->>P : "Trigger (click/hover/focus/right-click)" +P->>D : "Calculate optimal position and collision avoidance" +P->>C : "Render title/content slots" +P-->>U : "Display floating layer" +``` + +Diagram sources + +- [backend/modelscope_studio/components/antd/popover/**init**.py:14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) +- [frontend/antd/popover/popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) + +Section sources + +- [backend/modelscope_studio/components/antd/popover/**init**.py:10-104](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L104) +- [frontend/antd/popover/popover.tsx:7-34](file://frontend/antd/popover/popover.tsx#L7-L34) +- [frontend/antd/popover/Index.svelte:24-72](file://frontend/antd/popover/Index.svelte#L24-L72) + +### Component Classes and Bridge Layer Relationships + +```mermaid +classDiagram +class AntdPopconfirm { ++EVENTS ++SLOTS ++props and methods... +} +class PopconfirmBridge { ++slots : title, description, okText, okButtonProps.icon, cancelText, cancelButtonProps.icon ++afterOpenChange() ++getPopupContainer() +} +class AntdPopover { ++EVENTS ++SLOTS ++props and methods... +} +class PopoverBridge { ++slots : title, content ++afterOpenChange() ++getPopupContainer() +} +AntdPopconfirm --> PopconfirmBridge : "Instantiate and render" +AntdPopover --> PopoverBridge : "Instantiate and render" +``` + +Diagram sources + +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:10-37](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L10-L37) +- [frontend/antd/popconfirm/popconfirm.tsx:7-17](file://frontend/antd/popconfirm/popconfirm.tsx#L7-L17) +- [backend/modelscope_studio/components/antd/popover/**init**.py:10-21](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L21) +- [frontend/antd/popover/popover.tsx:7-12](file://frontend/antd/popover/popover.tsx#L7-L12) + +## Dependency Analysis + +- Frontend dependencies + - The Svelte wrapper layer depends on the bridge layer; the bridge layer depends on the Ant Design React component library. + - Events and slots are passed across frameworks through function wrapping and ReactSlot rendering. +- Backend dependencies + - Python component classes map the component name to the frontend directory via resolve_frontend_dir, ensuring the runtime can load it. +- Coupling and cohesion + - Component responsibilities are clear: Python handles prop/event/slot definitions, Svelte handles prop passthrough and event mapping, and the TS bridge layer handles slot rendering and callback wrapping. + +```mermaid +graph LR +PY_PCF["Python: AntdPopconfirm"] --> IDX_PCF["Svelte: popconfirm/Index.svelte"] +IDX_PCF --> BRG_PCF["TS: popconfirm.tsx"] +BRG_PCF --> AD_PCF["Ant Design Popconfirm"] +PY_POV["Python: AntdPopover"] --> IDX_POV["Svelte: popover/Index.svelte"] +IDX_POV --> BRG_POV["TS: popover.tsx"] +BRG_POV --> AD_POV["Ant Design Popover"] +``` + +Diagram sources + +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:138-138](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L138-L138) +- [frontend/antd/popconfirm/Index.svelte:10-10](file://frontend/antd/popconfirm/Index.svelte#L10-L10) +- [frontend/antd/popconfirm/popconfirm.tsx:1-5](file://frontend/antd/popconfirm/popconfirm.tsx#L1-L5) +- [backend/modelscope_studio/components/antd/popover/**init**.py:106-106](file://backend/modelscope_studio/components/antd/popover/__init__.py#L106-L106) +- [frontend/antd/popover/Index.svelte:10-10](file://frontend/antd/popover/Index.svelte#L10-L10) +- [frontend/antd/popover/popover.tsx:1-5](file://frontend/antd/popover/popover.tsx#L1-L5) + +Section sources + +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:138-138](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L138-L138) +- [backend/modelscope_studio/components/antd/popover/**init**.py:106-106](file://backend/modelscope_studio/components/antd/popover/__init__.py#L106-L106) +- [frontend/antd/popconfirm/Index.svelte:10-10](file://frontend/antd/popconfirm/Index.svelte#L10-L10) +- [frontend/antd/popover/Index.svelte:10-10](file://frontend/antd/popover/Index.svelte#L10-L10) +- [frontend/antd/popconfirm/popconfirm.tsx:1-5](file://frontend/antd/popconfirm/popconfirm.tsx#L1-L5) +- [frontend/antd/popover/popover.tsx:1-5](file://frontend/antd/popover/popover.tsx#L1-L5) + +## Performance Considerations + +- Lazy loading and lazy rendering + - The Svelte wrapper layer uses dynamic component imports to avoid an oversized initial bundle. +- Slot rendering optimization + - Slot content is rendered only when needed, reducing unnecessary virtual DOM updates. +- Container mounting and z-index management + - Mount the popup to an appropriate container via `getPopupContainer` to avoid z-index conflicts and reflows. +- Delay and destruction strategy + - Set appropriate mouse enter/leave delays to avoid frequent flickering; choose hide-then-destroy strategy based on the scenario to save memory. + +## Troubleshooting Guide + +- Cannot open/close + - Check that the trigger type and `open` state are consistent; confirm `open_change` event is correctly bound. + - Reference paths: [frontend/antd/popconfirm/Index.svelte:24-55](file://frontend/antd/popconfirm/Index.svelte#L24-L55), [frontend/antd/popover/Index.svelte:24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- Content not displayed or misaligned + - Confirm slot names and rendering logic; check if getPopupContainer returns a valid container. + - Reference paths: [frontend/antd/popconfirm/popconfirm.tsx:17-62](file://frontend/antd/popconfirm/popconfirm.tsx#L17-L62), [frontend/antd/popover/popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) +- Events not fired + - Confirm backend event listeners match frontend event mapping; check that callback function wrapping is effective. + - Reference paths: [backend/modelscope_studio/components/antd/popconfirm/**init**.py:14-27](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L14-L27), [backend/modelscope_studio/components/antd/popover/**init**.py:14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) + +Section sources + +- [frontend/antd/popconfirm/Index.svelte:24-55](file://frontend/antd/popconfirm/Index.svelte#L24-L55) +- [frontend/antd/popover/Index.svelte:24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- [frontend/antd/popconfirm/popconfirm.tsx:17-62](file://frontend/antd/popconfirm/popconfirm.tsx#L17-L62) +- [frontend/antd/popover/popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:14-27](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L14-L27) +- [backend/modelscope_studio/components/antd/popover/**init**.py:14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) + +## Conclusion + +Popconfirm and Popover are implemented in this project through a unified architecture of "Python component + Svelte wrapper + TS bridge + Ant Design component", ensuring behavioral consistency with Ant Design while providing flexible slot and event extension capabilities. By making proper use of triggers, positioning, container mounting, and event callbacks, stable and user-friendly interaction experiences can be achieved in complex interfaces. + +## Appendix + +- Example entries + - Popconfirm example entry: [docs/components/antd/popconfirm/README-zh_CN.md:5-8](file://docs/components/antd/popconfirm/README-zh_CN.md#L5-L8) + - Popover example entry: [docs/components/antd/popover/README-zh_CN.md:5-8](file://docs/components/antd/popover/README-zh_CN.md#L5-L8) diff --git a/.wiki/en/Ant Design Components/Feedback Components/Message and Notification.md b/.wiki/en/Ant Design Components/Feedback Components/Message and Notification.md new file mode 100644 index 00000000..58757a54 --- /dev/null +++ b/.wiki/en/Ant Design Components/Feedback Components/Message and Notification.md @@ -0,0 +1,332 @@ +# Message and Notification + + +**Files referenced in this document** +- [frontend/antd/message/message.tsx](file://frontend/antd/message/message.tsx) +- [frontend/antd/notification/notification.tsx](file://frontend/antd/notification/notification.tsx) +- [frontend/antd/message/Index.svelte](file://frontend/antd/message/Index.svelte) +- [frontend/antd/notification/Index.svelte](file://frontend/antd/notification/Index.svelte) +- [backend/modelscope_studio/components/antd/message/__init__.py](file://backend/modelscope_studio/components/antd/message/__init__.py) +- [backend/modelscope_studio/components/antd/notification/__init__.py](file://backend/modelscope_studio/components/antd/notification/__init__.py) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/antd/message/package.json](file://frontend/antd/message/package.json) +- [frontend/antd/notification/package.json](file://frontend/antd/notification/package.json) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance and Memory Management](#performance-and-memory-management) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Usage Examples and Best Practices](#appendix-usage-examples-and-best-practices) + +## Introduction + +This document systematically covers the message notification component group, focusing on two types of global feedback components: Message and Notification. It provides a complete explanation covering design philosophy, use cases, comparison of differences, configuration options and dynamic behavior, lifecycle and memory cleanup, accessibility and experience optimization, along with source-traceable path references to help developers get started quickly and use the components correctly. + +## Project Structure + +The message notification components are built from three layers: "backend Python component + frontend Svelte wrapper + React/antd implementation": + +- The backend component is responsible for parameter validation, event binding, rendering control, and frontend package export declarations. +- The frontend Svelte layer is responsible for prop passthrough, slot mapping, and visibility state synchronization. +- The React layer implements the specific message popup, stacking, and destruction logic based on the antd message/notification API. + +```mermaid +graph TB +subgraph "Backend" +PY_MSG["AntdMessage
Python Component"] +PY_NOTI["AntdNotification
Python Component"] +end +subgraph "Frontend Svelte" +SV_MSG["message/Index.svelte"] +SV_NOTI["notification/Index.svelte"] +end +subgraph "React/antd" +TSX_MSG["message.tsx
useMessage-driven"] +TSX_NOTI["notification.tsx
useNotification-driven"] +end +PY_MSG --> SV_MSG --> TSX_MSG +PY_NOTI --> SV_NOTI --> TSX_NOTI +``` + +Diagram sources + +- [backend/modelscope_studio/components/antd/message/**init**.py:10-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L10-L91) +- [backend/modelscope_studio/components/antd/notification/**init**.py:10-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L10-L109) +- [frontend/antd/message/Index.svelte:10-78](file://frontend/antd/message/Index.svelte#L10-L78) +- [frontend/antd/notification/Index.svelte:10-80](file://frontend/antd/notification/Index.svelte#L10-L80) +- [frontend/antd/message/message.tsx:9-79](file://frontend/antd/message/message.tsx#L9-L79) +- [frontend/antd/notification/notification.tsx:8-106](file://frontend/antd/notification/notification.tsx#L8-L106) + +Section sources + +- [frontend/antd/message/package.json:1-15](file://frontend/antd/message/package.json#L1-L15) +- [frontend/antd/notification/package.json:1-15](file://frontend/antd/notification/package.json#L1-L15) + +## Core Components + +- Message + - Design goal: Provide immediate, concise feedback for user actions, commonly used for submit success/failure, warning, or loading hints. + - Key features: Lightweight, no mask, auto-dismiss, configurable duration, key-based uniqueness and override control. +- Notification + - Design goal: Pop up richer content in a page corner, suitable for reminders that need to carry a title, description, buttons, actions, etc. + - Key features: Supports multiple placement positions (top/bottom/left/right), stacking management, progress bar, hover-to-pause, customizable buttons and actions. + +Section sources + +- [backend/modelscope_studio/components/antd/message/**init**.py:10-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L10-L91) +- [backend/modelscope_studio/components/antd/notification/**init**.py:10-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L10-L109) + +## Architecture Overview + +The message component call chain is: backend component instantiation → frontend Svelte rendering → React/antd executes open/destroy → lifecycle callbacks trigger state propagation back. + +```mermaid +sequenceDiagram +participant Py as "Backend Component" +participant S as "Svelte Wrapper" +participant R as "React/antd" +participant UI as "Browser Interface" +Py->>S : Pass props and slots +S->>R : Pass through props and slots +R->>R : Initialize useMessage/useNotification +alt Visible and open +R->>UI : open({key, content, duration, ...}) +else Close or destroy +R->>UI : destroy(key) +end +UI-->>R : User interaction (click/close) +R-->>S : Fire onVisible(false) callback +S-->>Py : Update visible state +``` + +Diagram sources + +- [frontend/antd/message/message.tsx:30-68](file://frontend/antd/message/message.tsx#L30-L68) +- [frontend/antd/notification/notification.tsx:31-95](file://frontend/antd/notification/notification.tsx#L31-L95) +- [frontend/antd/message/Index.svelte:58-77](file://frontend/antd/message/Index.svelte#L58-L77) +- [frontend/antd/notification/Index.svelte:59-79](file://frontend/antd/notification/Index.svelte#L59-L79) + +## Detailed Component Analysis + +### Message Component + +- Responsibilities and behavior + - Provides global message capabilities based on antd's `message.useMessage`; + - Supports controlling visibility via `visible` and uniqueness via `messageKey`; + - Supports `slots.content` and `slots.icon` for custom content and icons; + - Fires `onVisible(false)` on close and destroys the corresponding key when the component unmounts. +- Key configuration options (excerpt) + - Content and type: content, type (success/info/warning/error/loading) + - Display duration: duration (seconds) + - Container mount point: getContainer (function) + - Text and styles: className, style, rootClassName + - Key and visibility: messageKey, visible +- Dynamic updates and batch operations + - Use messageKey to override and update the same message position; + - Multiple messages can coexist without interfering with each other; + - Use `destroy(key)` or `destroyAll()` for batch cleanup. +- Lifecycle and memory + - Registered on open; destroyed on close/unmount; avoids residual DOM and event listeners. + +```mermaid +flowchart TD +Start(["Enter Effect"]) --> CheckVisible{"visible is true?"} +CheckVisible -- No --> Destroy["destroy(key) and return"] +CheckVisible -- Yes --> Open["messageApi.open({...})"] +Open --> OnClose["onClose callback fires onVisible(false)"] +OnClose --> End(["End"]) +Destroy --> End +``` + +Diagram sources + +- [frontend/antd/message/message.tsx:35-68](file://frontend/antd/message/message.tsx#L35-L68) + +Section sources + +- [frontend/antd/message/message.tsx:9-79](file://frontend/antd/message/message.tsx#L9-L79) +- [frontend/antd/message/Index.svelte:19-77](file://frontend/antd/message/Index.svelte#L19-L77) +- [backend/modelscope_studio/components/antd/message/**init**.py:26-72](file://backend/modelscope_studio/components/antd/message/__init__.py#L26-L72) + +### Notification Component + +- Responsibilities and behavior + - Provides global notification capabilities based on antd's `notification.useNotification`; + - Supports multiple positions (top/bottom/left/right and combinations) and stacking management; + - Supports rich slots: slots.message/description/icon/actions/btn/closeIcon; + - Fires `onVisible(false)` on close and destroys the corresponding key on unmount. +- Key configuration options (excerpt) + - Position and stacking: placement, stack, top, bottom, rtl + - Content and interaction: message, description, btn, actions, closeIcon, icon + - Behavior and experience: duration, showProgress, pauseOnHover, role (alert/status) + - Key and visibility: notificationKey, visible +- Dynamic updates and batch operations + - Use notificationKey to override the same notification; + - Supports `destroyAll()` for batch cleanup; + - In stacking mode, controls the arrangement and override strategy for new and old notifications. +- Lifecycle and memory + - Registered on open; destroyed on close/unmount; avoids memory leaks. + +```mermaid +sequenceDiagram +participant S as "Svelte Wrapper" +participant R as "React/antd" +participant N as "notificationApi" +participant U as "User" +S->>R : visible=true and pass props +R->>N : open({key, message, description, actions, ...}) +U-->>N : Click/close +N-->>R : onClose callback +R-->>S : onVisible(false) +S-->>S : updateProps({visible : false}) +R->>N : destroy(key) or destroyAll() +``` + +Diagram sources + +- [frontend/antd/notification/notification.tsx:38-95](file://frontend/antd/notification/notification.tsx#L38-L95) +- [frontend/antd/notification/Index.svelte:59-79](file://frontend/antd/notification/Index.svelte#L59-L79) + +Section sources + +- [frontend/antd/notification/notification.tsx:8-106](file://frontend/antd/notification/notification.tsx#L8-L106) +- [frontend/antd/notification/Index.svelte:19-79](file://frontend/antd/notification/Index.svelte#L19-L79) +- [backend/modelscope_studio/components/antd/notification/**init**.py:26-90](file://backend/modelscope_studio/components/antd/notification/__init__.py#L26-L90) + +### Differences and Use Cases + +- Use cases + - Message: Lightweight feedback, short text hints, no need for complex interaction; + - Notification: Requires a title/description/buttons/actions, multiple position display, emphasizes important information. +- Display position and stacking + - Message: Appears at the top of the container or in a specified container by default; does not support multiple positions; + - Notification: Supports top/bottom/left/right and combinations, with stacking management and progress bar. +- Interaction and accessibility + - Notification: Supports `role` (alert/status) for screen reader identification; + - Message: More oriented toward one-time hints with minimal interaction. +- Dynamic and batch operations + - Both support key-based uniqueness and override; Notification makes it easier to implement batch cleanup and stacking strategies. + +Section sources + +- [backend/modelscope_studio/components/antd/message/**init**.py:26-72](file://backend/modelscope_studio/components/antd/message/__init__.py#L26-L72) +- [backend/modelscope_studio/components/antd/notification/**init**.py:26-90](file://backend/modelscope_studio/components/antd/notification/__init__.py#L26-L90) + +## Dependency Analysis + +- Component export and entry + - Both message and notification expose Gradio-compatible entry points via package.json; +- Frontend bridge + - The Svelte wrapper handles prop and slot passthrough, and writes back the `visible` state; + - The React layer safely injects functions like getContainer into the antd API via useFunction; +- Events and slots + - The backend declares click/close events; the Svelte side binds them via the `_internal` flag; + - Slot mapping: Message (content/icon), Notification (actions/btn/closeIcon/description/icon/message/title). + +```mermaid +graph LR +PkgMsg["message/package.json"] --> SMsg["message/Index.svelte"] +PkgNoti["notification/package.json"] --> SNoti["notification/Index.svelte"] +SMsg --> TMsg["message.tsx"] +SNoti --> TNoti["notification.tsx"] +TMsg --> Hook["useFunction.ts"] +TNoti --> Hook +``` + +Diagram sources + +- [frontend/antd/message/package.json:1-15](file://frontend/antd/message/package.json#L1-L15) +- [frontend/antd/notification/package.json:1-15](file://frontend/antd/notification/package.json#L1-L15) +- [frontend/antd/message/Index.svelte:10](file://frontend/antd/message/Index.svelte#L10) +- [frontend/antd/notification/Index.svelte:10](file://frontend/antd/notification/Index.svelte#L10) +- [frontend/antd/message/message.tsx:29](file://frontend/antd/message/message.tsx#L29) +- [frontend/antd/notification/notification.tsx:31](file://frontend/antd/notification/notification.tsx#L31) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) + +Section sources + +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) + +## Performance and Memory Management + +- Performance characteristics + - Message: Lightweight, no mask, small DOM count — suitable for high-frequency hints; + - Notification: Supports stacking and progress bar with stronger visual feedback, but DOM count may increase. +- Memory cleanup strategy + - Uniformly call `destroy(key)`/`destroyAll()` on close and unmount; + - Use key to precisely control resource reclamation, avoiding duplicate rendering and event accumulation; + - Use getContainer to mount messages to the minimum necessary container, reducing reflow and repaint. +- Best practices + - Set a unique key for each independent message; + - Set a reasonable `duration` to avoid too many messages persisting for too long; + - Use `destroyAll()` in batch operations to clean up expired messages; + - For frequently triggered operations, prefer Message; introduce Notification only when necessary. + +Section sources + +- [frontend/antd/message/message.tsx:51-58](file://frontend/antd/message/message.tsx#L51-L58) +- [frontend/antd/notification/notification.tsx:74-77](file://frontend/antd/notification/notification.tsx#L74-L77) + +## Troubleshooting Guide + +- Common issues + - Message not displayed: Check if `visible` is true and that `messageKey` is correctly passed in; + - Cannot be closed: Confirm the `onClose` callback has not been overridden; ensure the `onVisible` callback chain is functioning correctly; + - Duplicate messages: Set a unique key for each message to avoid being overridden by subsequent `open` calls; + - Position is wrong: Confirm the mount node returned by `getContainer` exists and is visible. +- Debugging steps + - Print props and visible state in the Svelte layer; + - Confirm messageApi/notificationApi has been initialized in the React layer; + - Use `destroyAll()` to quickly clear the slate and verify whether any DOM remains; + - Check that the getContainer function consistently returns the same node. + +Section sources + +- [frontend/antd/message/message.tsx:35-68](file://frontend/antd/message/message.tsx#L35-L68) +- [frontend/antd/notification/notification.tsx:38-95](file://frontend/antd/notification/notification.tsx#L38-L95) + +## Conclusion + +The message notification component group implements highly available and extensible global feedback capabilities through a layered design of "backend parameters + frontend bridge + React/antd driver". Message is suitable for lightweight hints; Notification is suitable for rich notifications. By applying reasonable key strategies, duration configuration, and destruction mechanisms, excellent performance and memory health can be maintained while ensuring a great user experience. + +## Appendix: Usage Examples and Best Practices + +- Success hint (Message) + - Set `type` to `success`, use an appropriate `duration`, and make `messageKey` unique; + - Toggle display via `visible`; synchronize visible state with `onClose`. + - Example path reference: [frontend/antd/message/message.tsx:35-50](file://frontend/antd/message/message.tsx#L35-L50) +- Error alert (Notification) + - Set `type` to `error`, enrich content with `message`/`description`, and provide operations via `actions`; + - Use `destroyAll()` to clean up historical error messages and prevent accumulation. + - Example path reference: [frontend/antd/notification/notification.tsx:38-69](file://frontend/antd/notification/notification.tsx#L38-L69) +- Info notification (Notification) + - Use `placement` to specify position (e.g., topRight); set `role` to `status`; + - Control stacking with `stack`; improve readability with `pauseOnHover`. + - Example path reference: [frontend/antd/notification/notification.tsx:31-36](file://frontend/antd/notification/notification.tsx#L31-L36) +- Manual close + - Proactively close via `onVisible(false)`, or call `destroy(key)` externally; + - Example path reference: [frontend/antd/message/message.tsx:46-50](file://frontend/antd/message/message.tsx#L46-L50), [frontend/antd/notification/notification.tsx:65-69](file://frontend/antd/notification/notification.tsx#L65-L69) +- Dynamic updates and batch operations + - Use `messageKey` to override an existing message; + - Use `destroyAll()` for batch cleanup to avoid memory leaks. + - Example path reference: [frontend/antd/message/message.tsx:51-58](file://frontend/antd/message/message.tsx#L51-L58), [frontend/antd/notification/notification.tsx:74-77](file://frontend/antd/notification/notification.tsx#L74-L77) + +Accessibility and experience optimization recommendations + +- Set `role` (alert/status) on Notification to improve accessibility; +- Set a reasonable `duration` to avoid interrupting user tasks; +- Provide clear feedback text and action buttons for key operations; +- In dark themes or high-contrast environments, ensure message colors and icons are clearly distinguishable. + +Section sources + +- [backend/modelscope_studio/components/antd/notification/**init**.py:40-44](file://backend/modelscope_studio/components/antd/notification/__init__.py#L40-L44) +- [frontend/antd/notification/notification.tsx:65-69](file://frontend/antd/notification/notification.tsx#L65-L69) diff --git a/.wiki/en/Ant Design Components/Feedback Components/Modal.md b/.wiki/en/Ant Design Components/Feedback Components/Modal.md new file mode 100644 index 00000000..1492d5e7 --- /dev/null +++ b/.wiki/en/Ant Design Components/Feedback Components/Modal.md @@ -0,0 +1,322 @@ +# Modal + + +**Files referenced in this document** +- [frontend/antd/modal/modal.tsx](file://frontend/antd/modal/modal.tsx) +- [frontend/antd/modal/static/modal.static.tsx](file://frontend/antd/modal/static/modal.static.tsx) +- [backend/modelscope_studio/components/antd/modal/__init__.py](file://backend/modelscope_studio/components/antd/modal/__init__.py) +- [backend/modelscope_studio/components/antd/modal/static/__init__.py](file://backend/modelscope_studio/components/antd/modal/static/__init__.py) +- [frontend/antd/modal/static/Index.svelte](file://frontend/antd/modal/static/Index.svelte) +- [docs/components/antd/modal/README.md](file://docs/components/antd/modal/README.md) +- [docs/components/antd/modal/demos/basic.py](file://docs/components/antd/modal/demos/basic.py) +- [docs/components/antd/modal/demos/custom_footer.py](file://docs/components/antd/modal/demos/custom_footer.py) +- [docs/components/antd/modal/demos/static.py](file://docs/components/antd/modal/demos/static.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance and Animation](#performance-and-animation) +8. [Accessibility and Keyboard Interaction](#accessibility-and-keyboard-interaction) +9. [Troubleshooting](#troubleshooting) +10. [Conclusion](#conclusion) +11. [Appendix: Common Scenario Examples](#appendix-common-scenario-examples) + +## Introduction + +This document systematically covers the "Modal" component group, including the design principles, use cases, z-index management, focus control, keyboard interaction, event and style customization, animation and transitions, performance optimization, and accessibility support for both regular Modal and Static Modal. The document also provides practical guidance based on repository examples to help developers efficiently integrate and extend the components in the Gradio/ModelScope ecosystem. + +## Project Structure + +This component is positioned between the frontend Ant Design wrapper layer and the backend Python component bridge layer, using a layered design of "Frontend Svelte + React Slot + Backend LayoutComponent": + +- Frontend layer: Wraps Ant Design's Modal as a slottable component via `sveltify`; the static modal dynamically renders via the useModal API. +- Backend layer: Python components encapsulate AntdModal/AntdModalStatic, exposing a unified property and event interface and declaring supported slots. +- Documentation and examples: Provides three types of examples — basic, custom footer, and static call — for quick onboarding. + +```mermaid +graph TB +subgraph "Backend" +PY_API["AntdModal
AntdModalStatic"] +end +subgraph "Frontend" +F_Svelte["Index.svelte
Static Wrapper"] +F_Modal["Modal.tsx
Regular Dialog"] +F_Static["ModalStatic.tsx
Static Dialog"] +end +subgraph "Third-party" +AntD["Ant Design Modal"] +end +PY_API --> F_Svelte +F_Svelte --> F_Modal +F_Svelte --> F_Static +F_Modal --> AntD +F_Static --> AntD +``` + +Diagram sources + +- [frontend/antd/modal/modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) +- [frontend/antd/modal/static/modal.static.tsx:1-132](file://frontend/antd/modal/static/modal.static.tsx#L1-L132) +- [frontend/antd/modal/static/Index.svelte:1-69](file://frontend/antd/modal/static/Index.svelte#L1-L69) +- [backend/modelscope_studio/components/antd/modal/**init**.py:1-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L1-L136) +- [backend/modelscope_studio/components/antd/modal/static/**init**.py:1-133](file://backend/modelscope_studio/components/antd/modal/static/__init__.py#L1-L133) + +Section sources + +- [docs/components/antd/modal/README.md:1-13](file://docs/components/antd/modal/README.md#L1-L13) + +## Core Components + +- Regular Modal (AntdModal) + - Design positioning: Rendered directly as a component, suitable for scenarios that need to explicitly manage the lifecycle and z-index in the layout tree. + - Key capabilities: Supports slottable title, footer, button icons and text, close icon, custom renderer, container mount point, keyboard and mask behavior, etc. +- Static Modal (AntdModalStatic) + - Design positioning: Dynamically triggered via useModal without needing to be declared in the layout tree, suitable for one-time dialogs such as message hints and confirmation flows. + - Key capabilities: Supports info/success/error/warning/confirm types, auto-focus buttons, controlled visibility, onOk/onCancel callback linkage. + +Section sources + +- [backend/modelscope_studio/components/antd/modal/**init**.py:11-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L11-L136) +- [backend/modelscope_studio/components/antd/modal/static/**init**.py:10-133](file://backend/modelscope_studio/components/antd/modal/static/__init__.py#L10-L133) + +## Architecture Overview + +The following diagram shows the key call chain from user trigger to dialog presentation, including both regular and static modes: + +```mermaid +sequenceDiagram +participant U as "User" +participant PY as "Backend Component (AntdModal/Static)" +participant FE as "Frontend Wrapper (Index.svelte)" +participant MOD as "Modal/ModalStatic" +participant ANT as "Ant Design Modal" +U->>PY : Trigger display (e.g., click a button) +PY->>FE : Pass props and visibility +alt Regular mode +FE->>MOD : Render Modal component +MOD->>ANT : Render regular dialog +else Static mode +FE->>MOD : Pass visible/type etc. +MOD->>ANT : Call useModal(type) to create instance +end +ANT-->>U : Display dialog and respond to interactions +``` + +Diagram sources + +- [frontend/antd/modal/static/Index.svelte:54-68](file://frontend/antd/modal/static/Index.svelte#L54-L68) +- [frontend/antd/modal/modal.tsx:36-102](file://frontend/antd/modal/modal.tsx#L36-L102) +- [frontend/antd/modal/static/modal.static.tsx:46-128](file://frontend/antd/modal/static/modal.static.tsx#L46-L128) + +## Component Details + +### Regular Modal + +- Slot and prop mapping + - Supported slots: okText, okButtonProps.icon, cancelText, cancelButtonProps.icon, closable.closeIcon, closeIcon, footer, title, modalRender. + - Prop passthrough: afterOpenChange, afterClose, getContainer, keyboard, mask, maskClosable, width, zIndex, wrapClassName, etc. +- Event binding + - ok/cancel events are bound via event listeners to trigger callbacks or update visibility. +- Container mount and z-index + - getContainer can specify the mount node to avoid the z-index being blocked by a local container; defaults to mounting to body. +- Focus and keyboard + - `keyboard` controls whether Esc is allowed to close; `autoFocusButton` and similar props affect the initial focus. +- Custom rendering + - `modalRender` can replace the entire rendering logic; `footer` supports function-based slots for complex footer layouts. + +```mermaid +flowchart TD +Start(["Enter render"]) --> CheckSlots["Check if slots exist"] +CheckSlots --> |Exist| RenderSlot["Render slot content"] +CheckSlots --> |Do not exist| UseProp["Use prop value"] +RenderSlot --> Combine["Merge into final props"] +UseProp --> Combine +Combine --> Mount["Mount to target container"] +Mount --> Focus["Set focus/keyboard behavior based on config"] +Focus --> End(["Complete"]) +``` + +Diagram sources + +- [frontend/antd/modal/modal.tsx:36-99](file://frontend/antd/modal/modal.tsx#L36-L99) + +Section sources + +- [frontend/antd/modal/modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) +- [backend/modelscope_studio/components/antd/modal/**init**.py:18-32](file://backend/modelscope_studio/components/antd/modal/__init__.py#L18-L32) + +### Static Modal + +- Dynamic creation and destruction + - Obtains the API via `useModal`; creates the corresponding type instance when `visible` is true, otherwise destroys the current instance. + - Auto-focus on buttons is disabled by default unless explicitly passed in. +- Event and visibility linkage + - onOk/onCancel internally synchronize `onVisible(false)`, implementing the consistent behavior of "confirm/cancel = close". +- Slots and props + - Supports title, content, footer, okText, okButtonProps.icon, cancelText, cancelButtonProps.icon, closable.closeIcon, closeIcon, modalRender, etc. +- Usage restrictions + - Not declared in the layout tree; driven only by props such as visible/type; suitable for one-time hints and confirmation flows. + +```mermaid +sequenceDiagram +participant C as "Caller" +participant MS as "ModalStatic" +participant API as "useModal" +participant D as "Dialog Instance" +C->>MS : visible=true, type=info/success/... +MS->>API : Call corresponding type method (type) +API-->>MS : Return instance reference +MS->>D : Render and apply slots/props +D-->>MS : User action (confirm/cancel) +MS->>C : Fire onVisible(false) +MS->>API : Destroy instance +``` + +Diagram sources + +- [frontend/antd/modal/static/modal.static.tsx:46-128](file://frontend/antd/modal/static/modal.static.tsx#L46-L128) + +Section sources + +- [frontend/antd/modal/static/modal.static.tsx:1-132](file://frontend/antd/modal/static/modal.static.tsx#L1-L132) +- [backend/modelscope_studio/components/antd/modal/static/**init**.py:14-28](file://backend/modelscope_studio/components/antd/modal/static/__init__.py#L14-L28) + +### Component Relationships and Inheritance + +- The backend component classes AntdModal and AntdModalStatic both inherit from ModelScopeLayoutComponent, which unifies event, slot, prop, and lifecycle handling. +- The frontend Index.svelte serves as the dynamic loading entry point, responsible for passing props and slots to Modal or ModalStatic. + +```mermaid +classDiagram +class ModelScopeLayoutComponent +class AntdModal { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdModalStatic { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class Modal_tsx +class ModalStatic_tsx +class Index_svelte +ModelScopeLayoutComponent <|-- AntdModal +ModelScopeLayoutComponent <|-- AntdModalStatic +Index_svelte --> Modal_tsx : "Render regular" +Index_svelte --> ModalStatic_tsx : "Render static" +``` + +Diagram sources + +- [backend/modelscope_studio/components/antd/modal/**init**.py:11-16](file://backend/modelscope_studio/components/antd/modal/__init__.py#L11-L16) +- [backend/modelscope_studio/components/antd/modal/static/**init**.py:10-13](file://backend/modelscope_studio/components/antd/modal/static/__init__.py#L10-L13) +- [frontend/antd/modal/static/Index.svelte:10-68](file://frontend/antd/modal/static/Index.svelte#L10-L68) + +## Dependency Analysis + +- Frontend dependencies + - sveltify: Bridges React components to Svelte. + - useFunction: Stabilizes callback functions to avoid side effects from repeated rendering. + - renderParamsSlot: Supports slot rendering with parameters. + - Ant Design Modal: Core UI behavior and styles. +- Backend dependencies + - Gradio event system: Binds ok/cancel via event listeners. + - Component base class ModelScopeLayoutComponent: Unifies lifecycle and prop handling. + +```mermaid +graph LR +A["Modal.tsx"] --> B["Ant Design Modal"] +C["ModalStatic.tsx"] --> B +D["Index.svelte"] --> A +D --> C +E["AntdModal"] --> D +F["AntdModalStatic"] --> D +``` + +Diagram sources + +- [frontend/antd/modal/modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) +- [frontend/antd/modal/static/modal.static.tsx:1-132](file://frontend/antd/modal/static/modal.static.tsx#L1-L132) +- [frontend/antd/modal/static/Index.svelte:1-69](file://frontend/antd/modal/static/Index.svelte#L1-L69) +- [backend/modelscope_studio/components/antd/modal/**init**.py:1-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L1-L136) +- [backend/modelscope_studio/components/antd/modal/static/**init**.py:1-133](file://backend/modelscope_studio/components/antd/modal/static/__init__.py#L1-L133) + +## Performance and Animation + +- Rendering strategy + - Regular mode: Rendered on demand; when open=false, use destroyOnClose/destroyOnHidden to reduce memory usage. + - Static mode: Instances are dynamically created/destroyed when visible toggles, avoiding persistent DOM. +- Animation and transitions + - Ant Design Modal provides open/close animations and mask transitions; visual z-index and size can be adjusted via width, zIndex, wrapClassName, etc. +- Performance recommendations + - For scenarios with many dialogs, prefer the static mode to reduce the number of nodes in the layout tree. + - For frequently toggled dialogs, set getContainer appropriately to avoid unnecessary reflows. + - When using modalRender for custom rendering, minimize deep nesting and expensive computations. + +[This section provides general guidance and does not directly analyze specific files] + +## Accessibility and Keyboard Interaction + +- Keyboard interaction + - `keyboard` controls whether Esc is allowed to close; `maskClosable` controls whether clicking the mask closes the dialog. + - Static mode disables auto-focus on buttons by default to avoid interrupting user actions; can be explicitly specified via `autoFocusButton`. +- Focus management + - After opening, focus should move to the first interactive element (e.g., the confirm button); after closing, focus should return to the trigger source (`focusTriggerAfterClose`). +- Screen readers + - Provide clear title and content; supplement semantics with aria-\* attributes when necessary. + - Avoid hints in modalRender that rely solely on color; ensure text is readable. + +[This section provides general guidance and does not directly analyze specific files] + +## Troubleshooting + +- Issue: Dialog not displayed + - Check that visible/open is correctly passed in; for static mode, ensure visible switches from false to true. + - Confirm getContainer points to a valid node that is not clipped by a parent. +- Issue: Clicking the mask does not close + - Check maskClosable and keyboard settings; confirm no external events are intercepting. +- Issue: Static dialog does not disappear + - Ensure onOk/onCancel callbacks call `onVisible(false)`; or directly update visible to false. +- Issue: Slots not working + - Confirm slot names match the component's supported list; regular mode uses slots, static mode is driven by visible/type. + +Section sources + +- [frontend/antd/modal/static/modal.static.tsx:107-114](file://frontend/antd/modal/static/modal.static.tsx#L107-L114) +- [backend/modelscope_studio/components/antd/modal/**init**.py:18-32](file://backend/modelscope_studio/components/antd/modal/__init__.py#L18-L32) + +## Conclusion + +- Regular Modal is suitable for scenarios requiring fine-grained lifecycle and z-index control in the layout tree; Static Modal is suitable for one-time hints and confirmation flows. +- Through flexible combination of slots and props, rich interaction and style customization can be achieved; combining useModal with the event system enables a consistent user experience. +- For performance and accessibility, it is recommended to prefer static mode for high-frequency dialogs, set focus and keyboard behavior appropriately, and ensure content is screen-reader-friendly. + +[This section is a summary and does not directly analyze specific files] + +## Appendix: Common Scenario Examples + +The following examples come from the repository documentation and demos, showcasing different usage patterns and typical scenarios. + +- Basic dialog + - Scenario: Open/close, confirm/cancel. + - Example path: [docs/components/antd/modal/demos/basic.py:1-19](file://docs/components/antd/modal/demos/basic.py#L1-L19) +- Custom footer + - Scenario: Custom bottom buttons, link navigation, combined interactions. + - Example path: [docs/components/antd/modal/demos/custom_footer.py:1-31](file://docs/components/antd/modal/demos/custom_footer.py#L1-L31) +- Static dialog (info/success/error/warning/confirm) + - Scenario: Message hints, confirmation dialogs. + - Example path: [docs/components/antd/modal/demos/static.py:1-74](file://docs/components/antd/modal/demos/static.py#L1-L74) + +Section sources + +- [docs/components/antd/modal/demos/basic.py:1-19](file://docs/components/antd/modal/demos/basic.py#L1-L19) +- [docs/components/antd/modal/demos/custom_footer.py:1-31](file://docs/components/antd/modal/demos/custom_footer.py#L1-L31) +- [docs/components/antd/modal/demos/static.py:1-74](file://docs/components/antd/modal/demos/static.py#L1-L74) diff --git a/.wiki/en/Ant Design Components/Feedback Components/Progress and Result.md b/.wiki/en/Ant Design Components/Feedback Components/Progress and Result.md new file mode 100644 index 00000000..c37ef21f --- /dev/null +++ b/.wiki/en/Ant Design Components/Feedback Components/Progress and Result.md @@ -0,0 +1,289 @@ +# Progress and Result + + +**Files referenced in this document** +- [frontend/antd/progress/progress.tsx](file://frontend/antd/progress/progress.tsx) +- [frontend/antd/progress/Index.svelte](file://frontend/antd/progress/Index.svelte) +- [docs/components/antd/progress/README.md](file://docs/components/antd/progress/README.md) +- [docs/components/antd/progress/demos/basic.py](file://docs/components/antd/progress/demos/basic.py) +- [frontend/antd/result/result.tsx](file://frontend/antd/result/result.tsx) +- [frontend/antd/result/Index.svelte](file://frontend/antd/result/Index.svelte) +- [docs/components/antd/result/README.md](file://docs/components/antd/result/README.md) +- [docs/components/antd/result/demos/basic.py](file://docs/components/antd/result/demos/basic.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document focuses on the progress and result component group, systematically covering the functional characteristics, shape variants, status semantics, property configuration, animation and style customization methods for both the Progress and Result components, combined with demo examples from the repository to provide practical recommendations for typical application scenarios such as file upload progress, task execution status, and operation result feedback. It also covers key points for user experience optimization and accessibility support, helping developers use progress and result components efficiently and consistently in the Gradio ecosystem. + +## Project Structure + +- Component implementations reside in the frontend layer: each component has a Svelte entry file for property handling and slot rendering, and a TypeScript wrapper for interfacing with the native Ant Design component. +- Documentation and demos reside under docs/components/antd, providing component descriptions and runnable examples. +- The relationship between component entries and wrappers is shown in the following diagram: + +```mermaid +graph TB +subgraph "Frontend Implementation" +PIndex["progress/Index.svelte"] +PWrap["progress/progress.tsx"] +RIndex["result/Index.svelte"] +RWrap["result/result.tsx"] +end +subgraph "Third-party Library" +AntD["Ant Design Progress/Result"] +end +PIndex --> PWrap +RIndex --> RWrap +PWrap --> AntD +RWrap --> AntD +``` + +Diagram sources + +- [frontend/antd/progress/Index.svelte:1-64](file://frontend/antd/progress/Index.svelte#L1-L64) +- [frontend/antd/progress/progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [frontend/antd/result/Index.svelte:1-64](file://frontend/antd/result/Index.svelte#L1-L64) +- [frontend/antd/result/result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) + +Section sources + +- [frontend/antd/progress/Index.svelte:1-64](file://frontend/antd/progress/Index.svelte#L1-L64) +- [frontend/antd/progress/progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [frontend/antd/result/Index.svelte:1-64](file://frontend/antd/result/Index.svelte#L1-L64) +- [frontend/antd/result/result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) + +## Core Components + +- Progress + - Supports three shapes — line, circle, and dashboard (controlled via `type`) — and can add step segments (`steps`), info display toggle (`show_info`), and status color (`stroke_color`). + - Provides a percentage value (`percent`) and a format callback (`format`) for flexible text display control; supports a custom rounding function (`rounding`). + - Common statuses: default, active (`status='active'`), exception (`status='exception'`), success (`status='success'`). +- Result + - Used to display the final result of a series of operations, supporting success, info, warning, and error statuses. + - Supports title, sub_title, icon, and extra slots for extending buttons, links, or complex content. + +Section sources + +- [docs/components/antd/progress/README.md:1-8](file://docs/components/antd/progress/README.md#L1-L8) +- [docs/components/antd/result/README.md:1-8](file://docs/components/antd/result/README.md#L1-L8) +- [docs/components/antd/progress/demos/basic.py:1-39](file://docs/components/antd/progress/demos/basic.py#L1-L39) +- [docs/components/antd/result/demos/basic.py:1-57](file://docs/components/antd/result/demos/basic.py#L1-L57) + +## Architecture Overview + +The following diagram shows the call chain and slot passing mechanism from the Svelte entry to the native Ant Design component: + +```mermaid +sequenceDiagram +participant UI as "Page/Layout" +participant PIdx as "progress/Index.svelte" +participant PWrap as "progress/progress.tsx" +participant RIdx as "result/Index.svelte" +participant RWrap as "result/result.tsx" +participant Ant as "Ant Design Component" +UI->>PIdx : Pass props and slots +PIdx->>PIdx : Handle visibility/styles/additional props +PIdx->>PWrap : Render wrapper and pass through props +PWrap->>Ant : Call Ant Design Progress +Ant-->>UI : Render progress bar +UI->>RIdx : Pass props and slots +RIdx->>RIdx : Handle visibility/styles/additional props +RIdx->>RWrap : Render wrapper and pass through slots +RWrap->>Ant : Call Ant Design Result +Ant-->>UI : Render result panel +``` + +Diagram sources + +- [frontend/antd/progress/Index.svelte:10-61](file://frontend/antd/progress/Index.svelte#L10-L61) +- [frontend/antd/progress/progress.tsx:5-21](file://frontend/antd/progress/progress.tsx#L5-L21) +- [frontend/antd/result/Index.svelte:10-59](file://frontend/antd/result/Index.svelte#L10-L59) +- [frontend/antd/result/result.tsx:7-30](file://frontend/antd/result/result.tsx#L7-L30) + +## Detailed Component Analysis + +### Progress Component + +- Shapes and behavior + - Line progress bar: Default type, suitable for long-running tasks. + - Circle progress bar: `type="circle"`, suitable for emphasizing completion rate or as a card-level metric. + - Dashboard progress bar: `type="dashboard"`, suitable for threshold judgment and interval visualization. + - Step segments: The `steps` parameter splits the progress into multiple stages, commonly used for multi-stage tasks. +- Value display and formatting + - `percent` is the percentage input; `show_info` controls whether the number or status icon is displayed. + - The `format` callback can customize text content, such as showing "Done" text on completion. + - `rounding` allows customizing the rounding strategy for the percentage. +- Color and status + - `stroke_color` supports a single color or gradient array, coloring by step or overall. + - `status` controls the status color and animation: default, active, exception, success. +- Props and slots + - Props: percent, type, steps, stroke_color, status, show_info, format, rounding, etc. + - Slots: No built-in slots; text is mainly customized via `format`. +- Use cases + - File upload progress: Line progress bar showing real-time percentage, switching to success status on completion. + - Task execution status: Circle progress bar as a card-level metric; dashboard for threshold reminders. + - Multi-step flow: `steps` breaks down complex flows into multiple stages to improve perceived progress. + +```mermaid +flowchart TD +Start(["Start"]) --> SetType["Set type
type=linear/circle/dashboard"] +SetType --> SetPercent["Set percentage
percent"] +SetPercent --> ShowInfo{"Show info?"} +ShowInfo --> |Yes| FormatText["Format text
format callback"] +ShowInfo --> |No| SkipFormat["Skip text display"] +FormatText --> Color["Set color
stroke_color/status"] +SkipFormat --> Color +Color --> Steps{"Use steps?"} +Steps --> |Yes| StepSeg["Draw by step
steps"] +Steps --> |No| SingleSeg["Draw as whole"] +StepSeg --> Render["Render progress bar"] +SingleSeg --> Render +Render --> End(["End"]) +``` + +Diagram sources + +- [frontend/antd/progress/progress.tsx:5-21](file://frontend/antd/progress/progress.tsx#L5-L21) +- [docs/components/antd/progress/demos/basic.py:9-35](file://docs/components/antd/progress/demos/basic.py#L9-L35) + +Section sources + +- [frontend/antd/progress/progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [frontend/antd/progress/Index.svelte:10-61](file://frontend/antd/progress/Index.svelte#L10-L61) +- [docs/components/antd/progress/README.md:1-8](file://docs/components/antd/progress/README.md#L1-L8) +- [docs/components/antd/progress/demos/basic.py:1-39](file://docs/components/antd/progress/demos/basic.py#L1-L39) + +### Result Component + +- Status and semantics + - success: The operation completed successfully; encourage the user to proceed to the next step. + - info: Provides a neutral hint; guides the user to view details. + - warning: A risk or issue requiring attention; recommend the user confirm. + - error: The operation failed; the user needs to correct the issue and retry. +- Visual and content + - A title and sub_title clearly convey the result and context. + - The icon can be customized, combined with status colors to enhance recognition. + - The extra slot places action buttons, links, or supplementary notes. +- Props and slots + - Props: status, title, sub_title, icon, extra, etc. + - Slots: extra, icon, subTitle, title. +- Use cases + - Operation result feedback: A unified feedback interface after submitting a form or purchasing a service. + - Error diagnosis: Displaying the specific issue and repair guidance in an error state. + - Conversion guidance: Providing actions such as "Go to Console" or "Buy Again" after a success. + +```mermaid +sequenceDiagram +participant App as "Application" +participant R as "Result Component" +participant Slot as "Slot Content" +participant Ant as "Ant Design Result" +App->>R : Pass status/title/subTitle/icon +App->>Slot : Provide extra/icon/subTitle/title slots +R->>R : Parse slots and pass through to wrapper +R->>Ant : Render Result +Ant-->>App : Display result panel and action area +``` + +Diagram sources + +- [frontend/antd/result/result.tsx:7-30](file://frontend/antd/result/result.tsx#L7-L30) +- [frontend/antd/result/Index.svelte:10-59](file://frontend/antd/result/Index.svelte#L10-L59) + +Section sources + +- [frontend/antd/result/result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) +- [frontend/antd/result/Index.svelte:1-64](file://frontend/antd/result/Index.svelte#L1-L64) +- [docs/components/antd/result/README.md:1-8](file://docs/components/antd/result/README.md#L1-L8) +- [docs/components/antd/result/demos/basic.py:1-57](file://docs/components/antd/result/demos/basic.py#L1-L57) + +## Dependency Analysis + +- Component coupling and responsibilities + - The Svelte entry handles prop collection, visibility control, style concatenation, and slot parsing. + - The TypeScript wrapper interfaces with the Ant Design component, passing through props and callbacks (format, rounding). + - The slot system is implemented via ReactSlot and useTargets, ensuring dynamic rendering and fallback of slots. +- External dependencies + - Ant Design Progress/Result: Provides core UI and interaction behavior. + - @svelte-preprocess-react: Bridges React components with the Svelte context. + - @utils/hooks: Provides utility functions such as useFunction and useTargets. + +```mermaid +graph LR +PIdx["progress/Index.svelte"] --> PWrap["progress/progress.tsx"] +RIdx["result/Index.svelte"] --> RWrap["result/result.tsx"] +PWrap --> AntD["Ant Design Progress"] +RWrap --> AntD2["Ant Design Result"] +PWrap --> Hooks["@utils/hooks"] +RWrap --> Hooks +``` + +Diagram sources + +- [frontend/antd/progress/Index.svelte:1-64](file://frontend/antd/progress/Index.svelte#L1-L64) +- [frontend/antd/progress/progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [frontend/antd/result/Index.svelte:1-64](file://frontend/antd/result/Index.svelte#L1-L64) +- [frontend/antd/result/result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) + +Section sources + +- [frontend/antd/progress/progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [frontend/antd/result/result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) + +## Performance Considerations + +- Rendering overhead + - Progress bar: Line and circle rendering costs are similar; step segments (`steps`) increase path drawing times; it is recommended to reduce unnecessary re-renders in high-frequency update scenarios. + - Result: Content is relatively static; slot rendering is only triggered when content changes. +- Animation and smoothness + - Avoid complex computations when using the `format` callback; try to return lightweight strings. + - Circle/dashboard progress bars may impose GPU pressure at high refresh rates; use large circular progress bars with caution on mobile. +- Styles and theming + - When injecting styles via elem_style/elem_classes, prefer atomic classes or theme variables to reduce inline style jitter. + +## Troubleshooting Guide + +- Slots not working + - Confirm slot names are correct (extra, icon, subTitle, title), and that slots are explicitly passed through in the wrapper. + - If no slot content is provided, the wrapper will fall back to the corresponding prop field. +- Percentage not updating + - Ensure the `percent` prop updates as data changes; avoid expensive computations in `format` that cause lag. + - If custom rounding is needed, check the input/output types and boundary values of the `rounding` function. +- Status color anomaly + - When `status` and `stroke_color` are used simultaneously, note the status priority and color override order. + - When `steps` is an array, ensure its length matches the number of stages to avoid out-of-bounds errors. +- Accessibility + - Provide semantic labels and screen-reader-friendly text for key states (success/error). + - Provide alternative descriptions for invisible text in circle progress bars to ensure assistive technologies can understand the progress meaning. + +Section sources + +- [frontend/antd/result/result.tsx:10-30](file://frontend/antd/result/result.tsx#L10-L30) +- [frontend/antd/progress/progress.tsx:9-21](file://frontend/antd/progress/progress.tsx#L9-L21) + +## Conclusion + +The Progress and Result components in the Gradio ecosystem fulfill the dual responsibilities of "process visibility" and "result feedback". Through Ant Design's mature capabilities and this project's Svelte wrapper, developers can obtain a consistent, extensible, and customizable progress and result experience at minimal cost. It is recommended to choose the appropriate shape and status based on your business scenario in practice, and to follow accessibility and performance best practices to improve user satisfaction and maintainability. + +## Appendix + +- Example references + - Progress basic demo: [docs/components/antd/progress/demos/basic.py:1-39](file://docs/components/antd/progress/demos/basic.py#L1-L39) + - Result basic demo: [docs/components/antd/result/demos/basic.py:1-57](file://docs/components/antd/result/demos/basic.py#L1-L57) +- Component documentation + - Progress documentation: [docs/components/antd/progress/README.md:1-8](file://docs/components/antd/progress/README.md#L1-L8) + - Result documentation: [docs/components/antd/result/README.md:1-8](file://docs/components/antd/result/README.md#L1-L8) diff --git a/.wiki/en/Ant Design Components/Feedback Components/Spin and Skeleton.md b/.wiki/en/Ant Design Components/Feedback Components/Spin and Skeleton.md new file mode 100644 index 00000000..42e492a3 --- /dev/null +++ b/.wiki/en/Ant Design Components/Feedback Components/Spin and Skeleton.md @@ -0,0 +1,327 @@ +# Spin and Skeleton + + +**Files referenced in this document** +- [frontend/antd/skeleton/skeleton.tsx](file://frontend/antd/skeleton/skeleton.tsx) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx) +- [frontend/antd/skeleton/button/skeleton.button.tsx](file://frontend/antd/skeleton/button/skeleton.button.tsx) +- [frontend/antd/skeleton/image/skeleton.image.tsx](file://frontend/antd/skeleton/image/skeleton.image.tsx) +- [frontend/antd/skeleton/input/skeleton.input.tsx](file://frontend/antd/skeleton/input/skeleton.input.tsx) +- [frontend/antd/skeleton/node/skeleton.node.tsx](file://frontend/antd/skeleton/node/skeleton.node.tsx) +- [frontend/antd/spin/spin.tsx](file://frontend/antd/spin/spin.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Common Use Cases and Best Practices](#appendix-common-use-cases-and-best-practices) + +## Introduction + +This document focuses on the loading skeleton component group, systematically explaining the implementation patterns, usage strategies, and UX design considerations for Skeleton and Spin in this repository. Topics covered include: + +- Skeleton placeholder types, animation effects, and content layout simulation +- Spin loading indicator size variations and state management +- Component property configuration, custom animations, and style customization +- Practical recommendations for common scenarios such as list loading, image placeholders, form loading, and page transitions +- Timing and transition effects for switching between skeleton and real content +- Performance optimization recommendations and network condition adaptation strategies + +## Project Structure + +The loading skeleton component group resides in the frontend Ant Design component layer, following a unified "adapter" wrapping pattern that bridges Ant Design's React components to the Svelte ecosystem via preprocessing tools, ensuring a consistent invocation experience within this project's component system. + +```mermaid +graph TB +subgraph "Antd Skeleton Sub-components" +SA["Skeleton.Avatar
avatar/skeleton.avatar.tsx"] +SB["Skeleton.Button
button/skeleton.button.tsx"] +SI["Skeleton.Image
image/skeleton.image.tsx"] +SIN["Skeleton.Input
input/skeleton.input.tsx"] +SN["Skeleton.Node
node/skeleton.node.tsx"] +end +SMain["Skeleton
skeleton.tsx"] +subgraph "Antd Loading Indicator" +SP["Spin
spin.tsx"] +end +SMain --> SA +SMain --> SB +SMain --> SI +SMain --> SIN +SMain --> SN +``` + +Diagram sources + +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) +- [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) +- [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) +- [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) +- [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) + +Section sources + +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) +- [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) +- [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) +- [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) +- [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) + +## Core Components + +- Skeleton + - Main entry: Bridges Ant Design's Skeleton component to the Svelte environment in a unified way + - Sub-components: Avatar, Button, Image, Input, Node — each corresponding to a placeholder skeleton for a different element type +- Spin + - Main entry: Bridges Ant Design's Spin component to the Svelte environment in a unified way, with support for slottable `tip` and `indicator` customization + +Section sources + +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) +- [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) +- [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) +- [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) +- [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) + +## Architecture Overview + +The overall architecture uses a combination of "adapter + slots": + +- Adapter: The unified `sveltify` tool bridges Ant Design's React components as Svelte-usable components +- Slottable: Spin supports `tip` and `indicator` slots for custom tip text and indicator styles +- Target selection: Spin internally converts children into a locatable set of targets via a target selection hook, ensuring correct wrapping logic + +```mermaid +sequenceDiagram +participant U as "User Code" +participant S as "Spin Component" +participant Hook as "useTargets Hook" +participant AD as "Antd Spin" +U->>S : Pass children and props +S->>Hook : useTargets(children) +Hook-->>S : Return target set +S->>AD : Render Antd Spin(props, slots) +AD-->>U : Display loading indicator (with optional custom tip/indicator) +``` + +Diagram sources + +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) + +Section sources + +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) + +## Detailed Component Analysis + +### Skeleton Component Family + +- Design goals + - Provide stable content layout placeholders before data is ready, avoiding page jumps and layout jitter + - Improve perceived speed and usability by simulating real content with appropriate animations and shapes +- Placeholder types + - Avatar: Avatar placeholder + - Button: Button placeholder + - Image: Image placeholder + - Input: Input field placeholder + - Node: General-purpose node placeholder +- Animation and layout + - Based on Ant Design's Skeleton animation mechanism, typically manifests as a shimmer (gradient flash) effect + - Simulate complex layouts such as text, cards, and lists by setting different shapes (circle/square/rectangle) and row counts +- Usage recommendations + - List loading: Prefer Node or multiple Input rows to simulate list items + - Image placeholders: Use Image with dimensions matching the real image + - Form loading: Use Input/Button to simulate fields and action areas + - Page transitions: Wrap the container with Skeleton during route transitions to reduce the perception of a white screen + +```mermaid +classDiagram +class Skeleton { ++Main Entry +} +class SkeletonAvatar { ++Avatar Placeholder +} +class SkeletonButton { ++Button Placeholder +} +class SkeletonImage { ++Image Placeholder +} +class SkeletonInput { ++Input Placeholder +} +class SkeletonNode { ++General Node Placeholder +} +Skeleton --> SkeletonAvatar : "Contains" +Skeleton --> SkeletonButton : "Contains" +Skeleton --> SkeletonImage : "Contains" +Skeleton --> SkeletonInput : "Contains" +Skeleton --> SkeletonNode : "Contains" +``` + +Diagram sources + +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) +- [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) +- [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) +- [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) +- [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) + +Section sources + +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) +- [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) +- [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) +- [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) +- [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) + +### Spin Component + +- Design goals + - Provide clear feedback during async operations to prevent users from thinking the page is unresponsive + - Supports custom tip text and indicator to meet the visual needs of different scenarios +- Key features + - Slottable: Supports `tip` and `indicator` slots for injecting custom text and icons + - Target selection: Internally converts children into a target set via a target selection hook, ensuring correct wrapping logic + - Prop passthrough: All props are passed directly to Ant Design's Spin except for additional extensions +- Usage recommendations + - List loading: Use Spin as the list container with children as list items; `tip` indicates "Loading" + - Image placeholder: Wrap images with Spin before they finish loading; use a simple rotating icon for `indicator` + - Form submission: Disable interactions and display Spin during submission; `tip` indicates "Submitting" + - Page transitions: Wrap the entire page with Spin during route transitions to provide global loading feedback + +```mermaid +flowchart TD +Start(["Enter Spin render"]) --> Targets["useTargets(children)
Resolve target set"] +Targets --> HasTargets{"Targets exist?"} +HasTargets --> |No| HideChildren["Hide children (render placeholder only)"] +HasTargets --> |Yes| ShowChildren["Show children"] +HideChildren --> RenderAD["Render Antd Spin(props, slots)"] +ShowChildren --> RenderAD +RenderAD --> End(["End"]) +``` + +Diagram sources + +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) + +Section sources + +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) + +## Dependency Analysis + +- Component coupling + - The Skeleton family all depend on Ant Design's Skeleton implementation, bridged via sveltify + - Spin depends on Ant Design's Spin implementation, and introduces a target selection hook and ReactSlot slot mechanism +- External dependencies + - @svelte-preprocess-react: Provides sveltify and ReactSlot capabilities + - Ant Design: Provides the concrete implementations of Skeleton and Spin +- Potential issues + - Slot names and prop naming must be consistent with Ant Design to avoid runtime errors + - Target selection logic must ensure the children structure is reasonable to avoid wrapping anomalies + +```mermaid +graph LR +Spin["Spin Component"] --> AD_Spin["Antd Spin"] +Spin --> RS["ReactSlot"] +Spin --> UT["useTargets Hook"] +Skeleton["Skeleton Component"] --> AD_Skeleton["Antd Skeleton"] +Skeleton --> SA["Skeleton.Avatar"] +Skeleton --> SB["Skeleton.Button"] +Skeleton --> SI["Skeleton.Image"] +Skeleton --> SIN["Skeleton.Input"] +Skeleton --> SN["Skeleton.Node"] +``` + +Diagram sources + +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) +- [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) +- [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) +- [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) +- [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) + +Section sources + +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) + +## Performance Considerations + +- Skeleton rendering cost + - The number and depth of skeleton placeholder elements should approximate the real content to avoid excessive rendering causing lag + - For long lists, use Skeleton.Node or a small number of input rows as placeholders to reduce DOM count +- Loading indicator feedback + - Spin's `tip` and `indicator` should be as lightweight as possible to avoid additional repaints and reflows + - In high-frequency refresh scenarios, it is recommended to use throttling or debouncing to control the frequency of loading state transitions +- Network condition adaptation + - For poor network conditions, it is recommended to extend the Skeleton display time threshold to avoid frequent flickering + - For high-latency scenarios, Spin's `tip` text should clearly inform the user why they are waiting (e.g., "Connecting to server") + +## Troubleshooting Guide + +- Issue: Spin cannot correctly wrap children + - Debug: Confirm whether children have a recognizable target structure; check the return value of useTargets + - Reference implementation: [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- Issue: tip/indicator slots not working + - Debug: Confirm slot names are `tip` and `indicator`; ensure the slots object has the corresponding keys + - Reference implementation: [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- Issue: Skeleton sub-component style anomalies + - Debug: Confirm sub-components are correctly importing the corresponding Ant Design modules; check theme and style overrides + - Reference implementations: + - [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) + - [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) + - [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) + - [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) + - [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) + - [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) + +Section sources + +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) +- [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) +- [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) +- [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) +- [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) + +## Conclusion + +The loading skeleton component group in this repository achieves seamless integration of Ant Design Skeleton and Spin through a unified adapter and slottable design. In practice, the appropriate skeleton type and loading indicator form should be chosen based on the business scenario, and props and slots should be used for customization to meet branding and interaction needs. At the same time, pay attention to rendering performance and network condition adaptation to ensure a consistent, smooth user experience across different devices and environments. + +## Appendix: Common Use Cases and Best Practices + +- List loading + - Use Skeleton.Node or multiple Input rows to simulate list item placeholders + - Wrap the list container with Spin; `tip` indicates "Loading", `indicator` uses the default spinning icon +- Image placeholder + - Use Skeleton.Image to simulate image dimensions and placeholders + - When an image fails to load, switch to a skeleton placeholder or error hint +- Form loading + - Use Skeleton.Input and Skeleton.Button to simulate input fields and action areas + - Disable interactions and display Spin during submission; `tip` indicates "Submitting" +- Page transitions + - During route transitions, wrap the page body with Skeleton to reduce the perception of a white screen + - For high-latency scenarios, Spin's `tip` text should clearly inform the user why they are waiting diff --git a/.wiki/en/Ant Design Components/Feedback Components/Watermark.md b/.wiki/en/Ant Design Components/Feedback Components/Watermark.md new file mode 100644 index 00000000..c4429c60 --- /dev/null +++ b/.wiki/en/Ant Design Components/Feedback Components/Watermark.md @@ -0,0 +1,434 @@ +# Watermark + + +**Files referenced in this document** +- [watermark.tsx](file://frontend/antd/watermark/watermark.tsx) +- [Index.svelte](file://frontend/antd/watermark/Index.svelte) +- [__init__.py](file://backend/modelscope_studio/components/antd/watermark/__init__.py) +- [watermark-wBOVRUhz.js](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js) +- [basic.py](file://docs/components/antd/watermark/demos/basic.py) +- [modal_or_drawer.py](file://docs/components/antd/watermark/demos/modal_or_drawer.py) +- [README.md](file://docs/components/antd/watermark/README.md) +- [README-zh_CN.md](file://docs/components/antd/watermark/README-zh_CN.md) +- [app.py](file://docs/components/antd/watermark/app.py) +- [component.py](file://backend/modelscope_studio/utils/dev/component.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +The Watermark component is used to overlay text or image watermarks on a page or container, commonly used for copyright protection, version identification, customer differentiation, and similar scenarios. The Watermark component in this repository is based on Ant Design's Watermark implementation and is used within the Gradio ecosystem through a Svelte/React bridge layer. + +- Features + - Text watermark: Supports single-line or multi-line text watermarks. + - Image watermark: Supports a custom image as the watermark source. + - Position and layout: Controls repetition and arrangement through width, height, gap, and offset parameters. + - Rotation and scaling: Supports rotation angle and scale configuration. + - Opacity and z-index: Supports opacity and z-index control. + - Embedded usage: Can wrap any child element and automatically takes effect as the container changes. + - Event binding: Supports removal event binding for dynamic control. + +- Application scenarios + - Copyright protection: Add a "Copyright Protected" watermark to preview images or reports. + - Version identification: Add a "DEVELOPMENT" or "TEST" watermark in development/test environments. + - Customer differentiation: Add a dedicated watermark per customer or tenant for identification and auditing. + - Sensitive data protection: Add a watermark on export or display interfaces to reduce the risk of inadvertent propagation. + +- Implementation principles + - Frontend bridge: Wraps Ant Design's Watermark component as a Svelte-usable component via `sveltify`. + - Prop passthrough: Merges Gradio props (such as elem_id, elem_classes, elem_style, visible) with additional props and passes them to the underlying component. + - Render control: Controls whether to render based on `visible`; supports slots and children. + - Backend encapsulation: The Python layer provides the AntdWatermark class, carrying props and declaring the frontend directory mapping, while also declaring event listeners. + +- Usage notes + - Text and image: Set via `content` or `image` parameters; multi-line text can use array form. + - Repeat pattern: Control repetition and offset via width, height, gap, and offset. + - Rotation and scaling: `rotate` controls the angle; `z_index` controls the z-index. + - Dynamic updates: Watermark content and styles can be dynamically switched via Gradio's update mechanism. + - Style customization: Extend styles via elem_style, elem_classes, and additional props. + +**Section sources** + +- [README.md:1-9](file://docs/components/antd/watermark/README.md#L1-L9) +- [README-zh_CN.md:1-9](file://docs/components/antd/watermark/README-zh_CN.md#L1-L9) + +## Project Structure + +The organization of the Watermark component in the repository is as follows: + +- Frontend + - Svelte wrapper layer: Index.svelte handles prop processing, visibility control, and child node rendering. + - React bridge layer: watermark.tsx wraps Ant Design's Watermark as a Svelte component using `sveltify`. + - Runtime template: watermark-wBOVRUhz.js is the component runtime template, responsible for React component mounting and bridging logic. +- Backend + - Python encapsulation: The AntdWatermark class carries props and events, and declares the frontend directory mapping. +- Examples and documentation + - Basic example: basic.py demonstrates the basic usage of text and image watermarks. + - Dialog example: modal_or_drawer.py demonstrates how to use watermarks inside Modal/Drawer. + - Documentation pages: README/README-zh_CN.md provides example placeholders and links. + +```mermaid +graph TB +subgraph "Frontend" +IDX["Index.svelte
Prop handling and render control"] +WRAP["watermark.tsx
sveltify wrapper"] +RT["watermark-wBOVRUhz.js
Runtime template and bridge"] +end +subgraph "Backend" +PY["__init__.py
AntdWatermark class and props"] +DEV["component.py
ModelScopeLayoutComponent base class"] +end +subgraph "Examples and Documentation" +DEMO1["basic.py"] +DEMO2["modal_or_drawer.py"] +DOC["README.md / README-zh_CN.md"] +end +IDX --> WRAP --> RT +PY --> IDX +PY --> WRAP +PY --> RT +DEV --> PY +DEMO1 --> PY +DEMO2 --> PY +DOC --> DEMO1 +DOC --> DEMO2 +``` + +**Diagram sources** + +- [Index.svelte:1-64](file://frontend/antd/watermark/Index.svelte#L1-L64) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [watermark-wBOVRUhz.js:1-442](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js#L1-L442) +- [**init**.py:1-83](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L1-L83) +- [component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [basic.py:1-23](file://docs/components/antd/watermark/demos/basic.py#L1-L23) +- [modal_or_drawer.py:1-30](file://docs/components/antd/watermark/demos/modal_or_drawer.py#L1-L30) +- [README.md:1-9](file://docs/components/antd/watermark/README.md#L1-L9) +- [README-zh_CN.md:1-9](file://docs/components/antd/watermark/README-zh_CN.md#L1-L9) + +**Section sources** + +- [Index.svelte:1-64](file://frontend/antd/watermark/Index.svelte#L1-L64) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [watermark-wBOVRUhz.js:1-442](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js#L1-L442) +- [**init**.py:1-83](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L1-L83) +- [component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [README.md:1-9](file://docs/components/antd/watermark/README.md#L1-L9) +- [README-zh_CN.md:1-9](file://docs/components/antd/watermark/README-zh_CN.md#L1-L9) + +## Core Components + +- AntdWatermark (Backend) + - Responsibility: Carries the watermark component's props and events, declares the frontend directory mapping, and skips API calls. + - Key props (from constructor): content, width, height, inherit, rotate, z_index, image, font, gap, offset, root_class_name, etc. + - Events: remove (binds the removal event). + - Other: `skip_api` returns True, indicating this component does not participate in the standard API flow. + +- Watermark (Frontend Bridge) + - Responsibility: Wraps Ant Design's Watermark component as a Svelte component via `sveltify` for use in Gradio. + - Behavior: Directly exports Watermark as the default export. + +- Index.svelte (Frontend Wrapper) + - Responsibility: Handles Gradio props (elem_id, elem_classes, elem_style, visible), merges additional props, and controls visibility and child node rendering. + - Behavior: When `visible` is true, asynchronously loads Watermark and renders it; supports slots and children. + +- Runtime template (watermark-wBOVRUhz.js) + - Responsibility: Provides React component bridging, context merging, Portal rendering, and effect registration to ensure the component is correctly mounted and updated in the browser environment. + +**Section sources** + +- [**init**.py:8-83](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L8-L83) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [Index.svelte:1-64](file://frontend/antd/watermark/Index.svelte#L1-L64) +- [watermark-wBOVRUhz.js:330-442](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js#L330-L442) + +## Architecture Overview + +The following diagram shows the overall call chain and responsibilities from Python to the frontend and then to the runtime: + +```mermaid +sequenceDiagram +participant Py as "Python Backend
AntdWatermark" +participant Wrap as "Frontend Wrapper
Index.svelte" +participant Bridge as "Bridge Layer
watermark.tsx" +participant Runtime as "Runtime Template
watermark-wBOVRUhz.js" +Py->>Wrap : "Declare component and props" +Wrap->>Bridge : "Import and wrap Watermark" +Bridge->>Runtime : "Create React component instance" +Runtime-->>Wrap : "Return renderable React component" +Wrap-->>Py : "Render or hide based on visible" +``` + +**Diagram sources** + +- [**init**.py:66-66](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L66-L66) +- [Index.svelte:10-63](file://frontend/antd/watermark/Index.svelte#L10-L63) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [watermark-wBOVRUhz.js:330-442](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js#L330-L442) + +## Detailed Component Analysis + +### Props and Configuration + +- Text watermark + - content: A string or array of strings for setting watermark text; supports multi-line text. + - font: Font-related configuration (e.g., color, font size), supported by the underlying Ant Design. +- Image watermark + - image: An image URL for setting the image watermark source. +- Repetition and layout + - width, height: The width and height of the watermark unit. + - gap: The horizontal and vertical spacing between watermarks. + - offset: The initial offset of the watermark (typically used to control the starting position). +- Rotation and scaling + - rotate: Watermark rotation angle. + - inherit: Whether to inherit parent styles. +- Z-index and opacity + - z_index: Watermark z-index. + - Other styles: Control opacity, background, etc. via elem_style and elem_classes. +- Other + - root_class_name: Root node class name prefix. + - additional_props: Extra prop passthrough. + +- Dynamic updates and style customization + - visible: Controls whether the component is rendered. + - elem_id, elem_classes, elem_style: Used for positioning and style customization. + - slots and children: Supports slot and child node rendering. + +**Section sources** + +- [**init**.py:50-64](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L50-L64) +- [Index.svelte:21-44](file://frontend/antd/watermark/Index.svelte#L21-L44) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) + +### Usage Flow and Examples + +- Basic text watermark + - Nest Watermark inside a container and set `content` to a string or array. + - Reference example: basic.py. +- Image watermark + - Set `image` to an image URL; use width and height to control watermark dimensions. + - Reference example: basic.py. +- Usage inside dialogs/drawers + - Wrap Modal/Drawer with Watermark to achieve watermark coverage inside the dialog. + - Reference example: modal_or_drawer.py. + +```mermaid +sequenceDiagram +participant Demo as "Example Script
basic.py / modal_or_drawer.py" +participant Py as "AntdWatermark
Backend" +participant Wrap as "Index.svelte" +participant Bridge as "watermark.tsx" +participant RT as "watermark-wBOVRUhz.js" +Demo->>Py : "Create Watermark component and pass props" +Py->>Wrap : "Declare component and props" +Wrap->>Bridge : "Import and wrap" +Bridge->>RT : "Create React instance" +RT-->>Wrap : "Return renderable component" +Wrap-->>Demo : "Render result" +``` + +**Diagram sources** + +- [basic.py:1-23](file://docs/components/antd/watermark/demos/basic.py#L1-L23) +- [modal_or_drawer.py:1-30](file://docs/components/antd/watermark/demos/modal_or_drawer.py#L1-L30) +- [**init**.py:8-83](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L8-L83) +- [Index.svelte:50-63](file://frontend/antd/watermark/Index.svelte#L50-L63) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [watermark-wBOVRUhz.js:330-442](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js#L330-L442) + +**Section sources** + +- [basic.py:1-23](file://docs/components/antd/watermark/demos/basic.py#L1-L23) +- [modal_or_drawer.py:1-30](file://docs/components/antd/watermark/demos/modal_or_drawer.py#L1-L30) + +### Events and Lifecycle + +- remove event + - Bound via event listeners; can be used to remove the watermark when needed. + - The event callback updates internal state to enable the removal behavior. + +**Section sources** + +- [**init**.py:12-16](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L12-L16) + +### Class Relationship Diagram + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__init__() ++__exit__() +} +class AntdWatermark { ++EVENTS ++content ++width ++height ++inherit ++rotate ++z_index ++image ++font ++gap ++offset ++root_class_name ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +ModelScopeLayoutComponent <|-- AntdWatermark +``` + +**Diagram sources** + +- [component.py:11-127](file://backend/modelscope_studio/utils/dev/component.py#L11-L127) +- [**init**.py:8-83](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L8-L83) + +## Dependency Analysis + +- Component coupling + - AntdWatermark depends on the frontend directory mapping and runtime template to ensure correct rendering in the browser. + - Index.svelte depends on the wrapper layer and runtime template, responsible for prop processing and visibility control. + - watermark.tsx is responsible only for bridging, with low coupling, making it easy to maintain. +- External dependencies + - Ant Design Watermark: Underlying implementation. + - Svelte/React bridge tools: sveltify, @svelte-preprocess-react, etc. +- Potential issues + - If FRONTEND_DIR is not set correctly, it may cause frontend resources to fail to load. + - When `visible` is false, the component is not rendered; be aware of side effects when dynamically toggling. + +```mermaid +graph LR +PY["AntdWatermark
Backend"] --> IDX["Index.svelte
Frontend Wrapper"] +IDX --> WRAP["watermark.tsx
Bridge"] +WRAP --> RT["watermark-wBOVRUhz.js
Runtime Template"] +PY --> AD["Ant Design Watermark
External Dependency"] +``` + +**Diagram sources** + +- [**init**.py:66-66](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L66-L66) +- [Index.svelte:10-10](file://frontend/antd/watermark/Index.svelte#L10-L10) +- [watermark.tsx:1-1](file://frontend/antd/watermark/watermark.tsx#L1-L1) +- [watermark-wBOVRUhz.js:330-330](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js#L330-L330) + +**Section sources** + +- [**init**.py:66-66](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L66-L66) +- [Index.svelte:10-10](file://frontend/antd/watermark/Index.svelte#L10-L10) +- [watermark.tsx:1-1](file://frontend/antd/watermark/watermark.tsx#L1-L1) +- [watermark-wBOVRUhz.js:330-330](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js#L330-L330) + +## Performance Considerations + +- Rendering overhead + - Watermarks are essentially a background layer overlaid on a container, with minimal impact on the rendering of main content; however, a large number of repeating units may increase painting costs. +- Repaint and reflow + - Frequently changing props such as content, image, rotate, and z_index may trigger repaints; it is recommended to batch updates or reduce change frequency. +- Image watermark + - Image loading and decoding incur additional overhead; use appropriately sized and formatted images to avoid large images causing lag. +- Visibility control + - Controlling render timing via `visible` can effectively reduce unnecessary overhead. +- Recommendations + - Set width, height, and gap reasonably to avoid overly dense repetition. + - For frequently toggled scenarios, prioritize caching and throttling strategies. + - When using inside dialogs/drawers, pay attention to the rendering timing during dialog open/close. + +[This section provides general performance recommendations and does not require specific file sources] + +## Troubleshooting Guide + +- Watermark not displayed + - Check if `visible` is true; confirm props are correctly passed through to the component. + - Confirm FRONTEND_DIR correctly points to the frontend directory. +- Image watermark not displayed + - Check if the `image` URL is accessible; confirm image dimensions and format are reasonable. + - Adjust width and height to fit the container. +- Rotation or z-index anomaly + - Check that `rotate` and `z_index` settings match expectations; confirm no other styles are overriding them. +- Dynamic updates not working + - Confirm the update logic is correct; use a re-render strategy if necessary. +- Events not working + - Confirm the `remove` event has been bound; check that the event callback is executing correctly. + +**Section sources** + +- [Index.svelte:50-63](file://frontend/antd/watermark/Index.svelte#L50-L63) +- [**init**.py:66-66](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L66-L66) + +## Conclusion + +The Watermark component provides flexible watermarking capabilities in the Gradio ecosystem through a concise prop system and a stable bridging mechanism. It supports text and image watermarks, repeat layouts, rotation and scaling, and z-index control, applicable to a variety of scenarios including copyright protection, version identification, and customer differentiation. Combined with visibility control and event binding, a dynamic and maintainable watermarking solution can be achieved. + +[This section is a summary and does not require specific file sources] + +## Appendix + +### Common Use Case Example Paths + +- Copyright protection: Add a "Copyright Protected" text or image watermark to preview image or report containers. +- Version identification: Add a "DEVELOPMENT" or "TEST" watermark in development/test environments. +- Customer differentiation: Add a dedicated watermark per customer or tenant for identification and auditing. +- Export protection: Add a watermark on export interfaces or print preview to reduce the risk of inadvertent propagation. + +**Section sources** + +- [basic.py:1-23](file://docs/components/antd/watermark/demos/basic.py#L1-L23) +- [modal_or_drawer.py:1-30](file://docs/components/antd/watermark/demos/modal_or_drawer.py#L1-L30) + +### Quick Reference for Props + +- Text watermark: content (string or array), font +- Image watermark: image, width, height +- Repetition and layout: gap, offset +- Rotation and z-index: rotate, z_index +- Styles and visibility: elem_style, elem_classes, elem_id, visible +- Other: root_class_name, additional_props + +**Section sources** + +- [**init**.py:50-64](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L50-L64) +- [Index.svelte:21-44](file://frontend/antd/watermark/Index.svelte#L21-L44) + +### Security and Anti-tampering Recommendations + +- Trustworthy content sources: Ensure content and image come from trusted sources to avoid injecting malicious content. +- Access control: Restrict modification permissions for the watermark component to prevent it from being bypassed or removed. +- Audit logging: Record watermark change logs for tracking and auditing. +- Principle of least privilege: Grant only the necessary watermark configuration permissions to avoid over-authorization. + +[This section provides general security recommendations and does not require specific file sources] + +### Accessibility and Screen Reader Compatibility + +- Text watermark + - Ensure text semantics are clear; avoid using decorative text. + - Provide alternative text or titles for key information. +- Image watermark + - Provide descriptive alt text for image watermarks to help screen readers identify them. +- Interaction and focus + - Watermarks should not interfere with user operations; ensure focusable elements are not obscured. +- Styles and contrast + - Ensure the watermark has sufficient contrast with the background to avoid affecting readability. +- Accessibility testing + - Test with screen readers and keyboard navigation to verify the accessibility experience. + +[This section provides general accessibility recommendations and does not require specific file sources] diff --git a/.wiki/en/Ant Design Components/General Components/Button.md b/.wiki/en/Ant Design Components/General Components/Button.md new file mode 100644 index 00000000..140f9ce8 --- /dev/null +++ b/.wiki/en/Ant Design Components/General Components/Button.md @@ -0,0 +1,312 @@ +# Button + + +**Files referenced in this document** +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/button/group/button.group.tsx](file://frontend/antd/button/group/button.group.tsx) +- [frontend/antd/button/group/Index.svelte](file://frontend/antd/button/group/Index.svelte) +- [backend/modelscope_studio/components/antd/button/__init__.py](file://backend/modelscope_studio/components/antd/button/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [docs/components/antd/button/README-zh_CN.md](file://docs/components/antd/button/README-zh_CN.md) +- [docs/components/antd/button/demos/basic.py](file://docs/components/antd/button/demos/basic.py) +- [docs/components/antd/button/app.py](file://docs/components/antd/button/app.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document systematically introduces the Button component, covering its core functionality, property configuration, and event handling mechanism. It focuses on explaining configuration items such as type (variant), size, and state; explains the usage and layout control of button groups; provides example paths for various scenarios (such as basic buttons, icon buttons, ghost buttons, dashed buttons, etc.); elaborates on handling special states like disabled, loading, and danger; explains style customization, theme adaptation, and responsive design points; and provides best practice recommendations for accessibility and keyboard navigation. + +## Project Structure + +The Button component consists of backend Python component class and frontend Svelte/React wrapper layer, following Gradio ecosystem's "component as context" pattern, supporting custom rendering of icons and loading state icons through the Slot mechanism. + +```mermaid +graph TB +subgraph "Backend" +PY_BTN["AntdButton
Python Component Class"] +PY_GROUP["AntdButtonGroup
Python Component Class"] +end +subgraph "Frontend" +IDX["Index.svelte
Component Entry"] +BTN["button.tsx
React Wrapper"] +SLOT["Slot Processing
icon / loading.icon"] +GROUP_IDX["group/Index.svelte
Button Group Entry"] +GROUP_BTN["group/button.group.tsx
Antd Button.Group Wrapper"] +end +PY_BTN --> IDX +PY_GROUP --> GROUP_IDX +IDX --> BTN +GROUP_IDX --> GROUP_BTN +BTN --> SLOT +``` + +Diagram Source + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-138](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L138) +- [frontend/antd/button/Index.svelte:10-73](file://frontend/antd/button/Index.svelte#L10-L73) +- [frontend/antd/button/button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) +- [frontend/antd/button/group/Index.svelte:10-61](file://frontend/antd/button/group/Index.svelte#L10-L61) +- [frontend/antd/button/group/button.group.tsx:6-24](file://frontend/antd/button/group/button.group.tsx#L6-L24) + +Section Source + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-138](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L138) +- [frontend/antd/button/Index.svelte:10-73](file://frontend/antd/button/Index.svelte#L10-L73) +- [frontend/antd/button/button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) +- [frontend/antd/button/group/Index.svelte:10-61](file://frontend/antd/button/group/Index.svelte#L10-L61) +- [frontend/antd/button/group/button.group.tsx:6-24](file://frontend/antd/button/group/button.group.tsx#L6-L24) + +## Core Components + +- Backend Component Class: AntdButton provides all property and event definitions for buttons, supporting type, variant, size, color, shape, state, and other configurations, and declares supported slots (icon, loading.icon). +- Frontend Wrapper Layer: Index.svelte maps Python properties to React components, injecting styles and IDs; button.tsx uses sveltify to wrap Ant Design's Button, parsing and passing slots. +- Button Group: AntdButtonGroup corresponds to the frontend Button.Group wrapper, supporting group-level styles and theme variable injection. + +Section Source + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-138](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L138) +- [frontend/antd/button/Index.svelte:10-73](file://frontend/antd/button/Index.svelte#L10-L73) +- [frontend/antd/button/button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) +- [frontend/antd/button/group/Index.svelte:10-61](file://frontend/antd/button/group/Index.svelte#L10-L61) +- [frontend/antd/button/group/button.group.tsx:6-24](file://frontend/antd/button/group/button.group.tsx#L6-L24) + +## Architecture Overview + +The diagram below shows the call chain from Python component to frontend rendering, and the processing flow of Slot in loading state and icon state. + +```mermaid +sequenceDiagram +participant Py as "Python : AntdButton" +participant Svelte as "Svelte : Index.svelte" +participant Wrap as "React : button.tsx" +participant AD as "Antd : Button" +participant Slot as "Slot Resolution" +Py->>Svelte : Pass properties and values +Svelte->>Wrap : Render React wrapper component +Wrap->>AD : Pass props including icon, loading +Wrap->>Slot : Parse slots.icon / slots["loading.icon"] +Slot-->>Wrap : Return React node +Wrap-->>AD : Inject icon/loading icon +AD-->>Svelte : Render final button +``` + +Diagram Source + +- [frontend/antd/button/button.tsx:11-36](file://frontend/antd/button/button.tsx#L11-L36) +- [frontend/antd/button/Index.svelte:59-73](file://frontend/antd/button/Index.svelte#L59-L73) +- [backend/modelscope_studio/components/antd/button/**init**.py:41-49](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L49) + +## Detailed Component Analysis + +### Properties and Configuration + +- Type and Variant + - type: Supports primary, dashed, link, text, default + - variant: Supports outlined, dashed, solid, filled, text, link + - color: Supports default, primary, danger and a set of preset color names +- Size and Shape + - size: large, middle, small + - shape: default, circle, round +- State and Behavior + - disabled: Disabled state + - danger: Danger state + - ghost: Ghost button (transparent background) + - loading: Boolean or loading object with delay + - block: Block-level width + - html_type: button, submit, reset + - href/target: Link button and jump target +- Icon and Slots + - icon: Icon name or node + - loading.icon: Loading state custom icon +- Style and Identity + - elem_id, elem_classes, elem_style + - class_names, styles, root_class_name + +Section Source + +- [backend/modelscope_studio/components/antd/button/**init**.py:51-138](file://backend/modelscope_studio/components/antd/button/__init__.py#L51-L138) +- [frontend/antd/button/button.tsx:18-30](file://frontend/antd/button/button.tsx#L18-L30) + +### Event Handling Mechanism + +- click event: Bound through event listener, when triggered can update internal state to drive UI changes. +- Typical Usage: In the example, register click callback for button to output logs or trigger business logic. + +Section Source + +- [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) +- [docs/components/antd/button/demos/basic.py:9-10](file://docs/components/antd/button/demos/basic.py#L9-L10) + +### Slots and Icon Processing + +- Slot Definition: icon, loading.icon +- Rendering Strategy: + - If slots.icon exists, render with ReactSlot and clone + - When loading.icon exists, use that node as loading icon and preserve loading.delay value (when loading is an object) + - If no slot, fall back to props.icon or props.loading + +```mermaid +flowchart TD +Start(["Enter rendering"]) --> HasIcon{"Does slots.icon exist?"} +HasIcon --> |Yes| RenderIcon["Render slots.icon (cloned)"] +HasIcon --> |No| UseIcon["Use props.icon"] +RenderIcon --> Next1["Continue processing loading"] +UseIcon --> Next1 +Next1 --> HasLoadIcon{"Does slots['loading.icon'] exist?"} +HasLoadIcon --> |Yes| BuildLoadObj["Build loading object
containing icon and delay"] +HasLoadIcon --> |No| UseLoad["Use props.loading"] +BuildLoadObj --> End(["Complete"]) +UseLoad --> End +``` + +Diagram Source + +- [frontend/antd/button/button.tsx:18-30](file://frontend/antd/button/button.tsx#L18-L30) + +Section Source + +- [frontend/antd/button/button.tsx:11-36](file://frontend/antd/button/button.tsx#L11-L36) + +### Button Group (Button.Group) + +- Component Entry: group/Index.svelte +- Wrapper Implementation: group/button.group.tsx +- Theme Adaptation: Injects CSS variables through Ant Design's theme.token.lineWidth, unifying in-group borders and spacing +- Applicable Scenarios: Multiple buttons combined arrangement, sharing the same theme style + +```mermaid +sequenceDiagram +participant Py as "Python : AntdButtonGroup" +participant Svelte as "Svelte : group/Index.svelte" +participant Wrap as "React : group/button.group.tsx" +participant AD as "Antd : Button.Group" +Py->>Svelte : Pass properties +Svelte->>Wrap : Render wrapper component +Wrap->>AD : Pass props and inject theme variables +AD-->>Svelte : Render button group +``` + +Diagram Source + +- [frontend/antd/button/group/Index.svelte:48-61](file://frontend/antd/button/group/Index.svelte#L48-L61) +- [frontend/antd/button/group/button.group.tsx:10-24](file://frontend/antd/button/group/button.group.tsx#L10-L24) + +Section Source + +- [frontend/antd/button/group/Index.svelte:10-61](file://frontend/antd/button/group/Index.svelte#L10-L61) +- [frontend/antd/button/group/button.group.tsx:6-24](file://frontend/antd/button/group/button.group.tsx#L6-L24) + +### Examples and Usage Scenarios + +The following examples are from documentation demo scripts, demonstrating button usage with different variants and states: + +- Basic Buttons: Primary button, default button, dashed button, text button, link button +- Variants and Colors: Filled variant combined with default/danger color +- Loading State and Icons: Setting icon slot in loading state +- Block Buttons: block=True makes button fill container width + +Example Path + +- [docs/components/antd/button/demos/basic.py:9-22](file://docs/components/antd/button/demos/basic.py#L9-L22) + +Section Source + +- [docs/components/antd/button/demos/basic.py:5-25](file://docs/components/antd/button/demos/basic.py#L5-L25) + +### Style Customization, Theme Adaptation and Responsive Design + +- Style Injection: Add custom styles for individual buttons or button groups through elem_id, elem_classes, elem_style +- Theme Variables: Button groups inject CSS variables through Ant Design theme tokens, ensuring consistent in-group borders +- Responsive: Combined with Flex/Space and other layout components, buttons can automatically wrap and align under different screen sizes + +Section Source + +- [frontend/antd/button/group/button.group.tsx:10-24](file://frontend/antd/button/group/button.group.tsx#L10-L24) +- [docs/components/antd/button/demos/basic.py](file://docs/components/antd/button/demos/basic.py#L8) + +### Accessibility and Keyboard Navigation + +- Keyboard Accessibility: Buttons natively support Enter/Space triggering, recommend providing clear focus indicators in complex interactions +- Text and Icons: Provide readable text alternatives for icon buttons (aria-label), avoid relying solely on icons to convey critical information +- Disabled and Loading States: Disabled and loading states should maintain visual consistency, ensuring users perceive the current non-interactive state +- Combined Buttons: In button groups, recommend providing clear grouping semantics, adding titles or dividers when necessary + +## Dependency Analysis + +- Component Registration: AntdButton and AntdButtonGroup are centrally exported in backend component collection, facilitating unified import and usage +- Component Base Class: ModelScopeLayoutComponent provides common layout capabilities and event hooks +- Frontend Bridge: Bridges Ant Design's React components to Svelte environment through sveltify while preserving Slot capabilities + +```mermaid +graph LR +Export["components.py Export"] --> Btn["AntdButton"] +Export --> BtnGroup["AntdButtonGroup"] +Btn --> Base["ModelScopeLayoutComponent"] +BtnGroup --> Base +``` + +Diagram Source + +- [backend/modelscope_studio/components/antd/components.py:14-15](file://backend/modelscope_studio/components/antd/components.py#L14-L15) +- [backend/modelscope_studio/utils/dev/component.py:11-27](file://backend/modelscope_studio/utils/dev/component.py#L11-L27) + +Section Source + +- [backend/modelscope_studio/components/antd/components.py:14-15](file://backend/modelscope_studio/components/antd/components.py#L14-L15) +- [backend/modelscope_studio/utils/dev/component.py:11-27](file://backend/modelscope_studio/utils/dev/component.py#L11-L27) + +## Performance Considerations + +- Button Group Theme Variable Injection: Token is calculated only once during group component initialization, avoiding repeated calculation overhead +- Slot Rendering: Prioritize using slots.icon and slots["loading.icon"], reducing unnecessary props passing +- Delayed Loading: loading object supports delay field, avoiding flicker caused by frequent switching + +Section Source + +- [frontend/antd/button/group/button.group.tsx:10-24](file://frontend/antd/button/group/button.group.tsx#L10-L24) +- [frontend/antd/button/button.tsx:21-29](file://frontend/antd/button/button.tsx#L21-L29) + +## Troubleshooting Guide + +- Slot Not Working + - Check whether ms.Slot("icon") or ms.Slot("loading.icon") is correctly used to wrap icon component + - Confirm slots are correctly passed in frontend +- Loading Icon Not Displaying + - Ensure slots["loading.icon"] exists and is a valid node + - When loading is an object, confirm whether delay field is set as expected +- Button Group Style Abnormal + - Check whether theme token is available, confirm CSS variables are injected +- Event Not Triggered + - Confirm click event listener is bound and callback function is executable + +Section Source + +- [frontend/antd/button/button.tsx:18-30](file://frontend/antd/button/button.tsx#L18-L30) +- [frontend/antd/button/group/button.group.tsx:10-24](file://frontend/antd/button/group/button.group.tsx#L10-L24) +- [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) + +## Conclusion + +The Button component in this project achieves complete wrapping of Ant Design, with rich type, variant, size, and state configurations, while flexibly supporting icon and loading state customization through the Slot mechanism. Button groups provide good extensibility in theme adaptation and layout control. Combined with example scripts and best practices, developers can quickly build button interactions that meet design specifications and accessibility requirements. + +## Appendix + +- Documentation Entry and Examples + - [docs/components/antd/button/README-zh_CN.md:1-8](file://docs/components/antd/button/README-zh_CN.md#L1-L8) + - [docs/components/antd/button/demos/basic.py:1-26](file://docs/components/antd/button/demos/basic.py#L1-L26) + - [docs/components/antd/button/app.py:1-7](file://docs/components/antd/button/app.py#L1-L7) diff --git a/.wiki/en/Ant Design Components/General Components/FloatButton.md b/.wiki/en/Ant Design Components/General Components/FloatButton.md new file mode 100644 index 00000000..cfaff72f --- /dev/null +++ b/.wiki/en/Ant Design Components/General Components/FloatButton.md @@ -0,0 +1,351 @@ +# FloatButton + + +**Files referenced in this document** +- [Index.svelte](file://frontend/antd/float-button/Index.svelte) +- [float-button.tsx](file://frontend/antd/float-button/float-button.tsx) +- [group/Index.svelte](file://frontend/antd/float-button/group/Index.svelte) +- [group/float-button.group.tsx](file://frontend/antd/float-button/group/float-button.group.tsx) +- [back-top/Index.svelte](file://frontend/antd/float-button/back-top/Index.svelte) +- [back-top/float-button.back-top.tsx](file://frontend/antd/float-button/back-top/float-button.back-top.tsx) +- [__init__.py](file://backend/modelscope_studio/components/antd/float_button/__init__.py) +- [README-zh_CN.md](file://docs/components/antd/float_button/README-zh_CN.md) +- [app.py](file://docs/components/antd/float_button/app.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +FloatButton is a "floating button" component used to provide globally accessible function entries at any position on the page. It is implemented based on Ant Design's FloatButton and presented as a unified component form in the model domain through Gradio frontend bridge layer. This component supports extension capabilities such as icons, description text, tooltip popups, and badge count; meanwhile, it provides two enhanced sub-features: "FloatButton Group" and "Back to Top", used for combining multiple actions and quickly returning to the top of the page respectively. + +Design Goals: + +- Remain visible at any scroll state on the page, improving user accessibility +- Provide flexible layout position and size control, meeting different page styles +- Support slot-based extensions (such as custom icons, descriptions, tooltips, badges) +- Collaborate with scroll containers and content areas to avoid blocking critical information +- Cover mobile and responsive scenarios, ensuring consistent interaction experience + +## Project Structure + +FloatButton component consists of backend Python component class and frontend Svelte/React wrapper layer, with documentation examples demonstrated through the docs layer. + +```mermaid +graph TB +subgraph "Backend" +PY["AntdFloatButton.__init__.py"] +end +subgraph "Frontend" +IDX["float-button/Index.svelte"] +CMP["float-button.tsx"] +GRP_IDX["float-button/group/Index.svelte"] +GRP_CMP["float-button/group/float-button.group.tsx"] +BT_IDX["float-button/back-top/Index.svelte"] +BT_CMP["float-button/back-top/float-button.back-top.tsx"] +end +subgraph "Documentation" +DOC_README["docs/.../float_button/README-zh_CN.md"] +DOC_APP["docs/.../float_button/app.py"] +end +PY --> IDX +PY --> GRP_IDX +PY --> BT_IDX +IDX --> CMP +GRP_IDX --> GRP_CMP +BT_IDX --> BT_CMP +DOC_README --> DOC_APP +``` + +Diagram Source + +- [**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [Index.svelte:1-70](file://frontend/antd/float-button/Index.svelte#L1-L70) +- [float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [group/Index.svelte:1-72](file://frontend/antd/float-button/group/Index.svelte#L1-L72) +- [group/float-button.group.tsx:1-70](file://frontend/antd/float-button/group/float-button.group.tsx#L1-L70) +- [back-top/Index.svelte:1-73](file://frontend/antd/float-button/back-top/Index.svelte#L1-L73) +- [back-top/float-button.back-top.tsx:1-47](file://frontend/antd/float-button/back-top/float-button.back-top.tsx#L1-L47) +- [README-zh_CN.md:1-8](file://docs/components/antd/float_button/README-zh_CN.md#L1-L8) +- [app.py:1-7](file://docs/components/antd/float_button/app.py#L1-L7) + +Section Source + +- [**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [README-zh_CN.md:1-8](file://docs/components/antd/float_button/README-zh_CN.md#L1-L8) +- [app.py:1-7](file://docs/components/antd/float_button/app.py#L1-L7) + +## Core Components + +- AntdFloatButton: Backend component class, declares events, slots, and properties, responsible for mapping frontend components to Gradio ecosystem. +- FloatButton: Frontend wrapper, interfaces with Ant Design's FloatButton, supporting slot injection and function-type callback handling. +- FloatButton.Group: Frontend wrapper, used to combine multiple floating buttons, supporting close icon, shape, theme variables, etc. +- FloatButton.BackTop: Frontend wrapper, provides "back to top" capability, supporting custom scroll container retrieval logic. + +Section Source + +- [**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [float-button.tsx:14-75](file://frontend/antd/float-button/float-button.tsx#L14-L75) +- [group/float-button.group.tsx:10-70](file://frontend/antd/float-button/group/float-button.group.tsx#L10-L70) +- [back-top/float-button.back-top.tsx:7-47](file://frontend/antd/float-button/back-top/float-button.back-top.tsx#L7-L47) + +## Architecture Overview + +The diagram below shows the overall call chain from backend component class to frontend wrapper and then to Ant Design component. + +```mermaid +sequenceDiagram +participant Py as "Backend AntdFloatButton" +participant Svelte as "Svelte Entry Index.svelte" +participant Wrap as "React Wrapper float-button.tsx" +participant AD as "Ant Design FloatButton" +Py->>Svelte : Render component and pass properties/slots +Svelte->>Wrap : Dynamic import and pass props +Wrap->>AD : Inject icon/description/tooltip/badge slots +AD-->>Wrap : Return render result +Wrap-->>Svelte : Rendering complete +Svelte-->>Py : Component mounted +``` + +Diagram Source + +- [**init**.py:92-96](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L92-L96) +- [Index.svelte:10-69](file://frontend/antd/float-button/Index.svelte#L10-L69) +- [float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) + +## Detailed Component Analysis + +### Component 1: FloatButton + +- Design Concept + - As a global page entry, ensuring clickable trigger at any scroll position + - Supports extensions like icons, descriptions, tooltips, and badges through slot system +- Key Features + - Slot Support: icon, description, tooltip, tooltip.title, badge.count + - Callback Function Safety Handling: Wraps function-type properties like tooltip.afterOpenChange, tooltip.getPopupContainer + - Visibility Control: Controls rendering through visible +- Usage Scenarios + - Quick action entries (like "Back to Top", "Share", "Feedback") + - Entry buttons for multi-state switching or conditional display +- Configuration Points + - Icon and Shape: icon, shape + - Type and Style: type, root_class_name, class_names, styles + - Link and Native Properties: href, href_target, html_type + - Badge and Tooltip: badge, tooltip +- Interaction Behavior + - Supports click event binding + - Tooltip supports delayed open/close callbacks and popup container selection + +```mermaid +classDiagram +class AntdFloatButton { ++EVENTS ++SLOTS ++__init__(...) ++FRONTEND_DIR +} +class FloatButton { ++Slots : icon, description, tooltip, tooltip.title, badge.count ++Function Wrapping : afterOpenChange, getPopupContainer +} +AntdFloatButton --> FloatButton : "Backend drives frontend" +``` + +Diagram Source + +- [**init**.py:12-32](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L32) +- [float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) + +Section Source + +- [**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [Index.svelte:13-51](file://frontend/antd/float-button/Index.svelte#L13-L51) +- [float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) + +### Component 2: FloatButton.Group + +- Design Concept + - Combines multiple floating buttons into one group, forming a compound entry, reducing page element count + - Supports close icon, shape (circle/square), and theme variable injection +- Key Features + - Slot Support: icon, closeIcon, description, tooltip, badge.count + - Shape and Style: shape, className, inline style overriding theme variables + - Child Item Rendering: Separates slots from regular child nodes through useSlotsChildren +- Usage Scenarios + - Multi-function entry aggregation (like "Edit/Favorite/Share/More") + - Expandable/collapsible compound action areas +- Configuration Points + - Group Shape: shape (circle/square) + - Theme Variables: Inject border radius, etc. through CSS variables + - Slot-based Icons and Tooltips: Supports independent configuration for each child item + +```mermaid +classDiagram +class FloatButtonGroup { ++Slots : icon, closeIcon, description, tooltip, badge.count ++Properties : shape, className, style ++Theme : useToken() ++Children : useSlotsChildren() +} +``` + +Diagram Source + +- [group/float-button.group.tsx:10-67](file://frontend/antd/float-button/group/float-button.group.tsx#L10-L67) + +Section Source + +- [group/Index.svelte:14-50](file://frontend/antd/float-button/group/Index.svelte#L14-L50) +- [group/float-button.group.tsx:10-67](file://frontend/antd/float-button/group/float-button.group.tsx#L10-L67) + +### Component 3: FloatButton.BackTop + +- Design Concept + - Provides one-click back to top capability in long pages, improving navigation efficiency + - Supports custom scroll container retrieval logic, adapting to complex layouts +- Key Features + - Slot Support: icon, description, tooltip, badge.count + - Custom Target Container: target function wrapping, supports dynamic selection of scroll container +- Usage Scenarios + - Long content pages like content pages, list pages, detail pages + - Scenarios requiring frequent up/down scrolling +- Configuration Points + - Icon and Tooltip: icon, tooltip + - Badge and Description: badge, description + - Scroll Container: target (function), returns scroll container DOM node + +```mermaid +sequenceDiagram +participant User as "User" +participant BackTop as "BackTop Component" +participant Target as "target function" +participant Scroll as "Scroll Container" +User->>BackTop : Click "Back to Top" +BackTop->>Target : Get scroll container +Target-->>BackTop : Return DOM node +BackTop->>Scroll : Smooth scroll to top +Scroll-->>User : Page returns to top +``` + +Diagram Source + +- [back-top/float-button.back-top.tsx:7-44](file://frontend/antd/float-button/back-top/float-button.back-top.tsx#L7-L44) + +Section Source + +- [back-top/Index.svelte:14-50](file://frontend/antd/float-button/back-top/Index.svelte#L14-L50) +- [back-top/float-button.back-top.tsx:7-44](file://frontend/antd/float-button/back-top/float-button.back-top.tsx#L7-L44) + +### Component 4: Backend Bridge and Event Binding + +- Backend Component Class + - Defines events: click (binds internal event handler) + - Defines slots: icon, description, tooltip, tooltip.title, badge.count + - Frontend directory mapping: resolve_frontend_dir("float-button") +- Documentation and Examples + - README contains basic example placeholder + - app.py used to start documentation site + +Section Source + +- [**init**.py:22-32](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L22-L32) +- [**init**.py:92-96](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L92-L96) +- [README-zh_CN.md:1-8](file://docs/components/antd/float_button/README-zh_CN.md#L1-L8) +- [app.py:1-7](file://docs/components/antd/float_button/app.py#L1-L7) + +## Dependency Analysis + +- Component Coupling + - Backend AntdFloatButton only handles property and event declaration, does not directly render, reducing coupling + - Frontend achieves on-demand loading and decoupling through Svelte dynamic import wrapper +- Slots and Themes + - Group component introduces Ant Design theme token, injecting CSS variables to adapt border radius, etc. +- Function-type Properties + - Wraps tooltip callbacks and target through useFunction, ensuring stable operation in React/Svelte environments + +```mermaid +graph LR +PY["Backend AntdFloatButton"] --> IDX["Svelte Entry"] +IDX --> WRAP["React Wrapper"] +WRAP --> AD["Ant Design Component"] +WRAP --> THEME["Theme Token Injection"] +WRAP --> FN["useFunction Wrapped Callback"] +``` + +Diagram Source + +- [**init**.py:92-96](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L92-L96) +- [Index.svelte:10-69](file://frontend/antd/float-button/Index.svelte#L10-L69) +- [float-button.tsx:20-28](file://frontend/antd/float-button/float-button.tsx#L20-L28) +- [group/float-button.group.tsx:16-31](file://frontend/antd/float-button/group/float-button.group.tsx#L16-L31) +- [back-top/float-button.back-top.tsx:11](file://frontend/antd/float-button/back-top/float-button.back-top.tsx#L11) + +Section Source + +- [**init**.py:92-96](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L92-L96) +- [float-button.tsx:20-28](file://frontend/antd/float-button/float-button.tsx#L20-L28) +- [group/float-button.group.tsx:16-31](file://frontend/antd/float-button/group/float-button.group.tsx#L16-L31) +- [back-top/float-button.back-top.tsx:11](file://frontend/antd/float-button/back-top/float-button.back-top.tsx#L11) + +## Performance Considerations + +- On-demand Loading + - Svelte avoids initial bundle bloat through dynamic import wrapper +- Rendering Overhead + - Slot content is hidden by default, only injected into Ant Design component when needed +- Callback Functions + - Use useFunction to wrap function-type properties, reducing unnecessary re-renders +- Theme Injection + - Group component injects theme tokens through CSS variables, avoiding repeated style calculations + +Section Source + +- [Index.svelte:10-10](file://frontend/antd/float-button/Index.svelte#L10-L10) +- [float-button.tsx:30-71](file://frontend/antd/float-button/float-button.tsx#L30-L71) +- [group/float-button.group.tsx:16-31](file://frontend/antd/float-button/group/float-button.group.tsx#L16-L31) + +## Troubleshooting Guide + +- FloatButton Not Displaying + - Check whether visible is true + - Confirm FRONTEND_DIR mapping is correct +- Slot Not Working + - Ensure slot names match the component support list (icon, description, tooltip, tooltip.title, badge.count) + - Group component additionally supports closeIcon, badge.count +- Back to Top Not Working + - Check whether target function returns a valid scroll container DOM node +- Tooltip Callback Not Triggered + - Confirm tooltip.afterOpenChange, tooltip.getPopupContainer are wrapped through useFunction + +Section Source + +- [Index.svelte:56-69](file://frontend/antd/float-button/Index.svelte#L56-L69) +- [float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) +- [group/float-button.group.tsx:10-67](file://frontend/antd/float-button/group/float-button.group.tsx#L10-L67) +- [back-top/float-button.back-top.tsx:7-44](file://frontend/antd/float-button/back-top/float-button.back-top.tsx#L7-L44) + +## Conclusion + +The FloatButton component achieves seamless integration and extension with Ant Design through the collaboration of backend bridge and frontend wrapper. Its slot-based design, theme injection, and function-type property wrapping maintain good maintainability and extensibility even in complex page layouts. Combined with the enhanced capabilities of "FloatButton Group" and "Back to Top", it can cover various common interaction scenarios, improving user experience and development efficiency. + +## Appendix + +- Examples and Documentation + - Documentation example entry: docs/components/antd/float_button/README-zh_CN.md + - Documentation site startup: docs/components/antd/float_button/app.py + +Section Source + +- [README-zh_CN.md:1-8](file://docs/components/antd/float_button/README-zh_CN.md#L1-L8) +- [app.py:1-7](file://docs/components/antd/float_button/app.py#L1-L7) diff --git a/.wiki/en/Ant Design Components/General Components/General Components.md b/.wiki/en/Ant Design Components/General Components/General Components.md new file mode 100644 index 00000000..05e30fd1 --- /dev/null +++ b/.wiki/en/Ant Design Components/General Components/General Components.md @@ -0,0 +1,375 @@ +# General Components + + +**Files referenced in this document** +- [button.tsx](file://frontend/antd/button/button.tsx) +- [float-button.tsx](file://frontend/antd/float-button/float-button.tsx) +- [icon.tsx](file://frontend/antd/icon/icon.tsx) +- [typography.base.tsx](file://frontend/antd/typography/typography.base.tsx) +- [basic.py (Button)](file://docs/components/antd/button/demos/basic.py) +- [basic.py (FloatButton)](file://docs/components/antd/float_button/demos/basic.py) +- [basic.py (Icon)](file://docs/components/antd/icon/demos/basic.py) +- [basic.py (Typography)](file://docs/components/antd/typography/demos/basic.py) +- [README-zh_CN.md (Button)](file://docs/components/antd/button/README-zh_CN.md) +- [README-zh_CN.md (FloatButton)](file://docs/components/antd/float_button/README-zh_CN.md) +- [README-zh_CN.md (Icon)](file://docs/components/antd/icon/README-zh_CN.md) +- [README-zh_CN.md (Typography)](file://docs/components/antd/typography/README-zh_CN.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This chapter covers the implementation and usage of Ant Design general components in this repository, focusing on the following basic general components: Button, FloatButton, Icon, and Typography. The documentation provides in-depth analysis from aspects including system architecture, component responsibilities, data and event flow, accessibility and keyboard navigation, style and theme customization, best practices for combined usage, and performance optimization, with example paths to guide readers in getting started quickly. + +## Project Structure + +This project uses an organization of "frontend Svelte component wrapping + backend Gradio example demonstration": + +- Frontend components are located under frontend/antd, where each component consists of a svelte file and a tsx wrapper layer. The tsx layer is responsible for bridging Ant Design's React components to the Svelte ecosystem, and extending child content like icons, tooltips, and badges through the slots mechanism. +- Documentation examples are located under docs/components/antd, where each component provides multiple demo scripts (basic.py, etc.) to demonstrate different properties and interaction scenarios. + +```mermaid +graph TB +subgraph "Frontend Components" +BTN["Button
button.tsx"] +FBTN["FloatButton
float-button.tsx"] +ICON["Icon
icon.tsx"] +TYPO["Typography.Base
typography.base.tsx"] +end +subgraph "Documentation Examples" +DEMO_BTN["Button Example
button/demos/basic.py"] +DEMO_FBTN["FloatButton Example
float_button/demos/basic.py"] +DEMO_ICON["Icon Example
icon/demos/basic.py"] +DEMO_TYPO["Typography Example
typography/demos/basic.py"] +end +BTN --> DEMO_BTN +FBTN --> DEMO_FBTN +ICON --> DEMO_ICON +TYPO --> DEMO_TYPO +``` + +Diagram Source + +- [button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [typography.base.tsx:1-170](file://frontend/antd/typography/typography.base.tsx#L1-L170) +- [basic.py (Button):1-26](file://docs/components/antd/button/demos/basic.py#L1-L26) +- [basic.py (FloatButton):1-30](file://docs/components/antd/float_button/demos/basic.py#L1-L30) +- [basic.py (Icon):1-24](file://docs/components/antd/icon/demos/basic.py#L1-L24) +- [basic.py (Typography):1-23](file://docs/components/antd/typography/demos/basic.py#L1-L23) + +Section Source + +- [README-zh_CN.md (Button):1-8](file://docs/components/antd/button/README-zh_CN.md#L1-L8) +- [README-zh_CN.md (FloatButton):1-8](file://docs/components/antd/float_button/README-zh_CN.md#L1-L8) +- [README-zh_CN.md (Icon):1-10](file://docs/components/antd/icon/README-zh_CN.md#L1-L10) +- [README-zh_CN.md (Typography):1-8](file://docs/components/antd/typography/README-zh_CN.md#L1-L8) + +## Core Components + +- Button + - Responsibility: Wraps Ant Design's Button, supports injecting icon and custom loading icon through slots; supports dual entry rendering via value and children. + - Key Points: Uses useTargets to extract slot targets, dynamically determining render content; conditionally merges loading configuration, compatible with both objects and booleans. +- FloatButton + - Responsibility: Wraps Ant Design's FloatButton, supports slot-based configuration for icon, description, tooltip, badge, etc.; wraps function-type configuration items with useFunction to maintain reactivity. + - Key Points: tooltip supports title and overall configuration object; badge supports count slot; description supports slot. +- Icon + - Responsibility: Supports Ant Design built-in icon name mapping and IconFont rendering; supports custom component slot as SVG component. + - Key Points: slots.component has highest priority; otherwise maps to built-in icon by value; finally falls back to IconFont type. +- Typography.Base + - Responsibility: Unifies and aggregates four typography component types: Title, Text, Paragraph, Link, supporting slot-based configuration for copyable, editable, and ellipsis. + - Key Points: Dynamically selects specific Typography sub-component based on component; processes multiple slots with useTargets and renderParamsSlot, ensuring flexibility and extensibility. + +Section Source + +- [button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [typography.base.tsx:1-170](file://frontend/antd/typography/typography.base.tsx#L1-L170) + +## Architecture Overview + +The diagram below shows the call chain for general components: documentation examples start through Gradio application, internally use ConfigProvider for global theme configuration, then render each component; components internally bridge Ant Design's React components to Svelte components through sveltify, and inject icons, tooltips, badges, etc. using the slots mechanism. + +```mermaid +sequenceDiagram +participant Demo as "Example Script" +participant App as "Gradio Application" +participant Provider as "ConfigProvider" +participant Comp as "Component Wrapper Layer" +participant Antd as "Ant Design Component" +Demo->>App : "Build Blocks and start" +App->>Provider : "Apply global configuration" +App->>Comp : "Render component instance" +Comp->>Antd : "Pass properties and slots" +Antd-->>Comp : "Render result" +Comp-->>App : "Return Svelte wrapped node" +App-->>Demo : "Complete one render" +``` + +Diagram Source + +- [basic.py (Button):5-25](file://docs/components/antd/button/demos/basic.py#L5-L25) +- [basic.py (FloatButton):5-29](file://docs/components/antd/float_button/demos/basic.py#L5-L29) +- [basic.py (Icon):5-23](file://docs/components/antd/icon/demos/basic.py#L5-L23) +- [basic.py (Typography):10-22](file://docs/components/antd/typography/demos/basic.py#L10-L22) +- [button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) +- [float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) +- [icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- [typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) + +## Detailed Component Analysis + +### Button + +- Design Points + - Supports multiple types and variants: such as primary, dashed, text, link, filled, etc.; supports block layout and size control. + - Slot Capabilities: Inject icons through slots.icon; inject loading state icons through slots.loading.icon, supporting delay configuration. + - Content Entry: Supports directly passing text (children) or value field; when slots exist, slot content is rendered first. +- Events and Interaction + - click event: The example demonstrates click callback binding. + - Loading State: Can be configured via loading=true or passing an object to configure delay time. +- Styles and Themes + - Global theme takes effect through ConfigProvider; supports color and variant combinations. +- Usage Examples (Reference Path) + - Basic usage and variants: [basic.py (Button):8-22](file://docs/components/antd/button/demos/basic.py#L8-L22) + - Slot icons and loading state: [basic.py (Button):18-22](file://docs/components/antd/button/demos/basic.py#L18-L22) + +```mermaid +sequenceDiagram +participant U as "User" +participant Btn as "Button Wrapper Layer" +participant RBtn as "Antd Button" +U->>Btn : "Click triggers click event" +Btn->>RBtn : "Forward click event" +RBtn-->>U : "Execute callback and update interface" +Note over Btn,RBtn : "Slots icon/ loading.icon injected by slots" +``` + +Diagram Source + +- [button.tsx:11-36](file://frontend/antd/button/button.tsx#L11-L36) +- [basic.py (Button):10-10](file://docs/components/antd/button/demos/basic.py#L10-L10) + +Section Source + +- [button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) +- [basic.py (Button):8-22](file://docs/components/antd/button/demos/basic.py#L8-L22) + +### FloatButton + +- Design Points + - Supports sub-components like Group and BackTop; supports slot-based configuration for icon, description, tooltip, badge, etc. + - tooltip supports title and overall configuration object; badge supports count slot; description supports slot. + - Uses useFunction to wrap function-type configuration items (like afterOpenChange, getPopupContainer), ensuring reactive updates. +- Events and Interaction + - Supports click, visibility control (BackTop's visibility_height), etc. +- Styles and Themes + - Customize position and layout through elem_style; combine with Group to implement multi-button grouping. +- Usage Examples (Reference Path) + - Basic usage and grouping: [basic.py (FloatButton):8-13](file://docs/components/antd/float_button/demos/basic.py#L8-L13) + - Badge and icon: [basic.py (FloatButton):10-12](file://docs/components/antd/float_button/demos/basic.py#L10-L12) + - BackTop and Tooltip slots: [basic.py (FloatButton):13-13](file://docs/components/antd/float_button/demos/basic.py#L13-L13), [basic.py (FloatButton):23-27](file://docs/components/antd/float_button/demos/basic.py#L23-L27) + +```mermaid +sequenceDiagram +participant U as "User" +participant F as "FloatButton Wrapper Layer" +participant FB as "Antd FloatButton" +U->>F : "Click float button" +F->>FB : "Forward click event" +FB-->>U : "Execute callback and show/hide" +Note over F,FB : "tooltip.title/tooltip slot and badge.count slot injected by slots" +``` + +Diagram Source + +- [float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) +- [basic.py (FloatButton):13-13](file://docs/components/antd/float_button/demos/basic.py#L13-L13) +- [basic.py (FloatButton):23-27](file://docs/components/antd/float_button/demos/basic.py#L23-L27) + +Section Source + +- [float-button.tsx:7-72](file://frontend/antd/float-button/float-button.tsx#L7-L72) +- [basic.py (FloatButton):8-27](file://docs/components/antd/float_button/demos/basic.py#L8-L27) + +### Icon + +- Design Points + - Supports built-in icon name mapping (like HomeOutlined, SettingFilled, etc.); supports spin, rotate, twoTone, etc. properties. + - Supports IconFont fallback rendering; supports slots.component to inject custom SVG components. +- Events and Interaction + - The example demonstrates click event binding. +- Styles and Themes + - Supports style controls like color, rotation angle, two-tone icons, etc. +- Usage Examples (Reference Path) + - Basic icons and two-tone icons: [basic.py (Icon):9-16](file://docs/components/antd/icon/demos/basic.py#L9-L16) + - Custom component slots: [basic.py (Icon):19-21](file://docs/components/antd/icon/demos/basic.py#L19-L21) + +```mermaid +flowchart TD +Start(["Enter Icon rendering"]) --> CheckSlot["Check if slots.component exists"] +CheckSlot --> |Yes| RenderCustom["Render custom component"] +CheckSlot --> |No| CheckValue["Look up built-in icon by value"] +CheckValue --> Found{"Found built-in icon?"} +Found --> |Yes| RenderBuiltIn["Render built-in icon"] +Found --> |No| CheckIconFont["Check IconFont context"] +CheckIconFont --> HasFont{"Has IconFont?"} +HasFont --> |Yes| RenderIconFont["Render using IconFont"] +HasFont --> |No| Empty["Do not render empty"] +RenderCustom --> End(["End"]) +RenderBuiltIn --> End +RenderIconFont --> End +Empty --> End +``` + +Diagram Source + +- [icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- [basic.py (Icon):9-16](file://docs/components/antd/icon/demos/basic.py#L9-L16) +- [basic.py (Icon):19-21](file://docs/components/antd/icon/demos/basic.py#L19-L21) + +Section Source + +- [icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- [basic.py (Icon):9-21](file://docs/components/antd/icon/demos/basic.py#L9-L21) + +### Typography.Base + +- Design Points + - Unifies and aggregates four component types: Title, Text, Paragraph, Link, switching via component parameter. + - Supports slot-based configuration for copyable, editable, and ellipsis, enhancing customizability. + - Uses useSlotsChildren and useTargets to separate slot content from regular children, avoiding duplicate rendering. +- Events and Interaction + - editable_change event: The example demonstrates binding for edit change event and output update. +- Styles and Themes + - Generates class names through className and component name prefix, facilitating theme override. +- Usage Examples (Reference Path) + - Basic titles and text: [basic.py (Typography):13-15](file://docs/components/antd/typography/demos/basic.py#L13-L15) + - Copyable paragraphs and edit events: [basic.py (Typography):16-19](file://docs/components/antd/typography/demos/basic.py#L16-L19) + +```mermaid +sequenceDiagram +participant U as "User" +participant T as "Typography.Base" +participant TT as "Antd Typography.*" +U->>T : "Start editing" +T->>TT : "Trigger editable event" +TT-->>T : "Return edit result" +T-->>U : "Update content and close edit" +Note over T,TT : "copyable/ editable/ ellipsis slots injected by slots" +``` + +Diagram Source + +- [typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) +- [basic.py (Typography):16-19](file://docs/components/antd/typography/demos/basic.py#L16-L19) + +Section Source + +- [typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) +- [basic.py (Typography):13-19](file://docs/components/antd/typography/demos/basic.py#L13-L19) + +## Dependency Analysis + +- Inter-component Coupling + - Button, FloatButton, Icon, and Typography.Base all bridge Ant Design's React components to Svelte through sveltify, independent of each other with low coupling. + - The slot mechanism (slots) runs through all components, used to inject child content like icons, tooltips, badges, etc., enhancing extensibility. +- External Dependencies + - Ant Design React component library: Provides basic UI capabilities. + - @svelte-preprocess-react: Provides sveltify and ReactSlot, implementing Svelte and React interoperability. + - lodash-es: Provides utility functions (like isObject). + - @utils/\*: Provides useTargets, useFunction, renderParamsSlot, and other utilities, enhancing slot and event handling capabilities. +- Potential Circular Dependencies + - No circular dependencies found in the current structure; components all collaborate through utility functions and contexts, maintaining one-way dependencies. + +```mermaid +graph LR +BTN["Button.tsx"] --> AD["Ant Design Button"] +FBTN["FloatButton.tsx"] --> AD_FB["Ant Design FloatButton"] +ICON["Icon.tsx"] --> AD_Icons["Ant Design Icons"] +TYPO["Typography.Base.tsx"] --> AD_Typo["Ant Design Typography"] +BTN --> Utils["@utils/*"] +FBTN --> Utils +ICON --> Utils +TYPO --> Utils +Utils --> SveltePreprocess["@svelte-preprocess-react"] +AD --> React["React"] +AD_FB --> React +AD_Icons --> React +AD_Typo --> React +``` + +Diagram Source + +- [button.tsx:1-6](file://frontend/antd/button/button.tsx#L1-L6) +- [float-button.tsx:1-5](file://frontend/antd/float-button/float-button.tsx#L1-L5) +- [icon.tsx:1-6](file://frontend/antd/icon/icon.tsx#L1-L6) +- [typography.base.tsx:1-10](file://frontend/antd/typography/typography.base.tsx#L1-L10) + +Section Source + +- [button.tsx:1-6](file://frontend/antd/button/button.tsx#L1-L6) +- [float-button.tsx:1-5](file://frontend/antd/float-button/float-button.tsx#L1-L5) +- [icon.tsx:1-6](file://frontend/antd/icon/icon.tsx#L1-L6) +- [typography.base.tsx:1-10](file://frontend/antd/typography/typography.base.tsx#L1-L10) + +## Performance Considerations + +- Slot Rendering Optimization + - Uses useTargets and useSlotsChildren to separate slots from regular children, reducing unnecessary rendering overhead. + - Conditionally injects loading.icon, copyable.icon, editable.icon, etc., avoiding useless node mounting. +- Function-type Configuration Wrapping + - Uses useFunction to wrap function-type configurations for tooltip (like afterOpenChange, getPopupContainer), ensuring reactive updates without closure jitter. +- Conditional Merging + - Merges copyable, editable, ellipsis, etc. configurations through getConfig and omitUndefinedProps, only enabling corresponding capabilities when needed, reducing runtime burden. +- Theme and Styles + - Unifies theme through ConfigProvider, avoiding repeated calculations and style conflicts; reasonably uses className prefix for precise override. + +## Troubleshooting Guide + +- Slot Not Working + - Confirm whether slot names are correct (like icon, loading.icon, copyable.icon, editable.icon, ellipsis.symbol, etc.). + - Confirm slots.component has higher priority than built-in icon mapping; if provided, it will override default behavior. +- Tooltip Cannot Open or Callback Invalid + - Check whether tooltip is an object configuration; ensure function-type configuration items are wrapped through useFunction. +- Icon Not Displaying + - If slots.component is not provided, confirm whether value is a built-in icon name; otherwise, need to correctly configure IconFont context. +- Edit/Copy/Ellipsis Configuration Not Working + - Confirm that editable, copyable, or ellipsis enable corresponding capability if any exists; if it's an object configuration, ensure fields are complete. + +Section Source + +- [float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) +- [icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- [typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) + +## Conclusion + +This repository seamlessly integrates Ant Design's React components into the Svelte/Gradio ecosystem through unified sveltify wrapping and slot mechanism, achieving high customizability and ease of use for general components like Button, FloatButton, Icon, and Typography. With ConfigProvider, slots, and utility functions, developers can flexibly implement style customization, interaction extension, and accessibility requirements. It is recommended to follow slot naming conventions, reasonably use function-type configuration wrapping and conditional rendering strategies in actual projects for better performance and maintainability. + +## Appendix + +- Quick Example Paths + - Button: [basic.py (Button):8-22](file://docs/components/antd/button/demos/basic.py#L8-L22) + - FloatButton: [basic.py (FloatButton):8-27](file://docs/components/antd/float_button/demos/basic.py#L8-L27) + - Icon: [basic.py (Icon):9-21](file://docs/components/antd/icon/demos/basic.py#L9-L21) + - Typography: [basic.py (Typography):13-19](file://docs/components/antd/typography/demos/basic.py#L13-L19) +- Component Documentation Entry + - Button: [README-zh_CN.md (Button):1-8](file://docs/components/antd/button/README-zh_CN.md#L1-L8) + - FloatButton: [README-zh_CN.md (FloatButton):1-8](file://docs/components/antd/float_button/README-zh_CN.md#L1-L8) + - Icon: [README-zh_CN.md (Icon):1-10](file://docs/components/antd/icon/README-zh_CN.md#L1-L10) + - Typography: [README-zh_CN.md (Typography):1-8](file://docs/components/antd/typography/README-zh_CN.md#L1-L8) diff --git a/.wiki/en/Ant Design Components/General Components/Icon.md b/.wiki/en/Ant Design Components/General Components/Icon.md new file mode 100644 index 00000000..db7c8238 --- /dev/null +++ b/.wiki/en/Ant Design Components/General Components/Icon.md @@ -0,0 +1,360 @@ +# Icon + + +**Files referenced in this document** +- [frontend/antd/icon/Index.svelte](file://frontend/antd/icon/Index.svelte) +- [frontend/antd/icon/icon.tsx](file://frontend/antd/icon/icon.tsx) +- [frontend/antd/icon/iconfont-provider/Index.svelte](file://frontend/antd/icon/iconfont-provider/Index.svelte) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx) +- [backend/modelscope_studio/components/antd/icon/__init__.py](file://backend/modelscope_studio/components/antd/icon/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [docs/components/antd/icon/README-zh_CN.md](file://docs/components/antd/icon/README-zh_CN.md) +- [docs/components/antd/icon/demos/basic.py](file://docs/components/antd/icon/demos/basic.py) +- [docs/components/antd/icon/demos/iconfont.py](file://docs/components/antd/icon/demos/iconfont.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance and Optimization](#performance-and-optimization) +8. [Accessibility](#accessibility) +9. [Troubleshooting](#troubleshooting) +10. [Conclusion](#conclusion) +11. [Appendix: Usage Examples and Best Practices](#appendix-usage-examples-and-best-practices) + +## Introduction + +This document systematically introduces the Icon component in ModelScope Studio's frontend ecosystem, covering: + +- Usage guidelines and common scenarios (inline icons, button icons, navigation icons) +- Supported icon libraries and icon font integration (Ant Design built-in icons, iconfont.cn) +- Size, color, style, and other configuration options +- IconFontProvider configuration and usage +- Performance optimization, lazy loading, and caching strategies +- Accessibility, semantic markup, and screen reader compatibility +- Custom icon library integration solutions and best practices + +## Project Structure + +The Icon component consists of "backend Gradio component layer" and "frontend Svelte/React presentation layer", and supports custom rendering through the Slot mechanism. + +```mermaid +graph TB +subgraph "Backend" +PY_ICON["AntdIcon
Python Component"] +PY_PROVIDER["AntdIconIconfontProvider
Python Component"] +end +subgraph "Frontend" +SV_INDEX["Index.svelte
Component Entry (Svelte)"] +TS_ICON["icon.tsx
React Implementation (Ant Design Icons)"] +SV_PROVIDER_INDEX["iconfont-provider/Index.svelte
Provider Entry (Svelte)"] +TS_PROVIDER["iconfont-provider.tsx
React Provider (IconFont)"] +end +PY_ICON --> SV_INDEX +PY_PROVIDER --> SV_PROVIDER_INDEX +SV_INDEX --> TS_ICON +SV_PROVIDER_INDEX --> TS_PROVIDER +``` + +Diagram Source + +- [backend/modelscope_studio/components/antd/icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) +- [frontend/antd/icon/icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [frontend/antd/icon/iconfont-provider/Index.svelte:1-53](file://frontend/antd/icon/iconfont-provider/Index.svelte#L1-L53) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:1-44](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L1-L44) + +Section Source + +- [backend/modelscope_studio/components/antd/icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) +- [frontend/antd/icon/icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [frontend/antd/icon/iconfont-provider/Index.svelte:1-53](file://frontend/antd/icon/iconfont-provider/Index.svelte#L1-L53) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:1-44](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L1-L44) + +## Core Components + +- AntdIcon (Backend): Provides properties such as value, spin, rotate, twoToneColor, component, etc.; supports click event binding; supports a Slot named "component" to inject custom rendering. +- AntdIconIconfontProvider (Backend): Provides IconFont context, used to render icons by type in icon font libraries like iconfont.cn. +- Frontend Svelte Entry: Responsible for forwarding backend-passed properties and Slots to React implementation. +- Frontend React Implementation: Selects built-in Ant Design icons based on value or renders custom icon types through IconFont context. + +Section Source + +- [backend/modelscope_studio/components/antd/icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) +- [frontend/antd/icon/icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [frontend/antd/icon/iconfont-provider/Index.svelte:1-53](file://frontend/antd/icon/iconfont-provider/Index.svelte#L1-L53) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:1-44](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L1-L44) + +## Architecture Overview + +The diagram below shows the key call chain from backend to frontend and then to icon rendering: + +```mermaid +sequenceDiagram +participant Py as "Backend AntdIcon" +participant S as "Frontend Index.svelte" +participant R as "React Icon Implementation" +participant Ctx as "IconFont Context" +Py->>S : Pass value/props/Slots +S->>R : Render Icon and pass through properties +alt Using custom component Slot +R->>R : Render using custom component +else Using built-in or IconFont +R->>Ctx : Read IconFont context +alt IconFont exists +R->>Ctx : Call IconFont(type, props) +else Not exists +R->>R : Render Ant Design built-in icon +end +end +``` + +Diagram Source + +- [frontend/antd/icon/Index.svelte:52-66](file://frontend/antd/icon/Index.svelte#L52-L66) +- [frontend/antd/icon/icon.tsx:17-52](file://frontend/antd/icon/icon.tsx#L17-L52) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:36-41](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L36-L41) + +## Component Details + +### AntdIcon (Backend) + +- Supported Properties + - value: String, specifies icon name (like built-in icon name or IconFont type name) + - spin: Boolean, whether to rotate animation + - rotate: Numeric angle, icon rotation angle + - twoToneColor: Two-tone icon primary color + - component: Root node component placeholder (used to replace default container) + - Element-level styles and class names: elem_style, elem_classes + - Visibility and rendering: visible, render +- Events + - click: Bind click event +- Slot + - component: Used to inject custom rendering (such as text emoticons, SVG components) + +Section Source + +- [backend/modelscope_studio/components/antd/icon/**init**.py:27-68](file://backend/modelscope_studio/components/antd/icon/__init__.py#L27-L68) +- [backend/modelscope_studio/components/antd/icon/**init**.py:18-22](file://backend/modelscope_studio/components/antd/icon/__init__.py#L18-L22) + +### Frontend Svelte Entry (Index.svelte) + +- Passes backend-provided value, additionalProps, elem\_\*, and other properties to React Icon +- Gets and forwards to React Icon through Slot +- Conditional rendering: Only renders when visible is true + +Section Source + +- [frontend/antd/icon/Index.svelte:13-66](file://frontend/antd/icon/Index.svelte#L13-L66) + +### React Implementation (icon.tsx) + +- Key Logic Points + - Prioritizes custom component injected through "component" Slot for rendering + - Otherwise, if built-in icon name exists, renders corresponding Ant Design icon + - If no built-in icon and IconFont context exists, renders through IconFont(type, props) +- Key Context + - useIconFontContext: Gets IconFont context instance + +Section Source + +- [frontend/antd/icon/icon.tsx:17-52](file://frontend/antd/icon/icon.tsx#L17-L52) + +### AntdIconIconfontProvider (Backend) + +- Provides IconFont context, enabling child-level Icons to render custom icon fonts by type +- Common Usage: Wraps a set of icons that need to use iconfont.cn + +Section Source + +- [backend/modelscope_studio/components/antd/icon/**init**.py:16-16](file://backend/modelscope_studio/components/antd/icon/__init__.py#L16-L16) + +### Frontend Provider (iconfont-provider.tsx) + +- Functionality + - Creates IconFont instance based on createFromIconfontCN + - Instance Caching: Reuses same instance when scriptUrl and extraCommonProps are unchanged + - Exposes to subtree through IconFontContext.Provider +- Parameters + - scriptUrl: Icon font script address (can be an array) + - extraCommonProps: Extra common properties (like color, fontSize, etc.) + +Section Source + +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:12-41](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L12-L41) + +### Provider Frontend Entry (iconfont-provider/Index.svelte) + +- Passes backend-provided Provider properties to React Provider component +- Acts as parent context container for Icons + +Section Source + +- [frontend/antd/icon/iconfont-provider/Index.svelte:42-52](file://frontend/antd/icon/iconfont-provider/Index.svelte#L42-L52) + +## Dependency Analysis + +- Component Coupling + - AntdIcon and AntdIconIconfontProvider are associated through classes in backend + - Frontend Svelte entry and React implementation are decoupled, communicating through properties and Slots + - React Icon depends on Ant Design Icons and IconFont context +- External Dependencies + - @ant-design/icons: Built-in icon library + - lodash-es isEqual: Used for Provider instance cache comparison + +```mermaid +graph LR +PY_ICON["Backend AntdIcon"] --> SV_ICON["Svelte Entry"] +PY_PROVIDER["Backend IconFontProvider"] --> SV_PROVIDER["Svelte Provider Entry"] +SV_ICON --> REACT_ICON["React Icon Implementation"] +SV_PROVIDER --> REACT_PROVIDER["React Provider Implementation"] +REACT_ICON --> AD["@ant-design/icons"] +REACT_PROVIDER --> ADIF["createFromIconfontCN"] +``` + +Diagram Source + +- [backend/modelscope_studio/components/antd/icon/**init**.py:5-6](file://backend/modelscope_studio/components/antd/icon/__init__.py#L5-L6) +- [frontend/antd/icon/icon.tsx:5-5](file://frontend/antd/icon/icon.tsx#L5-L5) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:4-6](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L4-L6) + +Section Source + +- [backend/modelscope_studio/components/antd/icon/**init**.py:5-6](file://backend/modelscope_studio/components/antd/icon/__init__.py#L5-L6) +- [frontend/antd/icon/icon.tsx:5-5](file://frontend/antd/icon/icon.tsx#L5-L5) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:4-6](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L4-L6) + +## Performance and Optimization + +- Lazy Loading and Async Rendering + - Svelte entry uses async import for Icon and Provider, avoiding first-screen blocking +- Instance Caching + - Provider internally caches IconFont instances based on scriptUrl and extraCommonProps equality, reducing repeated initialization +- Render Path Short-circuit + - When custom Slot exists, directly renders custom component, skipping built-in icon resolution +- Recommendations + - For pages with many icons, prioritize using IconFont and centrally managing scriptUrl + - Reasonably set extraCommonProps to avoid frequent instance rebuilding + - Avoid mixing too many different script sources under the same Provider, reducing context switching cost + +Section Source + +- [frontend/antd/icon/Index.svelte:10-10](file://frontend/antd/icon/Index.svelte#L10-L10) +- [frontend/antd/icon/iconfont-provider/Index.svelte:8-9](file://frontend/antd/icon/iconfont-provider/Index.svelte#L8-L9) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:18-35](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L18-L35) + +## Accessibility + +- Semantic Recommendations + - If the icon carries interactive semantics (like "delete", "search"), it should be accompanied by readable text or aria-label + - For decorative icons, use aria-hidden or add no extra semantics +- Screen Readers + - Keep icons with alternative text (for example, through adjacent text or title attribute) + - Avoid relying solely on color to convey information +- Styles and Focus + - Click-type icons need to ensure focusable and keyboard accessible + - Rotation/animation should not affect accessibility experience + +[This section provides general guidance, no specific file references needed] + +## Troubleshooting + +- Icon Not Displaying + - Check whether value is a valid built-in icon name or IconFont type name + - If using Provider, confirm scriptUrl is correct and network accessible +- Custom Component Not Working + - Confirm that custom rendering is correctly injected using "component" Slot + - Check Slot name case and passing path +- Repeated Requests or Instance Jitter + - Frequent changes to Provider's extraCommonProps or scriptUrl will cause instance rebuilding + - Recommend fixing parameters or merging multiple script sources + +Section Source + +- [frontend/antd/icon/icon.tsx:32-51](file://frontend/antd/icon/icon.tsx#L32-L51) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:18-35](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L18-L35) + +## Conclusion + +This component uses a "backend component + frontend async rendering" pattern, balancing unified access to both Ant Design built-in icons and custom icon fonts like iconfont.cn. Through Slot mechanism and context caching, it satisfies both flexible extension and ensures performance and maintainability. It is recommended to centrally manage icon font resources and style parameters in projects, combining with accessibility guidelines to improve user experience. + +[This section is a summary, no specific file references needed] + +## Appendix: Usage Examples and Best Practices + +### Basic Usage and Built-in Icons + +- Scenarios: Inline icons, button icons, status icons +- Example Reference + - [docs/components/antd/icon/demos/basic.py:9-17](file://docs/components/antd/icon/demos/basic.py#L9-L17) + +Best Practices + +- Provide click callbacks and readable text for interactive icons +- Use twoToneColor to control two-tone icon primary color, maintaining brand consistency + +Section Source + +- [docs/components/antd/icon/demos/basic.py:9-17](file://docs/components/antd/icon/demos/basic.py#L9-L17) + +### Using iconfont.cn + +- Scenarios: Enterprise icon libraries, third-party icon fonts +- Example Reference + - [docs/components/antd/icon/demos/iconfont.py:9-18](file://docs/components/antd/icon/demos/iconfont.py#L9-L18) + +Best Practices + +- Merge multiple script sources into an array to reduce request count +- Set common properties like color, fontSize uniformly through extraCommonProps +- Wrap the set of icons that need to use the font outside the Provider + +Section Source + +- [docs/components/antd/icon/demos/iconfont.py:9-18](file://docs/components/antd/icon/demos/iconfont.py#L9-L18) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:29-33](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L29-L33) + +### Custom Icon Library Integration + +- Option 1: Use "component" Slot to inject any custom rendering (text, SVG, components) + - Example Reference + - [docs/components/antd/icon/demos/basic.py:19-21](file://docs/components/antd/icon/demos/basic.py#L19-L21) +- Option 2: Connect custom fonts through IconFontProvider + - Example Reference + - [docs/components/antd/icon/demos/iconfont.py:9-18](file://docs/components/antd/icon/demos/iconfont.py#L9-L18) + +Best Practices + +- Keep Slot rendering lightweight, avoid executing complex logic on icons +- Prefer localizing font resources or using stable CDN to reduce loading failure risk + +Section Source + +- [docs/components/antd/icon/demos/basic.py:19-21](file://docs/components/antd/icon/demos/basic.py#L19-L21) +- [docs/components/antd/icon/demos/iconfont.py:9-18](file://docs/components/antd/icon/demos/iconfont.py#L9-L18) + +### Configuration Quick Reference + +- AntdIcon (Backend) + - value: Icon name + - spin: Rotation animation + - rotate: Rotation angle + - twoToneColor: Two-tone primary color + - component: Root node component placeholder + - elem_style/elem_classes: Element styles and class names + - visible/render: Visibility and rendering control +- AntdIconIconfontProvider (Backend) + - script_url: Icon font script address (array) + - extra_common_props: Common properties (like color, fontSize) + +Section Source + +- [backend/modelscope_studio/components/antd/icon/**init**.py:27-68](file://backend/modelscope_studio/components/antd/icon/__init__.py#L27-L68) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:12-12](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L12-L12) diff --git a/.wiki/en/Ant Design Components/General Components/Typography.md b/.wiki/en/Ant Design Components/General Components/Typography.md new file mode 100644 index 00000000..3fef6aa3 --- /dev/null +++ b/.wiki/en/Ant Design Components/General Components/Typography.md @@ -0,0 +1,251 @@ +# Typography + + +**Files referenced in this document** +- [frontend/antd/typography/Base.svelte](file://frontend/antd/typography/Base.svelte) +- [frontend/antd/typography/typography.base.tsx](file://frontend/antd/typography/typography.base.tsx) +- [frontend/antd/typography/title/Index.svelte](file://frontend/antd/typography/title/Index.svelte) +- [frontend/antd/typography/paragraph/Index.svelte](file://frontend/antd/typography/paragraph/Index.svelte) +- [frontend/antd/typography/text/Index.svelte](file://frontend/antd/typography/text/Index.svelte) +- [frontend/antd/typography/link/Index.svelte](file://frontend/antd/typography/link/Index.svelte) +- [docs/components/antd/typography/README.md](file://docs/components/antd/typography/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +The Typography component is used to present text content such as headings, paragraphs, inline text, and links in the interface, unifying text hierarchy, readability, and consistency in the design system. This component is wrapped based on Ant Design's Typography capabilities, providing interactive features such as copyable, editable, and ellipsis, and integrates with Gradio through the Svelte component system, supporting dynamic values and slot-based extensions. + +## Project Structure + +Typography uses an organization of "sub-components + base bridge layer" on the frontend side: + +- Base.svelte: Svelte layer entry, responsible for property processing, slot pass-through, and rendering condition control +- typography.base.tsx: React bridge layer, uniformly scheduling Ant Design Typography component types, and injecting advanced capabilities like copyable/editable/ellipsis +- title/paragraph/text/link: Four specific semantic sub-components, mapping to Ant Design's Title/Paragraph/Text/Link respectively + +```mermaid +graph TB +subgraph "Svelte Layer" +Base["Base.svelte"] +Title["title/Index.svelte"] +Paragraph["paragraph/Index.svelte"] +Text["text/Index.svelte"] +Link["link/Index.svelte"] +end +subgraph "React Bridge Layer" +Bridge["typography.base.tsx"] +end +subgraph "Ant Design" +ADT["Typography.Title/Paragraph/Text/Link"] +end +Title --> Base +Paragraph --> Base +Text --> Base +Link --> Base +Base --> Bridge +Bridge --> ADT +``` + +Diagram Source + +- [frontend/antd/typography/Base.svelte:11-84](file://frontend/antd/typography/Base.svelte#L11-L84) +- [frontend/antd/typography/typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) + +Section Source + +- [frontend/antd/typography/Base.svelte:1-85](file://frontend/antd/typography/Base.svelte#L1-L85) +- [frontend/antd/typography/typography.base.tsx:1-170](file://frontend/antd/typography/typography.base.tsx#L1-L170) + +## Core Components + +- Base.svelte: Responsible for extracting from Gradio properties and converting to React-consumable props; handling visibility, DOM ID/class names, extra properties, and slots; rendering base bridge layer on demand +- typography.base.tsx: Selects corresponding Ant Design component based on component type; uniformly handles copyable, editable, and ellipsis configuration and slots; injects component instance and style class names to output +- Four semantic sub-components: title, paragraph, text, link, all using Base as carrier, only needing to specify component + +Section Source + +- [frontend/antd/typography/Base.svelte:15-62](file://frontend/antd/typography/Base.svelte#L15-L62) +- [frontend/antd/typography/typography.base.tsx:19-80](file://frontend/antd/typography/typography.base.tsx#L19-L80) +- [frontend/antd/typography/title/Index.svelte:1-12](file://frontend/antd/typography/title/Index.svelte#L1-L12) +- [frontend/antd/typography/paragraph/Index.svelte:1-12](file://frontend/antd/typography/paragraph/Index.svelte#L1-L12) +- [frontend/antd/typography/text/Index.svelte:1-12](file://frontend/antd/typography/text/Index.svelte#L1-L12) +- [frontend/antd/typography/link/Index.svelte:1-12](file://frontend/antd/typography/link/Index.svelte#L1-L12) + +## Architecture Overview + +The diagram below shows the call chain from Svelte to React and then to Ant Design Typography, as well as the assembly process of copyable/editable/ellipsis. + +```mermaid +sequenceDiagram +participant Svelte as "Svelte Sub-component
title/paragraph/text/link" +participant Base as "Base.svelte" +participant Bridge as "typography.base.tsx" +participant AD as "Ant Design Typography" +Svelte->>Base : Pass props + slots +Base->>Bridge : Convert and merge props +Bridge->>Bridge : Parse copyable/editable/ellipsis config and slots +Bridge->>AD : Render corresponding component (Title/Paragraph/Text/Link) +AD-->>Bridge : Return component with assembled interactive capabilities +Bridge-->>Base : Output final node +Base-->>Svelte : Render result +``` + +Diagram Source + +- [frontend/antd/typography/Base.svelte:65-84](file://frontend/antd/typography/Base.svelte#L65-L84) +- [frontend/antd/typography/typography.base.tsx:69-163](file://frontend/antd/typography/typography.base.tsx#L69-L163) + +## Detailed Component Analysis + +### Base Bridge Layer (typography.base.tsx) + +- Component Selection Logic: Switches among Title/Paragraph/Text/Link based on component value +- Capability Assembly: + - Copy (copyable): Supports custom icons, tooltips, or injection through slots + - Edit (editable): Supports edit icon, tooltip, and enter icon slot-based replacement + - Ellipsis (ellipsis): Supports ellipsis symbol and tooltip slot-based replacement; has special toggle behavior for link component +- Slot and Target Resolution: Uses useTargets to identify targets with specific slot markers in children, then renders with ReactSlot +- Class Name and Style: Appends namespace class name on top of original className, facilitating theme and override + +```mermaid +flowchart TD +Start(["Enter bridge layer"]) --> Choose["Select Ant Design component based on component"] +Choose --> Copyable{"Enable copy capability?"} +Copyable --> |Yes| BuildCopy["Merge config and inject icon/tooltip slots"] +Copyable --> |No| SkipCopy["Skip copy config"] +Choose --> Editable{"Enable edit capability?"} +Editable --> |Yes| BuildEdit["Inject edit icon/tooltip/enter icon slots"] +Editable --> |No| SkipEdit["Skip edit config"] +Choose --> Ellipsis{"Enable ellipsis capability?"} +Ellipsis --> |Yes| BuildEllipsis["Inject ellipsis symbol/tooltip slots"] +Ellipsis --> |No| SkipEllipsis["Skip ellipsis config"] +BuildCopy --> Render["Render final component"] +BuildEdit --> Render +BuildEllipsis --> Render +SkipCopy --> Render +SkipEdit --> Render +SkipEllipsis --> Render +Render --> End(["Return render result"]) +``` + +Diagram Source + +- [frontend/antd/typography/typography.base.tsx:40-167](file://frontend/antd/typography/typography.base.tsx#L40-L167) + +Section Source + +- [frontend/antd/typography/typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) + +### Svelte Entry (Base.svelte) + +- Property Processing: Gets component properties from Gradio, filters internal fields, preserves externally available props +- Slot Processing: Collects and passes through slots, while distinguishing value and children for rendering +- Conditional Rendering: Controls display based on visible; supports directly rendering children in layout mode +- DOM Properties: Injects elem_id, elem_classes, elem_style, etc. + +Section Source + +- [frontend/antd/typography/Base.svelte:15-62](file://frontend/antd/typography/Base.svelte#L15-L62) +- [frontend/antd/typography/Base.svelte:65-84](file://frontend/antd/typography/Base.svelte#L65-L84) + +### Semantic Sub-components (title/paragraph/text/link) + +- All render through Base.svelte, only needing to set component to switch semantics and hierarchy +- Support both children slot and value dynamic value as content sources +- Have independent toggle logic for link component's ellipsis behavior + +Section Source + +- [frontend/antd/typography/title/Index.svelte:1-12](file://frontend/antd/typography/title/Index.svelte#L1-L12) +- [frontend/antd/typography/paragraph/Index.svelte:1-12](file://frontend/antd/typography/paragraph/Index.svelte#L1-L12) +- [frontend/antd/typography/text/Index.svelte:1-12](file://frontend/antd/typography/text/Index.svelte#L1-L12) +- [frontend/antd/typography/link/Index.svelte:1-12](file://frontend/antd/typography/link/Index.svelte#L1-L12) + +## Dependency Analysis + +- Component Coupling + - Sub-components only depend on Base.svelte, maintaining low coupling and high cohesion + - Base.svelte depends on bridge layer, responsible for cross-framework (Svelte → React) adaptation + - Bridge layer depends on Ant Design Typography, centrally handling interactive capabilities +- Slot and Target Resolution + - Uses useTargets and ReactSlot to implement slot-based capability injection, avoiding hardcoding +- External Dependencies + - Ant Design Typography: Provides basic capabilities for headings, paragraphs, text, and links + - Gradio/Svelte preprocessing tools: Provide property processing, slot context, and async component loading + +```mermaid +graph LR +Title["title/Index.svelte"] --> Base["Base.svelte"] +Paragraph["paragraph/Index.svelte"] --> Base +Text["text/Index.svelte"] --> Base +Link["link/Index.svelte"] --> Base +Base --> Bridge["typography.base.tsx"] +Bridge --> AD["Ant Design Typography"] +``` + +Diagram Source + +- [frontend/antd/typography/title/Index.svelte:9](file://frontend/antd/typography/title/Index.svelte#L9) +- [frontend/antd/typography/paragraph/Index.svelte:9](file://frontend/antd/typography/paragraph/Index.svelte#L9) +- [frontend/antd/typography/text/Index.svelte:9](file://frontend/antd/typography/text/Index.svelte#L9) +- [frontend/antd/typography/link/Index.svelte:9](file://frontend/antd/typography/link/Index.svelte#L9) +- [frontend/antd/typography/Base.svelte:11-13](file://frontend/antd/typography/Base.svelte#L11-L13) +- [frontend/antd/typography/typography.base.tsx:8](file://frontend/antd/typography/typography.base.tsx#L8) + +Section Source + +- [frontend/antd/typography/Base.svelte:11-13](file://frontend/antd/typography/Base.svelte#L11-L13) +- [frontend/antd/typography/typography.base.tsx:8](file://frontend/antd/typography/typography.base.tsx#L8) + +## Performance Considerations + +- Async Component Loading: Base.svelte loads bridge layer lazily through importComponent, reducing first-screen size +- Conditional Rendering: Only renders when visible is true; assembles ellipsis tooltip on demand, reducing unnecessary overhead +- Slot Rendering: Through useTargets and ReactSlot, only renders actually matched slot content, avoiding full traversal + +Section Source + +- [frontend/antd/typography/Base.svelte:11-13](file://frontend/antd/typography/Base.svelte#L11-L13) +- [frontend/antd/typography/typography.base.tsx:51-64](file://frontend/antd/typography/typography.base.tsx#L51-L64) + +## Troubleshooting Guide + +- Text Not Displaying + - Check whether Base.svelte's visible field is true + - Confirm whether children or value is correctly passed in +- Copy/Edit/Ellipsis Button Not Working + - Confirm whether copyable/editable/ellipsis configuration object or slots are correctly passed in + - For link component, confirm ellipsis enable condition +- Slot Icon/Tooltip Not Appearing + - Check whether slot key names match (like copyable.icon, copyable.tooltips, editable.icon, etc.) + - Confirm useTargets can correctly identify slot markers in children +- Style Abnormal + - Confirm whether elem_classes and elem_style are correctly injected + - Check whether namespace class names are overridden + +Section Source + +- [frontend/antd/typography/Base.svelte:30-62](file://frontend/antd/typography/Base.svelte#L30-L62) +- [frontend/antd/typography/typography.base.tsx:40-167](file://frontend/antd/typography/typography.base.tsx#L40-L167) + +## Conclusion + +The Typography component effectively connects Svelte with Ant Design capabilities through clear layered design, ensuring both semantics and maintainability, while providing rich interactive capabilities like copy, edit, and ellipsis. Its slot-based and conditional assembly mechanism enables good extensibility and performance in different scenarios. + +## Appendix + +- Usage examples and instructions can be found in the documentation page's example placeholder + - [docs/components/antd/typography/README.md:5-8](file://docs/components/antd/typography/README.md#L5-L8) diff --git a/.wiki/en/Ant Design Components/Layout Components/Divider.md b/.wiki/en/Ant Design Components/Layout Components/Divider.md new file mode 100644 index 00000000..5bcfcfde --- /dev/null +++ b/.wiki/en/Ant Design Components/Layout Components/Divider.md @@ -0,0 +1,291 @@ +# Divider + + +**Files referenced in this document** +- [divider.tsx](file://frontend/antd/divider/divider.tsx) +- [Index.svelte](file://frontend/antd/divider/Index.svelte) +- [__init__.py](file://backend/modelscope_studio/components/antd/divider/__init__.py) +- [components.py](file://backend/modelscope_studio/components/antd/components.py) +- [README.md](file://docs/components/antd/divider/README.md) +- [README-zh_CN.md](file://docs/components/antd/divider/README-zh_CN.md) +- [basic.py](file://docs/components/antd/divider/demos/basic.py) +- [basic.py (form)](file://docs/components/antd/form/demos/basic.py) +- [basic.py (layout)](file://docs/components/antd/layout/demos/basic.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance and Accessibility](#performance-and-accessibility) +8. [Usage Scenarios and Examples](#usage-scenarios-and-examples) +9. [Troubleshooting](#troubleshooting) +10. [Conclusion](#conclusion) + +## Introduction + +The Divider component creates visual separation between content sections, helping users quickly identify information blocks. Based on Ant Design's Divider, it supports horizontal and vertical orientations, multiple line styles (solid, dashed, dotted), centered and left/right-aligned title text, plain text style, and provides a flexible style override interface for consistent styling across different layouts and themes. + +## Project Structure + +The Divider component consists of a backend Python component class and a frontend Svelte wrapper. Props are passed in a Gradio-style through to the Ant Design React component, which is ultimately rendered as a visible divider in the browser. + +```mermaid +graph TB +subgraph "Backend" +PY_INIT["AntdDivider.__init__()
Python component class"] +PY_EXPORT["components.py export"] +end +subgraph "Frontend" +SVELTE_INDEX["Index.svelte
Prop handling and rendering"] +TS_WRAPPER["divider.tsx
sveltify wrapper"] +ANTD_REACT["antd.Divider
Ant Design React component"] +end +PY_INIT --> PY_EXPORT +PY_EXPORT --> SVELTE_INDEX +SVELTE_INDEX --> TS_WRAPPER +TS_WRAPPER --> ANTD_REACT +``` + +Diagram sources + +- [**init**.py:1-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L1-L95) +- [components.py:37-37](file://backend/modelscope_studio/components/antd/components.py#L37-L37) +- [Index.svelte:1-75](file://frontend/antd/divider/Index.svelte#L1-L75) +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) + +Section sources + +- [**init**.py:1-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L1-L95) +- [components.py:37-37](file://backend/modelscope_studio/components/antd/components.py#L37-L37) +- [Index.svelte:1-75](file://frontend/antd/divider/Index.svelte#L1-L75) +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) + +## Core Components + +- Backend component class: `AntdDivider`, responsible for defining props, default values, styles, and rendering strategy, and declaring frontend resource paths. +- Frontend wrapper: `Index.svelte` handles prop merging, style injection, and conditional rendering. `divider.tsx` uses `sveltify` to bridge Ant Design's React Divider as a Svelte-compatible component. + +Key responsibilities + +- Prop mapping: Maps Python-layer props (`dashed`, `variant`, `orientation`, `orientation_margin`, `plain`, `type`, `size`, `value`, `elem_style`, `elem_classes`, etc.) to the React Divider. +- Rendering branch: Determines whether to render a divider with text or a plain line based on whether `children` or `value` is provided. +- Style injection: Injects custom styles and class names via `elem_style` and `elem_classes`. + +Section sources + +- [**init**.py:21-76](file://backend/modelscope_studio/components/antd/divider/__init__.py#L21-L76) +- [Index.svelte:23-57](file://frontend/antd/divider/Index.svelte#L23-L57) +- [divider.tsx:5-12](file://frontend/antd/divider/divider.tsx#L5-L12) + +## Architecture Overview + +The diagram below shows the call chain and data flow from the Python component to the browser rendering. + +```mermaid +sequenceDiagram +participant Py as "Python Backend
AntdDivider" +participant Svelte as "Frontend
Index.svelte" +participant Wrapper as "Wrapper
divider.tsx" +participant AD as "Ant Design React
Divider" +Py->>Svelte : Pass props and value +Svelte->>Svelte : Process visible, styles, additional props +Svelte->>Wrapper : Render React Divider +Wrapper->>AD : Pass props including children/value +AD-->>Wrapper : Render DOM +Wrapper-->>Svelte : Return node +Svelte-->>Py : Complete one render +``` + +Diagram sources + +- [**init**.py:77-77](file://backend/modelscope_studio/components/antd/divider/__init__.py#L77-L77) +- [Index.svelte:60-74](file://frontend/antd/divider/Index.svelte#L60-L74) +- [divider.tsx:5-12](file://frontend/antd/divider/divider.tsx#L5-L12) + +## Detailed Component Analysis + +### Props and Configuration + +- Type and orientation + - `type`: horizontal | vertical — controls horizontal or vertical divider. + - `size`: small | middle | large (horizontal only) — affects the overall visual size. +- Line style + - `variant`: dashed | dotted | solid — controls the line style. + - `dashed`: boolean toggle (legacy compatibility), equivalent to `variant=dashed`. +- Text and alignment + - `value` or slot content: text displayed on the divider. + - `orientation`: left | right | center | start | end — controls text position. + - `orientation_margin`: number or string (parsed with unit if provided, as px otherwise) — sets the margin between text and edge. + - `plain`: whether to display text in plain style. +- Style and appearance + - `elem_style`: inject inline styles (e.g., `borderColor`). + - `elem_classes`: inject additional CSS classes. + - `root_class_name`: root element class name (passed by parent container). + - `additional_props`: other passthrough props. +- Layout and visibility + - `visible`: controls whether the component is rendered. + - `as_item`, `_internal`, `render`, etc.: framework-internal props that affect rendering context. + +Section sources + +- [**init**.py:21-76](file://backend/modelscope_studio/components/antd/divider/__init__.py#L21-L76) +- [Index.svelte:13-57](file://frontend/antd/divider/Index.svelte#L13-L57) + +### Rendering Logic and Branches + +- When children or `value` is present, renders a divider with text. +- Otherwise renders a plain line divider. +- Supports direct child node rendering in inner layout mode. + +```mermaid +flowchart TD +Start(["Enter render"]) --> CheckVisible{"visible is true?"} +CheckVisible --> |No| EndHidden["Do not render"] +CheckVisible --> |Yes| CheckInternal{"Inner layout mode?"} +CheckInternal --> |Yes| RenderWithChildren["Render Divider with children"] +CheckInternal --> |No| CheckValue{"Has value?"} +CheckValue --> |Yes| RenderWithValue["Render Divider with value"] +CheckValue --> |No| RenderPlain["Render plain line Divider"] +RenderWithChildren --> End(["Done"]) +RenderWithValue --> End +RenderPlain --> End +EndHidden --> End +``` + +Diagram sources + +- [Index.svelte:60-74](file://frontend/antd/divider/Index.svelte#L60-L74) + +### Text Centering and Alignment + +- Use `orientation=center` (or equivalent `start`/`end`) to center text. +- Use `orientation=left`/`right` or `orientation=start`/`end` combined with `orientation_margin` to control the spacing between text and edge. +- With `plain=True`, text is rendered in a lighter style, suitable for smaller font sizes or subtle hints. + +Section sources + +- [**init**.py:27-32](file://backend/modelscope_studio/components/antd/divider/__init__.py#L27-L32) +- [basic.py:11-26](file://docs/components/antd/divider/demos/basic.py#L11-L26) + +### Style Customization and Color Configuration + +- Inject `borderColor`, `borderWidth`, and other styles via `elem_style` for color and thickness customization. +- Inject custom CSS classes via `elem_classes` for complex theming needs. +- `variant` and `dashed` provide line style switching (solid/dashed/dotted). + +Section sources + +- [basic.py:11-26](file://docs/components/antd/divider/demos/basic.py#L11-L26) +- [**init**.py:26-32](file://backend/modelscope_studio/components/antd/divider/__init__.py#L26-L32) + +### Responsive Behavior and Screen Adaptation + +- The component does not have built-in media query logic, but responsive behavior can be achieved through `elem_style` and layout containers (such as Flex and Layout). +- In horizontal layouts, `size` can subtly adjust the overall visual size; in vertical layouts, `size` has no effect. +- On narrow screens, adjust `orientation` and margin in combination with container width and text length to avoid text truncation. + +Section sources + +- [**init**.py:32-34](file://backend/modelscope_studio/components/antd/divider/__init__.py#L32-L34) +- [basic.py (layout):42-88](file://docs/components/antd/layout/demos/basic.py#L42-L88) + +## Dependency Analysis + +- Backend export: `AntdDivider` is exported in the antd component collection for modular usage. +- Frontend bridging: `Index.svelte` dynamically loads `divider.tsx` via `importComponent`. The latter uses `sveltify` to wrap Ant Design's React Divider as a Svelte component. +- Prop passthrough: All props except framework-reserved fields are passed through to the React Divider, maintaining consistency with the Ant Design API. + +```mermaid +graph LR +A["components.py"] --> B["AntdDivider.__init__"] +B --> C["FRONTEND_DIR=resolve_frontend_dir('divider')"] +C --> D["Index.svelte"] +D --> E["divider.tsx"] +E --> F["antd.Divider"] +``` + +Diagram sources + +- [components.py:37-37](file://backend/modelscope_studio/components/antd/components.py#L37-L37) +- [**init**.py:77-77](file://backend/modelscope_studio/components/antd/divider/__init__.py#L77-L77) +- [Index.svelte:10-10](file://frontend/antd/divider/Index.svelte#L10-L10) +- [divider.tsx:3-3](file://frontend/antd/divider/divider.tsx#L3-L3) + +Section sources + +- [components.py:37-37](file://backend/modelscope_studio/components/antd/components.py#L37-L37) +- [**init**.py:77-77](file://backend/modelscope_studio/components/antd/divider/__init__.py#L77-L77) +- [Index.svelte:10-10](file://frontend/antd/divider/Index.svelte#L10-L10) +- [divider.tsx:3-3](file://frontend/antd/divider/divider.tsx#L3-L3) + +## Performance and Accessibility + +- Rendering overhead: The component is a lightweight pure display element. Dynamic import and conditional rendering avoid unnecessary repaints. +- Accessibility: Text content is rendered with semantic tags. For important dividers, providing a short description (e.g., `aria-label`) is recommended to improve screen reader experience. +- Theme consistency: Unify styles via `elem_style` and `elem_classes` to reduce redundant computations and style conflicts. + +[This section contains general recommendations and does not require specific file references] + +## Usage Scenarios and Examples + +### Form Grouping + +- Use dividers to group different business domains within a form, improving readability. +- Example reference: The form demo shows dividers used between form controls. + +Section sources + +- [basic.py (form):16-90](file://docs/components/antd/form/demos/basic.py#L16-L90) + +### Content Area Separation + +- Use horizontal dividers in articles or pages to separate paragraphs. Use `orientation=center` for title-style separators. +- Example reference: The basic demo shows different variants and dividers with text. + +Section sources + +- [basic.py:5-29](file://docs/components/antd/divider/demos/basic.py#L5-L29) + +### Navigation Menu Separation + +- Use vertical or horizontal dividers to separate menu items in navigation lists. On narrow screens, adjust `orientation` and margin to avoid text overflow. +- Recommendation: Prefer vertical dividers for side navigation and horizontal dividers for top or bottom navigation. + +[This subsection is conceptual; no specific file references required] + +### Behavior in Responsive Layouts + +- Use layout components like Flex and Layout to adjust divider orientation and text length at different screen sizes. +- Recommendation: On mobile, prefer horizontal dividers with shorter text. If necessary, hide the text and keep only the line. + +Section sources + +- [basic.py (layout):42-88](file://docs/components/antd/layout/demos/basic.py#L42-L88) + +## Troubleshooting + +- Text not displayed + - Check whether `value` or child content has been passed. If not, the component renders a plain line. + - Confirm that `visible` is `True`. +- Text position incorrect + - When `orientation` is set to left/right/start/end, use `orientation_margin` to adjust spacing. + - `plain` affects the visual weight of the text. Remove it if stronger separation is needed. +- Line style not applied + - `dashed` and `variant=dashed` are equivalent. Ensure no conflicting props are set simultaneously. + - `borderColor`, `borderWidth`, and other styles in `elem_style` must be compatible with the target platform. +- Vertical divider size not working + - `size` only applies to horizontal dividers. For vertical dividers, control the visual size via container width and border properties. + +Section sources + +- [Index.svelte:60-74](file://frontend/antd/divider/Index.svelte#L60-L74) +- [**init**.py:26-34](file://backend/modelscope_studio/components/antd/divider/__init__.py#L26-L34) + +## Conclusion + +The Divider component provides rich visual expression through a clean API, capable of both basic line separation and title-style dividers with text. Through multi-dimensional configuration of type, line style, alignment, and styling, it reliably implements information hierarchy and spatial separation across different layouts and themes. In practice, it is recommended to combine layout containers with responsive strategies, choose `orientation` and `size` appropriately, and use `elem_style`/`elem_classes` for brand and theme customization. diff --git a/.wiki/en/Ant Design Components/Layout Components/Flex.md b/.wiki/en/Ant Design Components/Layout Components/Flex.md new file mode 100644 index 00000000..8bb5cf98 --- /dev/null +++ b/.wiki/en/Ant Design Components/Layout Components/Flex.md @@ -0,0 +1,291 @@ +# Flex + + +**Files referenced in this document** +- [frontend/antd/flex/flex.tsx](file://frontend/antd/flex/flex.tsx) +- [frontend/antd/flex/Index.svelte](file://frontend/antd/flex/Index.svelte) +- [backend/modelscope_studio/components/antd/flex/__init__.py](file://backend/modelscope_studio/components/antd/flex/__init__.py) +- [docs/components/antd/flex/README.md](file://docs/components/antd/flex/README.md) +- [docs/components/antd/flex/demos/basic.py](file://docs/components/antd/flex/demos/basic.py) +- [docs/components/antd/flex/demos/align.py](file://docs/components/antd/flex/demos/align.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document provides a systematic description of the Flex layout component and its implementation and usage in ModelScope Studio. The Flex component is based on Ant Design's Flex container, offering main axis and cross axis alignment, layout direction, wrapping control, spacing configuration, and is bridged between frontend and backend via the Gradio ecosystem. The document covers the following topics from concept to practice: + +- Core concepts: main axis/cross axis, and correspondence to justify-content, align-items, align-content +- Key props: orientation/vertical, wrap, justify, align, flex, gap +- Practical scenarios: button group alignment, content area distribution, responsive card layouts +- Complex nested layouts and best practices +- Compatibility and cross-browser considerations + +## Project Structure + +The Flex component in this repository uses a layered design of "backend Python component + frontend Svelte wrapper + Ant Design Flex container": + +- Backend: Python class responsible for parameter validation, rendering strategy, and frontend resource location +- Frontend: Svelte component responsible for dynamic import, prop passthrough, and style concatenation +- Dependencies: React/Ant Design components are bridged to Svelte via `svelte-preprocess-react` + +```mermaid +graph TB +subgraph "Backend" +PY["AntdFlex
Python component"] +DEV["ModelScopeLayoutComponent
Base layout component"] +end +subgraph "Frontend" +IDX["Index.svelte
Dynamic import wrapper"] +FLEX_TS["flex.tsx
sveltify wrapper"] +ANTDFLEX["Ant Design Flex
Container"] +end +subgraph "Docs and Examples" +DOC["README.md"] +DEMO1["basic.py example"] +DEMO2["align.py example"] +end +PY --> IDX +DEV --> PY +IDX --> FLEX_TS +FLEX_TS --> ANTDFLEX +DOC --> DEMO1 +DOC --> DEMO2 +``` + +Diagram sources + +- [backend/modelscope_studio/components/antd/flex/**init**.py:8-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L8-L98) +- [frontend/antd/flex/Index.svelte:10-61](file://frontend/antd/flex/Index.svelte#L10-L61) +- [frontend/antd/flex/flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [docs/components/antd/flex/README.md:1-9](file://docs/components/antd/flex/README.md#L1-L9) + +Section sources + +- [backend/modelscope_studio/components/antd/flex/**init**.py:8-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L8-L98) +- [frontend/antd/flex/Index.svelte:1-62](file://frontend/antd/flex/Index.svelte#L1-L62) +- [frontend/antd/flex/flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [docs/components/antd/flex/README.md:1-9](file://docs/components/antd/flex/README.md#L1-L9) + +## Core Components + +- AntdFlex (backend) + - Receives and validates all Flex-related parameters (direction, wrapping, main axis/cross axis alignment, flex shorthand, gap, etc.) and maps them to frontend-consumable props. + - Provides `FRONTEND_DIR` pointing to the frontend flex directory, ensuring the frontend component is loaded correctly at runtime. + - Follows the layout semantics of `ModelScopeLayoutComponent` and participates in the application-level layout context. + +- Index.svelte (frontend wrapper) + - Dynamically imports the frontend flex component via `importComponent`, avoiding first-screen blocking. + - Retrieves and processes component props via `getProps`/`processProps`, supporting additional prop passthrough and visibility control. + - Injects generic props like `elem_id`, `elem_classes`, and `elem_style` into the final render node. + +- flex.tsx (Svelte wrapper) + - Uses `sveltify` to convert Ant Design's Flex container into a Svelte-compatible component, passing props and children through directly. + +- Docs and examples + - `README.md` provides basic description and example placeholders. + - `basic.py` and `align.py` demonstrate interactive examples for vertical/horizontal direction switching and main axis/cross axis alignment. + +Section sources + +- [backend/modelscope_studio/components/antd/flex/**init**.py:21-79](file://backend/modelscope_studio/components/antd/flex/__init__.py#L21-L79) +- [frontend/antd/flex/Index.svelte:13-42](file://frontend/antd/flex/Index.svelte#L13-L42) +- [frontend/antd/flex/flex.tsx:4-8](file://frontend/antd/flex/flex.tsx#L4-L8) +- [docs/components/antd/flex/README.md:1-9](file://docs/components/antd/flex/README.md#L1-L9) +- [docs/components/antd/flex/demos/basic.py:8-23](file://docs/components/antd/flex/demos/basic.py#L8-L23) +- [docs/components/antd/flex/demos/align.py:8-41](file://docs/components/antd/flex/demos/align.py#L8-L41) + +## Architecture Overview + +The diagram below shows the call chain from user code to the final render, illustrating the collaboration between the Flex component's frontend and backend: + +```mermaid +sequenceDiagram +participant U as "User code" +participant PY as "AntdFlex (backend)" +participant IDX as "Index.svelte (frontend wrapper)" +participant F as "flex.tsx (Svelte wrapper)" +participant AD as "Ant Design Flex" +U->>PY : Create AntdFlex and pass params +PY->>IDX : Resolve FRONTEND_DIR and render +IDX->>F : Dynamically import Antd Flex component +F->>AD : Pass through props and children +AD-->>U : Rendered flexible layout container +``` + +Diagram sources + +- [backend/modelscope_studio/components/antd/flex/**init**.py:81-81](file://backend/modelscope_studio/components/antd/flex/__init__.py#L81-L81) +- [frontend/antd/flex/Index.svelte:10-10](file://frontend/antd/flex/Index.svelte#L10-L10) +- [frontend/antd/flex/flex.tsx:4-8](file://frontend/antd/flex/flex.tsx#L4-L8) + +## Detailed Component Analysis + +### Backend Class: AntdFlex Props and Behavior + +- Key props + - `orientation`/`vertical`: controls layout direction (horizontal/vertical) + - `wrap`: controls single-line or multi-line display + - `justify`: main axis alignment (start/end/center/flex-start/flex-end/space-\* etc.) + - `align`: cross axis alignment (start/end/center/flex-start/flex-end/baseline/stretch etc.) + - `flex`: flex shorthand property + - `gap`: element spacing (small/middle/large or numeric value) + - `component`/`root_class_name`/`class_names`/`styles`/`as_item`/`_internal`: generic props and style injection + - Visibility and DOM injection: `elem_id`/`elem_classes`/`elem_style`/`visible`/`render` + +- Behavioral characteristics + - `skip_api=True`: not exposed as a standard API component; suitable for internal layout use + - `FRONTEND_DIR` points to the frontend flex directory, ensuring component availability at runtime + - Inherits from `ModelScopeLayoutComponent`, providing layout context capabilities + +Section sources + +- [backend/modelscope_studio/components/antd/flex/**init**.py:21-79](file://backend/modelscope_studio/components/antd/flex/__init__.py#L21-L79) +- [backend/modelscope_studio/utils/dev/component.py:11-52](file://backend/modelscope_studio/utils/dev/component.py#L11-L52) + +### Frontend Wrapper: Index.svelte + +- Dynamic import: lazy-loads `flex.tsx` via `importComponent`, reducing first-screen overhead +- Prop processing: `getProps`/`processProps` extracts and merges component props, additional props, visibility, and DOM injection +- Style concatenation: `elem_classes` combined with fixed class names; `elem_id`/`elem_style` injected into the root node +- Conditional rendering: controls rendering based on `visible` + +Section sources + +- [frontend/antd/flex/Index.svelte:13-42](file://frontend/antd/flex/Index.svelte#L13-L42) +- [frontend/antd/flex/Index.svelte:48-61](file://frontend/antd/flex/Index.svelte#L48-L61) + +### Svelte Wrapper: flex.tsx + +- Uses `sveltify` to bridge Ant Design's Flex container as a Svelte component +- Passes props and children through directly, maintaining consistent semantics with Antd Flex + +Section sources + +- [frontend/antd/flex/flex.tsx:4-8](file://frontend/antd/flex/flex.tsx#L4-L8) + +### Examples: Basic and Alignment + +- `basic.py`: demonstrates vertical/horizontal direction switching and spacing configuration +- `align.py`: demonstrates main axis/cross axis alignment options and interactive updates + +Section sources + +- [docs/components/antd/flex/demos/basic.py:8-23](file://docs/components/antd/flex/demos/basic.py#L8-L23) +- [docs/components/antd/flex/demos/align.py:8-41](file://docs/components/antd/flex/demos/align.py#L8-L41) + +### Key Props and CSS Flex Correspondence + +- Main axis and cross axis + - Main axis: determined by layout direction (horizontal/vertical corresponds to row/column) + - Cross axis: perpendicular to the main axis +- Alignment mapping + - `justify-content` ↔ `justify` (main axis alignment) + - `align-items` ↔ `align` (cross axis alignment) + - `align-content` ↔ cross axis distribution for multi-line (effective when `wrap` is `wrap`/`wrap-reverse`) + +Section sources + +- [backend/modelscope_studio/components/antd/flex/**init**.py:52-58](file://backend/modelscope_studio/components/antd/flex/__init__.py#L52-L58) + +### Practical Application Scenarios + +- Button group alignment: use `justify`/`align` to quickly achieve horizontal or vertical centering, space-between, etc. +- Content area distribution: use `gap` and `wrap` for responsive grids with wrapping +- Responsive card layouts: combine `orientation`/`vertical` with `justify`/`align` for card flow arrangement + +Section sources + +- [docs/components/antd/flex/demos/basic.py:8-23](file://docs/components/antd/flex/demos/basic.py#L8-L23) +- [docs/components/antd/flex/demos/align.py:8-41](file://docs/components/antd/flex/demos/align.py#L8-L41) + +### Complex Nested Layouts and Best Practices + +- Nesting strategy + - Outer containers set main axis alignment and wrapping; inner containers focus on cross axis alignment + - Use `gap` to control spacing between levels, avoiding hard-coded margin/padding +- Best practices + - First use `vertical`/`orientation` to control direction, then fine-tune with `justify`/`align` + - In multi-line scenarios, choose `wrap` and `align-content` combinations carefully + - Combine with interactive components (such as Segmented) to dynamically switch alignment, improving discoverability + +Section sources + +- [docs/components/antd/flex/demos/align.py:8-41](file://docs/components/antd/flex/demos/align.py#L8-L41) + +## Dependency Analysis + +- Component coupling + - `AntdFlex` only depends on the frontend flex directory, resolved via `FRONTEND_DIR`, reducing coupling + - `Index.svelte` and `flex.tsx` are loosely coupled; the former handles runtime loading, the latter handles bridging +- External dependencies + - Ant Design Flex: provides core layout capability + - svelte-preprocess-react: provides `sveltify` and dynamic import utilities +- Potential circular dependencies + - No obvious circular dependencies in the current structure. Avoid inter-referencing backend components if extending in the future. + +```mermaid +graph LR +PY["AntdFlex (backend)"] --> |FRONTEND_DIR| FE["flex frontend directory"] +IDX["Index.svelte"] --> |dynamic import| FLEX_TS["flex.tsx"] +FLEX_TS --> |sveltify| AD["Ant Design Flex"] +``` + +Diagram sources + +- [backend/modelscope_studio/components/antd/flex/**init**.py:81-81](file://backend/modelscope_studio/components/antd/flex/__init__.py#L81-L81) +- [frontend/antd/flex/Index.svelte:10-10](file://frontend/antd/flex/Index.svelte#L10-L10) +- [frontend/antd/flex/flex.tsx:4-8](file://frontend/antd/flex/flex.tsx#L4-L8) + +Section sources + +- [backend/modelscope_studio/components/antd/flex/**init**.py:81-81](file://backend/modelscope_studio/components/antd/flex/__init__.py#L81-L81) +- [frontend/antd/flex/Index.svelte:10-10](file://frontend/antd/flex/Index.svelte#L10-L10) +- [frontend/antd/flex/flex.tsx:4-8](file://frontend/antd/flex/flex.tsx#L4-L8) + +## Performance Considerations + +- Dynamic import optimization: `Index.svelte` uses `importComponent` for lazy loading, reducing first-screen bundle size and render time +- Minimal prop passthrough: only necessary props are passed, avoiding redundant computation and reflow +- Spacing and wrapping: use `gap` and `wrap` appropriately to avoid complex layout reflows caused by excessive nesting + +## Troubleshooting Guide + +- Component not visible + - Check if `visible` is `true` + - Confirm that `elem_style`/`elem_classes` are not causing overflow or hidden behavior +- Direction and alignment issues + - Confirm that the combination of `orientation`/`vertical` and `justify`/`align` matches expectations + - In multi-line scenarios, check the effect of `wrap` and `align-content` +- Runtime load failure + - Confirm that `FRONTEND_DIR` points to the correct location and the frontend package is built + - Check for errors in the dynamic import (`{#await}` branch in `Index.svelte`) + +Section sources + +- [frontend/antd/flex/Index.svelte:48-61](file://frontend/antd/flex/Index.svelte#L48-L61) +- [backend/modelscope_studio/components/antd/flex/**init**.py:81-81](file://backend/modelscope_studio/components/antd/flex/__init__.py#L81-L81) + +## Conclusion + +The Flex layout component in ModelScope Studio is implemented as "backend params + frontend wrapper + Antd Flex container", maintaining semantic consistency with CSS Flex while providing good configurability and maintainability. Through key props such as `orientation`/`vertical`, `wrap`, `justify`, `align`, `flex`, and `gap`, it efficiently covers common scenarios including button group alignment, content area distribution, and responsive card layouts. Combined with dynamic import and prop passthrough mechanisms, it balances performance and flexibility. + +## Appendix + +- Example entry points + - Basic example: [basic.py:1-26](file://docs/components/antd/flex/demos/basic.py#L1-L26) + - Alignment example: [align.py:1-45](file://docs/components/antd/flex/demos/align.py#L1-L45) +- Documentation: [README.md:1-9](file://docs/components/antd/flex/README.md#L1-L9) diff --git a/.wiki/en/Ant Design Components/Layout Components/Grid.md b/.wiki/en/Ant Design Components/Layout Components/Grid.md new file mode 100644 index 00000000..51992779 --- /dev/null +++ b/.wiki/en/Ant Design Components/Layout Components/Grid.md @@ -0,0 +1,348 @@ +# Grid + + +**Files referenced in this document** +- [frontend/antd/grid/row/Index.svelte](file://frontend/antd/grid/row/Index.svelte) +- [frontend/antd/grid/row/row.tsx](file://frontend/antd/grid/row/row.tsx) +- [frontend/antd/grid/col/Index.svelte](file://frontend/antd/grid/col/Index.svelte) +- [frontend/antd/grid/col/col.tsx](file://frontend/antd/grid/col/col.tsx) +- [frontend/antd/grid/context.ts](file://frontend/antd/grid/context.ts) +- [backend/modelscope_studio/components/antd/grid/row/__init__.py](file://backend/modelscope_studio/components/antd/grid/row/__init__.py) +- [backend/modelscope_studio/components/antd/grid/col/__init__.py](file://backend/modelscope_studio/components/antd/grid/col/__init__.py) +- [docs/components/antd/grid/README.md](file://docs/components/antd/grid/README.md) +- [docs/components/antd/grid/demos/basic.py](file://docs/components/antd/grid/demos/basic.py) +- [docs/components/antd/grid/demos/playground.py](file://docs/components/antd/grid/demos/playground.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document provides a systematic description of the Grid component, covering its design principles, the 24-column grid system, and responsive breakpoint configuration. It explains how to use Row and Col in depth (including grid offset, ordering, nesting rules, and alignment), provides application ideas for common scenarios such as dashboard layouts, product display pages, and form layouts, and includes responsive behavior descriptions and performance optimization recommendations. + +## Project Structure + +The Grid component is built through collaboration between a frontend Svelte wrapper layer and a backend Python component layer: the frontend handles rendering and context passing, while the backend handles parameter passthrough and lifecycle management. The docs side provides examples and explanations. + +```mermaid +graph TB +subgraph "Backend Components" +PY_ROW["Python Row component
backend/modelscope_studio/components/antd/grid/row/__init__.py"] +PY_COL["Python Col component
backend/modelscope_studio/components/antd/grid/col/__init__.py"] +end +subgraph "Frontend Wrapper" +IDX_ROW["Row wrapper entry
frontend/antd/grid/row/Index.svelte"] +ROW_IMPL["Row implementation
frontend/antd/grid/row/row.tsx"] +IDX_COL["Col wrapper entry
frontend/antd/grid/col/Index.svelte"] +COL_IMPL["Col implementation
frontend/antd/grid/col/col.tsx"] +CTX["Grid context
frontend/antd/grid/context.ts"] +end +PY_ROW --> IDX_ROW --> ROW_IMPL +PY_COL --> IDX_COL --> COL_IMPL +ROW_IMPL --> CTX +COL_IMPL --> CTX +``` + +**Diagram sources** + +- [frontend/antd/grid/row/Index.svelte:1-61](file://frontend/antd/grid/row/Index.svelte#L1-L61) +- [frontend/antd/grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [frontend/antd/grid/col/Index.svelte:1-77](file://frontend/antd/grid/col/Index.svelte#L1-L77) +- [frontend/antd/grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:1-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L1-L94) +- [backend/modelscope_studio/components/antd/grid/col/**init**.py:1-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L1-L114) + +**Section sources** + +- [frontend/antd/grid/row/Index.svelte:1-61](file://frontend/antd/grid/row/Index.svelte#L1-L61) +- [frontend/antd/grid/col/Index.svelte:1-77](file://frontend/antd/grid/col/Index.svelte#L1-L77) +- [frontend/antd/grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [frontend/antd/grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:1-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L1-L94) +- [backend/modelscope_studio/components/antd/grid/col/**init**.py:1-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L1-L114) + +## Core Components + +- Row component + - Supports alignment, gutter, wrapping, and other props for holding multiple columns and managing layout direction and distribution. + - Key props: `align`, `justify`, `gutter`, `wrap`, etc. +- Col component + - Supports span, offset, ordering, left/right pushing, and responsive breakpoints for specific content blocks. + - Key props: `span`, `offset`, `order`, `pull`, `push`, `xs`/`sm`/`md`/`lg`/`xl`/`xxl`, etc. + +All of the above props are explicitly declared with default values in the backend component, making them directly usable from the Python layer. + +**Section sources** + +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:30-76](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L30-L76) +- [backend/modelscope_studio/components/antd/grid/col/**init**.py:30-95](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L30-L95) + +## Architecture Overview + +The runtime flow of Grid is as follows: the backend Python component receives params and renders the frontend wrapper; the frontend wrapper then calls the Ant Design Row/Col implementation and collects Col children via context, ultimately assembling the standard grid layout. + +```mermaid +sequenceDiagram +participant PyRow as "Backend Row component" +participant IdxRow as "Row wrapper entry" +participant RowImpl as "Row implementation" +participant Ctx as "Grid context" +participant PyCol as "Backend Col component" +participant IdxCol as "Col wrapper entry" +participant ColImpl as "Col implementation" +PyRow->>IdxRow : Render row wrapper +IdxRow->>RowImpl : Pass row params +PyCol->>IdxCol : Render col wrapper +IdxCol->>ColImpl : Pass col params +ColImpl->>Ctx : Register col item +RowImpl->>Ctx : Consume col items and render +RowImpl-->>IdxRow : Output Row container +IdxRow-->>PyRow : Return render result +``` + +**Diagram sources** + +- [frontend/antd/grid/row/Index.svelte:10-44](file://frontend/antd/grid/row/Index.svelte#L10-L44) +- [frontend/antd/grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [frontend/antd/grid/col/Index.svelte:10-47](file://frontend/antd/grid/col/Index.svelte#L10-L47) +- [frontend/antd/grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) +- [frontend/antd/grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) + +## Detailed Component Analysis + +### Row Component Analysis + +- Design notes + - Based on Ant Design Row, supports horizontal alignment (`justify`), vertical alignment (`align`), gutter, and auto-wrapping (`wrap`). + - Collects Col children via context and renders them uniformly, avoiding hard-coded child elements in Row. +- Usage recommendations + - In complex layouts, set `gutter` first to ensure consistency across breakpoints. + - Use `wrap` appropriately to avoid horizontal scrolling from long lists. +- Key props + - `align`: top/middle/bottom/stretch + - `justify`: start/end/center/space-between/space-around/space-evenly + - `gutter`: number or object (with breakpoints) or array [horizontal, vertical] + - `wrap`: boolean + +```mermaid +classDiagram +class Row { ++align ++justify ++gutter ++wrap ++render() +} +class Context { ++register(item) ++collect() +} +Row --> Context : "consume col items" +``` + +**Diagram sources** + +- [frontend/antd/grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [frontend/antd/grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) + +**Section sources** + +- [frontend/antd/grid/row/Index.svelte:12-42](file://frontend/antd/grid/row/Index.svelte#L12-L42) +- [frontend/antd/grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:30-76](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L30-L76) + +### Col Component Analysis + +- Design notes + - Based on Ant Design Col, supports `span`, `offset`, `order`, `pull`, `push`, and other basic capabilities. + - Supports responsive breakpoints xs/sm/md/lg/xl/xxl; each can specify a span value or a full attribute object. + - Registers itself via context for Row to dispatch uniformly. +- Usage recommendations + - Plan each row so total span does not exceed 24; overflowing columns will wrap automatically. + - Use `offset`/`push`/`pull` for visual offset and reordering, but be mindful of accessibility and semantics. + - On mobile, prioritize `xs`; use larger breakpoints on desktop for consistent device experience. +- Key props + - `span`: number of grid cells occupied (0 means not displayed) + - `offset`/`push`/`pull`: offset/left-shift/right-shift + - `order`: ordering + - `xs`/`sm`/`md`/`lg`/`xl`/`xxl`: breakpoint-level configuration + +```mermaid +classDiagram +class Col { ++span ++offset ++order ++pull ++push ++xs/sm/md/lg/xl/xxl ++render() +} +class Context { ++register(item) ++collect() +} +Col --> Context : "register to context" +``` + +**Diagram sources** + +- [frontend/antd/grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) +- [frontend/antd/grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) +- [backend/modelscope_studio/components/antd/grid/col/**init**.py:30-95](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L30-L95) + +**Section sources** + +- [frontend/antd/grid/col/Index.svelte:23-47](file://frontend/antd/grid/col/Index.svelte#L23-L47) +- [frontend/antd/grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) +- [backend/modelscope_studio/components/antd/grid/col/**init**.py:30-95](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L30-L95) + +### Responsive Breakpoints and Behavior + +- Breakpoint definitions + - xs: screen width less than 576px, also the default breakpoint + - sm: ≥ 576px + - md: ≥ 768px + - lg: ≥ 992px + - xl: ≥ 1200px + - xxl: ≥ 1600px +- Configuration methods + - Can pass an integer span directly, or pass an object to configure span and other props (such as offset, order) per breakpoint. +- Behavioral notes + - When the total span of all columns in a row exceeds 24, the overflowing columns will wrap to the next line. + - `gutter` supports breakpoint-level configuration, enabling different spacing at different screen sizes. + +**Section sources** + +- [backend/modelscope_studio/components/antd/grid/col/**init**.py:58-72](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L58-L72) +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:54-60](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L54-L60) + +### Nesting Rules and Alignment + +- Nesting rules + - Only place Col inside Row; Col can continue to nest Row to form nested grids. + - Avoid excessively deep nesting to prevent styling and maintainability issues. +- Alignment + - Row provides horizontal (`justify`) and vertical (`align`) alignment. Combined with `gutter`, stable layouts are achieved. + - Vertical alignment supports `stretch`, which allows column heights to adapt to the container height. + +**Section sources** + +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:34-40](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L34-L40) +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:56-59](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L56-L59) + +### Practical Application Cases + +- Dashboard layout + - Use Row's `gutter` and `wrap` to control card spacing and wrapping. Col's `span` and responsive breakpoints adapt to multiple screen sizes. + - Reduce columns on narrow screens and increase on wide screens to maintain information density and readability. +- Product display page + - Hero image area uses a single full-width column; product list uses equal-width columns; sidebar uses a fixed span, main content adapts. + - Use xs/sm/md/lg/xl/xxl to configure different column counts and spacing for each breakpoint. +- Form layout + - Small form fields use smaller spans; composite fields use larger spans. On xs, merge into a single column to improve mobile usability. + - Use `offset` for fine-tuning, but avoid excessive offset that affects reading order. + +(The above are general layout strategy descriptions; see examples for specific implementations.) + +**Section sources** + +- [docs/components/antd/grid/README.md:1-9](file://docs/components/antd/grid/README.md#L1-L9) +- [docs/components/antd/grid/demos/basic.py:7-24](file://docs/components/antd/grid/demos/basic.py#L7-L24) +- [docs/components/antd/grid/demos/playground.py:17-90](file://docs/components/antd/grid/demos/playground.py#L17-L90) + +## Dependency Analysis + +- Component coupling + - Col registers itself via context; Row collects and renders from context, reducing direct coupling. + - Frontend wrapper components are only responsible for prop passthrough and rendering; logic is concentrated in the Row/Col implementations and context. +- External dependencies + - Depends on Ant Design's Row/Col components, reusing their mature grid system. + - Uses the Svelte Preprocess React toolchain for bridging and slot handling. + +```mermaid +graph LR +PY_ROW["Backend Row component"] --> IDX_ROW["Row wrapper entry"] +IDX_ROW --> ROW_IMPL["Row implementation"] +PY_COL["Backend Col component"] --> IDX_COL["Col wrapper entry"] +IDX_COL --> COL_IMPL["Col implementation"] +ROW_IMPL --> CTX["Grid context"] +COL_IMPL --> CTX +ROW_IMPL --> ANTDESIGN["Ant Design Row/Col"] +COL_IMPL --> ANTDESIGN +``` + +**Diagram sources** + +- [frontend/antd/grid/row/Index.svelte:10-18](file://frontend/antd/grid/row/Index.svelte#L10-L18) +- [frontend/antd/grid/col/Index.svelte:10-21](file://frontend/antd/grid/col/Index.svelte#L10-L21) +- [frontend/antd/grid/row/row.tsx:3-5](file://frontend/antd/grid/row/row.tsx#L3-L5) +- [frontend/antd/grid/col/col.tsx:3-5](file://frontend/antd/grid/col/col.tsx#L3-L5) +- [frontend/antd/grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) + +**Section sources** + +- [frontend/antd/grid/row/Index.svelte:10-44](file://frontend/antd/grid/row/Index.svelte#L10-L44) +- [frontend/antd/grid/col/Index.svelte:10-47](file://frontend/antd/grid/col/Index.svelte#L10-L47) +- [frontend/antd/grid/row/row.tsx:3-5](file://frontend/antd/grid/row/row.tsx#L3-L5) +- [frontend/antd/grid/col/col.tsx:3-5](file://frontend/antd/grid/col/col.tsx#L3-L5) +- [frontend/antd/grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) + +## Performance Considerations + +- Reduce unnecessary re-renders + - Split sub-components appropriately to avoid frequent full-row updates. Statically define Col responsive breakpoint configurations as much as possible to reduce dynamic computation. +- Limit nesting depth + - Deeper nesting increases style computation and layout costs. It is recommended not to exceed three levels of nesting. +- Use gutter wisely + - Many small gaps may trigger frequent reflows. Set `gutter` on the Row level rather than on individual Cols. +- Choose appropriate breakpoints + - Enable responsive configuration only at necessary breakpoints to avoid rendering overhead from too many conditional branches. +- Use span and wrap + - Reasonable span allocation and wrapping reduce complex computation and extra DOM structures. + +(This section contains general optimization recommendations and does not involve specific file analysis.) + +## Troubleshooting Guide + +- Col not showing or misaligned + - Check whether the total span per row exceeds 24; overflowing columns will wrap. + - Check for conflicts in xs/sm/md/lg/xl/xxl breakpoint configurations. +- Offset/ordering not working + - Confirm that Col's `offset`/`push`/`pull`/`order` are taking effect at the correct breakpoint. + - Ensure Row's `justify`/`align` is not overriding the expected visual result. +- Responsive not working + - Confirm that breakpoint param types are objects containing the correct attributes (e.g., span, offset). + - Confirm that the parent Row's `gutter`/`justify`/`align` is not conflicting with the breakpoint configuration. +- Performance issues + - Check for deep nesting and excessive dynamic computation; simplify the layout structure if needed. + - Avoid setting the same spacing and styles on each Col repeatedly; configure at the Row level instead. + +**Section sources** + +- [backend/modelscope_studio/components/antd/grid/col/**init**.py:58-72](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L58-L72) +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:54-60](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L54-L60) + +## Conclusion + +The Grid component, through collaboration between backend params and frontend wrappers, provides grid capabilities consistent with Ant Design, while enhancing responsive breakpoints and context-based collection mechanisms. Using Row/Col's alignment, gutter, nesting, and breakpoint configuration appropriately enables stable, maintainable layout solutions to be built quickly across multiple scenarios. + +## Appendix + +- Example entry points + - Basic example: [docs/components/antd/grid/demos/basic.py:7-24](file://docs/components/antd/grid/demos/basic.py#L7-L24) + - Playground example: [docs/components/antd/grid/demos/playground.py:17-90](file://docs/components/antd/grid/demos/playground.py#L17-L90) +- Documentation: [docs/components/antd/grid/README.md:1-9](file://docs/components/antd/grid/README.md#L1-L9) diff --git a/.wiki/en/Ant Design Components/Layout Components/Layout Components.md b/.wiki/en/Ant Design Components/Layout Components/Layout Components.md new file mode 100644 index 00000000..ee16aecc --- /dev/null +++ b/.wiki/en/Ant Design Components/Layout Components/Layout Components.md @@ -0,0 +1,385 @@ +# Layout Components + + +**Files referenced in this document** +- [divider.tsx](file://frontend/antd/divider/divider.tsx) +- [flex.tsx](file://frontend/antd/flex/flex.tsx) +- [layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) +- [space.tsx](file://frontend/antd/space/space.tsx) +- [splitter.tsx](file://frontend/antd/splitter/splitter.tsx) +- [context.ts](file://frontend/antd/grid/context.ts) +- [col.tsx](file://frontend/antd/grid/col/col.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance and Responsive Behavior](#performance-and-responsive-behavior) +8. [Mobile and Screen Adaptation](#mobile-and-screen-adaptation) +9. [Troubleshooting](#troubleshooting) +10. [Conclusion](#conclusion) +11. [Appendix: Complex Page Layout Examples and Best Practices](#appendix-complex-page-layout-examples-and-best-practices) + +## Introduction + +This chapter is intended for developers using Ant Design layout components. It systematically covers the implementation and usage of Divider, Flex, Grid, Layout, Space, Splitter, and Masonry components in this repository. The documentation focuses on the layout algorithm concepts, responsive behavior, nesting rules, and composition patterns of each component, along with recommendations for mobile adaptation and screen size compatibility. + +## Project Structure + +These layout components reside in the `antd` submodule of the frontend directory. They adopt a unified "Svelte wrapping React components" strategy (bridging Ant Design React components to Svelte via `sveltify`), and in some cases introduce context and utility functions to support more complex layout capabilities (such as grid column collection and splitter panel item rendering). + +```mermaid +graph TB +subgraph "Antd Layout Components" +D["Divider"] +F["Flex"] +L["Layout.Base"] +S["Space"] +SP["Splitter"] +G["Grid.Context"] +GC["Grid.Col"] +end +D --> |"uses Ant Design"| D +F --> |"uses Ant Design"| F +L --> |"uses Ant Design"| L +S --> |"uses Ant Design"| S +SP --> |"uses Ant Design"| SP +GC --> |"consumes context"| G +``` + +Diagram sources + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +Section sources + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +## Core Components + +- **Divider**: A lightweight wrapper around Ant Design's Divider. Renders an empty divider when no children are present, or a divider with content when children are provided. +- **Flex**: A simple wrapper around Ant Design's Flex that passes through all props and children directly. +- **Layout.Base**: Dynamically selects between Header, Footer, Content, or Layout based on the `component` prop, and injects CSS class names to distinguish layout regions. +- **Space**: Extends Ant Design's Space with slot rendering and `split` slot support. Internally uses `useTargets` to map children to a target collection. +- **Splitter**: Extends Ant Design's Splitter with context-based default panel collection, passing each panel's element and props through to `Panel`. +- **Grid**: Collects columns (Col) via context and injects them into Row/Col rendering logic. The Col component registers itself into the context via `ItemHandler`. +- **Masonry**: Based on Ant Design's Masonry component, supports responsive column count configuration and automatic item height adjustment. Ideal for image walls, card streams, and other unequal-height layout scenarios. Refer to [Masonry](file://.qoder/repowiki/en/content/Ant%20Design%20Components/Layout%20Components/Masonry.md) for details. + +Section sources + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +## Architecture Overview + +The diagram below shows the dependency and collaboration relationships among the layout components: Space and Splitter resolve child nodes and establish target mappings before rendering; Layout.Base dynamically selects the specific layout sub-component; Grid collects Col instances via context and participates in grid layout rendering. + +```mermaid +graph LR +A["Space"] --> B["ReactSlot Rendering"] +C["Splitter"] --> D["Panel List Rendering"] +E["Layout.Base"] --> F["Header/Footer/Content/Layout"] +G["Grid.Col"] --> H["Grid.Context Collection"] +H --> I["Row/Col Rendering"] +``` + +Diagram sources + +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +## Component Details + +### Divider + +- Implementation notes + - Wraps Ant Design's Divider using `sveltify`. + - Renders a divider with children when children are present; otherwise renders an empty divider. +- Nesting rules + - Used as a separator; can be placed inside any container without affecting the parent's layout mode. +- Responsive behavior + - Determined by Ant Design; no breakpoint control by default. +- Typical usage + - Insert dividers between list items, form sections, or cards to enhance visual hierarchy. + +Section sources + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) + +### Flex + +- Implementation notes + - Wraps Ant Design's Flex using `sveltify`, passing all props and children through directly. +- Layout algorithm + - Follows the Flexbox specification, supporting main axis, cross axis, wrapping, alignment, and other common properties. +- Nesting rules + - Flex can nest other Flex, Grid, Space, and layout components to form composite layouts. +- Responsive behavior + - Flex properties can change at breakpoints to achieve adaptive layouts using Ant Design's breakpoint configuration. +- Typical usage + - Header navigation, card groups, button groups, and other scenarios requiring flexible alignment and distribution. + +Section sources + +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) + +### Layout.Base + +- Implementation notes + - Dynamically selects between rendering Header, Footer, Content, or Layout based on the `component` prop. + - Injects CSS class names for non-layout sub-components to facilitate styling and debugging. +- Layout algorithm + - Implements page frame layout using Ant Design's Layout family of components. +- Nesting rules + - Header/Footer/Content must be direct children of Layout; Sider and other sub-components can be nested inside. +- Responsive behavior + - Achieves a responsive sidebar by combining Sider collapse/expand behavior with breakpoint strategies. +- Typical usage + - Overall page framework: top navigation + side menu + main content + footer. + +```mermaid +flowchart TD +Start(["Enter Layout.Base"]) --> CheckComp{"component type"} +CheckComp --> |header| RenderHeader["Render Header"] +CheckComp --> |footer| RenderFooter["Render Footer"] +CheckComp --> |content| RenderContent["Render Content"] +CheckComp --> |layout| RenderLayout["Render Layout"] +RenderHeader --> End(["Done"]) +RenderFooter --> End +RenderContent --> End +RenderLayout --> End +``` + +Diagram sources + +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +Section sources + +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +### Space + +- Implementation notes + - Uses Ant Design's Space and extends it with slot rendering and `split` slot support. + - Internally maps children to a target collection via `useTargets`, then renders them through `ReactSlot`. +- Layout algorithm + - Calculates spacing between elements based on direction and size, supporting wrapping and compact composition modes. +- Nesting rules + - Can nest any component; the `split` slot is used to render separators. +- Responsive behavior + - Spacing values can change at breakpoints to optimize spacing for different screen sizes. +- Typical usage + - Navigation button groups, action button groups, compact arrangement between form items. + +```mermaid +sequenceDiagram +participant U as "Caller" +participant S as "Space" +participant T as "useTargets" +participant R as "ReactSlot" +U->>S : Pass children and slots +S->>T : Parse children into targets +S->>R : Render targets +S->>R : Render split slot (if present) +R-->>U : Output layout with spacing +``` + +Diagram sources + +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) + +Section sources + +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) + +### Splitter + +- Implementation notes + - Uses Ant Design's Splitter and collects default panel list via context. + - Passes each panel's element and props through to Panel for flexible multi-panel layout. +- Layout algorithm + - Split layout based on drag or fixed proportions, supporting horizontal and vertical directions. +- Nesting rules + - Sub-panels register via context; each panel independently renders its own content. +- Responsive behavior + - Can adjust initial proportions and minimum sizes at breakpoints to ensure mobile usability. +- Typical usage + - Code editor + preview area, left/right content comparison, multi-view side-by-side display. + +```mermaid +sequenceDiagram +participant U as "Caller" +participant P as "Splitter" +participant Ctx as "Items Context" +participant Panel as "Panel" +U->>P : Provide panel slots +P->>Ctx : Get default panel list +loop Iterate panels +P->>Panel : Pass props and render +Panel-->>P : Return panel content +end +P-->>U : Output split panel layout +``` + +Diagram sources + +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) + +Section sources + +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) + +### Grid (Col and Context) + +- Implementation notes + - Col registers itself into a context named `antd-grid-cols` via `ItemHandler`. + - The context provides `withItemsContextProvider` and `useItems` for collecting and consuming column definitions. +- Layout algorithm + - Based on a 24-column grid system. Col props such as `span`, `offset`, `order`, and `gutter` determine column width and order. +- Nesting rules + - Col must be placed within a Row/Col context; responsive behavior can be configured via breakpoints. +- Responsive behavior + - Supports breakpoints: xs/sm/md/lg/xl. Different `span`/`offset` values can be set per breakpoint. +- Typical usage + - Form grids, card grids, image walls, etc. + +```mermaid +flowchart TD +A["Col component"] --> B["Register to context
key: antd-grid-cols"] +B --> C["Row/Col reads context during render"] +C --> D["Calculate layout by span/offset/order"] +D --> E["Output grid column"] +``` + +Diagram sources + +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +Section sources + +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +## Dependency Analysis + +- Inter-component coupling + - Space and Splitter directly depend on ReactSlot and context for slot and child item rendering. + - Layout.Base depends on Ant Design's Layout family components and dynamically selects sub-component types. + - Grid uses context to collect and consume Col instances, reducing coupling between Row and Col. +- External dependencies + - All components depend on their corresponding Ant Design components; layout algorithms and styles are provided by Ant Design. +- Potential circular dependencies + - No direct circular dependencies found; context is only used for data passing and does not reverse-depend on components. + +```mermaid +graph TB +Space["Space"] --> ReactSlot["ReactSlot"] +Splitter["Splitter"] --> ItemsCtx["Items Context"] +LayoutBase["Layout.Base"] --> ADLayout["Ant Design Layout"] +GridCol["Grid.Col"] --> GridCtx["Grid Context"] +``` + +Diagram sources + +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +Section sources + +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +## Performance and Responsive Behavior + +- Performance characteristics + - Components use lightweight wrappers to avoid additional state management overhead. Space's `useTargets` performs mapping only once during initialization. + - Layout.Base uses `useMemo` to cache component types, reducing unnecessary re-renders. +- Responsive behavior + - The responsiveness of Flex, Space, Grid, and Splitter is primarily driven by Ant Design's breakpoints and props. Layout parameters for different screen sizes can be configured individually in the breakpoint configuration. + - It is recommended to define breakpoint thresholds and column counts clearly during the design phase to avoid frequent reflows. + +## Mobile and Screen Adaptation + +- General strategies + - Use breakpoint configuration (e.g., xs/sm/md/lg/xl) to adjust column widths, spacing, and layout direction for small screens. + - Use compact mode and appropriate spacing in Space to avoid horizontal scrolling on mobile. + - Set minimum panel sizes and initial proportions in Splitter to ensure touch usability. +- Layout containers + - On small screens, prefer vertical layouts (Flex direction column). Hide secondary areas or use a drawer-style sidebar if necessary. +- Grid system + - Configure `offset` and `order` appropriately to maintain readability and clickability on small screens. + +## Troubleshooting + +- Children not rendering correctly + - Space hides children internally and renders targets via ReactSlot. Verify that slots are being used correctly. +- Splitter panels are empty + - Splitter relies on the default panel list provided by context. If panels are empty, nothing is rendered. Check slot naming and context registration. +- Grid columns not taking effect + - Confirm that Col is registered within a Row/Col context. Check breakpoint configuration and whether `span`/`offset` values are reasonable. +- Layout container type error + - Layout.Base only supports four types: header/footer/content/layout. Passing any other value will fall back to Layout. + +Section sources + +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +## Conclusion + +The layout components in this repository are designed around a "lightweight wrapper + context" core philosophy. They reuse Ant Design's mature layout algorithms and styling system, while providing extensibility through slot rendering, dynamic component selection, and context collection. Through breakpoint configuration and appropriate nesting rules, high-quality page layouts that work well on both desktop and mobile can be built. + +## Appendix: Complex Page Layout Examples and Best Practices + +- Example 1: Dashboard page + - Use Layout.Base to build a header + sidebar + main body. Use Flex and Space inside the main body to organize cards and action areas. Use Divider at the bottom for separation. + - Breakpoint strategy: On small screens, collapse the action area into cards or use a drawer. +- Example 2: Content editing page + - Use Splitter to split the left directory tree from the right editor. Use Grid for form layout inside the editor. Use Space for action buttons at the bottom. + - Breakpoint strategy: On small screens, hide the directory tree and display the editor at full width. +- Example 3: Comparison display page + - Use Splitter to place two content blocks side by side. Inside each block, use Flex and Space for title, description, and action alignment. + - Breakpoint strategy: On small screens, switch to vertical stacking to preserve readability. + +Best practices + +- Prefer Flex and Space for simple layouts; introduce Splitter only for complex scenarios. +- Unify breakpoint configuration in the grid system to avoid multiple breakpoint strategies on the same page. +- Inject semantic class names into layout containers to facilitate style overrides and debugging. +- On mobile, prioritize touch interaction and adequate tap target sizes by increasing spacing and font size appropriately. diff --git a/.wiki/en/Ant Design Components/Layout Components/Layout.md b/.wiki/en/Ant Design Components/Layout Components/Layout.md new file mode 100644 index 00000000..94a9fd9b --- /dev/null +++ b/.wiki/en/Ant Design Components/Layout Components/Layout.md @@ -0,0 +1,295 @@ +# Layout + + +**Files referenced in this document** +- [frontend/antd/layout/Index.svelte](file://frontend/antd/layout/Index.svelte) +- [frontend/antd/layout/Base.svelte](file://frontend/antd/layout/Base.svelte) +- [frontend/antd/layout/layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) +- [frontend/antd/layout/content/Index.svelte](file://frontend/antd/layout/content/Index.svelte) +- [frontend/antd/layout/footer/Index.svelte](file://frontend/antd/layout/footer/Index.svelte) +- [frontend/antd/layout/header/Index.svelte](file://frontend/antd/layout/header/Index.svelte) +- [frontend/antd/layout/sider/Index.svelte](file://frontend/antd/layout/sider/Index.svelte) +- [frontend/antd/layout/sider/layout.sider.tsx](file://frontend/antd/layout/sider/layout.sider.tsx) +- [docs/components/antd/layout/README.md](file://docs/components/antd/layout/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document provides a systematic introduction to the overall architecture and usage of the Layout component, covering the combination and nesting rules of layout regions including Header, Sider, Content, and Footer. It explains responsive behavior and fixed positioning strategies, provides ideas for classic page templates such as sidebar layouts, top navigation layouts, and hybrid layouts, and describes integration with the grid system and adaptive behavior at different screen sizes. It also provides practical recommendations for style customization, theme switching, and animation effects. + +## Project Structure + +The Layout component adopts a "unified base + regional sub-components" layered design: + +- Base layer: `Index.svelte` serves as the entry point. `Base.svelte` handles prop processing and rendering. `layout.base.tsx` wraps the specific Ant Design components (Header/Footer/Content/Layout). +- Region layer: header, footer, content, and sider each specify a `component` type via their own `Index.svelte`, reusing the `Base.svelte` rendering logic. +- Special region: sider provides its own `layout.sider.tsx` to support a `trigger` slot for the collapse trigger. + +```mermaid +graph TB +subgraph "Layout Component Layer" +L["Index.svelte
Unified entry"] +HB["Base.svelte
Common base"] +C["content/Index.svelte"] +F["footer/Index.svelte"] +H["header/Index.svelte"] +S["sider/Index.svelte"] +end +subgraph "Underlying Implementation Layer" +LB["layout.base.tsx
Ant Design component wrapper"] +LS["layout.sider.tsx
Sider implementation with trigger slot"] +end +L --> HB +C --> HB +F --> HB +H --> HB +S --> HB +HB --> LB +S --> LS +``` + +Diagram sources + +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +Section sources + +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/content/Index.svelte:1-15](file://frontend/antd/layout/content/Index.svelte#L1-L15) +- [frontend/antd/layout/footer/Index.svelte:1-15](file://frontend/antd/layout/footer/Index.svelte#L1-L15) +- [frontend/antd/layout/header/Index.svelte:1-15](file://frontend/antd/layout/header/Index.svelte#L1-L15) +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +## Core Components + +- Layout (overall container) + - Entry: `Index.svelte` passes props to `Base.svelte` and specifies `component` as `layout`. + - Base: `Base.svelte` reuses common prop handling logic; `layout.base.tsx` ultimately decides to render Ant Design's Layout container. +- Header (top area) + - Entry: `header/Index.svelte` specifies `component` as `header`, reusing `Base.svelte` to render Ant Design's Header. +- Footer (bottom area) + - Entry: `footer/Index.svelte` specifies `component` as `footer`, reusing `Base.svelte` to render Ant Design's Footer. +- Content (content area) + - Entry: `content/Index.svelte` specifies `component` as `content`, reusing `Base.svelte` to render Ant Design's Content. +- Sider (sidebar) + - Entry: `sider/Index.svelte` asynchronously loads `layout.sider.tsx` to implement Ant Design's Sider with `trigger` slot support. + +Section sources + +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/header/Index.svelte:1-15](file://frontend/antd/layout/header/Index.svelte#L1-L15) +- [frontend/antd/layout/footer/Index.svelte:1-15](file://frontend/antd/layout/footer/Index.svelte#L1-L15) +- [frontend/antd/layout/content/Index.svelte:1-15](file://frontend/antd/layout/content/Index.svelte#L1-L15) +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +## Architecture Overview + +The diagram below shows the render chain from Svelte to Ant Design, as well as the Sider trigger slot mechanism: + +```mermaid +sequenceDiagram +participant U as "User code" +participant L as "Layout/Index.svelte" +participant B as "Base.svelte" +participant LB as "layout.base.tsx" +participant AD as "Ant Design Layout" +U->>L : Pass props such as children +L->>B : Pass through props and set component="layout" +B->>LB : Compute and select component type +LB->>AD : Render Ant Design Layout +AD-->>U : Layout container render complete +``` + +Diagram sources + +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +Section sources + +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +## Detailed Component Analysis + +### Layout Nesting and Region Composition + +- Nesting rules + - Layout is the root container and can directly contain Header, Sider, Content, and Footer. + - Sider is usually placed on the left side of Layout, Content on the right, Header at the top, and Footer at the bottom. + - More fine-grained layouts or grid systems can be further nested inside Content. +- Responsive and fixed positioning + - Implement mobile responsiveness by combining Sider's collapse props with breakpoint configuration. + - When Header/Footer has a fixed height, ensure Content height calculation is not interfered with to avoid scroll conflicts. +- Trigger and interaction + - Sider supports a custom `trigger` slot for implementing a collapse button with icon switching. + +```mermaid +flowchart TD +Start(["Start"]) --> Root["Layout root container"] +Root --> Hdr["Header top area"] +Root --> Sider["Sider sidebar"] +Root --> Cnt["Content main area"] +Root --> Ftr["Footer bottom area"] +Sider --> Trigger["trigger slot (optional)"] +Cnt --> Inner["Inner nested grids/cards/lists etc."] +Hdr --> End(["End"]) +Ftr --> End +``` + +Diagram sources + +- [frontend/antd/layout/header/Index.svelte:1-15](file://frontend/antd/layout/header/Index.svelte#L1-L15) +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/content/Index.svelte:1-15](file://frontend/antd/layout/content/Index.svelte#L1-L15) +- [frontend/antd/layout/footer/Index.svelte:1-15](file://frontend/antd/layout/footer/Index.svelte#L1-L15) + +Section sources + +- [frontend/antd/layout/header/Index.svelte:1-15](file://frontend/antd/layout/header/Index.svelte#L1-L15) +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/content/Index.svelte:1-15](file://frontend/antd/layout/content/Index.svelte#L1-L15) +- [frontend/antd/layout/footer/Index.svelte:1-15](file://frontend/antd/layout/footer/Index.svelte#L1-L15) + +### Sider Component and Trigger Slot + +- Trigger mechanism + - If a `trigger` slot is provided, that slot content takes priority. If no slot is provided and `trigger` is the default value, the default trigger is rendered. Otherwise, the rendered state is determined by the passed `trigger` value. +- Collapse state management + - Use Sider's `collapsed` state together with trigger behavior to implement click-toggle expand/collapse. + +```mermaid +flowchart TD +A["Enter Sider render"] --> B{"trigger slot provided?"} +B -- Yes --> C["Render slot content as trigger"] +B -- No --> D{"trigger is default value?"} +D -- Yes --> E["Render default trigger"] +D -- No --> F{"trigger is null/undefined?"} +F -- Yes --> G["Do not render trigger"] +F -- No --> H["Render passed trigger content"] +C --> I["Done"] +E --> I +G --> I +H --> I +``` + +Diagram sources + +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +Section sources + +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +### Classic Page Layout Templates + +- Sidebar layout + - Use Layout + Header + Sider + Content + Footer. Sider has a fixed width and is collapsible on mobile. +- Top navigation layout + - Use Layout + Header (top navigation only) + Content. Sider can be omitted or hidden. +- Hybrid layout + - Nest a grid system inside Content to implement multi-column content with a side information panel. + +Section sources + +- [docs/components/antd/layout/README.md:1-8](file://docs/components/antd/layout/README.md#L1-L8) + +### Integration with the Grid System + +- Use Row/Col in Content for column division, combined with responsive breakpoints for adaptive layouts. +- Note: When Header/Footer has a fixed height, Content height calculation must account for the remaining visible area to avoid overflow or scroll anomalies. + +## Dependency Analysis + +- Component coupling + - All region components depend on `Base.svelte`'s prop handling and rendering process, reducing duplicate code and improving consistency. + - Sider independently implements `layout.sider.tsx` to avoid coupling with the common Base process, enhancing extensibility. +- External dependencies + - Ant Design's Layout, Header, Footer, Content, and Sider components as render targets. + - Svelte Slot and React Slot bridging for slot passing and cloning. + +```mermaid +graph LR +Base["Base.svelte"] --> Wrap["layout.base.tsx"] +Wrap --> ADL["Ant Design Layout"] +Wrap --> ADH["Ant Design Header"] +Wrap --> ADF["Ant Design Footer"] +Wrap --> ADC["Ant Design Content"] +SBase["sider/Index.svelte"] --> SWrap["layout.sider.tsx"] +SWrap --> ADS["Ant Design Sider"] +``` + +Diagram sources + +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +Section sources + +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +## Performance Considerations + +- Async loading + - Sider is asynchronously loaded via `importComponent`, reducing initial bundle size and first-screen blocking. +- Prop passthrough and derivation + - `Base.svelte` handles and derives props in a unified manner, avoiding unnecessary re-renders. +- Class names + - Class names are conditionally concatenated, avoiding excessive runtime string concatenation overhead. + +Section sources + +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) + +## Troubleshooting Guide + +- No content rendered + - Check if the `visible` prop has been set to `false`. Confirm the visibility check logic in `Base.svelte`. +- Sider trigger not showing + - Confirm whether a `trigger` slot has been provided. Check if the `trigger` value is `null`/`undefined` or the default value. +- Style anomalies + - Confirm that class names are correctly concatenated. Check if external styles are causing layout misalignment. + +Section sources + +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +## Conclusion + +The Layout component achieves complete encapsulation of Ant Design's layout system through a unified base and regionalized decomposition. With the Sider trigger slot and async loading mechanism, it ensures both flexibility and performance. Combined with the grid system and responsive breakpoints, a variety of classic page layout templates can be quickly assembled, while style and theme customization meets the needs of complex business scenarios. + +## Appendix + +- Example entry reference: [docs/components/antd/layout/README.md:1-8](file://docs/components/antd/layout/README.md#L1-L8) diff --git a/.wiki/en/Ant Design Components/Layout Components/Masonry.md b/.wiki/en/Ant Design Components/Layout Components/Masonry.md new file mode 100644 index 00000000..8b818970 --- /dev/null +++ b/.wiki/en/Ant Design Components/Layout Components/Masonry.md @@ -0,0 +1,464 @@ +# Masonry + + +**Files referenced in this document** +- [frontend/antd/masonry/masonry.tsx](file://frontend/antd/masonry/masonry.tsx) +- [frontend/antd/masonry/context.ts](file://frontend/antd/masonry/context.ts) +- [frontend/antd/masonry/Index.svelte](file://frontend/antd/masonry/Index.svelte) +- [frontend/antd/masonry/package.json](file://frontend/antd/masonry/package.json) +- [backend/modelscope_studio/components/antd/masonry/__init__.py](file://backend/modelscope_studio/components/antd/masonry/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [docs/components/antd/masonry/README.md](file://docs/components/antd/masonry/README.md) +- [docs/components/antd/masonry/README-zh_CN.md](file://docs/components/antd/masonry/README-zh_CN.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) + +## Introduction + +Masonry is an important layout component in ModelScope Studio, implemented based on Ant Design's Masonry component. This component is specifically designed to display content of varying heights, such as images and cards, and automatically creates a waterfall/masonry effect that distributes content evenly across multiple columns. + +The masonry layout is particularly well-suited for the following scenarios: + +- Displaying images or cards with irregular heights +- Distributing content evenly between columns +- Layout requirements that need responsive column count adjustment + +## Project Structure + +ModelScope Studio adopts a frontend-backend separated architecture. The Masonry component is organized as follows: + +```mermaid +graph TB +subgraph "Frontend Layer" +A[frontend/antd/masonry/] --> A1[masonry.tsx] +A --> A2[Index.svelte] +A --> A3[context.ts] +A --> A4[package.json] +subgraph "utils/" +B[frontend/utils/] --> B1[createItemsContext.tsx] +B --> B2[renderItems.tsx] +B --> B3[renderParamsSlot.tsx] +end +end +subgraph "Backend Layer" +C[backend/modelscope_studio/] --> C1[components/antd/masonry/] +C --> C2[components/antd/components.py] +C1 --> C3[__init__.py] +end +subgraph "Docs Layer" +D[docs/components/antd/masonry/] --> D1[README.md] +D --> D2[README-zh_CN.md] +end +A1 --> B1 +A1 --> B2 +A1 --> B3 +C3 --> A2 +``` + +**Diagram sources** + +- [frontend/antd/masonry/masonry.tsx:1-52](file://frontend/antd/masonry/masonry.tsx#L1-L52) +- [frontend/antd/masonry/Index.svelte:1-64](file://frontend/antd/masonry/Index.svelte#L1-L64) +- [backend/modelscope_studio/components/antd/masonry/**init**.py:1-83](file://backend/modelscope_studio/components/antd/masonry/__init__.py#L1-L83) + +**Section sources** + +- [frontend/antd/masonry/masonry.tsx:1-52](file://frontend/antd/masonry/masonry.tsx#L1-L52) +- [frontend/antd/masonry/Index.svelte:1-64](file://frontend/antd/masonry/Index.svelte#L1-L64) +- [backend/modelscope_studio/components/antd/masonry/**init**.py:1-83](file://backend/modelscope_studio/components/antd/masonry/__init__.py#L1-L83) + +## Core Components + +### Frontend Core Components + +The core implementation of the Masonry component resides in `frontend/antd/masonry/masonry.tsx`. It uses React and Ant Design's Masonry component and integrates with ModelScope Studio's component system. + +Main features include: + +- **React wrapper**: uses `sveltify` to wrap Svelte components as React components +- **Context management**: integrates `createItemsContext` for data sharing between components +- **Slot rendering**: supports custom slot rendering +- **Dynamic content**: supports dynamic content updates and re-rendering + +### Backend Integration Component + +The backend component is located at `backend/modelscope_studio/components/antd/masonry/__init__.py` and provides a Python interface bridging to the frontend component. + +Key props and methods: + +- **EVENTS**: defines the `layout_change` event listener +- **SLOTS**: supports `items` and `itemRender` slots +- **PROPS**: provides configuration options such as `columns`, `gutter`, and `fresh` + +**Section sources** + +- [frontend/antd/masonry/masonry.tsx:10-49](file://frontend/antd/masonry/masonry.tsx#L10-L49) +- [backend/modelscope_studio/components/antd/masonry/**init**.py:10-65](file://backend/modelscope_studio/components/antd/masonry/__init__.py#L10-L65) + +## Architecture Overview + +The overall architecture of the Masonry component uses a layered design to ensure good maintainability and extensibility: + +```mermaid +graph TD +subgraph "UI Layer" +UI[Masonry Component] +end +subgraph "Frontend Logic Layer" +FC[Function Component] +CTX[Context Provider] +SL[Slot Handling] +end +subgraph "Utility Layer" +CIC[createItemsContext] +RI[renderItems] +RPS[renderParamsSlot] +end +subgraph "Ant Design Layer" +AD[Antd Masonry] +end +subgraph "Backend Integration Layer" +BC[Backend Component] +PC[Python Interface] +end +UI --> FC +FC --> CTX +FC --> SL +FC --> AD +CTX --> CIC +SL --> RI +SL --> RPS +BC --> PC +BC --> UI +``` + +**Diagram sources** + +- [frontend/antd/masonry/masonry.tsx:1-52](file://frontend/antd/masonry/masonry.tsx#L1-L52) +- [frontend/utils/createItemsContext.tsx:97-184](file://frontend/utils/createItemsContext.tsx#L97-L184) +- [frontend/utils/renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +## Detailed Component Analysis + +### Masonry Component Implementation + +The core implementation of the Masonry component includes the following key parts: + +#### Component Wrapping and Prop Handling + +The component uses the `sveltify` function to wrap Svelte components as React components, supporting prop passing and event handling: + +```mermaid +sequenceDiagram +participant User as User +participant Masonry as Masonry Component +participant Context as Context Provider +participant Utils as Utility Functions +User->>Masonry : Pass props and children +Masonry->>Context : withItemsContextProvider wrapping +Context->>Utils : useItems to get data +Utils->>Utils : renderItems processes slots +Utils->>Masonry : Return processed data +Masonry->>Masonry : useMemo optimizes rendering +Masonry->>User : Render final result +``` + +**Diagram sources** + +- [frontend/antd/masonry/masonry.tsx:16-48](file://frontend/antd/masonry/masonry.tsx#L16-L48) +- [frontend/antd/masonry/context.ts:3-4](file://frontend/antd/masonry/context.ts#L3-L4) + +#### Data Flow Handling Mechanism + +The component manages data flow via `createItemsContext`: + +```mermaid +flowchart TD +Start([Component initialization]) --> GetItems[Get useItems context] +GetItems --> CheckSlots{Check slot type} +CheckSlots --> |has items| UseItems[Use items prop] +CheckSlots --> |no items| UseSlots[Use slot data] +UseSlots --> ResolveSlot[Resolve slot data] +ResolveSlot --> RenderItems[Call renderItems] +UseItems --> RenderItems +RenderItems --> MemoOptimize[useMemo optimization] +MemoOptimize --> FinalRender[Final render] +FinalRender --> End([Done]) +``` + +**Diagram sources** + +- [frontend/antd/masonry/masonry.tsx:18-43](file://frontend/antd/masonry/masonry.tsx#L18-L43) +- [frontend/utils/renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +**Section sources** + +- [frontend/antd/masonry/masonry.tsx:1-52](file://frontend/antd/masonry/masonry.tsx#L1-L52) +- [frontend/antd/masonry/context.ts:1-7](file://frontend/antd/masonry/context.ts#L1-L7) + +### Context Management System + +`createItemsContext` provides comprehensive context management: + +#### Context Provider Pattern + +```mermaid +classDiagram +class ItemsContextProvider { ++allowedSlots : string[] ++items : ItemsContextValue ++setItem(slotKey, index, value) ++onChange(items) +} +class ItemsContextValue { ++items : Record~string, Item[]~ ++setItem : Function ++initial : boolean +} +class ItemHandler { ++itemIndex : number ++itemSlotKey : string ++itemElement : HTMLElement ++itemProps(props, items) ++itemChildren(items) ++slots : Record~string, Slot~ +} +ItemsContextProvider --> ItemsContextValue : "provides" +ItemHandler --> ItemsContextProvider : "uses" +``` + +**Diagram sources** + +- [frontend/utils/createItemsContext.tsx:108-170](file://frontend/utils/createItemsContext.tsx#L108-L170) +- [frontend/utils/createItemsContext.tsx:190-261](file://frontend/utils/createItemsContext.tsx#L190-L261) + +#### Data Processing Flow + +The component's data processing follows this flow: + +1. **Data collection**: collects all child elements from slots +2. **Data transformation**: converts HTML elements into internal data structures +3. **Context passing**: passes data through the React Context in the component tree +4. **State management**: manages component state using `useState` and `useEffect` + +**Section sources** + +- [frontend/utils/createItemsContext.tsx:97-274](file://frontend/utils/createItemsContext.tsx#L97-L274) + +### Slot Rendering System + +The Masonry component supports a flexible slot rendering mechanism: + +#### Slot Handling Functions + +```mermaid +flowchart LR +Slots[Slot object] --> CheckSlot{Check slot exists} +CheckSlot --> |exists| RenderSlot[renderSlot rendering] +CheckSlot --> |not exists| Fallback[Fallback handling] +RenderSlot --> ParamsSlot{Parameterized slot} +ParamsSlot --> |has params| RenderParams[renderParamsSlot] +ParamsSlot --> |no params| DirectRender[Direct rendering] +RenderParams --> Clone[Clone element] +DirectRender --> Clone +Clone --> Result[Return React node] +Fallback --> Result +``` + +**Diagram sources** + +- [frontend/utils/renderParamsSlot.tsx:5-49](file://frontend/utils/renderParamsSlot.tsx#L5-L49) +- [frontend/utils/renderItems.tsx:72-94](file://frontend/utils/renderItems.tsx#L72-L94) + +**Section sources** + +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + +## Dependency Analysis + +### Component Dependency Diagram + +```mermaid +graph TB +subgraph "Masonry Component Dependencies" +A[masonry.tsx] --> B[createItemsContext.tsx] +A --> C[renderItems.tsx] +A --> D[renderParamsSlot.tsx] +A --> E[context.ts] +end +subgraph "Context Dependencies" +B --> F[React Hooks] +B --> G[useMemoizedEqualValue] +B --> H[useMemoizedFn] +end +subgraph "Utility Function Dependencies" +C --> I[ReactSlot] +C --> J[ContextPropsProvider] +D --> K[renderSlot] +end +subgraph "Backend Integration" +L[__init__.py] --> M[AntdMasonry] +L --> N[AntdMasonryItem] +end +A -.-> O[Antd Masonry] +L -.-> P[Gradio Events] +``` + +**Diagram sources** + +- [frontend/antd/masonry/masonry.tsx:1-6](file://frontend/antd/masonry/masonry.tsx#L1-L6) +- [frontend/utils/createItemsContext.tsx:1-18](file://frontend/utils/createItemsContext.tsx#L1-L18) +- [backend/modelscope_studio/components/antd/masonry/**init**.py:1-8](file://backend/modelscope_studio/components/antd/masonry/__init__.py#L1-L8) + +### Key Dependency Descriptions + +1. **Ant Design Masonry**: core layout component providing masonry layout functionality +2. **React Hooks**: used for state management and performance optimization +3. **Gradio integration**: supports Python backend event handling +4. **Svelte Preprocess**: implements the transformation from Svelte to React + +**Section sources** + +- [frontend/antd/masonry/masonry.tsx:1-6](file://frontend/antd/masonry/masonry.tsx#L1-L6) +- [backend/modelscope_studio/components/antd/masonry/**init**.py:23-27](file://backend/modelscope_studio/components/antd/masonry/__init__.py#L23-L27) + +## Performance Considerations + +### Rendering Optimization Strategies + +The Masonry component employs multiple performance optimization techniques: + +#### useMemo Optimization + +The component uses `useMemo` to cache computation results, avoiding unnecessary re-renders: + +```typescript +const memoizedItems = useMemo(() => { + return items || renderItems(resolvedSlotItems); +}, [items, resolvedSlotItems]); +``` + +#### Event Handler Optimization + +Uses `useFunction` and `useMemoizedFn` to optimize event handler performance: + +```typescript +const itemRenderFunction = useFunction(props.itemRender); +``` + +#### Conditional Rendering + +Reduces DOM operations through conditional rendering: + +```html +
{children}
+```
+
+### Memory Management
+
+The component implements intelligent memory management:
+
+1. **Reference caching**: uses `useRef` to cache expensive computation results
+2. **State synchronization**: synchronizes state changes via `useEffect`
+3. **Cleanup mechanism**: cleans up event listeners when the component unmounts
+
+## Troubleshooting Guide
+
+### Common Issues and Solutions
+
+#### 1. Component shows no content
+
+**Symptom**: Masonry component renders blank
+
+**Possible causes**:
+
+- Slot data not set correctly
+- `items` prop not provided
+- React component not wrapped correctly
+
+**Solutions**:
+
+1. Check if slots are passed correctly
+2. Confirm that the `items` prop contains valid data
+3. Verify that the component wrapping is correct
+
+#### 2. Layout is disordered
+
+**Symptom**: Masonry layout displays abnormally
+
+**Possible causes**:
+
+- Column count configuration is incorrect
+- Gutter settings are improper
+- Content height calculation error
+
+**Solutions**:
+
+1. Check the `columns` configuration
+2. Adjust the `gutter` setting
+3. Ensure content has correct height information
+
+#### 3. Performance issues
+
+**Symptom**: Component renders slowly or stutters
+
+**Possible causes**:
+
+- Large amounts of data causing rendering pressure
+- Unnecessary re-renders
+- Event handler performance issues
+
+**Solutions**:
+
+1. Use virtual scrolling to handle large datasets
+2. Optimize `useMemo` dependencies
+3. Reduce the complexity of event handlers
+
+**Section sources**
+
+- [frontend/antd/masonry/masonry.tsx:36-43](file://frontend/antd/masonry/masonry.tsx#L36-L43)
+- [frontend/utils/createItemsContext.tsx:124-153](file://frontend/utils/createItemsContext.tsx#L124-L153)
+
+## Conclusion
+
+The Masonry layout component is a powerful and well-designed layout solution in ModelScope Studio. The component demonstrates excellent architectural design through the following characteristics:
+
+### Key Advantages
+
+1. **Modular design**: clear module division for easy maintenance and extension
+2. **Performance optimization**: implements multiple performance optimization techniques to ensure a smooth user experience
+3. **Flexibility**: supports various configuration options and custom rendering functionality
+4. **Type safety**: complete TypeScript type definitions for a good development experience
+
+### Technical Highlights
+
+- **Context management pattern**: implements powerful data flow management via `createItemsContext`
+- **Slot rendering system**: supports complex slot rendering and parameterized rendering
+- **React integration**: seamlessly integrated into the React ecosystem
+- **Backend compatibility**: provides a Python backend interface supporting Gradio event handling
+
+### Application Scenarios
+
+The Masonry component is particularly well-suited for:
+
+- Image gallery display
+- Card content layouts
+- Dynamic content containers
+- Responsive grid layouts
+
+The component provides powerful layout capabilities for ModelScope Studio and is an important piece of infrastructure for building modern web applications.
diff --git a/.wiki/en/Ant Design Components/Layout Components/Space.md b/.wiki/en/Ant Design Components/Layout Components/Space.md
new file mode 100644
index 00000000..b8fa4abe
--- /dev/null
+++ b/.wiki/en/Ant Design Components/Layout Components/Space.md
@@ -0,0 +1,268 @@
+# Space
+
+
+**Files Referenced in This Document**
+- [frontend/antd/space/space.tsx](file://frontend/antd/space/space.tsx)
+- [frontend/antd/space/Index.svelte](file://frontend/antd/space/Index.svelte)
+- [frontend/antd/space/compact/space.compact.tsx](file://frontend/antd/space/compact/space.compact.tsx)
+- [frontend/antd/space/compact/Index.svelte](file://frontend/antd/space/compact/Index.svelte)
+- [backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js](file://backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js)
+- [backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js](file://backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js)
+- [docs/components/antd/space/README.md](file://docs/components/antd/space/README.md)
+- [docs/components/antd/space/README-zh_CN.md](file://docs/components/antd/space/README-zh_CN.md)
+
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Project Structure](#project-structure)
+3. [Core Components](#core-components)
+4. [Architecture Overview](#architecture-overview)
+5. [Detailed Component Analysis](#detailed-component-analysis)
+6. [Dependency Analysis](#dependency-analysis)
+7. [Performance Considerations](#performance-considerations)
+8. [Troubleshooting Guide](#troubleshooting-guide)
+9. [Conclusion](#conclusion)
+10. [Appendix](#appendix)
+
+## Introduction
+
+The Space component automatically inserts uniform spacing between multiple child elements, supporting direction control, spacing size configuration, and collaboration with separator slots. This repository provides two variants:
+
+- Standard Space: A wrapper around Ant Design's Space component, responsible for automatic spacing distribution and direction control.
+- Compact Space (Space.Compact): A wrapper around Ant Design's Space.Compact, emphasizing tighter layouts and compact spacing strategies.
+
+Both variants bridge Svelte child nodes to React Space/Space.Compact children via the Svelte–React bridging mechanism, ensuring stable rendering in the Gradio ecosystem.
+
+## Project Structure
+
+The Space component consists of a frontend Svelte layer and a backend template layer:
+
+- Frontend Svelte layer: Handles property pass-through, style concatenation, visibility control, and child node rendering.
+- Backend template layer: Generates the final React wrapper, handling slot ordering, ReactSlot rendering, and Portal bridging.
+
+```mermaid
+graph TB
+subgraph "Frontend Svelte Layer"
+IDX["Index.svelteStandard Space Entry"] +COMPACT_IDX["compact/Index.svelte
Compact Space Entry"] +SPACE_TSX["space.tsx
Standard Space React Wrapper"] +COMPACT_TSX["compact/space.compact.tsx
Compact Space React Wrapper"] +end +subgraph "Backend Template Layer" +RT_SPACE["space-BWI0-XH7.js
Standard Space Template"] +RT_COMPACT["space.compact-C2LVtCsM.js
Compact Space Template"] +end +IDX --> SPACE_TSX --> RT_SPACE +COMPACT_IDX --> COMPACT_TSX --> RT_COMPACT +``` + +**Diagram Sources** + +- [frontend/antd/space/Index.svelte:1-61](file://frontend/antd/space/Index.svelte#L1-L61) +- [frontend/antd/space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js:651-679](file://backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L651-L679) +- [frontend/antd/space/compact/Index.svelte:1-60](file://frontend/antd/space/compact/Index.svelte#L1-L60) +- [frontend/antd/space/compact/space.compact.tsx:1-24](file://frontend/antd/space/compact/space.compact.tsx#L1-L24) +- [backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:651-674](file://backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L651-L674) + +**Section Sources** + +- [frontend/antd/space/Index.svelte:1-61](file://frontend/antd/space/Index.svelte#L1-L61) +- [frontend/antd/space/compact/Index.svelte:1-60](file://frontend/antd/space/compact/Index.svelte#L1-L60) +- [docs/components/antd/space/README.md:1-8](file://docs/components/antd/space/README.md#L1-L8) +- [docs/components/antd/space/README-zh_CN.md:1-8](file://docs/components/antd/space/README-zh_CN.md#L1-L8) + +## Core Components + +- Standard Space: Responsible for automatically collecting child nodes, injecting separator slots, rendering children in order, and supporting direction, size, and alignment configuration. +- Compact Space (Space.Compact): In compact mode, reduces default spacing and emphasizes tight arrangement of adjacent elements, suitable for dense layouts such as toolbars and button groups. + +Both variants dynamically load the corresponding React wrapper via Svelte's `importComponent`, and pass slots and additional props to the underlying React component. + +**Section Sources** + +- [frontend/antd/space/space.tsx:7-26](file://frontend/antd/space/space.tsx#L7-L26) +- [frontend/antd/space/compact/space.compact.tsx:7-21](file://frontend/antd/space/compact/space.compact.tsx#L7-L21) +- [frontend/antd/space/Index.svelte:10-60](file://frontend/antd/space/Index.svelte#L10-L60) +- [frontend/antd/space/compact/Index.svelte:10-60](file://frontend/antd/space/compact/Index.svelte#L10-L60) + +## Architecture Overview + +The Space call chain runs from Svelte to React and back to the DOM, involving slot resolution, child node ordering, and Portal bridging. + +```mermaid +sequenceDiagram +participant Svelte as "Svelte Component (Index.svelte)" +participant Loader as "importComponent" +participant ReactWrap as "React Wrapper (space.tsx or space.compact.tsx)" +participant BackendRT as "Backend Template (space-BWI0-XH7.js / space.compact-C2LVtCsM.js)" +participant Antd as "Ant Design Space/Space.Compact" +Svelte->>Loader : Load corresponding React wrapper +Loader-->>Svelte : Return React component +Svelte->>ReactWrap : Pass props and slots +ReactWrap->>BackendRT : Convert children to ReactSlot +BackendRT->>Antd : Render Space/Space.Compact and inject child nodes +Antd-->>Svelte : Output final DOM structure +``` + +**Diagram Sources** + +- [frontend/antd/space/Index.svelte:10-60](file://frontend/antd/space/Index.svelte#L10-L60) +- [frontend/antd/space/space.tsx:7-26](file://frontend/antd/space/space.tsx#L7-L26) +- [backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js:651-679](file://backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L651-L679) +- [frontend/antd/space/compact/Index.svelte:10-60](file://frontend/antd/space/compact/Index.svelte#L10-L60) +- [frontend/antd/space/compact/space.compact.tsx:7-21](file://frontend/antd/space/compact/space.compact.tsx#L7-L21) +- [backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:651-674](file://backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L651-L674) + +## Detailed Component Analysis + +### Standard Space Component + +- Automatic child node collection: Parses children via utility functions, converting them to ReactSlots with controllable ordering and cloning strategy. +- Separator slot: Supports injecting a separator via `slots.split`; falls back to `props.split` if not provided. +- Property pass-through: All props except internal ones are passed through to Ant Design Space, maintaining API compatibility with the native component. + +```mermaid +flowchart TD +Start(["Enter Space Render"]) --> Collect["Collect children and resolve to targets"] +Collect --> SplitCheck{"Is split slot provided?"} +SplitCheck --> |Yes| UseSlot["Use ReactSlot for slots.split"] +SplitCheck --> |No| UseProp["Use props.split"] +UseSlot --> Render["Iterate targets and render each ReactSlot"] +UseProp --> Render +Render --> End(["Render Complete"]) +``` + +**Diagram Sources** + +- [frontend/antd/space/space.tsx:8-25](file://frontend/antd/space/space.tsx#L8-L25) +- [backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js:656-673](file://backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L656-L673) + +**Section Sources** + +- [frontend/antd/space/space.tsx:7-26](file://frontend/antd/space/space.tsx#L7-L26) +- [backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js:651-679](file://backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L651-L679) + +### Compact Space Component + +- Compact mode: Uses Ant Design's Space.Compact to reduce default spacing, suitable for button groups, toolbars, and other densely packed layouts. +- Child node handling: Similar to the standard Space — hides original children first, then renders each one as a ReactSlot, ensuring consistent slot ordering and cloning strategy. + +```mermaid +flowchart TD +StartC(["Enter Space.Compact Render"]) --> Targets["Resolve children into target node array"] +Targets --> RenderC["Render each ReactSlot and inject into Compact container"] +RenderC --> EndC(["Render Complete"]) +``` + +**Diagram Sources** + +- [frontend/antd/space/compact/space.compact.tsx:8-20](file://frontend/antd/space/compact/space.compact.tsx#L8-L20) +- [backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:651-669](file://backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L651-L669) + +**Section Sources** + +- [frontend/antd/space/compact/space.compact.tsx:7-21](file://frontend/antd/space/compact/space.compact.tsx#L7-L21) +- [backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:651-674](file://backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L651-L674) + +### Svelte-to-React Bridging Mechanism + +- Slot ordering: Performs stable sorting of child nodes by `slotIndex` and `subSlotIndex`, ensuring consistent render order. +- Portal bridging: Clones Svelte slot content and mounts it into the React environment while preserving event listeners and styles. +- Visibility and styles: The Svelte layer concatenates `className` and inline styles, which are ultimately injected into the React component. + +```mermaid +sequenceDiagram +participant Svelte as "Svelte (Index.svelte)" +participant SlotSort as "Slot Ordering" +participant Bridge as "Portal Bridging" +participant React as "React Wrapper" +participant DOM as "Antd Space/Space.Compact" +Svelte->>SlotSort : Retrieve and sort slots +SlotSort-->>Bridge : Return ordered portalTargets +Bridge->>React : Generate ReactSlots and clone nodes +React->>DOM : Render final DOM +``` + +**Diagram Sources** + +- [frontend/antd/space/Index.svelte:44-60](file://frontend/antd/space/Index.svelte#L44-L60) +- [backend/modelspace_studio/components/antd/space/templates/component/space-BWI0-XH7.js:642-650](file://backend/modelspace_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L642-L650) +- [frontend/antd/space/compact/Index.svelte:43-60](file://frontend/antd/space/compact/Index.svelte#L43-L60) +- [backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:642-650](file://backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L642-L650) + +**Section Sources** + +- [frontend/antd/space/Index.svelte:10-60](file://frontend/antd/space/Index.svelte#L10-L60) +- [frontend/antd/space/compact/Index.svelte:10-60](file://frontend/antd/space/compact/Index.svelte#L10-L60) +- [backend/modelspace_studio/components/antd/space/templates/component/space-BWI0-XH7.js:642-650](file://backend/modelspace_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L642-L650) +- [backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:642-650](file://backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L642-L650) + +## Dependency Analysis + +- Component coupling: Space and Space.Compact share the same bridging logic in the frontend layer, differing only in the underlying Ant Design component used. +- External dependencies: Depends on Ant Design's Space/Space.Compact; slot and ReactSlot support is provided by `@svelte-preprocess-react`. +- Backend template: The template layer converts Svelte's slot ordering and Portal bridging logic into executable React code. + +```mermaid +graph LR +Svelte_Index["Index.svelte"] --> React_Space["space.tsx"] +Svelte_Compact["compact/Index.svelte"] --> React_Compact["compact/space.compact.tsx"] +React_Space --> RT_Space["space-BWI0-XH7.js"] +React_Compact --> RT_Compact["space.compact-C2LVtCsM.js"] +RT_Space --> Antd["Ant Design Space"] +RT_Compact --> AntdCompact["Ant Design Space.Compact"] +``` + +**Diagram Sources** + +- [frontend/antd/space/Index.svelte:10-60](file://frontend/antd/space/Index.svelte#L10-L60) +- [frontend/antd/space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [backend/modelspace_studio/components/antd/space/templates/component/space-BWI0-XH7.js:651-679](file://backend/modelspace_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L651-L679) +- [frontend/antd/space/compact/Index.svelte:10-60](file://frontend/antd/space/compact/Index.svelte#L10-L60) +- [frontend/antd/space/compact/space.compact.tsx:1-24](file://frontend/antd/space/compact/space.compact.tsx#L1-L24) +- [backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:651-674](file://backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L651-L674) + +**Section Sources** + +- [frontend/antd/space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [frontend/antd/space/compact/space.compact.tsx:1-24](file://frontend/antd/space/compact/space.compact.tsx#L1-L24) +- [backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js:651-679](file://backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L651-L679) +- [backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:651-674](file://backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L651-L674) + +## Performance Considerations + +- Child node cloning and Portal: Cloning and Portal mounting avoid direct DOM manipulation, but be aware of rendering costs when there are many child nodes. +- Slot ordering stability: Index-based sorting remains stable even with large datasets, but it is recommended to minimize unnecessary slot changes to reduce reflow overhead. +- SSR and Hugging Face Space: In certain deployment environments, SSR must be disabled to avoid custom component compatibility issues, which affects initial render time. Optimize resource loading at build time. + +[This section contains general performance advice and does not directly analyze specific files] + +## Troubleshooting Guide + +- Child nodes not rendering correctly: Check whether the Svelte layer is properly passing `slots` and `children`; verify that `slotIndex` and `subSlotIndex` are set correctly. +- Separator not taking effect: Confirm whether the `split` slot is correctly passed, or whether `props.split` is provided as expected. +- SSR compatibility issues: When encountering UI anomalies in Hugging Face Space, try adding `ssr_mode=False` to `demo.launch`. + +**Section Sources** + +- [frontend/antd/space/space.tsx:15-17](file://frontend/antd/space/space.tsx#L15-L17) +- [docs/components/antd/space/README.md:1-8](file://docs/components/antd/space/README.md#L1-L8) +- [docs/components/antd/space/README-zh_CN.md:1-8](file://docs/components/antd/space/README-zh_CN.md#L1-L8) + +## Conclusion + +The Space component achieves seamless integration of Ant Design Space/Space.Compact in the Gradio ecosystem through Svelte–React bridging. Standard Space is suitable for general layouts, while Space.Compact is better suited for scenarios requiring tight element arrangement. With slot ordering and Portal bridging, the component maintains good maintainability and consistency even in complex layouts. + +[This section contains summary content and does not directly analyze specific files] + +## Appendix + +- Usage examples: See the example tabs in the documentation directory for basic usage demonstrations. +- Documentation entry: Documentation for both Standard Space and Compact Space is located under `docs/components/antd/space`. + +**Section Sources** + +- [docs/components/antd/space/README.md:5-8](file://docs/components/antd/space/README.md#L5-L8) +- [docs/components/antd/space/README-zh_CN.md:5-8](file://docs/components/antd/space/README-zh_CN.md#L5-L8) diff --git a/.wiki/en/Ant Design Components/Layout Components/Splitter.md b/.wiki/en/Ant Design Components/Layout Components/Splitter.md new file mode 100644 index 00000000..2ca8ba7d --- /dev/null +++ b/.wiki/en/Ant Design Components/Layout Components/Splitter.md @@ -0,0 +1,387 @@ +# Splitter + + +**Files Referenced in This Document** +- [frontend/antd/splitter/Index.svelte](file://frontend/antd/splitter/Index.svelte) +- [frontend/antd/splitter/splitter.tsx](file://frontend/antd/splitter/splitter.tsx) +- [frontend/antd/splitter/panel/Index.svelte](file://frontend/antd/splitter/panel/Index.svelte) +- [frontend/antd/splitter/panel/splitter.panel.tsx](file://frontend/antd/splitter/panel/splitter.panel.tsx) +- [frontend/antd/splitter/context.ts](file://frontend/antd/splitter/context.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [backend/modelscope_studio/components/antd/splitter/panel/__init__.py](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py) +- [docs/components/antd/splitter/README.md](file://docs/components/antd/splitter/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +Splitter is a panel-splitting component based on Ant Design that divides the interface into multiple resizable areas via drag handles. It supports both horizontal and vertical orientations and uses the Panel sub-component for declarative panel organization. The component is widely applicable to scenarios such as code editors (left-right layout), image comparison (left-right or top-bottom), and multi-view side-by-side displays. + +This document provides a systematic explanation of the component's architecture design, data flow, drag-and-resize controls, responsive behavior, interaction experience, styling, and accessibility, along with typical usage examples and best practice recommendations. + +## Project Structure + +Splitter adopts a Svelte + React Slot bridging approach on the frontend, while the backend encapsulates properties and rendering logic via Python components. Key files are distributed as follows: + +- Frontend entry and bridging: `frontend/antd/splitter/Index.svelte` +- Splitter container implementation: `frontend/antd/splitter/splitter.tsx` +- Panel sub-component bridging: `frontend/antd/splitter/panel/Index.svelte` +- Panel sub-component implementation: `frontend/antd/splitter/panel/splitter.panel.tsx` +- Context and item management: `frontend/antd/splitter/context.ts`, `frontend/utils/createItemsContext.tsx` +- Backend Panel component wrapper: `backend/modelscope_studio/components/antd/splitter/panel/__init__.py` +- Documentation and examples entry: `docs/components/antd/splitter/README.md` + +```mermaid +graph TB +subgraph "Frontend (Svelte)" +A["Index.svelte
Entry Bridging"] +B["splitter.tsx
Splitter Container"] +C["panel/Index.svelte
Panel Bridging"] +D["panel/splitter.panel.tsx
Panel Implementation"] +E["context.ts
Items Context"] +F["createItemsContext.tsx
Generic Item Context Utility"] +end +subgraph "Backend (Python)" +G["panel/__init__.py
AntdSplitterPanel Wrapper"] +end +A --> B +A --> C +C --> D +B --> E +D --> E +E --> F +G --> C +``` + +Diagram Sources + +- [frontend/antd/splitter/Index.svelte:1-71](file://frontend/antd/splitter/Index.svelte#L1-L71) +- [frontend/antd/splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [frontend/antd/splitter/panel/Index.svelte:1-77](file://frontend/antd/splitter/panel/Index.svelte#L1-L77) +- [frontend/antd/splitter/panel/splitter.panel.tsx:1-14](file://frontend/antd/splitter/panel/splitter.panel.tsx#L1-L14) +- [frontend/antd/splitter/context.ts:1-7](file://frontend/antd/splitter/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [backend/modelscope_studio/components/antd/splitter/panel/**init**.py:1-85](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L1-L85) + +Section Sources + +- [frontend/antd/splitter/Index.svelte:1-71](file://frontend/antd/splitter/Index.svelte#L1-L71) +- [frontend/antd/splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [frontend/antd/splitter/panel/Index.svelte:1-77](file://frontend/antd/splitter/panel/Index.svelte#L1-L77) +- [frontend/antd/splitter/panel/splitter.panel.tsx:1-14](file://frontend/antd/splitter/panel/splitter.panel.tsx#L1-L14) +- [frontend/antd/splitter/context.ts:1-7](file://frontend/antd/splitter/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [backend/modelscope_studio/components/antd/splitter/panel/**init**.py:1-85](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L1-L85) +- [docs/components/antd/splitter/README.md:1-8](file://docs/components/antd/splitter/README.md#L1-L8) + +## Core Components + +- Splitter Container: Receives the collection of child panels, renders the Ant Design split container, and maps each Panel to an Antd Panel child item. +- Panel Sub-component: Serves as the placeholder and rendering unit for each panel, collecting panel properties and slot content via the Items context and injecting them into Splitter. +- Items Context: Provides "item collection" capability, allowing Panel to inject its own properties and DOM content into Splitter during rendering. +- Backend Wrapper: Python-layer `AntdSplitterPanel` declares and passes properties such as default size, min/max size, collapsibility, and resizability. + +Section Sources + +- [frontend/antd/splitter/splitter.tsx:7-35](file://frontend/antd/splitter/splitter.tsx#L7-L35) +- [frontend/antd/splitter/panel/splitter.panel.tsx:7-11](file://frontend/antd/splitter/panel/splitter.panel.tsx#L7-L11) +- [frontend/antd/splitter/context.ts:3-4](file://frontend/antd/splitter/context.ts#L3-L4) +- [frontend/utils/createItemsContext.tsx:97-184](file://frontend/utils/createItemsContext.tsx#L97-L184) +- [backend/modelscope_studio/components/antd/splitter/panel/**init**.py:8-68](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L8-L68) + +## Architecture Overview + +The Splitter runtime flow is as follows: + +- The Svelte entry bridging component loads the Splitter and Panel components; +- Panel writes its own properties and slot content to the Items context via ItemHandler; +- Splitter is wrapped with `withItemsContextProvider` and reads the collected panel list from the context; +- Finally, Ant Design's Splitter and Panel are rendered. + +```mermaid +sequenceDiagram +participant U as "User" +participant S as "Splitter.Index.svelte" +participant P as "Panel.Index.svelte" +participant IH as "ItemHandler (splt.panel.tsx)" +participant CTX as "ItemsContext (context.ts)" +participant RCTX as "createItemsContext.tsx" +participant C as "Antd Splitter" +U->>S : Render Splitter +S->>RCTX : Initialize Items context +U->>P : Render Panel +P->>IH : Create ItemHandler +IH->>CTX : setItem(..., index, item) +CTX-->>S : Context change callback +S->>C : Render Antd Splitter +C-->>U : Draggable split panels +``` + +Diagram Sources + +- [frontend/antd/splitter/Index.svelte:10-52](file://frontend/antd/splitter/Index.svelte#L10-L52) +- [frontend/antd/splitter/panel/Index.svelte:10-69](file://frontend/antd/splitter/panel/Index.svelte#L10-L69) +- [frontend/antd/splitter/panel/splitter.panel.tsx:7-11](file://frontend/antd/splitter/panel/splitter.panel.tsx#L7-L11) +- [frontend/antd/splitter/context.ts:3-4](file://frontend/antd/splitter/context.ts#L3-L4) +- [frontend/utils/createItemsContext.tsx:108-170](file://frontend/utils/createItemsContext.tsx#L108-L170) +- [frontend/antd/splitter/splitter.tsx:7-35](file://frontend/antd/splitter/splitter.tsx#L7-L35) + +## Detailed Component Analysis + +### Splitter Container Component + +- Responsibility boundary: Maps collected panel items to Ant Design Panel elements and renders the split container. +- Key points: + - Wrapped with `withItemsContextProvider` to ensure it can read `items` injected by Panels. + - Renders slot content to the corresponding Panel via ReactSlot. + - When no panels are present, nothing is rendered, avoiding layout issues caused by empty containers. + +```mermaid +flowchart TD +Start(["Enter Splitter"]) --> Read["Read context items"] +Read --> HasPanels{"Are there panels?"} +HasPanels -- No --> Exit["Return empty"] +HasPanels -- Yes --> Render["Iterate panels and render Antd Panel"] +Render --> Done(["Complete"]) +``` + +Diagram Sources + +- [frontend/antd/splitter/splitter.tsx:8-35](file://frontend/antd/splitter/splitter.tsx#L8-L35) + +Section Sources + +- [frontend/antd/splitter/splitter.tsx:7-35](file://frontend/antd/splitter/splitter.tsx#L7-L35) + +### Panel Sub-component + +- Responsibility boundary: Serves as the placeholder and rendering unit for a single panel, responsible for injecting its own properties and slot content into the Items context. +- Key points: + - Writes `itemIndex`, `itemSlotKey`, `itemElement`, and other information to the context via `ItemHandler`. + - Supports `visible` for display control; supports additional property pass-through and style class binding. + - Slot content is collected via the Svelte slot mechanism and rendered in Splitter as ReactSlot. + +```mermaid +classDiagram +class PanelBridge { ++props : all pass-through properties ++visible : visibility flag ++_internal.index : panel index ++elem_id/ elem_classes/ elem_style : styles and identifiers ++slots : slot content +} +class ItemHandler { ++itemIndex : number ++itemSlotKey : string ++itemElement : HTMLElement ++setItem(...) +} +PanelBridge --> ItemHandler : "Inject item" +``` + +Diagram Sources + +- [frontend/antd/splitter/panel/Index.svelte:25-69](file://frontend/antd/splitter/panel/Index.svelte#L25-L69) +- [frontend/antd/splitter/panel/splitter.panel.tsx:7-11](file://frontend/antd/splitter/panel/splitter.panel.tsx#L7-L11) +- [frontend/antd/splitter/context.ts:3-4](file://frontend/antd/splitter/context.ts#L3-L4) + +Section Sources + +- [frontend/antd/splitter/panel/Index.svelte:14-69](file://frontend/antd/splitter/panel/Index.svelte#L14-L69) +- [frontend/antd/splitter/panel/splitter.panel.tsx:7-11](file://frontend/antd/splitter/panel/splitter.panel.tsx#L7-L11) +- [frontend/antd/splitter/context.ts:3-4](file://frontend/antd/splitter/context.ts#L3-L4) + +### Items Context and Item Collection Mechanism + +- Purpose: Establishes an "item collection" channel in the component tree, enabling Panel to write its own properties and DOM content into Splitter. +- Key points: + - `withItemsContextProvider`: Provides an `ItemsContextProvider` for the component tree, maintaining an `items` map and a `setItem` method. + - `useItems`: Reads the `items` list within Splitter. + - `ItemHandler`: Writes items during Panel rendering, supporting `itemProps`, `itemChildren`, and other extended capabilities. + +```mermaid +sequenceDiagram +participant P as "Panel" +participant IH as "ItemHandler" +participant CTX as "ItemsContext" +participant SP as "Splitter" +P->>IH : Call ItemHandler +IH->>CTX : setItem(slotKey, index, item) +CTX-->>SP : Trigger onChange callback +SP->>SP : Update internal items and re-render +``` + +Diagram Sources + +- [frontend/utils/createItemsContext.tsx:108-170](file://frontend/utils/createItemsContext.tsx#L108-L170) +- [frontend/utils/createItemsContext.tsx:186-261](file://frontend/utils/createItemsContext.tsx#L186-L261) +- [frontend/antd/splitter/splitter.tsx:8-11](file://frontend/antd/splitter/splitter.tsx#L8-L11) + +Section Sources + +- [frontend/utils/createItemsContext.tsx:97-184](file://frontend/utils/createItemsContext.tsx#L97-L184) +- [frontend/utils/createItemsContext.tsx:186-261](file://frontend/utils/createItemsContext.tsx#L186-L261) +- [frontend/antd/splitter/context.ts:3-4](file://frontend/antd/splitter/context.ts#L3-L4) + +### Backend Wrapper and Property Passing + +- `AntdSplitterPanel` provides the following key properties (from the Python wrapper): + - `default_size`: Default panel size + - `min` / `max`: Minimum/maximum size + - `size`: Current size + - `collapsible`: Whether the panel is collapsible + - `resizable`: Whether the panel is resizable + - `elem_id` / `elem_classes` / `elem_style`: Styles and identifiers +- These properties are passed through the Svelte bridging layer to frontend components, ultimately affecting the behavior and appearance of Ant Design Splitter. + +Section Sources + +- [backend/modelscope_studio/components/antd/splitter/panel/**init**.py:8-68](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L8-L68) + +## Dependency Analysis + +- Component coupling: + - Splitter depends on the Items context to obtain the panel collection. + - Panel depends on the Items context via ItemHandler to write its own item. + - The frontend bridging layer (Index.svelte) is responsible for passing properties and slots to React components. +- External dependencies: + - Ant Design's Splitter/Panel interface. + - Svelte Preprocess React toolchain (`sveltify`, `ReactSlot`, `processProps`, etc.). +- Potential circular dependencies: + - Decoupled through context and callbacks to avoid circular references caused by direct mutual referencing. + +```mermaid +graph LR +IDX["Index.svelte"] --> SPLIT["splitter.tsx"] +IDX --> PANEL_IDX["panel/Index.svelte"] +PANEL_IDX --> PANEL_IMPL["panel/splitter.panel.tsx"] +SPLIT --> CTX["context.ts"] +PANEL_IMPL --> CTX +CTX --> UTILS["createItemsContext.tsx"] +``` + +Diagram Sources + +- [frontend/antd/splitter/Index.svelte:10-52](file://frontend/antd/splitter/Index.svelte#L10-L52) +- [frontend/antd/splitter/splitter.tsx:5-6](file://frontend/antd/splitter/splitter.tsx#L5-L6) +- [frontend/antd/splitter/panel/Index.svelte:10-11](file://frontend/antd/splitter/panel/Index.svelte#L10-L11) +- [frontend/antd/splitter/panel/splitter.panel.tsx:5-5](file://frontend/antd/splitter/panel/splitter.panel.tsx#L5-L5) +- [frontend/antd/splitter/context.ts:3-4](file://frontend/antd/splitter/context.ts#L3-L4) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +Section Sources + +- [frontend/antd/splitter/Index.svelte:1-71](file://frontend/antd/splitter/Index.svelte#L1-L71) +- [frontend/antd/splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [frontend/antd/splitter/panel/Index.svelte:1-77](file://frontend/antd/splitter/panel/Index.svelte#L1-L77) +- [frontend/antd/splitter/panel/splitter.panel.tsx:1-14](file://frontend/antd/splitter/panel/splitter.panel.tsx#L1-L14) +- [frontend/antd/splitter/context.ts:1-7](file://frontend/antd/splitter/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +## Performance Considerations + +- Rendering strategy + - Splitter only renders the container when panels are present, avoiding the overhead of empty renders. + - `useMemoizedEqualValue` and `useMemoizedFn` reduce context update frequency and repeated renders. +- Events and state + - `setItem` and `onChange` are triggered only when values change, reducing unnecessary re-renders. +- Recommendations + - For scenarios with many panels or frequent size adjustments, limit the number of panels and update frequency. + - Set reasonable min/max sizes to avoid reflow jitter caused by extreme sizes. + +Section Sources + +- [frontend/antd/splitter/splitter.tsx:15-31](file://frontend/antd/splitter/splitter.tsx#L15-L31) +- [frontend/utils/createItemsContext.tsx:113-153](file://frontend/utils/createItemsContext.tsx#L113-L153) +- [frontend/utils/createItemsContext.tsx:234-254](file://frontend/utils/createItemsContext.tsx#L234-L254) + +## Troubleshooting Guide + +- Panel not displaying + - Check whether Panel's `visible` is true; confirm that the bridging layer has correctly passed `visible`. + - Confirm whether Panel has successfully written to the Items context (check `setItem` calls and indices). +- Drag not working + - Confirm that `resizable` and resizable direction settings are correct; check Ant Design version and whether styles are complete. +- Size anomalies + - Check whether `min`/`max` and `default_size` settings are reasonable; avoid setting them to 0 or negative values. +- Slot content not rendering + - Confirm that Panel's slot bindings are consistent with ReactSlot usage; avoid premature slot destruction. + +Section Sources + +- [frontend/antd/splitter/panel/Index.svelte:52-69](file://frontend/antd/splitter/panel/Index.svelte#L52-L69) +- [frontend/antd/splitter/splitter.tsx:14-31](file://frontend/antd/splitter/splitter.tsx#L14-L31) +- [backend/modelscope_studio/components/antd/splitter/panel/**init**.py:62-66](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L62-L66) + +## Conclusion + +Splitter achieves flexible panel organization and rendering through the Items context and Svelte/React bridging. Its core strengths are: + +- User-facing declarative API (Panel sub-component) +- Deep integration with Ant Design (drag, direction, size control) +- Extensible item collection mechanism (supports dynamic add/remove/update) + +In practice, it is recommended to set reasonable size constraints and interaction behaviors based on business scenarios, with attention to performance and maintainability. + +## Appendix + +### Configuration and Property Reference + +- Splitter Container + - Direction: Controlled by Ant Design's direction property (horizontal/vertical) + - Drag: Provided by Ant Design's drag capability + - Events: `resizeStart`/`resizeEnd` (mapped via bridging layer) +- Panel Sub-component + - `default_size` / `size`: Default/current size + - `min` / `max`: Minimum/maximum size + - `collapsible` / `resizable`: Collapsible/resizable + - `elem_id` / `elem_classes` / `elem_style`: Styles and identifiers + - `visible`: Visibility flag + +Section Sources + +- [frontend/antd/splitter/Index.svelte:25-52](file://frontend/antd/splitter/Index.svelte#L25-L52) +- [frontend/antd/splitter/splitter.tsx:16-30](file://frontend/antd/splitter/splitter.tsx#L16-L30) +- [backend/modelscope_studio/components/antd/splitter/panel/**init**.py:61-66](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L61-L66) + +### Application Scenario Examples + +- Code editor: File tree/outline on the left, code editing area on the right, with left-right drag to adjust width. +- Image comparison: Two images arranged left-right or top-bottom, with drag to adjust the ratio. +- Multi-view display: Three-column layout (left/center/right), center as main view, sides as tool/preview panels. + +Section Sources + +- [docs/components/antd/splitter/README.md:1-8](file://docs/components/antd/splitter/README.md#L1-L8) + +### Responsive Behavior and Interaction Experience + +- Responsive behavior: Adapts panel ratios based on container width/height; it is recommended to enable collapsibility on small-screen devices. +- Interaction experience: Provides visual feedback during dragging; set reasonable minimum sizes to avoid accidental triggers. + +Section Sources + +- [backend/modelscope_studio/components/antd/splitter/panel/**init**.py:14-16](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L14-L16) + +### Style Customization and Accessibility + +- Style customization: Inject custom styles via `elem_classes` and `elem_style`; note compatibility with Ant Design default styles. +- Animation effects: Combine CSS transitions or third-party animation libraries for smooth size switching. +- Accessibility: Provide accessible labels and keyboard operation hints for drag handles; ensure collapsible states have clear ARIA attributes. + +Section Sources + +- [frontend/antd/splitter/panel/Index.svelte:54-55](file://frontend/antd/splitter/panel/Index.svelte#L54-L55) +- [frontend/antd/splitter/splitter.tsx:16-30](file://frontend/antd/splitter/splitter.tsx#L16-L30) diff --git a/.wiki/en/Ant Design Components/Navigation Components/Anchor.md b/.wiki/en/Ant Design Components/Navigation Components/Anchor.md new file mode 100644 index 00000000..0ccd423e --- /dev/null +++ b/.wiki/en/Ant Design Components/Navigation Components/Anchor.md @@ -0,0 +1,302 @@ +# Anchor + + +**Files Referenced in This Document** +- [frontend/antd/anchor/Index.svelte](file://frontend/antd/anchor/Index.svelte) +- [frontend/antd/anchor/anchor.tsx](file://frontend/antd/anchor/anchor.tsx) +- [frontend/antd/anchor/context.ts](file://frontend/antd/anchor/context.ts) +- [frontend/antd/anchor/item/Index.svelte](file://frontend/antd/anchor/item/Index.svelte) +- [frontend/antd/anchor/item/anchor.item.tsx](file://frontend/antd/anchor/item/anchor.item.tsx) +- [backend/modelscope_studio/components/antd/anchor/__init__.py](file://backend/modelscope_studio/components/antd/anchor/__init__.py) +- [backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js](file://backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js) +- [docs/components/antd/anchor/README.md](file://docs/components/antd/anchor/README.md) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +The Anchor component provides clickable navigation links within a single page, supporting scroll-based positioning to corresponding headings or sections, and can be combined with fixed mode (Affix) to remain visible while the page scrolls. This component is a wrapper around Ant Design's Anchor component and provides the following capabilities: + +- Scroll positioning: Smooth or direct scrolling to target positions of anchor items +- Link generation: Supports dynamically generating anchor items via an `items` list or slots +- Active state management: Automatically highlights anchor items currently in the viewport +- Nested structure: Anchor items support nesting to form hierarchical navigation +- Events and extensions: Supports `change`, `click`, and `affix_change` event bindings, as well as Affix fixed mode + +## Project Structure + +The Anchor component consists of a frontend Svelte wrapper layer and a backend Gradio component layer, along with an anchor item sub-component to support nesting and slot rendering. + +```mermaid +graph TB +subgraph "Frontend" +A_Index["frontend/antd/anchor/Index.svelte"] +A_Component["frontend/antd/anchor/anchor.tsx"] +A_Context["frontend/antd/anchor/context.ts"] +A_Item_Index["frontend/antd/anchor/item/Index.svelte"] +A_Item_Component["frontend/antd/anchor/item/anchor.item.tsx"] +end +subgraph "Backend" +B_Anchor["backend/modelscope_studio/components/antd/anchor/__init__.py"] +B_Item_Template["backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js"] +end +subgraph "Documentation" +D_Readme["docs/components/antd/anchor/README.md"] +end +A_Index --> A_Component +A_Component --> A_Context +A_Item_Index --> A_Item_Component +A_Component --> B_Anchor +A_Item_Component --> B_Item_Template +D_Readme --> B_Anchor +``` + +Diagram Sources + +- [frontend/antd/anchor/Index.svelte:1-66](file://frontend/antd/anchor/Index.svelte#L1-L66) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [frontend/antd/anchor/item/Index.svelte:1-75](file://frontend/antd/anchor/item/Index.svelte#L1-L75) +- [frontend/antd/anchor/item/anchor.item.tsx:1-22](file://frontend/antd/anchor/item/anchor.item.tsx#L1-L22) +- [backend/modelscope_studio/components/antd/anchor/**init**.py:1-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L1-L117) +- [backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js:1-450](file://backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js#L1-L450) +- [docs/components/antd/anchor/README.md:1-8](file://docs/components/antd/anchor/README.md#L1-L8) + +Section Sources + +- [frontend/antd/anchor/Index.svelte:1-66](file://frontend/antd/anchor/Index.svelte#L1-L66) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [frontend/antd/anchor/item/Index.svelte:1-75](file://frontend/antd/anchor/item/Index.svelte#L1-L75) +- [frontend/antd/anchor/item/anchor.item.tsx:1-22](file://frontend/antd/anchor/item/anchor.item.tsx#L1-L22) +- [backend/modelscope_studio/components/antd/anchor/**init**.py:1-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L1-L117) +- [backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js:1-450](file://backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js#L1-L450) +- [docs/components/antd/anchor/README.md:1-8](file://docs/components/antd/anchor/README.md#L1-L8) + +## Core Components + +- Top-level Anchor component (AntdAnchor) + - Receives an `items` list or slot children, converting them to the items structure required by Ant Design Anchor + - Supports `affix`, `bounds`, `offsetTop`, `direction`, `replace`, `rootClassName`, and other properties + - Provides `change`, `click`, and `affix_change` event binding entry points +- Anchor item component (AntdAnchorItem) + - Acts as the container for anchor items, supporting default slot content rendering + - Collaborates with the parent anchor component via the context system to achieve nesting and hierarchical display + +Section Sources + +- [backend/modelscope_studio/components/antd/anchor/**init**.py:11-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L11-L117) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [frontend/antd/anchor/item/Index.svelte:1-75](file://frontend/antd/anchor/item/Index.svelte#L1-L75) +- [frontend/antd/anchor/item/anchor.item.tsx:1-22](file://frontend/antd/anchor/item/anchor.item.tsx#L1-L22) + +## Architecture Overview + +The following diagram shows the call chain from the backend Gradio component to the frontend Svelte/React wrapper layer and on to Ant Design Anchor, as well as the event and slot passing process. + +```mermaid +sequenceDiagram +participant Backend as "Backend Component
AntdAnchor" +participant FrontIndex as "Frontend Wrapper
Index.svelte" +participant AnchorTSX as "Frontend Implementation
anchor.tsx" +participant Context as "Context
context.ts" +participant Antd as "Ant Design Anchor" +Backend->>FrontIndex : Render wrapper component and pass props +FrontIndex->>AnchorTSX : Pass restProps, additionalProps, slots +AnchorTSX->>Context : Use Items context to resolve slots items/default +AnchorTSX->>Antd : Render Anchor and inject items, getContainer, getCurrentAnchor +Antd-->>AnchorTSX : Trigger change/click/affix_change event callbacks +AnchorTSX-->>FrontIndex : Pass events to backend +``` + +Diagram Sources + +- [frontend/antd/anchor/Index.svelte:1-66](file://frontend/antd/anchor/Index.svelte#L1-L66) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [backend/modelscope_studio/components/antd/anchor/**init**.py:11-33](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L11-L33) + +## Detailed Component Analysis + +### Top-level Anchor Component (AntdAnchor) + +- Feature highlights + - Receives an `items` list or slot children; internally converts slots to items via utility functions + - Supports `getContainer` and `getCurrentAnchor` for custom container and current anchor determination logic + - Provides Affix fixed mode, `bounds` boundary distance, `offsetTop` top offset, `direction`, `replace` history replacement, and other configurations + - Events: `change` (anchor changed), `click` (clicked), `affix_change` (fixed state changed) +- Data flow + - Slots `items/default` → context resolution → Ant Design Anchor items + - `getContainer`/`getCurrentAnchor` are passed to Ant Design Anchor after being wrapped with `useFunction` +- Applicable scenarios + - Document tables of contents, long-list navigation, help centers, product introduction pages, and other scenarios requiring quick jumping + +```mermaid +flowchart TD +Start(["Start"]) --> Resolve["Resolve slots items/default"] +Resolve --> HasItems{"Are items params provided?"} +HasItems --> |Yes| UseParam["Use passed-in items"] +HasItems --> |No| RenderItems["Render items via utility functions"] +UseParam --> BuildProps["Build Anchor properties"] +RenderItems --> BuildProps +BuildProps --> Inject["Inject getContainer / getCurrentAnchor"] +Inject --> Render["Render Ant Design Anchor"] +Render --> End(["End"]) +``` + +Diagram Sources + +- [frontend/antd/anchor/anchor.tsx:13-42](file://frontend/antd/anchor/anchor.tsx#L13-L42) + +Section Sources + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [backend/modelscope_studio/components/antd/anchor/**init**.py:38-98](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L38-L98) + +### Anchor Item Component (AntdAnchorItem) + +- Feature highlights + - Acts as the container for anchor items, supporting default slot content rendering + - Maps slot content to AntdAnchor item children via `ItemHandler` + - Supports `href_target` property mapped to `target` attribute, for controlling link opening behavior +- Nested structure + - Cooperates with the parent via `createItemsContext` to support multi-level nested anchor items +- Applicable scenarios + - Grouping and hierarchically displaying sections in complex documents + +```mermaid +classDiagram +class AnchorItem { ++Allowed slot : "default" ++Property : "href_target" -> "target" ++Function : "Map slot content to item children" +} +class Context { ++useItems() ++withItemsContextProvider() ++ItemHandler +} +AnchorItem --> Context : "Use context" +``` + +Diagram Sources + +- [frontend/antd/anchor/item/anchor.item.tsx:1-22](file://frontend/antd/anchor/item/anchor.item.tsx#L1-L22) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) + +Section Sources + +- [frontend/antd/anchor/item/Index.svelte:1-75](file://frontend/antd/anchor/item/Index.svelte#L1-L75) +- [frontend/antd/anchor/item/anchor.item.tsx:1-22](file://frontend/antd/anchor/item/anchor.item.tsx#L1-L22) +- [backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js:437-449](file://backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js#L437-L449) + +### Events and Lifecycle + +- `change`: Triggered when the currently active anchor changes +- `click`: Triggered when an anchor link is clicked +- `affix_change`: Triggered when the Affix fixed mode state changes +- Lifecycle: The component updates the layout marker when it exits scope, ensuring correct render ordering + +Section Sources + +- [backend/modelscope_studio/components/antd/anchor/**init**.py:20-33](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L20-L33) +- [backend/modelscope_studio/utils/dev/component.py:24-26](file://backend/modelscope_studio/utils/dev/component.py#L24-L26) + +## Dependency Analysis + +- The frontend wrapper layer depends on Ant Design Anchor, bridged via `sveltify` and `withItemsContextProvider` +- The slot system implements parent-child component communication via `createItemsContext`, supporting both `items` and `default` slots +- The backend component inherits from `ModelScopeLayoutComponent`, providing unified layout and event binding capabilities + +```mermaid +graph LR +AnchorTSX["anchor.tsx"] --> Antd["Ant Design Anchor"] +AnchorTSX --> Context["context.ts"] +AnchorItemTSX["anchor.item.tsx"] --> Context +AnchorTSX --> Backend["AntdAnchor(__init__.py)"] +AnchorItemTSX --> BackendItem["anchor.item Template"] +``` + +Diagram Sources + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [frontend/antd/anchor/item/anchor.item.tsx:1-22](file://frontend/antd/anchor/item/anchor.item.tsx#L1-L22) +- [backend/modelscope_studio/components/antd/anchor/**init**.py:1-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L1-L117) +- [backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js:1-450](file://backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js#L1-L450) + +Section Sources + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [frontend/antd/anchor/item/anchor.item.tsx:1-22](file://frontend/antd/anchor/item/anchor.item.tsx#L1-L22) +- [backend/modelscope_studio/components/antd/anchor/**init**.py:1-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L1-L117) +- [backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js:1-450](file://backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js#L1-L450) + +## Performance Considerations + +- items rendering optimization + - Use `useMemo` to cache items computation results, avoiding unnecessary re-renders + - Prefer passing the `items` parameter rather than relying on slots to reduce slot resolution costs +- Function wrapping + - Wrap `getContainer`/`getCurrentAnchor` with `useFunction` to ensure callbacks are stable and reusable +- Scroll monitoring + - Set `bounds` and `offsetTop` reasonably to avoid frequent `change` event triggers + - For large documents, consider using `replace` to replace history records, reducing memory usage +- Fixed mode (Affix) + - Affix mode keeps the component visible during scrolling; pay attention to container selection and z-index relationships to avoid occlusion + +## Troubleshooting Guide + +- Anchor not working + - Check whether `getContainer` points to the correct scroll container; if not set, the viewport may not be calculated correctly + - Confirm the target element exists and has the corresponding anchor identifier +- Active state not updating + - Check whether `bounds` and `offsetTop` settings are reasonable; too small a boundary may cause delayed switching + - Confirm the `getCurrentAnchor` return value matches the `key` or `href` in `items` +- Link opening behavior abnormal + - `href_target` maps to `target`; confirm whether it needs to open in a new window or the current window +- Events not triggering + - Confirm event bindings are enabled (`bind_change_event`, `bind_click_event`, `bind_affix_change_event`) + - Check whether state changes in Affix mode behave as expected + +Section Sources + +- [frontend/antd/anchor/anchor.tsx:13-42](file://frontend/antd/anchor/anchor.tsx#L13-L42) +- [backend/modelscope_studio/components/antd/anchor/**init**.py:20-33](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L20-L33) + +## Conclusion + +The Anchor component provides flexible anchor navigation capabilities through frontend-backend collaboration. Its core strengths are: + +- Dual-channel anchor item generation via `items` and slots, meeting different scenario needs +- Deep integration with Ant Design Anchor, with comprehensive scroll positioning and active state management +- A complete event system that facilitates extended interactions and analytics tracking +- Support for nested structure and fixed mode, suitable for complex documents and long-page navigation + +## Appendix + +- Usage examples and documentation + - Refer to basic examples in the documentation for fundamental usage and parameter descriptions +- Common issues + - If the page has multiple scroll containers, explicitly specify `getContainer` + - For large documents, consider enabling `replace` to optimize history management + - To customize highlight strategy, use `getCurrentAnchor` for customization + +Section Sources + +- [docs/components/antd/anchor/README.md:1-8](file://docs/components/antd/anchor/README.md#L1-L8) diff --git a/.wiki/en/Ant Design Components/Navigation Components/Breadcrumb.md b/.wiki/en/Ant Design Components/Navigation Components/Breadcrumb.md new file mode 100644 index 00000000..36ceca66 --- /dev/null +++ b/.wiki/en/Ant Design Components/Navigation Components/Breadcrumb.md @@ -0,0 +1,393 @@ +# Breadcrumb + + +**Files Referenced in This Document** +- [frontend/antd/breadcrumb/breadcrumb.tsx](file://frontend/antd/breadcrumb/breadcrumb.tsx) +- [frontend/antd/breadcrumb/context.ts](file://frontend/antd/breadcrumb/context.ts) +- [frontend/antd/breadcrumb/Index.svelte](file://frontend/antd/breadcrumb/Index.svelte) +- [backend/modelscope_studio/components/antd/breadcrumb/__init__.py](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py) +- [backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) +- [docs/components/antd/breadcrumb/README.md](file://docs/components/antd/breadcrumb/README.md) +- [docs/components/antd/breadcrumb/README-zh_CN.md](file://docs/components/antd/breadcrumb/README-zh_CN.md) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Usage Examples and Best Practices](#appendix-usage-examples-and-best-practices) + +## Introduction + +The Breadcrumb component displays the current location within a hierarchical structure and allows users to return to previous states. The breadcrumb component in this repository is based on Ant Design's Breadcrumb implementation, wrapped via React and bridged to the Svelte frontend, while also providing a Python backend component to support layout and event binding in the Gradio ecosystem. The component supports: + +- Navigation path display and click-to-navigate +- Custom separators and rendering of each breadcrumb item +- Advanced interactions such as dropdown menus and overflow indicators +- Dynamic path generation and permission control when integrating with routing systems +- Multi-language and theme style customization + +## Project Structure + +The Breadcrumb component consists of a frontend React wrapper layer, a Svelte bridging layer, a backend Gradio component layer, and a runtime template, organized as follows: + +```mermaid +graph TB +subgraph "Frontend" +SvelteIndex["frontend/antd/breadcrumb/Index.svelte"] +ReactWrapper["frontend/antd/breadcrumb/breadcrumb.tsx"] +ItemsCtx["frontend/antd/breadcrumb/context.ts"] +end +subgraph "Backend" +PyComp["backend/modelscope_studio/components/antd/breadcrumb/__init__.py"] +PyItem["backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py"] +DevBase["backend/modelscope_studio/utils/dev/component.py"] +ResolveDir["backend/modelscope_studio/utils/dev/resolve_frontend_dir.py"] +end +subgraph "Runtime Template" +RuntimeJS["backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js"] +end +SvelteIndex --> ReactWrapper +ReactWrapper --> ItemsCtx +PyComp --> ResolveDir +PyComp --> RuntimeJS +PyItem --> ResolveDir +PyItem --> RuntimeJS +DevBase --> PyComp +DevBase --> PyItem +``` + +Diagram Sources + +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:1-114](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L1-L114) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:1-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L1-L17) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:1-766](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L1-L766) + +Section Sources + +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:1-114](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L1-L114) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:1-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L1-L17) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:1-766](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L1-L766) + +## Core Components + +- Frontend React wrapper: Connects Ant Design's Breadcrumb with the Slots rendering system, supporting custom separators, item renderer functions, and dropdown icons. +- Svelte bridging: Converts backend-provided properties and slots into frontend-consumable props, and imports React components as needed. +- Backend components: Provides `AntdBreadcrumb` and `AntdBreadcrumbItem`, supporting event bindings, slots, and frontend directory resolution. +- Runtime template: Contains the actual React component implementation and slot handling logic. + +Section Sources + +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:1-114](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L1-L114) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:1-766](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L1-L766) + +## Architecture Overview + +The Breadcrumb component call chain from backend to frontend is as follows: + +```mermaid +sequenceDiagram +participant Py as "Python Backend Component
AntdBreadcrumb/AntdBreadcrumbItem" +participant Svelte as "Svelte Bridging
Index.svelte" +participant React as "React Wrapper
breadcrumb.tsx" +participant AD as "Ant Design Breadcrumb" +Py->>Svelte : Resolve frontend directory and pass properties/slots +Svelte->>React : Convert props and inject slots +React->>AD : Render Breadcrumb, apply custom separator/item renderer/dropdown icon +AD-->>React : Render result +React-->>Svelte : Return DOM +Svelte-->>Py : Render complete +``` + +Diagram Sources + +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:1-114](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L1-L114) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:1-766](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L1-L766) + +## Detailed Component Analysis + +### Frontend React Wrapper (breadcrumb.tsx) + +- Key points + - Uses `sveltify` to bridge the Svelte component to React. + - Provides breadcrumb item context via `withItemsContextProvider`. + - Supports slots: `separator`, `itemRender`, `dropdownIcon`; prefers slots, falls back to props. + - Uses `renderItems` to convert slot items into the `ItemType` list required by Ant Design. + - Uses `renderParamsSlot` to render the parameterized `itemRender` slot. +- Key flow + - Reads `items/default` from context. + - Computes the final items list (items takes priority over slots). + - Renders Ant Design Breadcrumb with injected custom separator and item renderer. + +```mermaid +flowchart TD +Start(["Enter React Wrapper"]) --> ReadCtx["Read context items/default"] +ReadCtx --> DecideItems{"Are items params provided?"} +DecideItems --> |Yes| UseParam["Use passed-in items"] +DecideItems --> |No| UseSlot["Use items/default slot"] +UseParam --> RenderItems["renderItems converts to AntD Item type"] +UseSlot --> RenderItems +RenderItems --> ApplySlots{"Do slots exist?"} +ApplySlots --> |separator| SepSlot["Use separator slot"] +ApplySlots --> |itemRender| ItemRenderSlot["Use itemRender slot"] +ApplySlots --> |dropdownIcon| DropSlot["Use dropdownIcon slot"] +ApplySlots --> |none| UseProps["Use original prop values"] +SepSlot --> RenderAD["Render AntD Breadcrumb"] +ItemRenderSlot --> RenderAD +DropSlot --> RenderAD +UseProps --> RenderAD +RenderAD --> End(["Complete"]) +``` + +Diagram Sources + +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:727-761](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L727-L761) + +Section Sources + +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:727-761](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L727-L761) + +### Svelte Bridging (Index.svelte) + +- Key points + - Retrieves backend-provided props and additional properties. + - Maps event names to camelCase as required by Ant Design. + - Renders `children` as child nodes of the React component. + - Asynchronously loads the React-wrapped Breadcrumb via `importComponent`. +- Key flow + - `processProps` normalizes properties and handles event aliases. + - `getSlots` retrieves the set of slots. + - Renders Breadcrumb and passes in slots and children. + +```mermaid +sequenceDiagram +participant Svelte as "Index.svelte" +participant Loader as "importComponent" +participant Wrapper as "breadcrumb.tsx" +Svelte->>Loader : Load React wrapper component +Loader-->>Svelte : Return component reference +Svelte->>Wrapper : Pass props/slots/children +Wrapper-->>Svelte : Return render result +``` + +Diagram Sources + +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) + +Section Sources + +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) + +### Backend Components (AntdBreadcrumb / AntdBreadcrumbItem) + +- AntdBreadcrumb + - Supported slots: `separator`, `itemRender`, `items`, `dropdownIcon`. + - Points to the frontend breadcrumb directory via `resolve_frontend_dir`. + - Inherits `ModelScopeLayoutComponent` with general layout component capabilities. +- AntdBreadcrumbItem + - Supported slots: `title`, `menu.*`, `dropdownProps.*`, `dropdownProps.menu.*`. + - Supports events: `click`, `menu_*`, `dropdownProps_*`, etc., for interacting with routes or menus. + - Points to the frontend breadcrumb/item sub-component directory via `resolve_frontend_dir`. + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++skip_api : bool ++SLOTS : list ++__init__(...) +} +class AntdBreadcrumb { ++SLOTS : list ++FRONTEND_DIR : str ++__init__(...) +} +class AntdBreadcrumbItem { ++SLOTS : list ++EVENTS : list ++FRONTEND_DIR : str ++__init__(...) +} +ModelScopeLayoutComponent <|-- AntdBreadcrumb +ModelScopeLayoutComponent <|-- AntdBreadcrumbItem +``` + +Diagram Sources + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:1-114](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L1-L114) + +Section Sources + +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:1-114](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L1-L114) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:1-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L1-L17) + +### Runtime Template (breadcrumb-C7MaDQtV.js) + +- Key points + - Provides `createItemsContext` context for sharing breadcrumb items in the React layer. + - Provides runtime implementations of `renderItems` and `renderParamsSlot`, supporting slot cloning and parameterized rendering. + - Converts Svelte slots into React-consumable structures, supporting nested slots and menu items. +- Key flow + - Reads `items/default` from context. + - Uses utility functions `ve/oe/Mt` to convert slots into props required by AntD. + - Renders AntD Breadcrumb with custom separator and item renderer applied. + +```mermaid +flowchart TD +LoadCtx["Read context items/default"] --> MergeItems["Merge items/default"] +MergeItems --> Convert["ve/oe/Mt convert slots to React structure"] +Convert --> RenderAD["Render AntD Breadcrumb"] +RenderAD --> Done(["Complete"]) +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:727-761](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L727-L761) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:649-726](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L649-L726) + +Section Sources + +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:1-766](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L1-L766) + +## Dependency Analysis + +- Frontend dependencies + - React wrapper depends on Ant Design Breadcrumb types and rendering utilities. + - Svelte bridging depends on `@svelte-preprocess-react` component import and slot system. +- Backend dependencies + - `AntdBreadcrumb`/`AntdBreadcrumbItem` depend on `resolve_frontend_dir` for frontend directory resolution. + - Inherits `ModelScopeLayoutComponent`, reusing general layout component capabilities. +- Runtime dependencies + - The template file provides slot and context handling logic, ensuring consistent rendering behavior between frontend and backend. + +```mermaid +graph LR +PyComp["AntdBreadcrumb"] --> Resolve["resolve_frontend_dir"] +PyItem["AntdBreadcrumbItem"] --> Resolve +PyComp --> Runtime["Runtime Template breadcrumb-C7MaDQtV.js"] +PyItem --> Runtime +Svelte["Index.svelte"] --> ReactWrap["breadcrumb.tsx"] +ReactWrap --> AD["Ant Design Breadcrumb"] +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:56-56](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L56-L56) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:97-97](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L97-L97) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-16](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L16) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:1-766](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L1-L766) +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) + +Section Sources + +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:1-114](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L1-L114) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:1-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L1-L17) +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:1-766](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L1-L766) + +## Performance Considerations + +- Slot cloning strategy + - Slot rendering defaults to a cloning strategy to avoid duplicate rendering overhead, but can be controlled via `forceClone`. +- Computation caching + - Uses `useMemo` to cache the final items list, reducing unnecessary re-renders. +- Event mapping + - CamelCase event name mapping is performed uniformly in the Svelte layer, reducing runtime conversion costs. +- Template optimization + - The runtime template provides stable slot conversion and context merging logic, reducing branching logic and object copying. + +Section Sources + +- [frontend/antd/breadcrumb/breadcrumb.tsx:44-51](file://frontend/antd/breadcrumb/breadcrumb.tsx#L44-L51) +- [frontend/antd/breadcrumb/Index.svelte:27-58](file://frontend/antd/breadcrumb/Index.svelte#L27-L58) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:190-206](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L190-L206) + +## Troubleshooting Guide + +- Slots not taking effect + - Confirm slot names are correct (e.g., `separator`, `itemRender`), and that they are declared as supported in the React wrapper layer. + - Check whether slot elements exist in children and have not been hidden or removed. +- Events not triggering + - Confirm event names are registered in the backend component (e.g., `click`, `menu_*`, `dropdownProps_*`). + - Check whether the Svelte layer correctly maps to camelCase names required by AntD. +- Routing integration issues + - If using dropdown menus or overflow indicators, confirm that menu item `href`/`path` matches the route. + - For permission control, it is recommended to dynamically decide whether to render an item or disable clicks in `itemRender` based on user permissions. +- Style anomalies + - Use `elem_classes`/`elem_style` or `classNames`/`styles` to apply styles; ensure compatibility with AntD themes. + - To override default styles, use CSS Modules or theme variables for customization. + +Section Sources + +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:15-46](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L15-L46) +- [frontend/antd/breadcrumb/Index.svelte:51-57](file://frontend/antd/breadcrumb/Index.svelte#L51-L57) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:370-391](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L370-L391) + +## Conclusion + +The Breadcrumb component achieves flexible path display and user guidance through a collaborative frontend-backend design. Its core strengths are: + +- Slot-based extensibility: Supports custom separators, item renderers, and dropdown icons. +- Event-driven: Built-in rich event listeners, making it easy to integrate with routing systems. +- Theme adaptability: Easily adapts to different themes via style properties and runtime context. +- Performance-friendly: Reduces rendering costs via caching and cloning strategies. + +## Appendix: Usage Examples and Best Practices + +- Basic usage + - Refer to documentation examples to quickly build breadcrumb paths. +- Dynamic path generation + - Use the `items` parameter or slot `items` to dynamically build a path array, generating titles and links combined with route parameters. +- Permission control + - In `itemRender`, decide whether to render an item or disable clicks based on user roles. +- Multi-language support + - Pass title and separator text via slots, or switch language-specific content in `itemRender`. +- Style customization + - Use `elem_classes`/`elem_style` or `classNames`/`styles` for custom styles; override default styles via theme variables as needed. +- Performance optimization + - Use `forceClone` and `useMemo` judiciously to avoid unnecessary cloning and re-renders. + - Enable dropdown menus and overflow indicators for long lists to reduce the number of rendered nodes. + +Section Sources + +- [docs/components/antd/breadcrumb/README.md:1-8](file://docs/components/antd/breadcrumb/README.md#L1-L8) +- [docs/components/antd/breadcrumb/README-zh_CN.md:1-8](file://docs/components/antd/breadcrumb/README-zh_CN.md#L1-L8) +- [frontend/antd/breadcrumb/breadcrumb.tsx:44-51](file://frontend/antd/breadcrumb/breadcrumb.tsx#L44-L51) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:727-761](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L727-L761) diff --git a/.wiki/en/Ant Design Components/Navigation Components/Dropdown.md b/.wiki/en/Ant Design Components/Navigation Components/Dropdown.md new file mode 100644 index 00000000..fc819847 --- /dev/null +++ b/.wiki/en/Ant Design Components/Navigation Components/Dropdown.md @@ -0,0 +1,325 @@ +# Dropdown + + +**Files Referenced in This Document** +- [frontend/antd/dropdown/dropdown.tsx](file://frontend/antd/dropdown/dropdown.tsx) +- [frontend/antd/dropdown/button/Index.svelte](file://frontend/antd/dropdown/button/Index.svelte) +- [backend/modelscope_studio/components/antd/dropdown/__init__.py](file://backend/modelscope_studio/components/antd/dropdown/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [docs/components/antd/dropdown/README.md](file://docs/components/antd/dropdown/README.md) +- [docs/components/antd/dropdown/demos/basic.py](file://docs/components/antd/dropdown/demos/basic.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document systematically introduces the implementation and usage of the Dropdown component in the ModelScope Studio frontend, covering the following topics: + +- Trigger mechanisms and popup containers +- Menu item configuration and rendering +- Popup positioning and placement strategies +- Interaction behaviors and event handling +- Keyboard navigation and accessibility support +- Integration with forms, icon buttons, and text links +- Advanced usage: multi-level menus, dynamic menus, remote loading +- Performance optimization recommendations and common issues + +## Project Structure + +The Dropdown component consists of backend Python components and a frontend Svelte/React wrapper layer, bridged through the Gradio ecosystem. + +```mermaid +graph TB +subgraph "Backend" +PY_API["AntdDropdown
Python Component"] +BTN_PY["AntdDropdown.Button
Python Component"] +end +subgraph "Frontend" +WRAP["Dropdown Wrapper
dropdown.tsx"] +BTN_SVLT["Dropdown.Button Frontend Wrapper
button/Index.svelte"] +ANTD["Antd Dropdown Component"] +MENU_CTX["Menu Context Provider"] +end +PY_API --> WRAP +BTN_PY --> BTN_SVLT +WRAP --> ANTD +WRAP --> MENU_CTX +BTN_SVLT --> ANTD +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:11-38](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L11-L38) +- [frontend/antd/dropdown/dropdown.tsx:15-108](file://frontend/antd/dropdown/dropdown.tsx#L15-L108) +- [frontend/antd/dropdown/button/Index.svelte:10-70](file://frontend/antd/dropdown/button/Index.svelte#L10-L70) + +Section Sources + +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:11-38](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L11-L38) +- [frontend/antd/dropdown/dropdown.tsx:15-108](file://frontend/antd/dropdown/dropdown.tsx#L15-L108) +- [frontend/antd/dropdown/button/Index.svelte:10-70](file://frontend/antd/dropdown/button/Index.svelte#L10-L70) + +## Core Components + +- Backend Python components: `AntdDropdown` and `AntdDropdown.Button` +- Frontend wrapper layer: Dropdown (React wrapper + Antd Dropdown), Dropdown.Button (Svelte wrapper) +- Menu context: Injects "menu items" into the dropdown via the Menu Context Provider + +Key features + +- Supports injecting menu items, expand icons, overflow indicators, and custom popup rendering via slots +- Supports `getPopupContainer` for custom popup containers +- Supports `open_change`, `menu_*` series of event bindings +- Provides inline style pass-through (`innerStyle`) and container style (`overlayStyle`) + +Section Sources + +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:34-38](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L34-L38) +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:40-100](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L40-L100) +- [frontend/antd/dropdown/dropdown.tsx:15-25](file://frontend/antd/dropdown/dropdown.tsx#L15-L25) +- [frontend/antd/dropdown/dropdown.tsx:44-92](file://frontend/antd/dropdown/dropdown.tsx#L44-L92) + +## Architecture Overview + +The Dropdown call chain is as follows: + +```mermaid +sequenceDiagram +participant User as "User" +participant Py as "AntdDropdown (Python)" +participant Wrap as "Dropdown Wrapper (React)" +participant MenuCtx as "Menu Context Provider" +participant Antd as "Antd Dropdown" +participant Popup as "Popup Layer" +User->>Py : Render dropdown +Py->>Wrap : Pass properties and slots +Wrap->>MenuCtx : Read menu items +Wrap->>Antd : Render Antd Dropdown +Antd->>Popup : Display based on trigger condition +User->>Popup : Click/hover/keyboard interaction +Popup-->>Antd : Trigger callback +Antd-->>Wrap : Pass event back +Wrap-->>Py : Trigger open_change / menu_* events +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:16-32](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L16-L32) +- [frontend/antd/dropdown/dropdown.tsx:26-107](file://frontend/antd/dropdown/dropdown.tsx#L26-L107) + +## Detailed Component Analysis + +### Component 1: Dropdown + +- Role: Combines Ant Design's Dropdown with the internal menu context, supporting slot-based menu item injection and custom rendering +- Key points + - Menu item source: Uses `props.menu.items` first; otherwise renders "menu.items" from menu context + - Expand icon and overflow indicator: Can inject ReactSlot via slots or fall back to native properties + - Popup container: Supports `getPopupContainer` for custom containers + - Custom rendering: `dropdownRender` and `popupRender` can be injected via slots or passed as functions + - Inline styles: `innerStyle` is passed through to the content container + +```mermaid +flowchart TD +Start(["Enter Dropdown Wrapper"]) --> ReadCtx["Read items from menu context"] +ReadCtx --> MergeItems{"Are props.menu.items provided?"} +MergeItems --> |Yes| UseProps["Use props.menu.items"] +MergeItems --> |No| RenderItems["Render menu context items"] +UseProps --> Slots["Handle slots: expandIcon / overflowedIndicator / dropdownRender / popupRender"] +RenderItems --> Slots +Slots --> Container["getPopupContainer positioning"] +Container --> Mount["Mount to Antd Dropdown and render"] +Mount --> End(["Complete"]) +``` + +Diagram Sources + +- [frontend/antd/dropdown/dropdown.tsx:26-107](file://frontend/antd/dropdown/dropdown.tsx#L26-L107) + +Section Sources + +- [frontend/antd/dropdown/dropdown.tsx:15-108](file://frontend/antd/dropdown/dropdown.tsx#L15-L108) + +### Component 2: Dropdown.Button + +- Role: Wraps Antd Dropdown.Button in a Svelte manner, supporting slots and event mapping +- Key points + - Dynamically imports the React version of Dropdown.Button via `importComponent` + - Property mapping: `open_change` → `openChange`, `menu_open_change` → `menu_OpenChange` + - Visibility control: Controls rendering via `visible` + - Styles and IDs: Supports `elem_style`, `elem_id`, `elem_classes` pass-through + +```mermaid +sequenceDiagram +participant User as "User" +participant BtnPy as "AntdDropdown.Button (Python)" +participant BtnSvlt as "Dropdown.Button (Svelte)" +participant BtnReact as "Dropdown.Button (React)" +participant Antd as "Antd Dropdown.Button" +User->>BtnPy : Render Dropdown.Button +BtnPy->>BtnSvlt : Pass properties and slots +BtnSvlt->>BtnReact : Dynamic import and render +BtnReact->>Antd : Render Antd Dropdown.Button +User->>Antd : Click/interact +Antd-->>BtnReact : Callback event +BtnReact-->>BtnSvlt : Event pass-through +BtnSvlt-->>BtnPy : Event pass-through +``` + +Diagram Sources + +- [frontend/antd/dropdown/button/Index.svelte:10-70](file://frontend/antd/dropdown/button/Index.svelte#L10-L70) +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:8-8](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L8-L8) + +Section Sources + +- [frontend/antd/dropdown/button/Index.svelte:10-70](file://frontend/antd/dropdown/button/Index.svelte#L10-L70) +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:15-15](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L15-L15) + +### Event Handling and Keyboard Navigation + +- Event bindings + - `open_change`: Dropdown panel visibility state change + - `menu_click` / `menu_select` / `menu_deselect` / `menu_open_change`: Menu item click, selection, deselection, menu panel visibility change +- Keyboard navigation + - Uses Antd Dropdown's default keyboard behavior (up/down to move, Enter/Space to select, Esc to close) +- Accessibility support + - Preserves native semantic tags and accessibility attributes (provided by Antd Dropdown) + - Recommendation: Set `aria-controls`, `aria-expanded`, and other attributes on trigger elements to enhance accessibility + +Section Sources + +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:16-32](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L16-L32) + +### Popup Positioning and Container + +- Positioning strategy + - `placement`: Supports `topLeft`/`top`/`topRight`/`bottomLeft`/`bottom`/`bottomRight` + - `auto_adjust_overflow`: Automatically adjusts overflow +- Container selection + - `get_popup_container`: Custom popup container, commonly used for fixing to specific areas or inside scroll containers + +Section Sources + +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:56-59](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L56-L59) +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:52-52](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L52-L52) + +### Integration with Forms, Icon Buttons, and Text Links + +- Form components + - When embedding input-type components in menu items, be aware of form linkage and validation timing +- Icon buttons + - Combine `antd.Icon` with `antd.Button` (type="text" or "primary"/"default") +- Text links + - Use `antd.Button` (type="link") as menu item labels, supporting `href` and new window opening + +Section Sources + +- [docs/components/antd/dropdown/demos/basic.py:6-31](file://docs/components/antd/dropdown/demos/basic.py#L6-L31) +- [docs/components/antd/dropdown/demos/basic.py:37-47](file://docs/components/antd/dropdown/demos/basic.py#L37-L47) + +### Advanced Usage + +- Multi-level menus + - Nest sub-menu items within menu items to achieve two-level or multi-level dropdown menus +- Dynamic menus + - Inject "menu.items" via slots and update dynamically based on state at runtime +- Remote loading + - Add loading and error states in `dropdownRender`/`popupRender`, update menu items after async requests + +Section Sources + +- [frontend/antd/dropdown/dropdown.tsx:20-24](file://frontend/antd/dropdown/dropdown.tsx#L20-L24) +- [frontend/antd/dropdown/dropdown.tsx:71-92](file://frontend/antd/dropdown/dropdown.tsx#L71-L92) + +## Dependency Analysis + +- Python layer + - `AntdDropdown` exports the Button sub-component and declares supported slots and events + - Component is registered in `components.py` for unified export +- Frontend layer + - Dropdown wrapper depends on Antd Dropdown, Menu Context Provider, and slot rendering utilities + - Dropdown.Button wraps the React component via Svelte + +```mermaid +graph LR +PY["AntdDropdown (Python)"] --> WRAP["Dropdown (React)"] +WRAP --> ANTD["Antd Dropdown"] +WRAP --> CTX["Menu Context Provider"] +BTN_PY["AntdDropdown.Button (Python)"] --> BTN_SVLT["Dropdown.Button (Svelte)"] +BTN_SVLT --> BTN_REACT["Dropdown.Button (React)"] +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:39-40](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L39-L40) +- [backend/modelscope_studio/components/antd/components.py:39-40](file://backend/modelscope_studio/components/antd/components.py#L39-L40) +- [frontend/antd/dropdown/dropdown.tsx:10-13](file://frontend/antd/dropdown/dropdown.tsx#L10-L13) +- [frontend/antd/dropdown/button/Index.svelte:10-12](file://frontend/antd/dropdown/button/Index.svelte#L10-L12) + +Section Sources + +- [backend/modelscope_studio/components/antd/components.py:39-40](file://backend/modelscope_studio/components/antd/components.py#L39-L40) +- [frontend/antd/dropdown/dropdown.tsx:10-13](file://frontend/antd/dropdown/dropdown.tsx#L10-L13) + +## Performance Considerations + +- Menu item rendering + - Use `useMemo` to cache the menu item list, avoiding unnecessary re-renders +- Slot rendering + - Render slots only when needed, reducing unused nodes +- Popup container + - Set `getPopupContainer` reasonably to avoid frequent popup layer reflows +- Event binding + - Bind `open_change` and `menu_*` events only when necessary, avoiding excessive listeners + +Section Sources + +- [frontend/antd/dropdown/dropdown.tsx:49-57](file://frontend/antd/dropdown/dropdown.tsx#L49-L57) +- [frontend/antd/dropdown/dropdown.tsx:37-39](file://frontend/antd/dropdown/dropdown.tsx#L37-L39) + +## Troubleshooting Guide + +- Unable to display menu items + - Check whether "menu.items" is injected via slots, or whether `props.menu.items` is correctly passed +- Popup layer position abnormal + - Check whether `getPopupContainer` returns the correct container element + - Adjust `placement` and `auto_adjust_overflow` +- Events not triggering + - Confirm the corresponding events (`open_change`, `menu_*`) are enabled and correctly bound in the Python layer +- Styles not taking effect + - `innerStyle` only applies to the content container; `overlayStyle` should be passed via backend properties + +Section Sources + +- [frontend/antd/dropdown/dropdown.tsx:44-92](file://frontend/antd/dropdown/dropdown.tsx#L44-L92) +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:52-59](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L52-L59) +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:16-32](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L16-L32) + +## Conclusion + +The Dropdown component implements flexible menu item injection, popup layer customization, and event binding through a "Python component + frontend wrapper + menu context" design. Combined with Antd Dropdown's mature capabilities, it can handle scenarios ranging from basic dropdowns to complex multi-level menus, dynamic and remote loading. In real projects, it is recommended to focus on performance and accessibility, using slots and events reasonably to ensure a good user experience. + +## Appendix + +- Example references + - Basic examples: Contains normal dropdown and dropdown button, as well as embedded buttons and links in menu items +- Documentation entry + - Component documentation home and example entry + +Section Sources + +- [docs/components/antd/dropdown/README.md:1-8](file://docs/components/antd/dropdown/README.md#L1-L8) +- [docs/components/antd/dropdown/demos/basic.py:33-47](file://docs/components/antd/dropdown/demos/basic.py#L33-L47) diff --git a/.wiki/en/Ant Design Components/Navigation Components/Menu.md b/.wiki/en/Ant Design Components/Navigation Components/Menu.md new file mode 100644 index 00000000..ab49acb3 --- /dev/null +++ b/.wiki/en/Ant Design Components/Navigation Components/Menu.md @@ -0,0 +1,344 @@ +# Menu + + +**Files Referenced in This Document** +- [menu.tsx](file://frontend/antd/menu/menu.tsx) +- [menu.item.tsx](file://frontend/antd/menu/item/menu.item.tsx) +- [Index.svelte](file://frontend/antd/menu/item/Index.svelte) +- [context.ts](file://frontend/antd/menu/context.ts) +- [menu.less](file://frontend/antd/menu/menu.less) +- [createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [README.md](file://docs/components/antd/menu/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document systematically introduces the design and implementation of the navigation Menu component, covering layout modes, menu item configuration, state management, interaction behaviors, icons and disabled states, sub-menu nesting, horizontal/vertical layout switching, collapse/expand mechanisms, responsive adaptation, integration with routing systems (dynamic menus, permission control, breadcrumb linkage), accordion and multi-select modes, searchable menus, and other advanced capabilities, along with usage examples, style customization, and performance optimization recommendations. + +## Project Structure + +The Menu component consists of three parts: "container component + menu item component + context and rendering utilities". It uses Ant Design's Menu component as the underlying implementation, bridged to React via Svelte preprocessing, combined with an in-house "item context" system for flexible menu item collection and rendering. + +```mermaid +graph TB +subgraph "frontend/antd/menu" +M["menu.tsx
Menu Container"] +MI["menu.item.tsx
Menu Item Wrapper"] +IDX["Index.svelte
Menu Item Entry"] +CTX["context.ts
Item Context Export"] +LESS["menu.less
Styles and Transitions"] +end +subgraph "Utility Layer" +CIC["createItemsContext.tsx
Item Context Factory"] +RIT["renderItems.tsx
Item Renderer"] +end +subgraph "External Dependencies" +AD["Ant Design Menu
Underlying UI"] +end +IDX --> MI +MI --> CTX +CTX --> CIC +M --> RIT +M --> AD +M --> LESS +``` + +Diagram Sources + +- [menu.tsx:14-93](file://frontend/antd/menu/menu.tsx#L14-L93) +- [menu.item.tsx:9-33](file://frontend/antd/menu/item/menu.item.tsx#L9-L33) +- [Index.svelte:13-83](file://frontend/antd/menu/item/Index.svelte#L13-L83) +- [context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [createItemsContext.tsx:97-273](file://frontend/utils/createItemsContext.tsx#L97-L273) +- [renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +Section Sources + +- [menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [menu.item.tsx:1-36](file://frontend/antd/menu/item/menu.item.tsx#L1-L36) +- [Index.svelte:1-84](file://frontend/antd/menu/item/Index.svelte#L1-L84) +- [context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [menu.less:1-45](file://frontend/antd/menu/menu.less#L1-L45) +- [createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + +## Core Components + +- Menu Container (Menu) + - Purpose: Wraps Ant Design Menu, unifying event pass-through, slot rendering, custom rendering of icons and overflow indicators, and item context injection. + - Key points: Supports slot extensions (e.g., `expandIcon`, `overflowedIndicator`, `popupRender`); supports `items` or slots as data sources; internally uses `renderItems` to convert the "item context" into the `ItemType` array required by Antd. +- Menu Item (MenuItem) + - Purpose: Wraps menu items from the "item context" as Antd MenuItem/SubMenu, auto-detects type (regular item/sub-menu), and injects style class names. +- Item Context (createItemsContext) + - Purpose: Provides "item collection + child item collection" context, supporting multiple slots, index positioning, property and child item transformation, change callbacks, etc. +- Renderer (renderItems) + - Purpose: Renders the "item context" tree structure into the props structure required by Antd, supporting slot injection, cloning, parameterized slots, etc. + +Section Sources + +- [menu.tsx:14-93](file://frontend/antd/menu/menu.tsx#L14-L93) +- [menu.item.tsx:9-33](file://frontend/antd/menu/item/menu.item.tsx#L9-L33) +- [createItemsContext.tsx:97-273](file://frontend/utils/createItemsContext.tsx#L97-L273) +- [renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +## Architecture Overview + +The Menu component uses a layered design of "container + item wrapper + context", bridged to React via Svelte preprocessing, then React calls Antd Menu. The item context is responsible for collecting menu items and their slots at runtime, and the renderer ultimately outputs a data structure recognizable by Antd. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Menu as "Menu Container" +participant Ctx as "Item Context" +participant Render as "renderItems" +participant Antd as "Antd Menu" +Dev->>Menu : Pass items or slots +Menu->>Ctx : withItemsContextProvider injection +Ctx-->>Menu : useItems provides items +Menu->>Render : renderItems(resolvedSlotItems, { clone }) +Render-->>Menu : Return Antd Item list +Menu->>Antd : Render and bind events +Antd-->>Dev : Trigger openChange/onSelect/onDeselect +``` + +Diagram Sources + +- [menu.tsx:18-54](file://frontend/antd/menu/menu.tsx#L18-L54) +- [createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) +- [renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +## Detailed Component Analysis + +### Menu Container (Menu) + +- Data source selection + - Supports directly passing `items` (Antd Item type array) or collecting via slots (default/items slots). + - If slots exist, items from slots are preferred; otherwise falls back to the default slot. +- Slot extensions + - `expandIcon`: Custom expand icon, supports parameterized rendering. + - `overflowedIndicator`: Overflow indicator (e.g., "More" button). + - `popupRender`: Custom rendering for dropdown popup layers. +- Event pass-through + - `onOpenChange`, `onSelect`, `onDeselect` are passed through as-is to Antd Menu. +- Performance optimization + - Uses `useMemo` to cache items computation results, avoiding duplicate rendering. + - Only recomputes when `items` or `resolvedSlotItems` changes. + +Section Sources + +- [menu.tsx:14-93](file://frontend/antd/menu/menu.tsx#L14-L93) + +### Menu Item (MenuItem) + +- Type detection + - When default slot children exist, auto-detects as sub-menu (SubMenu); otherwise as a regular menu item (MenuItem). +- Style class names + - Automatically injects `ms-gr-antd-menu-item` or `ms-gr-antd-menu-item-{type}` for theme and style customization. +- Slot handling + - Injects the `icon` slot into Antd's `icon` field via cloning, ensuring consistent spacing between icon and text. + +Section Sources + +- [menu.item.tsx:9-33](file://frontend/antd/menu/item/menu.item.tsx#L9-L33) + +### Item Context (createItemsContext) + +- Multi-slot support + - Allows defining multiple slots (e.g., `default`, `items`) and writing by index via `setItem`. +- Child item collection + - `ItemHandler` internally wraps `ItemsContextProvider` again, forming a "parent collection + child collection" tree structure. +- Property and child item transformation + - `itemProps` and `itemChildren` support transforming props and children of the current item for dynamic generation. +- Change notification + - The `onChange` callback returns the complete items under the current slot, making it easy for upper layers to listen for changes. + +Section Sources + +- [createItemsContext.tsx:97-273](file://frontend/utils/createItemsContext.tsx#L97-L273) + +### Renderer (renderItems) + +- Slot injection + - Injects slot elements recorded in the item context into corresponding fields (supports nested paths), with support for `withParams` parameterized slots. +- Cloning and force cloning + - `clone` controls whether to clone nodes; `forceClone` is enabled by default with `withParams` to ensure correct parameter passing. +- Child item recursion + - Recursively renders the `children` field to form a complete menu tree. +- Key generation + - Generates stable keys for each item to avoid React diff anomalies. + +Section Sources + +- [renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +### Styles and Responsive (menu.less) + +- Icon and text spacing + - When an icon is present, automatically sets `margin-inline-start` for adjacent text and adds transition animations. +- Collapsed mode + - In the `inline-collapsed` state, text is hidden and only icons are shown to improve space utilization. +- Animations and transitions + - Controls transition duration and easing via CSS variables, ensuring visual consistency. + +Section Sources + +- [menu.less:1-45](file://frontend/antd/menu/menu.less#L1-L45) + +### Svelte Entry (Index.svelte) + +- Property and slot handling + - Retrieves component properties and additional properties via `getProps`/`processProps`, supports `visible` for visibility control. + - Injects the `icon` slot into Antd's `icon` field via cloning. +- Theme and styles + - Supports `elem_id`, `elem_classes`, `elem_style` injection for theme and style customization. +- Conditional rendering + - Renders `children` only when `visible` is true. + +Section Sources + +- [Index.svelte:1-84](file://frontend/antd/menu/item/Index.svelte#L1-L84) + +## Dependency Analysis + +- Component coupling + - Menu depends on `createItemsContext` and `renderItems`; MenuItem depends on `ItemHandler` and context; Svelte entry handles property and slot preprocessing. +- External dependencies + - Ant Design Menu as the underlying UI; `ReactSlot` for slot rendering; `classnames` for class name concatenation. +- Circular dependencies + - Avoided through "exported factory + context injection"; Menu and MenuItem are decoupled via context. + +```mermaid +graph LR +Menu["menu.tsx"] --> Ctx["context.ts"] +Ctx --> CIC["createItemsContext.tsx"] +Menu --> RIT["renderItems.tsx"] +Menu --> AD["Antd Menu"] +MenuItem["menu.item.tsx"] --> Ctx +IDX["Index.svelte"] --> MenuItem +Menu --> LESS["menu.less"] +``` + +Diagram Sources + +- [menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [menu.item.tsx:1-36](file://frontend/antd/menu/item/menu.item.tsx#L1-L36) +- [Index.svelte:1-84](file://frontend/antd/menu/item/Index.svelte#L1-L84) +- [menu.less:1-45](file://frontend/antd/menu/menu.less#L1-L45) + +Section Sources + +- [menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [menu.item.tsx:1-36](file://frontend/antd/menu/item/menu.item.tsx#L1-L36) +- [Index.svelte:1-84](file://frontend/antd/menu/item/Index.svelte#L1-L84) +- [context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [menu.less:1-45](file://frontend/antd/menu/menu.less#L1-L45) + +## Performance Considerations + +- Render caching + - Menu uses `useMemo` for items computation, avoiding unnecessary re-renders. +- Event function memoization + - `createItemsContext` internally uses `useMemoizedFn`, reducing side effects caused by callback function rebuilds. +- Slot cloning strategy + - Default slot element cloning avoids state confusion caused by DOM reuse; forced cloning in `withParams` scenarios. +- Recursive rendering optimization + - `renderItems` only filters and maps valid items, avoiding empty items participating in rendering. + +Section Sources + +- [menu.tsx:46-54](file://frontend/antd/menu/menu.tsx#L46-L54) +- [createItemsContext.tsx:203-254](file://frontend/utils/createItemsContext.tsx#L203-L254) +- [renderItems.tsx:19-22](file://frontend/utils/renderItems.tsx#L19-L22) + +## Troubleshooting Guide + +- Slots not taking effect + - Check whether slot names are declared in `allowedSlots`; confirm slot elements are correctly injected into `ItemHandler`'s slots. +- Icons not showing or text not appearing + - Confirm the icon slot has been injected into the `icon` field via the Svelte entry; check behavior when the menu is in collapsed mode. +- Events not triggering + - Confirm Menu correctly passes through `onOpenChange`/`onSelect`/`onDeselect`; check Antd version compatibility. +- Sub-menus not expanding + - Check whether sub-item `children` are correctly recursed via `renderItems`; confirm the `itemChildren` callback returns the correct child item list. +- Style anomalies + - Check whether `menu.less` is imported; confirm theme variables (e.g., `--ms-gr-ant-menu-icon-margin-inline-end`) are set correctly. + +Section Sources + +- [menu.tsx:35-88](file://frontend/antd/menu/menu.tsx#L35-L88) +- [menu.item.tsx:16-30](file://frontend/antd/menu/item/menu.item.tsx#L16-L30) +- [Index.svelte:69-78](file://frontend/antd/menu/item/Index.svelte#L69-L78) +- [menu.less:1-45](file://frontend/antd/menu/menu.less#L1-L45) + +## Conclusion + +This Menu component enhances and extends Ant Design Menu through a "container + item wrapper + context" architecture, featuring a flexible slot system, powerful sub-menu and icon support, and good performance and maintainability. Combined with routing systems and permission control, complex navigation scenarios can be quickly built. + +## Appendix + +### Usage Examples (Path Guide) + +- Basic examples + - Refer to documentation example tabs: `
Anchor Links"] +B["Breadcrumb
Breadcrumb Trail"] +C["Dropdown
Dropdown Menu"] +D["Menu
Navigation Menu"] +E["Pagination
Pagination"] +F["Steps
Steps Bar"] +end +subgraph "Utility Tools" +U1["createItemsContext.tsx
Context Factory"] +U2["renderItems.tsx
Slot Item Renderer"] +U3["renderParamsSlot.tsx
Parameterized Slot"] +U4["useFunction.ts
Function Wrapper"] +U5["omitUndefinedProps.ts
Property Filter"] +end +subgraph "Layout" +L1["layout.base.tsx
Base Layout Container"] +L2["layout/Index.svelte
Layout Entry"] +L3["layout/package.json
Export Configuration"] +end +A --> U1 +B --> U1 +D --> U1 +F --> U1 +C --> D +A --> U2 +B --> U2 +D --> U2 +F --> U2 +A --> U3 +B --> U3 +D --> U3 +F --> U3 +C --> U4 +D --> U5 +L1 --> L2 +L3 --> L2 +``` + +Diagram Sources + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/package.json:1-15](file://frontend/antd/layout/package.json#L1-L15) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/utils/omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +Section Sources + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/package.json:1-15](file://frontend/antd/layout/package.json#L1-L15) + +## Core Components + +This section provides an overall capability and behavioral description of each navigation component for quick orientation. + +- Anchor + - Responsible for in-page positioning and highlighting, supporting container selectors and current anchor callbacks + - Injects items via context, supporting slot-based child item rendering +- Breadcrumb + - Displays the current page path, supporting custom separators, item renderers, and dropdown icons + - Supports replacing default rendering logic via slots +- Dropdown + - Based on Ant Design Dropdown, supports nested menu items, popup layer rendering, and overflow indicators + - Shares items rendering strategy with the menu context +- Menu + - Supports expand icons, overflow indicators, and popup rendering + - Provides open/select/deselect event pass-through +- Pagination + - Supports total count rendering, quick jumper, and custom page number rendering + - Event callbacks are uniformly handled by function wrappers +- Steps + - Supports custom progress dot rendering + - Injects items via context, supporting slot-based child items + +Section Sources + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) + +## Architecture Overview + +Navigation components universally adopt a unified architecture of "Svelte wrapper + React component + slot rendering + context injection". Key characteristics are: + +- Use `sveltify` to bridge React components as Svelte components +- Inject items context via `withItemsContextProvider` to uniformly handle combinations of children and slots +- Use `renderItems` and `renderParamsSlot` to render slot items and parameterized slots +- Use `useFunction` to wrap callbacks, ensuring stable execution in the Svelte environment +- Use `omitUndefinedProps` to filter undefined properties, avoiding passing invalid values to underlying components + +```mermaid +sequenceDiagram +participant S as "Svelte Component" +participant P as "withItemsContextProvider" +participant R as "renderItems/renderParamsSlot" +participant A as "Antd Component" +participant U as "useFunction/omitUndefinedProps" +S->>P : Pass props and slots +P->>R : Resolve items and slots +R-->>P : Return normalized items/rendered nodes +P->>U : Wrap callbacks / filter properties +U-->>P : Return safe props +P->>A : Render Antd component +A-->>S : Trigger event callbacks +``` + +Diagram Sources + +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/utils/omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +## Detailed Component Analysis + +### Anchor Analysis + +- Data flow and state + - Injects items via context, supporting combinations of children and slots + - Uses `useMemo` to cache items computation results, avoiding redundant renders +- Events and callbacks + - `getContainer` and `getCurrentAnchor` are wrapped with `useFunction` for stable invocation in Svelte +- Slots and rendering + - Uses explicit items first; otherwise resolves from `default` or `items` slot in context +- Performance and usability + - Recomputes items only when necessary, reducing rendering overhead + - Hides the children container to avoid duplicate rendering + +```mermaid +flowchart TD +Start(["Enter Anchor Render"]) --> Resolve["Resolve context items"] +Resolve --> HasExplicit{"Are explicit items provided?"} +HasExplicit --> |Yes| UseExplicit["Use explicit items"] +HasExplicit --> |No| UseSlot["Use items/default slot"] +UseSlot --> Memo["useMemo caches items"] +UseExplicit --> Memo +Memo --> Render["Render Antd Anchor"] +Render --> End(["Complete"]) +``` + +Diagram Sources + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) + +Section Sources + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) + +### Breadcrumb Analysis + +- Data flow and state + - Merges items and slots, supporting custom separators and item renderers + - `dropdownIcon` and `separator` can be replaced via slots +- Slots and rendering + - `itemRender`, `dropdown_icon`, and `separator` are rendered via `renderParamsSlot` and ReactSlot +- Callbacks and events + - Maintains interface compatibility with Antd Breadcrumb, with no additional wrapping + +```mermaid +sequenceDiagram +participant S as "Svelte Breadcrumb" +participant Ctx as "Context Resolution" +participant Slot as "Slot Rendering" +participant A as "Antd Breadcrumb" +S->>Ctx : Get items/default +Ctx-->>S : Return items +S->>Slot : Render separator/itemRender/dropdownIcon +Slot-->>S : Return nodes +S->>A : Pass items and rendered slots +A-->>S : Trigger click/navigation +``` + +Diagram Sources + +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) + +Section Sources + +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) + +### Dropdown Analysis + +- Data flow and state + - Internal menu items are injected via menu context, supporting `expandIcon` and overflow indicator slots + - `dropdownRender` and `popupRender` support parameterized slots +- Events and callbacks + - `getPopupContainer` is wrapped with `useFunction` +- Relationship with Menu + - Shares menu context and reuses the items rendering strategy + +```mermaid +classDiagram +class Dropdown { ++props ++slots ++menu.items ++dropdownRender() ++popupRender() ++getPopupContainer() +} +class MenuContext { ++items ++expandIcon ++overflowedIndicator +} +Dropdown --> MenuContext : "Shared context" +``` + +Diagram Sources + +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) + +Section Sources + +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) + +### Menu Analysis + +- Data flow and state + - Injects items via context, supporting `expandIcon`, overflow indicator, and popup render slot + - open/select/deselect events are passed through +- Property handling + - Uses `omitUndefinedProps` to filter undefined properties, avoiding passing invalid values to underlying components +- Slots and rendering + - `expandIcon`, `overflowedIndicator`, `popup_render` are rendered via `renderParamsSlot` and ReactSlot + +```mermaid +flowchart TD +Enter(["Enter Menu Render"]) --> Ctx["Resolve context items/default"] +Ctx --> Items["renderItems normalization"] +Items --> Props["omitUndefinedProps filter properties"] +Props --> Slots["Slots: expandIcon/overflowedIndicator/popup_render"] +Slots --> Antd["Render Antd Menu"] +Antd --> Events["Pass through open/select/deselect"] +Events --> Exit(["Complete"]) +``` + +Diagram Sources + +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [frontend/utils/omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +Section Sources + +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) + +### Pagination Analysis + +- Data flow and state + - Supports slot-based configuration for `showTotal`, `itemRender`, and `showQuickJumper.goButton` + - `onChange` callback is wrapped with `useFunction` +- Slots and rendering + - `itemRender` and `goButton` are rendered via `renderParamsSlot` and ReactSlot + +```mermaid +sequenceDiagram +participant S as "Svelte Pagination" +participant Slot as "Slot Rendering" +participant A as "Antd Pagination" +S->>Slot : Render itemRender/goButton +Slot-->>S : Return nodes +S->>A : Pass configuration and wrapped callbacks +A-->>S : onChange(page, pageSize) +``` + +Diagram Sources + +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) + +Section Sources + +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) + +### Steps Analysis + +- Data flow and state + - Injects items via context, supporting `progressDot` slotting + - Wraps `progressDot` callback via `useFunction` +- Slots and rendering + - `progressDot` is rendered via `renderParamsSlot` + +```mermaid +flowchart TD +Start(["Enter Steps Render"]) --> Ctx["Resolve items/default"] +Ctx --> Normalize["renderItems normalization"] +Normalize --> Slot["Render progressDot"] +Slot --> Antd["Render Antd Steps"] +Antd --> End(["Complete"]) +``` + +Diagram Sources + +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/steps/context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) + +Section Sources + +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/steps/context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) + +### Layout and Navigation Patterns + +- Base layout container + - The Base component dynamically selects Layout, Header, Footer, or Content based on the `component` parameter + - Class names differentiate style scopes +- Layout entry and exports + - `Index.svelte` serves as the entry point; `layout/package.json` provides Gradio export configuration + +```mermaid +graph LR +Base["layout.base.tsx
Base Component"] --> |component| L["Layout"] +Base --> H["Header"] +Base --> F["Footer"] +Base --> C["Content"] +Index["layout/Index.svelte"] --> Base +Package["layout/package.json"] --> Index +``` + +Diagram Sources + +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/package.json:1-15](file://frontend/antd/layout/package.json#L1-L15) + +Section Sources + +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/package.json:1-15](file://frontend/antd/layout/package.json#L1-L15) + +## Dependency Analysis + +- Inter-component coupling + - Dropdown and Menu share menu context, forming a weakly-coupled reuse relationship + - Anchor, Breadcrumb, Steps, and Menu all depend on the `createItemsContext` factory and `renderItems` +- External dependencies + - Ant Design React component library + - Svelte Preprocess React (`sveltify`, `ReactSlot`) + - Utility functions (`useFunction`, `renderItems`, `renderParamsSlot`, `omitUndefinedProps`) + +```mermaid +graph TB +subgraph "Components" +M["Menu"] +D["Dropdown"] +A["Anchor"] +B["Breadcrumb"] +S["Steps"] +P["Pagination"] +end +subgraph "Utilities" +Ctx["createItemsContext"] +RI["renderItems"] +RS["renderParamsSlot"] +UF["useFunction"] +OU["omitUndefinedProps"] +end +M --> Ctx +D --> Ctx +A --> Ctx +B --> Ctx +S --> Ctx +M --> RI +D --> RI +A --> RI +B --> RI +S --> RI +M --> RS +D --> RS +A --> RS +B --> RS +S --> RS +M --> OU +D --> UF +A --> UF +B --> UF +S --> UF +P --> UF +``` + +Diagram Sources + +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/utils/omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +Section Sources + +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) + +## Performance Considerations + +- Rendering optimization + - Many components use `useMemo` to cache items computation results, avoiding unnecessary re-renders + - Using `renderItems` and `renderParamsSlot` for unified slot rendering reduces branching logic +- Callbacks and properties + - Using `useFunction` to wrap callbacks ensures stable execution within the Svelte lifecycle + - Using `omitUndefinedProps` to filter undefined properties reduces the processing burden on underlying components +- Complexity and extensibility + - The `createItemsContext` factory provides a consistent items injection strategy for multiple components, improving extensibility + - Slot-based design gives components stronger customizability while keeping default behavior stable + +## Troubleshooting Guide + +- Slots not taking effect + - Check whether slot key names match the component conventions (e.g., `menu.items`, `itemRender`, `progressDot`) + - Confirm slot nodes have been correctly passed to the component (ReactSlot and renderParamsSlot) +- items not displaying + - Confirm context is correctly injected (`withItemsContextProvider`) + - Check whether the combination of children and slots is being correctly resolved +- Callbacks not triggering + - Confirm callbacks are wrapped with `useFunction` + - Check the event pass-through chain (`onOpenChange`/`onSelect`/`onDeselect`, etc.) +- Layout anomalies + - Check the `component` parameter and class name mapping of `layout.base` + - Confirm style scopes have not been overridden by external styles + +Section Sources + +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +## Conclusion + +The navigation components in this repository use a unified context and slot rendering strategy as their core, achieving a high-cohesion, low-coupling component system. Through collaboration among tools like `useMemo`, `useFunction`, and `renderItems`, they ensure both performance and powerful customizability. Combined with layout components, they can flexibly construct multiple navigation patterns such as top navigation, sidebar navigation, and hybrid navigation, with good extensibility for routing integration and permission control. + +## Appendix + +- Navigation Pattern Design Guide (conceptual recommendations) + - Top navigation: Suitable for scenarios with clear entry points and shallow hierarchy; pair with Breadcrumb for improved path awareness + - Sidebar navigation: Suitable for content-rich admin systems requiring quick switching; pair with Anchor for fast positioning + - Hybrid navigation: Top main navigation + sidebar secondary navigation, balancing global and local operations +- Routing Integration and Permission Control (conceptual recommendations) + - Routing integration: Inject route metadata into the `items` of Menu/Breadcrumb/Steps to achieve navigation-route linkage + - Permission control: Filter `items` before rendering to show only nodes the user has permission to access +- Multi-level Navigation Implementation and Performance Considerations (conceptual recommendations) + - Use virtual scrolling and lazy loading to reduce large list rendering pressure + - Enable folding and caching for deep-level menus to avoid frequent re-renders + - Preserve necessary navigation state during route transitions to improve user experience diff --git a/.wiki/en/Ant Design Components/Navigation Components/Pagination.md b/.wiki/en/Ant Design Components/Navigation Components/Pagination.md new file mode 100644 index 00000000..662cae68 --- /dev/null +++ b/.wiki/en/Ant Design Components/Navigation Components/Pagination.md @@ -0,0 +1,340 @@ +# Pagination + + +**Files Referenced in This Document** +- [pagination.tsx](file://frontend/antd/pagination/pagination.tsx) +- [Index.svelte](file://frontend/antd/pagination/Index.svelte) +- [__init__.py](file://backend/modelscope_studio/components/antd/pagination/__init__.py) +- [basic.py](file://docs/components/antd/pagination/demos/basic.py) +- [data_changes.py](file://docs/components/antd/pagination/demos/data_changes.py) +- [README.md](file://docs/components/antd/pagination/README.md) +- [app.py](file://docs/components/antd/pagination/app.py) +- [table/__init__.py](file://backend/modelscope_studio/components/antd/table/__init__.py) +- [list/__init__.py](file://backend/modelscope_studio/components/antd/list/__init__.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document systematically introduces the implementation and usage of the Pagination component in the ModelScope Studio frontend and backend, covering the following topics: + +- Data pagination mechanism: How to calculate page ranges and boundaries based on total item count and page size +- Page navigation logic: Clicking page numbers, quick jumper, previous/next page, first/last page +- Total count display: Displaying current range and total via the "show total" callback or property +- Configuration details: Page size settings, default page number, page size selector, quick jumper, simple mode, size, disabled state, single-page hiding, etc. +- Integration with data tables and list views: How to link pagination with tables/lists for data loading, state synchronization, and error handling +- Internationalization support, style customization, responsive adaptation +- Advanced usage: large data pagination, virtual scrolling, server-side pagination +- Complete examples and performance optimization recommendations + +## Project Structure + +The Pagination component consists of three parts: + +- Frontend Svelte wrapper layer: Handles property pass-through, slot rendering, and visibility control +- Frontend React encapsulation layer: Connects to Ant Design's Pagination and supports slots and function-based rendering +- Backend Gradio component: Defines events, slots, property mappings, and render entry points + +```mermaid +graph TB +subgraph "Backend" +PY_INIT["Python Initialization
__init__.py"] +end +subgraph "Frontend" +IDX["Svelte Wrapper Layer
Index.svelte"] +REACT["React Encapsulation Layer
pagination.tsx"] +ANTDP["Ant Design Pagination"] +end +PY_INIT --> IDX --> REACT --> ANTDP +``` + +Diagram Sources + +- [Index.svelte:1-68](file://frontend/antd/pagination/Index.svelte#L1-L68) +- [pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [**init**.py:1-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L1-L107) + +Section Sources + +- [Index.svelte:1-68](file://frontend/antd/pagination/Index.svelte#L1-L68) +- [pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [**init**.py:1-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L1-L107) + +## Core Components + +- Backend component class: Defines events, slots, property mappings, and render directory +- Frontend wrapper layer: Uniformly handles properties, class names, styles, visibility, and slots +- React encapsulation layer: Connects to Ant Design's Pagination, supporting custom rendering and slot injection + +Key points + +- Events: `change`, `showSizeChange` +- Slots: `showQuickJumper.goButton`, `itemRender` +- Property mapping: e.g., `show_size_change` → `showSizeChange` + +Section Sources + +- [**init**.py:14-25](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L14-L25) +- [Index.svelte:22-48](file://frontend/antd/pagination/Index.svelte#L22-L48) +- [pagination.tsx:8-52](file://frontend/antd/pagination/pagination.tsx#L8-L52) + +## Architecture Overview + +The Pagination component call chain is as follows: + +```mermaid +sequenceDiagram +participant User as "User" +participant Backend as "Backend Component Class
AntdPagination" +participant FrontIndex as "Frontend Wrapper Layer
Index.svelte" +participant ReactLayer as "React Encapsulation Layer
pagination.tsx" +participant Antd as "Ant Design Pagination" +User->>Backend : Render request +Backend->>FrontIndex : Pass properties and slots +FrontIndex->>ReactLayer : Pass through properties and slots +ReactLayer->>Antd : Render component and bind events +User->>Antd : Trigger pagination/page size change +Antd-->>ReactLayer : onChange(page, pageSize) +ReactLayer-->>FrontIndex : Callback triggered +FrontIndex-->>Backend : Event callback e.g. change +``` + +Diagram Sources + +- [**init**.py:14-21](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L14-L21) +- [Index.svelte:54-66](file://frontend/antd/pagination/Index.svelte#L54-L66) +- [pagination.tsx:36-38](file://frontend/antd/pagination/pagination.tsx#L36-L38) + +## Detailed Component Analysis + +### Configuration Options and Behavior + +- Basic parameters + - Total items: `total` + - Default page number: `default_current` + - Current page: `current` + - Items per page: `default_page_size` / `page_size` + - Page size options: `page_size_options` + - Disabled: `disabled` + - Hide on single page: `hide_on_single_page` + - Size: `size` (small/default) + - Alignment: `align` (start/center/end) + - Simple mode: `simple` + - Show title: `show_title` + - Show fewer items: `show_less_items` + - Responsive: `responsive` + - Custom rendering: `item_render` + - Show total: `show_total` + - Quick jumper: `show_quick_jumper` (with optional `goButton` slot) + - Show page size selector: `show_size_changer` +- Slots + - `showQuickJumper.goButton`: Quick jump button + - `itemRender`: Custom page number item rendering + +Section Sources + +- [**init**.py:26-88](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L26-L88) +- [Index.svelte:46-47](file://frontend/antd/pagination/Index.svelte#L46-L47) +- [pagination.tsx:12-47](file://frontend/antd/pagination/pagination.tsx#L12-L47) + +### Events and State Synchronization + +- `change`: Triggered when page number or page size changes, returns (page, pageSize) +- `showSizeChange`: Triggered when page size changes +- Gradio state linkage: Write page number and page size to `gr.State` via event callbacks to drive data loading + +Section Sources + +- [**init**.py:14-21](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L14-L21) +- [data_changes.py:6-11](file://docs/components/antd/pagination/demos/data_changes.py#L6-L11) + +### Data Pagination Mechanism and Page Navigation Logic + +- Calculation rules + - Total pages: `Math.ceil(total / pageSize)` + - Current page range: 1 to total pages + - Boundary handling: `current` falls back to a valid value when out of range +- Navigation flow + - Click page number: Triggers `change` + - Previous/next/first/last page: Handled internally by Ant Design and triggers `change` + - Quick jump: When `show_quick_jumper` is enabled and a `goButton` slot is provided, the slot button executes the jump +- Custom rendering + - Use `itemRender` to customize page button content + - Use `show_total` to display range/total on the left side of pagination + +```mermaid +flowchart TD +Start(["Start"]) --> Init["Receive total and pageSize"] +Init --> CalcPages["Calculate total pages"] +CalcPages --> ValidateCurrent["Validate current is in valid range"] +ValidateCurrent --> Render["Render page buttons"] +Render --> Jump["User clicks page/jump button"] +Jump --> ChangeEvent["Trigger change(page, pageSize)"] +ChangeEvent --> UpdateState["Update state e.g. gr.State"] +UpdateState --> LoadData["Load data based on new page number"] +LoadData --> End(["End"]) +``` + +Diagram Sources + +- [pagination.tsx:36-38](file://frontend/antd/pagination/pagination.tsx#L36-L38) +- [data_changes.py:6-11](file://docs/components/antd/pagination/demos/data_changes.py#L6-L11) + +### Integration with Data Tables and List Views + +- Table integration + - Enable `pagination` in the table component and bind the pagination `change` event with the table data loading logic + - Use `show_size_changer` to dynamically switch items per page, linked with table column width and row height +- List integration + - List components support a `pagination` parameter that can directly accept a pagination instance + - List's load-more (`load_more`) and pagination can be used separately or in combination +- State synchronization + - Write pagination state to `gr.State` as input for subsequent data requests + - Table/list `loading` state and pagination `disabled` state can be linked to avoid concurrent requests + +Section Sources + +- [table/**init**.py:114-133](file://backend/modelscope_studio/components/antd/table/__init__.py#L114-L133) +- [list/**init**.py:59-82](file://backend/modelscope_studio/components/antd/list/__init__.py#L59-L82) +- [data_changes.py:24-28](file://docs/components/antd/pagination/demos/data_changes.py#L24-L28) + +### Internationalization, Style Customization, and Responsive Adaptation + +- Internationalization + - Provide locale via `ConfigProvider`; pagination text follows global configuration +- Style customization + - Supports `elem_id`, `elem_classes`, `elem_style`, and `additional_props` + - Theme-level customization via `root_class_name` and `class_names`/`styles` +- Responsive + - When `responsive` is enabled, the component automatically adjusts layout and font size on small-screen devices + +Section Sources + +- [README.md:1-14](file://docs/components/antd/pagination/README.md#L1-L14) +- [Index.svelte:56-58](file://frontend/antd/pagination/Index.svelte#L56-L58) +- [**init**.py:49-50](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L49-L50) + +### Advanced Usage: Large Data Pagination, Virtual Scrolling, Server-side Pagination + +- Large data pagination + - Use a large `total` combined with a smaller `page_size` and reasonable `page_size_options` + - Load data on demand via the `change` event to avoid rendering all data at once +- Virtual scrolling + - Table components support a `virtual` parameter that can significantly improve rendering performance for large datasets +- Server-side pagination + - Pagination only handles UI interaction; actual data is provided by backend APIs, with the frontend making requests in `change` and updating tables/lists + - Combine `loading` state and disabled state to prevent duplicate requests + +Section Sources + +- [table/**init**.py:129-130](file://backend/modelscope_studio/components/antd/table/__init__.py#L129-L130) +- [data_changes.py:6-11](file://docs/components/antd/pagination/demos/data_changes.py#L6-L11) + +### Examples and Best Practices + +- Basic example + - Demonstrates `total`, quick jumper, page size selector, and total count display +- Data change example + - Write page number and page size to `gr.State` via `change` event, and show a notification on button click +- Best practices + - Decouple pagination state from data requests using event-driven approach + - Disable pagination during data loading to avoid concurrency + - Set `page_size_options` reasonably to balance loading speed and user experience + +Section Sources + +- [basic.py:7-11](file://docs/components/antd/pagination/demos/basic.py#L7-L11) +- [data_changes.py:6-11](file://docs/components/antd/pagination/demos/data_changes.py#L6-L11) + +## Dependency Analysis + +- Component coupling + - Backend component class and frontend wrapper layer are loosely coupled, communicating via properties and slots as contracts + - React encapsulation layer's dependency on Ant Design is explicit, making it easy to upgrade and replace +- Events and slots + - Events: `change`, `showSizeChange` + - Slots: `showQuickJumper.goButton`, `itemRender` +- External dependencies + - Ant Design Pagination + - Gradio event system and state management + +```mermaid +graph LR +PY["Backend Component Class
__init__.py"] --> IDX["Frontend Wrapper Layer
Index.svelte"] +IDX --> REACT["React Encapsulation Layer
pagination.tsx"] +REACT --> ANTDP["Ant Design Pagination"] +PY --> |"Events/Slots"| PY +``` + +Diagram Sources + +- [**init**.py:14-25](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L14-L25) +- [Index.svelte:54-66](file://frontend/antd/pagination/Index.svelte#L54-L66) +- [pagination.tsx:28-48](file://frontend/antd/pagination/pagination.tsx#L28-L48) + +Section Sources + +- [**init**.py:14-25](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L14-L25) +- [Index.svelte:54-66](file://frontend/antd/pagination/Index.svelte#L54-L66) +- [pagination.tsx:28-48](file://frontend/antd/pagination/pagination.tsx#L28-L48) + +## Performance Considerations + +- Rendering optimization + - Use virtual scrolling (tables) to reduce DOM count + - Control `page_size` to avoid excessive single-page rendering pressure +- Request optimization + - Only make data requests on `change` to avoid frequent refreshes + - Disable pagination during requests to prevent duplicate requests +- Styles and resources + - Use `elem_classes` and style caching reasonably to reduce repaints + - Avoid heavy computations in `itemRender` + +## Troubleshooting Guide + +- Issue: Pagination not triggering `change` + - Check whether the `change` event is correctly bound + - Confirm `total` and `page_size` settings are reasonable +- Issue: Page size switching not working + - Check whether `show_size_changer` is enabled + - Confirm `show_size_change` property mapping is correct +- Issue: Quick jump button not displaying + - Check whether the `showQuickJumper.goButton` slot is provided +- Issue: Styles not taking effect + - Check usage of `elem_id`, `elem_classes`, `elem_style`, and `root_class_name` +- Issue: Internationalization text anomalies + - Confirm `ConfigProvider` is correctly configured with the locale + +Section Sources + +- [Index.svelte:46-47](file://frontend/antd/pagination/Index.svelte#L46-L47) +- [pagination.tsx:39-47](file://frontend/antd/pagination/pagination.tsx#L39-L47) +- [README.md:1-14](file://docs/components/antd/pagination/README.md#L1-L14) + +## Conclusion + +The Pagination component achieves a flexible pagination experience through clear frontend-backend separation and event/slot contracts. Combined with table and list components, high-performance, extensible data browsing interfaces can be easily built. For large dataset scenarios, combining virtual scrolling and server-side pagination strategies is recommended to ensure smooth interactions and efficient resource usage. + +## Appendix + +- Example entry + - Documentation app entry: [app.py:1-7](file://docs/components/antd/pagination/app.py#L1-L7) +- Example scripts + - Basic example: [basic.py:1-15](file://docs/components/antd/pagination/demos/basic.py#L1-L15) + - Data change example: [data_changes.py:1-36](file://docs/components/antd/pagination/demos/data_changes.py#L1-L36) +- Component source code + - Backend component class: [**init**.py:1-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L1-L107) + - Frontend wrapper layer: [Index.svelte:1-68](file://frontend/antd/pagination/Index.svelte#L1-L68) + - React encapsulation layer: [pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) diff --git a/.wiki/en/Ant Design Components/Navigation Components/Steps.md b/.wiki/en/Ant Design Components/Navigation Components/Steps.md new file mode 100644 index 00000000..093c2db9 --- /dev/null +++ b/.wiki/en/Ant Design Components/Navigation Components/Steps.md @@ -0,0 +1,425 @@ +# Steps + + +**Files Referenced in This Document** +- [steps.tsx](file://frontend/antd/steps/steps.tsx) +- [steps.item.tsx](file://frontend/antd/steps/item/steps.item.tsx) +- [Index.svelte](file://frontend/antd/steps/item/Index.svelte) +- [context.ts](file://frontend/antd/steps/context.ts) +- [package.json](file://frontend/antd/steps/package.json) +- [gradio.config.js](file://frontend/antd/steps/gradio.config.js) +- [__init__.py](file://backend/modelscope_studio/components/antd/steps/__init__.py) +- [README.md](file://docs/components/antd/steps/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +The Steps component guides users through multiple stages in sequence within a task flow, serving as a typical process indicator component. This component is based on Ant Design's Steps implementation, provided in a form directly usable from the Python backend via Gradio/Svelte frontend bridging. It supports multiple layout modes (horizontal/vertical), size specifications (default/small), state management (wait/process/finish/error), and custom progress dot rendering (progressDot slot). The component also provides integration capabilities for form wizards, business processes, user registration, and other scenarios, with support for style customization and responsive adaptation. + +## Project Structure + +The Steps component consists of frontend Svelte components and backend ModelScope component wrappers, with frontend-backend interaction following Gradio component conventions. Key files are distributed as follows: + +- Frontend: `steps.tsx` (main component), `steps.item.tsx` (step item wrapper), `Index.svelte` (step item entry), `context.ts` (step item context), `package.json` (export config), `gradio.config.js` (build config) +- Backend: `__init__.py` (Python wrapper, exposing properties and events) +- Documentation: `README.md` (component description and example placeholders) + +```mermaid +graph TB +subgraph "Frontend" +F_steps_tsx["steps.tsx
Main Component"] +F_item_index["Index.svelte
Step Item Entry"] +F_item_impl["steps.item.tsx
Step Item Implementation"] +F_context["context.ts
Step Item Context"] +F_pkg["package.json
Export Config"] +F_cfg["gradio.config.js
Build Config"] +end +subgraph "Backend" +B_init["__init__.py
Python Wrapper"] +end +subgraph "Documentation" +D_readme["README.md
Component Description"] +end +F_steps_tsx --> F_context +F_steps_tsx --> F_item_impl +F_item_index --> F_item_impl +F_steps_tsx --> B_init +F_pkg --> F_steps_tsx +F_cfg --> F_steps_tsx +D_readme --> B_init +``` + +**Diagram Sources** + +- [steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [steps.item.tsx:1-14](file://frontend/antd/steps/item/steps.item.tsx#L1-L14) +- [Index.svelte:1-65](file://frontend/antd/steps/item/Index.svelte#L1-L65) +- [context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) +- [package.json:1-15](file://frontend/antd/steps/package.json#L1-L15) +- [gradio.config.js:1-4](file://frontend/antd/steps/gradio.config.js#L1-L4) +- [**init**.py:1-95](file://backend/modelscope_studio/components/antd/steps/__init__.py#L1-L95) +- [README.md:1-8](file://docs/components/antd/steps/README.md#L1-L8) + +**Section Sources** + +- [steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [steps.item.tsx:1-14](file://frontend/antd/steps/item/steps.item.tsx#L1-L14) +- [Index.svelte:1-65](file://frontend/antd/steps/item/Index.svelte#L1-L65) +- [context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) +- [package.json:1-15](file://frontend/antd/steps/package.json#L1-L15) +- [gradio.config.js:1-4](file://frontend/antd/steps/gradio.config.js#L1-L4) +- [**init**.py:1-95](file://backend/modelscope_studio/components/antd/steps/__init__.py#L1-L95) +- [README.md:1-8](file://docs/components/antd/steps/README.md#L1-L8) + +## Core Components + +- Main Component Steps (frontend): Responsible for receiving props, parsing slots (e.g., `progressDot`), merging items data sources (explicit items or slot items/default), and passing the final data to Ant Design's Steps. +- Step Item StepsItem (frontend): Serves as the React wrapper for step items, injecting step items into the Steps container through the ItemHandler context. +- Step Item Entry Index.svelte: Renders StepsItem in Svelte and handles properties such as visibility, class names, IDs, inline styles, and slots. +- Context: Provides `createItemsContext` capabilities to establish a stable parent-child relationship and data channel between Steps and StepsItem. +- Backend wrapper AntdSteps: Provides rich properties (`current`, `direction`, `size`, `status`, `type`, `responsive`, etc.) and declares supported slots (`progressDot`, `items`). + +**Section Sources** + +- [steps.tsx:10-49](file://frontend/antd/steps/steps.tsx#L10-L49) +- [steps.item.tsx:7-11](file://frontend/antd/steps/item/steps.item.tsx#L7-L11) +- [Index.svelte:16-64](file://frontend/antd/steps/item/Index.svelte#L16-L64) +- [context.ts:3-4](file://frontend/antd/steps/context.ts#L3-L4) +- [**init**.py:11-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L11-L77) + +## Architecture Overview + +The runtime control flow of the Steps component: the frontend Steps component reads the step item collection from context and resolves `items` or the default slot; if a `progressDot` slot exists, it renders via parameterized slot; otherwise falls back to function or boolean value form. Ant Design's Steps receives the final items and progress dot configuration, renders the UI, and triggers the `change` event (monitored by the backend). + +```mermaid +sequenceDiagram +participant Py as "Backend Component
AntdSteps" +participant FE as "Frontend Component
Steps" +participant Ctx as "Context
withItemsContextProvider" +participant AD as "Ant Design Steps" +Py->>FE : Render component and pass props +FE->>Ctx : Request current step item collection +Ctx-->>FE : Return items/default +FE->>FE : Resolve items or default slot +FE->>FE : Handle progressDot slot/function +FE->>AD : Pass items and progress dot configuration +AD-->>FE : Render UI +FE-->>Py : Trigger change event monitored by backend +``` + +**Diagram Sources** + +- [steps.tsx:16-44](file://frontend/antd/steps/steps.tsx#L16-L44) +- [context.ts:3-4](file://frontend/antd/steps/context.ts#L3-L4) +- [**init**.py:16-20](file://backend/modelscope_studio/components/antd/steps/__init__.py#L16-L20) + +**Section Sources** + +- [steps.tsx:16-44](file://frontend/antd/steps/steps.tsx#L16-L44) +- [context.ts:3-4](file://frontend/antd/steps/context.ts#L3-L4) +- [**init**.py:16-20](file://backend/modelscope_studio/components/antd/steps/__init__.py#L16-L20) + +## Detailed Component Analysis + +### Steps Main Component (Steps) + +- Functional responsibilities + - Receives all available props for Ant Design Steps and extends children support. + - Reads step item collection from context; prefers explicit items, then uses default slot items/default. + - Progress dot configuration supports two forms: slot `progressDot` (parameterized rendering) or function/boolean value. + - Uses `useMemo` to stabilize items, avoiding unnecessary re-renders. +- Key behaviors + - Hides children (`display: none`) to avoid duplicate rendering; actual content is injected via slots. + - `progressDot` priority: uses slot rendering if a slot exists; otherwise uses function or native boolean/string configuration. +- Typical usage + - Directly pass a steps array in `items`, or inject step items via slots. + - Use the `progressDot` slot to customize the rendering logic of each step indicator. + +```mermaid +flowchart TD +Start(["Enter Steps Render"]) --> ReadCtx["Read items/default from context"] +ReadCtx --> HasExplicit{"Are explicit items provided?"} +HasExplicit --> |Yes| UseExplicit["Use explicit items"] +HasExplicit --> |No| UseDefault["Use default slot items/default"] +UseExplicit --> ResolveItems["Resolve step item list"] +UseDefault --> ResolveItems +ResolveItems --> HasProgressDotSlot{"Does progressDot slot exist?"} +HasProgressDotSlot --> |Yes| RenderSlot["Parameterized slot rendering"] +HasProgressDotSlot --> |No| UseFuncOrProp["Use function/boolean/string configuration"] +RenderSlot --> RenderAD["Render Ant Design Steps"] +UseFuncOrProp --> RenderAD +RenderAD --> End(["Complete"]) +``` + +**Diagram Sources** + +- [steps.tsx:18-44](file://frontend/antd/steps/steps.tsx#L18-L44) + +**Section Sources** + +- [steps.tsx:10-49](file://frontend/antd/steps/steps.tsx#L10-L49) + +### Step Item (StepsItem) + +- Functional responsibilities + - Serves as the React wrapper for step items, combining step item properties with context, handed to `ItemHandler`. + - Bridges TypeScript/React components to the Svelte ecosystem via `sveltify`. +- Integration key points + - Works with Steps context to ensure step items are correctly injected into the container. + - Supports additional property pass-through and internal index (`itemIndex`) passing. + +```mermaid +classDiagram +class StepsItem { ++props : step item properties ++Renders to ItemHandler +} +class ItemHandler { ++Inject step item ++Maintain context +} +StepsItem --> ItemHandler : "Wrap and inject" +``` + +**Diagram Sources** + +- [steps.item.tsx:7-11](file://frontend/antd/steps/item/steps.item.tsx#L7-L11) +- [context.ts:3-4](file://frontend/antd/steps/context.ts#L3-L4) + +**Section Sources** + +- [steps.item.tsx:7-11](file://frontend/antd/steps/item/steps.item.tsx#L7-L11) +- [context.ts:3-4](file://frontend/antd/steps/context.ts#L3-L4) + +### Step Item Entry (Index.svelte) + +- Functional responsibilities + - Dynamically imports StepsItem in Svelte and renders it. + - Handles visibility, class names, IDs, inline styles, slots, and other properties. + - Injects child nodes into StepsItem via `{@render children()}`. +- Design key points + - Uses `getProps`/`processProps` to retrieve and filter internal properties that don't need pass-through. + - Gets the slot key via `getSlotKey` and passes it to StepsItem for slot identification. + +```mermaid +flowchart TD +SStart(["Index.svelte Render Start"]) --> ImportItem["Dynamic import StepsItem"] +ImportItem --> GetProps["Extract component and additional properties"] +GetProps --> CheckVisible{"Visibility check"} +CheckVisible --> |Hidden| Skip["Skip rendering"] +CheckVisible --> |Visible| RenderItem["Render StepsItem with properties/slots"] +RenderItem --> SEnd(["End"]) +Skip --> SEnd +``` + +**Diagram Sources** + +- [Index.svelte:16-64](file://frontend/antd/steps/item/Index.svelte#L16-L64) + +**Section Sources** + +- [Index.svelte:1-65](file://frontend/antd/steps/item/Index.svelte#L1-L65) + +### Backend Wrapper (AntdSteps) + +- Property overview (selected) + - Current step `current`, direction `direction` (horizontal/vertical), initial value `initial`, label position `label_placement`, title position `title_placement`, percentage `percent`, progress dot `progress_dot`, responsive `responsive`, size `size` (small/default), status `status` (wait/process/finish/error), type `type` (default/navigation/inline), root class name `root_class_name`, class names `class_names`, styles `styles`, slots `items`/`progressDot`, etc. +- Events + - `change`: Listens for step change events (bound by the backend). +- Others + - `FRONTEND_DIR` points to the frontend steps component directory. + - `skip_api` is `True`, indicating the component does not participate in the standard API flow. + +```mermaid +classDiagram +class AntdSteps { ++current : number ++direction : "horizontal|vertical" ++initial : number ++label_placement : "horizontal|vertical" ++title_placement : "horizontal|vertical"|None ++percent : number|None ++progress_dot : bool|string ++responsive : bool ++size : "small|default"|None ++status : "wait|process|finish|error" ++type : "default|navigation|inline" ++items : list|None ++root_class_name : str|None ++class_names : dict|str|None ++styles : dict|str|None ++EVENTS : ["change"] ++SLOTS : ["progressDot","items"] +} +``` + +**Diagram Sources** + +- [**init**.py:25-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L25-L77) + +**Section Sources** + +- [**init**.py:11-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L11-L77) + +## Dependency Analysis + +- Frontend dependencies + - Uses Ant Design's Steps as the underlying UI component. + - Bridges React components to Svelte via `sveltify`. + - Provides step item context via `createItemsContext`. + - Renders step items and slots using `renderItems`/`renderParamsSlot`. +- Backend dependencies + - Interacts with Gradio via `ModelScopeLayoutComponent`. + - Specifies the frontend component directory via `resolve_frontend_dir`. +- Exports and build + - `package.json` specifies Gradio and default export paths. + - `gradio.config.js` performs build configuration based on global `defineConfig`. + +```mermaid +graph LR +Pkg["package.json"] --> StepsTSX["steps.tsx"] +Cfg["gradio.config.js"] --> StepsTSX +StepsTSX --> AD["Ant Design Steps"] +StepsTSX --> Ctx["createItemsContext"] +StepsTSX --> Utils["renderItems / renderParamsSlot"] +StepsTSX --> Py["AntdSteps(__init__.py)"] +``` + +**Diagram Sources** + +- [package.json:4-12](file://frontend/antd/steps/package.json#L4-L12) +- [gradio.config.js:1-4](file://frontend/antd/steps/gradio.config.js#L1-L4) +- [steps.tsx:1-8](file://frontend/antd/steps/steps.tsx#L1-L8) +- [**init**.py:77-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L77-L77) + +**Section Sources** + +- [package.json:1-15](file://frontend/antd/steps/package.json#L1-L15) +- [gradio.config.js:1-4](file://frontend/antd/steps/gradio.config.js#L1-L4) +- [steps.tsx:1-8](file://frontend/antd/steps/steps.tsx#L1-L8) +- [**init**.py:77-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L77-L77) + +## Performance Considerations + +- Data stabilization: Uses `useMemo` to stabilize items, reducing unnecessary re-renders. +- Slot rendering: The `progressDot` slot uses parameterized rendering to avoid repeatedly creating complex structures in each render. +- Visibility control: The step item entry checks `visible` to hide invisible items, reducing DOM overhead. +- Event binding: Binds the `change` event only when needed, avoiding unnecessary callback triggers. + +[This section contains general performance advice and does not require specific file references] + +## Troubleshooting Guide + +- Issue: Step items not displaying + - Check whether Steps has correctly injected `items` or slot `items/default`. + - Confirm the step item's `visible` property is true. +- Issue: Progress dots not rendering as expected + - If using the `progressDot` slot, confirm the slot key matches the component conventions. + - If using function/boolean value, confirm the passed configuration matches Ant Design's expectations. +- Issue: Styles or class names not taking effect + - Check whether `root_class_name`, `class_names`, `styles` are correctly passed. + - Confirm CSS scope and override rules. +- Issue: Responsive layout anomalies + - Check whether the combination of `responsive` and `direction` is as expected. + - Confirm parent container width and breakpoint settings. + +**Section Sources** + +- [steps.tsx:20-44](file://frontend/antd/steps/steps.tsx#L20-L44) +- [Index.svelte:49-64](file://frontend/antd/steps/item/Index.svelte#L49-L64) +- [**init**.py:25-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L25-L77) + +## Conclusion + +The Steps component achieves complete wrapping and extension of Ant Design Steps through a clear frontend-backend layered design. It supports multiple layouts, multiple states, customizable progress dots, and responsive adaptation, suitable for form wizards, business processes, user registration, and other scenarios. Through context and slot mechanisms, the component has good composability and maintainability. + +[This section contains summary content and does not require specific file references] + +## Appendix + +### Step Item (Item) Configuration Options + +- Basic properties + - Title: Text for the step item title. + - Description: Description text for the step item. + - Icon: Icon element for the step item. +- State and behavior + - Status: `wait`, `process`, `finish`, `error`, indicating the current state of the step. + - Visibility: `visible` controls whether the step item is rendered. + - Internal index: `itemIndex` identifies the step item's position in the list. +- Slots and styles + - Slots: Support injecting custom content via slots. + - Class names and IDs: `elem_classes`, `elem_id` for styling and positioning. + - Inline styles: `elem_style` for local style overrides. + +**Section Sources** + +- [Index.svelte:16-64](file://frontend/antd/steps/item/Index.svelte#L16-L64) +- [steps.item.tsx:7-11](file://frontend/antd/steps/item/steps.item.tsx#L7-L11) + +### Layout Modes and Application Scenarios + +- Horizontal steps bar (horizontal) + - Suitable for linear processes such as form wizards and payment flows. +- Vertical steps bar (vertical) + - Suitable for long processes or scenarios emphasizing chronological order. +- Small steps bar (small) + - Suitable for space-constrained or simplified interfaces. + +**Section Sources** + +- [**init**.py:30-39](file://backend/modelscope_studio/components/antd/steps/__init__.py#L30-L39) + +### Integration with Form Wizards, Business Processes, and User Registration + +- Form wizards + - Use `current` and `status` to control the current step and state; synchronize backend state via `change` events. +- Business processes + - Use `direction` and `responsive` for process visualization; use `progress_dot` to customize process nodes. +- User registration + - Use `size` and `type` to switch between different styles; use `items` and slots to organize registration steps. + +**Section Sources** + +- [**init**.py:25-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L25-L77) +- [steps.tsx:16-44](file://frontend/antd/steps/steps.tsx#L16-L44) + +### Style Customization and Responsive Adaptation + +- Style customization + - Use `root_class_name`, `class_names`, `styles` for overall and local style control. + - Granularly control step item appearance via `elem_classes`, `elem_id`, `elem_style`. +- Responsive adaptation + - Use the combination of `responsive` and `direction` to adapt for mobile and desktop layouts. + +**Section Sources** + +- [**init**.py:40-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L40-L77) +- [Index.svelte:52-58](file://frontend/antd/steps/item/Index.svelte#L52-L58) + +### Usage Examples and Best Practices + +- Example references + - The documentation provides basic example placeholders; combine with `AntdSteps` properties and slots for demonstrations. +- Best practices + - Clearly define step states and navigation logic to avoid state confusion. + - Use the `progress_dot` slot judiciously to maintain visual consistency. + - Break down steps for complex processes to improve user experience. + +**Section Sources** + +- [README.md:1-8](file://docs/components/antd/steps/README.md#L1-L8) +- [**init**.py:25-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L25-L77) diff --git a/.wiki/en/Ant Design Components/Other Components.md b/.wiki/en/Ant Design Components/Other Components.md new file mode 100644 index 00000000..1e73e57f --- /dev/null +++ b/.wiki/en/Ant Design Components/Other Components.md @@ -0,0 +1,325 @@ +# Other Components + + +**Files referenced in this document** +- [frontend/antd/affix/affix.tsx](file://frontend/antd/affix/affix.tsx) +- [frontend/antd/affix/Index.svelte](file://frontend/antd/affix/Index.svelte) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) +- [frontend/antd/config-provider/Index.svelte](file://frontend/antd/config-provider/Index.svelte) +- [frontend/antd/float-button/float-button.tsx](file://frontend/antd/float-button/float-button.tsx) +- [frontend/antd/layout/layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) +- [frontend/antd/float-button/group/float-button.group.less](file://frontend/antd/float-button/group/float-button.group.less) +- [frontend/antd/menu/menu.less](file://frontend/antd/menu/menu.less) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This chapter focuses on the "Other Components" scenario of Ant Design Studio, covering two types of auxiliary components: Affix and ConfigProvider. We will systematically explain positioning mechanisms, scroll monitoring and boundary handling, as well as theme customization, language switching, and component default configuration, combining real implementations from the repository to provide actionable application scenarios, performance optimization and memory management suggestions, and best practices for component collaboration. + +## Project Structure + +- Frontend uses Svelte + React hybrid encapsulation mode: Svelte layer handles property/slot pass-through and conditional rendering, React layer handles specific UI behaviors (such as Affix, ConfigProvider, etc.). +- Utility layer provides common capabilities, such as converting external functions into function wrappers that can be safely used in React. +- Style layer ensures theme and prefix isolation through CSS-in-JS StyleProvider, avoiding global pollution. + +```mermaid +graph TB +subgraph "Svelte Layer" +A_Index["Affix/Index.svelte"] +C_Index["ConfigProvider/Index.svelte"] +end +subgraph "React Layer" +A_Impl["affix.tsx
Wraps Ant Design Affix"] +C_Impl["config-provider.tsx
Wraps Ant Design ConfigProvider"] +FBT["float-button.tsx
Float Button"] +LBase["layout.base.tsx
Layout Base"] +end +subgraph "Utilities and Resources" +UF["useFunction.ts
Function Wrapper"] +LOC["locales.ts
Multi-language Mapping and On-demand Loading"] +FBGroupLess["float-button.group.less
Group Styles"] +MenuLess["menu.less
Menu Styles"] +end +A_Index --> A_Impl +C_Index --> C_Impl +A_Impl --> UF +C_Impl --> UF +C_Impl --> LOC +FBT --> UF +LBase --> |"Layout Composition"| A_Impl +LBase --> |"Layout Composition"| C_Impl +FBGroupLess --> FBT +MenuLess --> C_Impl +``` + +Diagram Source + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/antd/float-button/group/float-button.group.less:1-31](file://frontend/antd/float-button/group/float-button.group.less#L1-L31) +- [frontend/antd/menu/menu.less:1-45](file://frontend/antd/menu/menu.less#L1-L45) + +Section Source + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/antd/float-button/group/float-button.group.less:1-31](file://frontend/antd/float-button/group/float-button.group.less#L1-L31) +- [frontend/antd/menu/menu.less:1-45](file://frontend/antd/menu/menu.less#L1-L45) + +## Core Components + +- Affix + - Positioning Mechanism: Calculates element fixed state based on target container scroll position; supports custom target containers (such as page or a scroll area). + - Boundary Handling: Controls fixed/unbind timing through threshold to avoid elements being incorrectly fixed or prematurely unbound. + - Scroll Monitoring: Converts externally passed container selectors into React-usable callbacks through function wrappers. +- ConfigProvider + - Theme Customization: Supports light/dark mode and compact algorithm switch, dynamically combining algorithm lists to achieve theme switching. + - Language Switching: According to browser or specified language, asynchronously loads Antd language pack and dayjs language pack on demand. + - Component Default Configuration: Uniformly encapsulates global behaviors like getPopupContainer, getTargetContainer, renderEmpty, etc. + - Style Isolation: Injects high-priority styles through CSS-in-JS StyleProvider to avoid style conflicts. + +Section Source + +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) + +## Architecture Overview + +The diagram below shows the interaction relationship between Svelte and React layers, as well as ConfigProvider's extension points in theme and language aspects. + +```mermaid +sequenceDiagram +participant S as "Svelte Layer" +participant R as "React Layer" +participant U as "Utility Layer" +participant L as "Language Resources" +S->>R : Pass-through properties/slots +R->>U : useFunction wraps container selector/callback +R->>L : On-demand load language pack and dayjs language +L-->>R : Return language pack object +R-->>S : Render result with theme and language +``` + +Diagram Source + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) + +## Detailed Component Analysis + +### Affix Component + +- Design Points + - Svelte layer handles conditional rendering and property pass-through, supports visible for display control. + - React layer converts externally passed container selectors into React-executable functions through useFunction, ensuring stable and reliable scroll monitoring. + - Supports slots and child node rendering for carrying complex content in fixed state. +- Key Flow + - Property Processing: Maps get_target to target, handled internally by the Affix component. + - Rendering: Only renders when visible is true, reducing unnecessary DOM overhead. +- Usage Suggestions + - For non-window scroll containers, be sure to explicitly pass the target function to point to the correct container. + - Set thresholds reasonably to avoid jitter caused by frequent switching between fixed/unbound states. + +```mermaid +sequenceDiagram +participant UI as "Caller" +participant S as "Affix/Index.svelte" +participant R as "affix.tsx" +participant A as "Antd Affix" +UI->>S : Pass visible/get_target/properties +S->>R : Pass-through properties and slots +R->>R : useFunction wraps target +R->>A : Render Affix and pass target +A-->>UI : Fixed/unbound state update +``` + +Diagram Source + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) + +Section Source + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) + +### ConfigProvider Component + +- Design Points + - Theme: Dynamically combines algorithms through themeMode and theme.algorithm, supporting dark and compact modes. + - Language: Automatically maps to available language sets based on locale, asynchronously loads Antd language pack and dayjs language pack on demand. + - Container: Uniformly provides function wrappers for getPopupContainer and getTargetContainer, ensuring popups and overlays render to the correct container. + - Slots: Supports slot parameters like renderEmpty, implemented through renderParamsSlot for flexible extension. + - Styles: Injects high-priority styles through StyleProvider to avoid style conflicts. +- Key Flow + - Language Initialization: Parses browser language or passed locale into standard format and loads corresponding language pack. + - Theme Initialization: Generates algorithm array based on themeMode and user configuration, passes to Ant Design. + - Container Callback: Uses useFunction to wrap callbacks, ensuring stable operation within React lifecycle. + - Slot Rendering: Wraps slot content as ReactSlot or renderParamsSlot, maintaining type safety. + +```mermaid +sequenceDiagram +participant UI as "Caller" +participant S as "ConfigProvider/Index.svelte" +participant R as "config-provider.tsx" +participant U as "useFunction.ts" +participant LOC as "locales.ts" +participant SP as "StyleProvider" +UI->>S : Pass theme_mode/locale/theme etc. +S->>R : Pass-through properties and slots +R->>U : useFunction wraps getPopupContainer/getTargetContainer/renderEmpty +R->>LOC : Parse locale and on-demand load language pack +LOC-->>R : Return language pack object +R->>SP : Inject high-priority styles +SP-->>UI : Render subtree with theme and language +``` + +Diagram Source + +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) + +Section Source + +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) + +### FloatButton and Layout.Base + +- FloatButton + - Supports slots like icon/description/tooltip/badge, implemented through ReactSlot for flexible rendering. + - tooltip supports object configuration and callback wrapping, ensuring popup container and callback stability. +- Layout.Base + - Dynamically selects Header/Footer/Content/Layout through component type selector, unifies class name prefix for easy style control. + +Section Source + +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +## Dependency Analysis + +- Component Coupling + - Both Affix and ConfigProvider depend on useFunction for function wrapping, reducing cross-layer call risks. + - ConfigProvider depends on language mapping and on-demand loading capabilities provided by locales.ts. +- External Dependencies + - Ant Design component library and dayjs language packs. + - CSS-in-JS StyleProvider for style isolation and priority control. +- Potential Circular Dependencies + - No direct circular dependencies in current implementation; if business side re-introduces ConfigProvider/Affix in slots, carefully control rendering levels. + +```mermaid +graph LR +A["affix.tsx"] --> UF["useFunction.ts"] +C["config-provider.tsx"] --> UF +C --> LOC["locales.ts"] +C --> SP["StyleProvider"] +F["float-button.tsx"] --> UF +L["layout.base.tsx"] --> |"Composition"| A +L --> |"Composition"| C +``` + +Diagram Source + +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) + +Section Source + +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) + +## Performance Considerations + +- Scroll Monitoring and Repaint + - Affix's target should point to minimized scroll containers as much as possible to avoid pressure on full-page scrolling. + - Set thresholds and fixed heights reasonably to reduce reflow and repaint caused by frequent switching. +- Language Pack On-demand Loading + - ConfigProvider only triggers language pack loading when locale changes, avoiding repeated requests. + - dayjs language pack and Antd language pack are loaded asynchronously, note network and caching strategies. +- Function Wrapping and Stability + - Use useFunction to wrap callbacks to avoid new functions being generated on each render causing unnecessary child component updates. +- Style Injection + - StyleProvider high-priority injection reduces style override costs; avoid frequent theme switching in hot paths. + +## Troubleshooting Guide + +- Affix not working + - Check whether the target function is correctly passed, or whether updates are not triggered when container scrolls. + - Confirm visible condition is satisfied and container has scrollbar. +- Language switching ineffective + - Check whether locale has a mapping in locales.ts; confirm asynchronous loading succeeded. + - Ensure dayjs.locale switching succeeded. +- Theme switching abnormal + - Check whether themeMode and theme.algorithm combination is as expected. + - Note algorithm array concatenation order and null value filtering. +- Slot rendering issues + - Confirm slot key and renderParamsSlot mapping consistency. + - ReactSlot's clone parameter should be enabled as needed to avoid duplicate mounting. + +Section Source + +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) + +## Conclusion + +- Affix and ConfigProvider, as auxiliary components, undertake the key responsibilities of "positioning and scrolling" and "theme and language" in Ant Design Studio. +- Through layered encapsulation of Svelte and React, both usability and powerful extensibility are guaranteed. +- In actual projects, it is recommended to prioritize using ConfigProvider for global unified configuration at the application root, then use Affix locally on pages that need fixed layouts or toolbars. + +## Appendix + +- Best Practices for Component Collaboration + - Place ConfigProvider at the application root to centrally manage theme and language; use Affix locally on pages that need fixed elements. + - Use Layout.Base to unify layout structure, combined with FloatButton to improve interaction efficiency. + - For complex slot scenarios, prefer using ReactSlot and renderParamsSlot to ensure type safety and controllable rendering. +- Styles and Themes + - Avoid style conflicts through StyleProvider and prefix class names (like ms-gr-ant). + - Menu and float button style files can be used as references, adjust border-radius, spacing, and transition effects as needed. diff --git a/.wiki/en/Ant Design X Components/Ant Design X Components.md b/.wiki/en/Ant Design X Components/Ant Design X Components.md new file mode 100644 index 00000000..207c9fdb --- /dev/null +++ b/.wiki/en/Ant Design X Components/Ant Design X Components.md @@ -0,0 +1,626 @@ +# Ant Design X Components + + +**Files referenced in this document** +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/antdx/file_card/__init__.py](file://backend/modelscope_studio/components/antdx/file_card/__init__.py) +- [backend/modelscope_studio/components/antdx/file_card/list/__init__.py](file://backend/modelscope_studio/components/antdx/file_card/list/__init__.py) +- [backend/modelscope_studio/components/antdx/file_card/list/item/__init__.py](file://backend/modelscope_studio/components/antdx/file_card/list/item/__init__.py) +- [backend/modelscope_studio/components/antdx/mermaid/__init__.py](file://backend/modelscope_studio/components/antdx/mermaid/__init__.py) +- [backend/modelscope_studio/components/antdx/folder/directory_icon/__init__.py](file://backend/modelscope_studio/components/antdx/folder/directory_icon/__init__.py) +- [backend/modelscope_studio/components/antdx/folder/tree_node/__init__.py](file://backend/modelscope_studio/components/antdx/folder/tree_node/__init__.py) +- [frontend/antdx/file-card/file-card.tsx](file://frontend/antdx/file-card/file-card.tsx) +- [frontend/antdx/file-card/base.tsx](file://frontend/antdx/file-card/base.tsx) +- [frontend/antdx/mermaid/mermaid.tsx](file://frontend/antdx/mermaid/mermaid.tsx) +- [frontend/antdx/folder/folder.tsx](file://frontend/antdx/folder/folder.tsx) +- [frontend/antdx/thought-chain/thought-chain.tsx](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [frontend/antdx/conversations/conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [frontend/antdx/welcome/welcome.tsx](file://frontend/antdx/welcome/welcome.tsx) +- [frontend/antdx/prompts/prompts.tsx](file://frontend/antdx/prompts/prompts.tsx) +- [frontend/antdx/attachments/attachments.tsx](file://frontend/antdx/attachments/attachments.tsx) +- [frontend/antdx/sender/sender.tsx](file://frontend/antdx/sender/sender.tsx) +- [frontend/antdx/suggestion/suggestion.tsx](file://frontend/antdx/suggestion/suggestion.tsx) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/think/think.tsx](file://frontend/antdx/think/think.tsx) +- [frontend/antdx/notification/notification.tsx](file://frontend/antdx/notification/notification.tsx) +- [frontend/antdx/sources/sources.tsx](file://frontend/antdx/sources/sources.tsx) + + +## Update Summary + +**Changes Made** + +- Added file card component system (FileCard, FileCardList, FileCardListItem) +- Added Mermaid diagram component +- Added folder component (Folder) and its subcomponents (DirectoryIcon, TreeNode) +- Added thought chain component (ThoughtChain) and its subcomponents +- Updated component export structure to sync with Ant Design X version +- Enhanced component collaboration capabilities, supporting richer slot-based rendering + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance and Usability Recommendations](#performance-and-usability-recommendations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document focuses on the Ant Design X component library for ModelScope Studio, designed for machine learning and AI application scenarios. It systematically covers general components (such as bubbles, conversation lists), wake components (welcome pages, prompts), expression components (attachments, sender, suggestions), confirmation components (thought chain), feedback components (actions), and newly added advanced components like file cards, Mermaid diagrams, and folders. It provides end-to-end examples and best practices to help developers build consistent, scalable, and user-friendly interfaces for conversational AI, multimodal input, knowledge retrieval augmentation, and chart visualization scenarios. + +## Project Structure + +The Ant Design X component library exports through Python packages on the backend and encapsulates @ant-design/x capabilities using Svelte/React bidirectional bridging on the frontend, exposing composable components uniformly. The overall structure is as follows: + +```mermaid +graph TB +subgraph "Backend Export Layer" +A["backend/modelscope_studio/components/antdx/__init__.py"] +B["backend/modelscope_studio/components/antdx/components.py"] +end +subgraph "Frontend Wrapper Layer" +C["frontend/antdx/bubble/bubble.tsx"] +D["frontend/antdx/conversations/conversations.tsx"] +E["frontend/antdx/welcome/welcome.tsx"] +F["frontend/antdx/prompts/prompts.tsx"] +G["frontend/antdx/attachments/attachments.tsx"] +H["frontend/antdx/sender/sender.tsx"] +I["frontend/antdx/suggestion/suggestion.tsx"] +J["frontend/antdx/actions/actions.tsx"] +K["frontend/antdx/think/think.tsx"] +L["frontend/antdx/notification/notification.tsx"] +M["frontend/antdx/sources/sources.tsx"] +N["frontend/antdx/file-card/file-card.tsx"] +O["frontend/antdx/mermaid/mermaid.tsx"] +P["frontend/antdx/folder/folder.tsx"] +Q["frontend/antdx/thought-chain/thought-chain.tsx"] +end +A --> C +A --> D +A --> E +A --> F +A --> G +A --> H +A --> I +A --> J +A --> K +A --> L +A --> M +A --> N +A --> O +A --> P +A --> Q +B --> C +B --> D +B --> E +B --> F +B --> G +B --> H +B --> I +B --> J +B --> K +B --> L +B --> M +B --> N +B --> O +B --> P +B --> Q +``` + +**Diagram Source** + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) + +**Section Source** + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## Core Components + +This section provides a categorized functional overview of key AI scenario components, including newly added advanced components, for quick identification and combined use. + +- General Components + - Bubble: Used to display message content, avatars, additional information, and footers, supporting slot-based rendering and editable configurations. + - Conversations: Used to display and manage historical conversations, supporting menus, grouping, and expand controls. +- Wake Components + - Welcome: Used as a guide page after application startup or reset, supporting titles, descriptions, icons, and additional areas. + - Prompts: Used to display a set of clickable prompt templates, helping users quickly start conversations. +- Expression Components + - Attachments: Used to upload and manage files, supporting placeholders, previews, image properties, and upload hooks. + - Sender: Used for text input and paste file upload, supporting skill hints, prefix/suffix, and submit interception. + - Suggestion: Used for autocomplete/suggestion panels in input context, supporting trigger strategies and slot-based item rendering. +- Confirmation Components + - Think: Used to display loading state, icons, and titles during reasoning, enhancing perceptibility. + - ThoughtChain: Used to display multi-step reasoning processes, supporting sub-item components and slot-based rendering. +- Feedback Components + - Actions: Used to provide action entries (such as copy, download, feedback) on the right side of content area, supporting dropdown menus and popup rendering. +- Advanced Components + - FileCard: Used to display file information, supporting multiple types, previews, masks, and loading states. + - Mermaid Diagram: Used to render Mermaid flowcharts, sequence diagrams, etc., supporting theme switching and custom actions. + - Folder: Used for file system browsing, supporting directory icon mapping, file content services, and preview rendering. +- Tool Components + - XProvider: Global configuration and context provider, extending antd's ConfigProvider, providing theme, language, popup container, and other global capabilities for @ant-design/x components. + - CodeHighlighter: Code highlighting display component, supporting theme customization, header slots, and syntax highlighting style overrides. + - Mermaid: Flowchart/mind map component, integrating highlighting and action item rendering, supporting light/dark theme switching and custom actions. + - Notification: Browser notification wrapper, providing permission requests, open/close, visibility control, and callbacks. +- Data Components + - FileCard: Used to display a single file card, supporting image placeholder, preview configuration, mask, and loading indicator slot customization. + - Folder: Used to display folder tree structure, supporting treeData, directoryIcons, empty state rendering, directory title, preview rendering slots. + - Sources: Used to display data source list, supporting items and title slots. + - Think: Used to display "thinking" records and status, supporting loading, icon, title slots for different visual feedback in different states. + +**Section Source** + +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/welcome/welcome.tsx:1-44](file://frontend/antdx/welcome/welcome.tsx#L1-L44) +- [frontend/antdx/prompts/prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) +- [frontend/antdx/suggestion/suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) +- [frontend/antdx/think/think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) + +## Architecture Overview + +The diagram below shows how frontend components bridge to @ant-design/x and achieve flexible rendering and event handling through slots and function wrapping, including the architecture of newly added components. + +```mermaid +graph TB +subgraph "Frontend Wrapper" +U["sveltify wrapper
slot rendering/function wrapping"] +V["@ant-design/x native components"] +W["Utilities and context
renderItems / renderParamsSlot / useFunction"] +X["File service and resource resolution
getFetchableUrl / resolveFileSrc"] +Y["Theme and styles
themeMode / highlightProps"] +end +U --> V +U --> W +U --> X +U --> Y +``` + +**Diagram Source** + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) + +## Component Details + +### General Components + +#### Bubble + +- Key Capabilities + - Supports slot-based rendering for avatars, titles, content, footers, and extra areas. + - Supports editable configuration (including "OK/Cancel" text slots). + - Supports loading state and content rendering function wrapping. +- Usage Recommendations + - Use as a message carrier in conversation flows, combined with Sender input and Attachments. + - For long content, enable editable and content rendering functions to improve interaction efficiency. +- Key Paths + - [frontend/antdx/bubble/bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) + +**Section Source** + +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) + +#### Conversations + +- Key Capabilities + - Supports slot-based configuration for menu items, overflow indicators, and expand icons. + - Supports functional configuration for grouping and collapse behavior. + - Internally reuses menu context for unified event propagation and DOM blocking. +- Usage Recommendations + - Combine with Sender/Attachments to form a closed loop of "input-generate-review". + - Implement "delete, rename, export" operations through menu items. +- Key Paths + - [frontend/antdx/conversations/conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) + +**Section Source** + +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) + +### Wake Components + +#### Welcome + +- Key Capabilities + - Supports slot-based title, description, icon, and additional areas. + - Icon supports passing file data and automatically resolves to accessible URL. +- Usage Recommendations + - Use as the first screen guide after application initialization or conversation reset. +- Key Paths + - [frontend/antdx/welcome/welcome.tsx:8-41](file://frontend/antdx/welcome/welcome.tsx#L8-L41) + +**Section Source** + +- [frontend/antdx/welcome/welcome.tsx:1-44](file://frontend/antdx/welcome/welcome.tsx#L1-L44) + +#### Prompts + +- Key Capabilities + - Supports title slot and item collection slot-based rendering. + - Provides item collection through context, simplifying external parameter passing. +- Usage Recommendations + - Place above welcome page or input box to help users quickly select intent templates. +- Key Paths + - [frontend/antdx/prompts/prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) + +**Section Source** + +- [frontend/antdx/prompts/prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) + +### Expression Components + +#### Attachments + +- Key Capabilities + - Supports placeholders, previews, image properties, upload hooks, and maximum count limits. + - Supports custom beforeUpload, customRequest, isImageUrl, previewFile, and other functions. + - Slot-based extension for "extra icons, download/remove/preview icons, placeholder content". +- Usage Recommendations + - Combine with Sender's paste upload for drag/paste-to-upload functionality. + - Note the interaction between maxCount and upload status to avoid concurrency conflicts. +- Key Paths + - [frontend/antdx/attachments/attachments.tsx:36-410](file://frontend/antdx/attachments/attachments.tsx#L36-L410) + +**Section Source** + +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) + +#### Sender + +- Key Capabilities + - Supports prefix/suffix/header/footer slots; supports "skill hint" configuration. + - Supports paste file upload callback, uniformly outputting file path array. + - Through value change hooks and submit interception, avoids mistaken submission when suggestion panel is open. +- Usage Recommendations + - Collaborate with Suggestion to ensure submission only after suggestion panel closes. + - Connect with backend streaming output via onValueChange. +- Key Paths + - [frontend/antdx/sender/sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) + +**Section Source** + +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +#### Suggestion + +- Key Capabilities + - Supports items slot and children slot-based rendering. + - Passes keyboard events and trigger logic through context, supporting custom shouldTrigger. + - Supports getPopupContainer functional configuration. +- Usage Recommendations + - Combine with Sender/Textarea to implement @mentions, /commands, keyword completion. + - Control open state and shouldTrigger to avoid triggering during IME composition. +- Key Paths + - [frontend/antdx/suggestion/suggestion.tsx:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) + +**Section Source** + +- [frontend/antdx/suggestion/suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) + +### Confirmation Components + +#### Think + +- Key Capabilities + - Displays loading state, icon, and title during reasoning, enhancing perceptibility. + - Supports slot-based override of default rendering. +- Usage Recommendations + - Insert before streaming output to clearly inform users that the model is thinking. +- Key Paths + - [frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +**Section Source** + +- [frontend/antdx/think/think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +#### ThoughtChain + +- Key Capabilities + - Supports multi-step reasoning process display, with built-in default and sub-item rendering logic. + - Provides item collection through context, supporting slot-based and default item fallback. + - Reuses common rendering utilities to maintain consistency with other components. +- Usage Recommendations + - Display step-by-step thinking process in complex reasoning scenarios. + - Combine with Bubble component to form a complete reasoning display chain. +- Key Paths + - [frontend/antdx/thought-chain/thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) + +**Section Source** + +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) + +### Feedback Components + +#### Actions + +- Key Capabilities + - Supports dropdown menus, popup rendering, and menu item slot-based configuration. + - Reuses menu context for unified event propagation. +- Usage Recommendations + - Provide "copy, download, feedback" operations on the right side of Bubble or content card. +- Key Paths + - [frontend/antdx/actions/actions.tsx:17-120](file://frontend/antdx/actions/actions.tsx#L17-L120) + +**Section Source** + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) + +### Advanced Components + +#### FileCard + +- Key Capabilities + - Supports multiple file types (image, file, audio, video) display. + - Supports slot-based configuration for icons, descriptions, masks, loading states. + - Built-in image preview functionality, supporting custom preview container and toolbar. + - Automatically resolves file sources, supporting local files and remote URLs. +- Usage Recommendations + - Display file information after upload completion. + - Combine with file list component to form a complete file management interface. +- Key Paths + - [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) + - [frontend/antdx/file-card/base.tsx:15-41](file://frontend/antdx/file-card/base.tsx#L15-L41) + +**Section Source** + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) + +#### Mermaid Diagram + +- Key Capabilities + - Supports Mermaid syntax diagram rendering, including flowcharts, sequence diagrams, etc. + - Built-in syntax highlighting, supporting light/dark theme switching. + - Supports custom action buttons and header slots. + - Reuses action component context for consistent interaction experience. +- Usage Recommendations + - Use in document generation or process display scenarios. + - Combine with thought chain component to display complex algorithm flows. +- Key Paths + - [frontend/antdx/mermaid/mermaid.tsx:33-82](file://frontend/antdx/mermaid/mermaid.tsx#L33-L82) + +**Section Source** + +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) + +#### Folder + +- Key Capabilities + - Supports file system browsing and directory structure display. + - Supports custom directory icon mapping and node rendering. + - Built-in file content service, supporting dynamic loading of file content. + - Supports empty state rendering, preview rendering, and title slot-based configuration. +- Usage Recommendations + - Use in knowledge base or project file management scenarios. + - Combine with file card component to provide complete file browsing experience. +- Key Paths + - [frontend/antdx/folder/folder.tsx:16-121](file://frontend/antdx/folder/folder.tsx#L16-L121) + +**Section Source** + +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) + +### Other Utility Components + +#### Notification + +- Key Capabilities + - Lightweight notification based on browser notification permission, supporting visibility control and permission callbacks. +- Usage Recommendations + - Push desktop notifications when background tasks complete or important events occur. +- Key Paths + - [frontend/antdx/notification/notification.tsx:6-50](file://frontend/antdx/notification/notification.tsx#L6-L50) + +**Section Source** + +- [frontend/antdx/notification/notification.tsx:1-51](file://frontend/antdx/notification/notification.tsx#L1-L51) + +#### Sources + +- Key Capabilities + - Supports title slot and item collection slot-based rendering. +- Usage Recommendations + - Display reference sources at the end of answers to enhance credibility. +- Key Paths + - [frontend/antdx/sources/sources.tsx:9-41](file://frontend/antdx/sources/sources.tsx#L9-L41) + +**Section Source** + +- [frontend/antdx/sources/sources.tsx:1-42](file://frontend/antdx/sources/sources.tsx#L1-L42) + +## Dependency Analysis + +- Backend Export Layer + - Unifies Ant Design X component exports through **init**.py and components.py, including newly added file cards, Mermaid, folders, and other components. +- Frontend Wrapper Layer + - All components use sveltify wrapping, uniformly handling slots, function wrapping, and event propagation. + - Extensively uses renderItems, renderParamsSlot, useFunction, and other utilities to ensure rendering consistency and flexibility. + - Most components reuse menu and item collection contexts to reduce duplicate configuration costs. + - Newly added components introduce file service resolution and theme switching mechanisms. + +```mermaid +graph LR +P["Python Export
__init__.py / components.py
New Component Exports"] --> Q["Svelte/React Wrapper
sveltify + New Components"] +Q --> R["Utilities and Rendering
renderItems / renderParamsSlot / useFunction"] +Q --> S["Context Providers
menu/items/context + New Contexts"] +Q --> T["@ant-design/x Native Components"] +Q --> U["File Service
getFetchableUrl / resolveFileSrc"] +Q --> V["Theme System
themeMode / highlightProps"] +``` + +**Diagram Source** + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) + +**Section Source** + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## Performance and Usability Recommendations + +- Rendering Optimization + - Use useMemo to wrap complex calculation results (such as menu items, suggestion items, tree data, file lists) to reduce unnecessary re-rendering. + - Reasonably split slot rendering to avoid repeated slot mounting when parent level changes frequently. + - Use virtual scrolling for large file lists to improve rendering performance. +- Events and State + - Intercept submission during suggestion panel open to avoid mistaken triggering. + - Disable interaction or show progress during upload to prevent duplicate uploads. + - File card component supports lazy loading to avoid rendering too many images at once. +- Accessibility + - Provide alternative text for icons and buttons to ensure screen reader friendliness. + - Provide keyboard accessibility and focus management for notifications and prompts. + - Mermaid diagrams provide accessibility labels for screen reader narration. +- Data Consistency + - Uniformly update file list after successful upload to avoid state drift. + - In streaming output scenarios, maintain clear transitions between "thinking state - content state - action state". + - File service uses caching mechanism to avoid repeated loading of the same file. +- Theme Adaptation + - Mermaid component automatically adapts to theme mode to ensure diagram readability. + - File card supports dark mode to enhance visual experience. + +## Troubleshooting Guide + +- Slots Not Working + - Check if slots object and corresponding key names are passed correctly. + - Confirm if slot rendering function is correctly wrapped as executable function. +- Upload Failed or Stuck + - Verify beforeUpload/customRequest/isImageUrl function return values and exception handling. + - Check maxCount and current file list length to avoid exceeding limits. +- Suggestion Panel Not Appearing + - Confirm shouldTrigger trigger conditions and input focus state. + - Check open state and whether getPopupContainer container exists. +- Notification Not Showing + - Confirm browser notification permission is granted, request permission flow if necessary. +- Menu Event Abnormal + - Check if onClick is correctly stopped from bubbling to avoid affecting outer interactions. +- File Card Display Abnormal + - Check if file source resolution is correct, confirm getFetchableUrl function works properly. + - Confirm file type and icon mapping match. +- Mermaid Diagram Rendering Failed + - Check if Mermaid syntax is correct, confirm chart type support. + - Confirm theme mode configuration is correct. +- Folder Component Not Responding + - Check if file content service is correctly implemented, confirm async loading function works properly. + - Confirm directory icon mapping and node data format are correct. + +**Section Source** + +- [frontend/antdx/attachments/attachments.tsx:275-354](file://frontend/antdx/attachments/attachments.tsx#L275-L354) +- [frontend/antdx/sender/sender.tsx:126-130](file://frontend/antdx/sender/sender.tsx#L126-L130) +- [frontend/antdx/suggestion/suggestion.tsx:135-140](file://frontend/antdx/suggestion/suggestion.tsx#L135-L140) +- [frontend/antdx/notification/notification.tsx:20-46](file://frontend/antdx/notification/notification.tsx#L20-L46) +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/mermaid/mermaid.tsx:33-82](file://frontend/antdx/mermaid/mermaid.tsx#L33-L82) +- [frontend/antdx/folder/folder.tsx:16-121](file://frontend/antdx/folder/folder.tsx#L16-L121) + +## Conclusion + +The Ant Design X component library provides a complete closed loop from "input-generate-feedback-confirm-display" for AI applications in ModelScope Studio. Through unified slot-based and function wrapping mechanisms, components maintain strong consistency with @ant-design/x while enhancing customizability and maintainability in multimodal, conversational, and chart visualization scenarios. The newly added file cards, Mermaid diagrams, folders, and other components further enrich the display capabilities of AI applications. It is recommended to follow the interaction rhythm of "template first, then generate; think first, then display; confirm first, then submit" in actual projects, and continuously optimize performance and accessibility combining with best practices. + +## Appendix + +### Component Collaboration and Integration Example (Conceptual Flow) + +The following is an end-to-end flow diagram of a typical "Q&A + attachments + charts + file management" scenario to help understand the collaboration between newly added components. + +```mermaid +sequenceDiagram +participant U as "User" +participant W as "Welcome" +participant P as "Prompts" +participant S as "Sender" +participant A as "Attachments" +participant B as "Bubble" +participant T as "Think" +participant TC as "ThoughtChain" +participant X as "Actions" +participant So as "Sources" +participant FC as "FileCard" +participant M as "Mermaid Diagram" +U->>W : Open application +W-->>U : Display welcome page +U->>P : Click prompt +P-->>S : Fill input content +U->>A : Upload attachment +A-->>FC : Render file card +U->>S : Submit question +S-->>T : Show thinking state +T-->>TC : Display reasoning process +TC-->>B : Display generated content +B-->>X : Provide actions on right side +B-->>So : Display reference sources +U->>B : View diagram +B-->>M : Render Mermaid diagram +``` + +**Diagram Source** + +- [frontend/antdx/welcome/welcome.tsx:8-41](file://frontend/antdx/welcome/welcome.tsx#L8-L41) +- [frontend/antdx/prompts/prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) +- [frontend/antdx/sender/sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) +- [frontend/antdx/attachments/attachments.tsx:36-410](file://frontend/antdx/attachments/attachments.tsx#L36-L410) +- [frontend/antdx/bubble/bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) +- [frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) +- [frontend/antdx/thought-chain/thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [frontend/antdx/actions/actions.tsx:17-120](file://frontend/antdx/actions/actions.tsx#L17-L120) +- [frontend/antdx/sources/sources.tsx:9-41](file://frontend/antdx/sources/sources.tsx#L9-L41) +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/mermaid/mermaid.tsx:33-82](file://frontend/antdx/mermaid/mermaid.tsx#L33-L82) + +### New Component Feature Comparison Table + +| Component Category | Component Name | Main Function | Applicable Scenarios | +| ----------------------- | --------------- | ------------------------------------------------------- | ---------------------------------------------------------- | +| General Components | Bubble | Message content display, avatar, additional information | Conversation interface, message display | +| General Components | Conversations | Historical conversation management, menu operations | Conversation management, history records | +| Wake Components | Welcome | Application guide, initialization interface | First visit, reset interface | +| Wake Components | Prompts | Template prompts, quick start | Guide users, improve efficiency | +| Expression Components | Attachments | File upload management, preview | Multimodal input, file processing | +| Expression Components | Sender | Text input, paste upload | User input, real-time interaction | +| Expression Components | Suggestion | Autocomplete, suggestion panel | Improve input efficiency, smart hints | +| Confirmation Components | Think | Reasoning process indication, loading state | Streaming output, status feedback | +| Confirmation Components | ThoughtChain | Multi-step reasoning display | Complex algorithms, process display | +| Feedback Components | Actions | Action entries, menu rendering | Content operations, quick functions | +| Advanced Components | FileCard | File information display, preview | File management, content display | +| Advanced Components | Mermaid Diagram | Flowchart, sequence diagram rendering | Document generation, algorithm display | +| Advanced Components | Folder | File system browsing, content service | Knowledge base, project management | +| Tool Components | XProvider | Global configuration, theme/language provider | Application root node, global configuration | +| Tool Components | CodeHighlighter | Code highlighting, theme customization | Code display, document generation | +| Data Components | Sources | Data source list display, title slot | Reference source display, knowledge retrieval augmentation | +| Data Components | Think | Thinking state display, slot-based | AI thinking process visualization | + +**Section Source** + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) diff --git a/.wiki/en/Ant Design X Components/Components Overview.md b/.wiki/en/Ant Design X Components/Components Overview.md new file mode 100644 index 00000000..989c5f00 --- /dev/null +++ b/.wiki/en/Ant Design X Components/Components Overview.md @@ -0,0 +1,368 @@ +# Components Overview + + +**Files referenced in this document** +- [README-zh_CN.md](file://README-zh_CN.md) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/pro/__init__.py](file://backend/modelscope_studio/components/pro/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [frontend/antdx/package.json](file://frontend/antdx/package.json) +- [frontend/base/package.json](file://frontend/base/package.json) +- [frontend/pro/package.json](file://frontend/pro/package.json) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [frontend/pro/chatbot/chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +Ant Design X component library is an enhanced UI component system designed for machine learning and large model application scenarios, built on Gradio. It provides more flexible layout capabilities, richer interaction patterns, and specialized components for AI scenarios such as conversations, visualization, and multimodal input. Its core goal is to significantly improve the user experience and development efficiency of AI applications while maintaining ease of use. + +- Design Philosophy + - Centered on "composable, extensible, customizable", covering full-stack capabilities from basic controls to professional scenario components. + - Deeply optimized for AI application interaction paradigms (such as conversation bubbles, thought chains, prompt engineering, file cards, mind maps, etc.). + - Seamlessly integrates with Ant Design and Ant Design X ecosystems, reusing mature design languages and interaction specifications. + +- Value Proposition + - Improves professionalism and consistency of AI application interfaces, reducing costs from prototype to production. + - Directly addresses typical business pain points through specialized components (such as chat bubbles, thought chains, code highlighting, Mermaid diagrams, etc.). + - Compatible with Gradio ecosystem, can be used independently or mixed with traditional components. + +**Section Source** + +- [README-zh_CN.md:17-32](file://README-zh_CN.md#L17-L32) + +## Project Structure + +The project adopts a multi-package organization with frontend-backend separation. The backend Python packages handle component export and ecosystem bridging, while the frontend uses Svelte/React hybrid approach to wrap Ant Design/Ant Design X components and adapts them to Gradio-usable components through the unified sveltify tool. + +```mermaid +graph TB +subgraph "Backend Python Packages" +A_init["components/__init__.py"] +A_antd["antd/__init__.py"] +A_antdx["antdx/__init__.py"] +A_pro["pro/__init__.py"] +A_base["base/__init__.py"] +end +subgraph "Frontend NPM Packages" +F_antd["@modelscope-studio/antd
version: 2.0.0"] +F_antdx["@modelscope-studio/antdx
version: 2.0.0"] +F_pro["@modelscope-studio/pro
version: 2.0.0"] +F_base["@modelscope-studio/base
version: 2.0.0"] +end +A_init --> A_antd +A_init --> A_antdx +A_init --> A_pro +A_init --> A_base +A_antd --> F_antd +A_antdx --> F_antdx +A_pro --> F_pro +A_base --> F_base +``` + +**Diagram Source** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) +- [frontend/base/package.json:1-6](file://frontend/base/package.json#L1-L6) + +**Section Source** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) +- [frontend/base/package.json:1-6](file://frontend/base/package.json#L1-L6) + +## Core Components + +- Base Layer (Base) + - Provides basic capabilities such as common containers, text, slots, loops, filtering, etc., supporting complex layouts and conditional rendering. + - Typical components: Application, AutoLoading, Div, Each, Filter, Fragment, Markdown, Slot, Span, Text. + +- Ant Design (Antd) + - Covers the complete Ant Design component family, including buttons, forms, layouts, navigation, feedback, display, editors, etc. + - Supports nested sub-components (such as Button.Group, Form.Item, Tree.TreeNode, etc.) for building complex forms and tree structures. + +- Ant Design X (AntdX) + - Advanced components specifically designed for AI scenarios, such as conversation bubbles, thought chains, prompts, file cards, Mermaid diagrams, etc. + - Emphasizes content editability, renderability, and interactivity, suitable for dynamic content presentation and editing in LLM applications. + +- Pro (Pro) + - Integrated component collection for professional scenarios, such as Chatbot, Monaco Editor, Multimodal Input, Web Sandbox. + - Integrates multiple sub-components with contexts to provide out-of-the-box AI application scaffolds. + +**Section Source** + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) + +## Architecture Overview + +The overall architecture consists of three parts: "backend component export + frontend adaptation layer + ecosystem integration". The backend aggregates and exports sub-modules through Python packages; the frontend wraps native components using Svelte/React hybrid approach and bridges React components to Svelte/Gradio environment through sveltify; meanwhile providing utility functions and contexts for advanced capabilities like slots, render functions, and event callbacks. + +```mermaid +graph TB +subgraph "Backend" +Py_API["Python Export API
components/__init__.py"] +Py_antd["Antd Component Export"] +Py_antdx["AntdX Component Export"] +Py_pro["Pro Component Export"] +Py_base["Base Component Export"] +end +subgraph "Frontend" +FE_antd["antd/button.tsx
sveltify adaptation"] +FE_antdx["antdx/bubble/bubble.tsx
slots/render functions"] +FE_pro["pro/chatbot/chatbot.tsx
context+state management"] +end +subgraph "Ecosystem" +AD["Ant Design"] +ADX["Ant Design X"] +GR["Gradio"] +end +Py_API --> Py_antd +Py_API --> Py_antdx +Py_API --> Py_pro +Py_API --> Py_base +Py_antd --> FE_antd +Py_antdx --> FE_antdx +Py_pro --> FE_pro +FE_antd --> AD +FE_antdx --> ADX +FE_pro --> ADX +FE_antd --> GR +FE_antdx --> GR +FE_pro --> GR +``` + +**Diagram Source** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) + +## Detailed Component Analysis + +### Antd Button Component (Basic Control) + +- Design Points + - Uses sveltify to adapt Ant Design's Button to Svelte/Gradio component. + - Supports slots (such as icon, loading.icon) and value binding, automatically handling priority between children and controlled value. + - Compatible handling of loading's delay configuration to ensure combination with slots. + +```mermaid +flowchart TD +Start(["Enter Button Rendering"]) --> ParseSlots["Parse Slots and Props"] +ParseSlots --> HasIcon{"Has icon slot?"} +HasIcon --> |Yes| RenderIcon["Use ReactSlot to render icon slot"] +HasIcon --> |No| UsePropIcon["Use prop icon"] +RenderIcon --> HasLoadingIcon{"Has loading.icon slot?"} +UsePropIcon --> HasLoadingIcon +HasLoadingIcon --> |Yes| RenderLoadingIcon["Use ReactSlot to render loading.icon slot
and preserve delay config"] +HasLoadingIcon --> |No| UsePropLoading["Use prop loading"] +RenderLoadingIcon --> RenderButton["Render Ant Design Button"] +UsePropLoading --> RenderButton +RenderButton --> End(["Complete"]) +``` + +**Diagram Source** + +- [frontend/antd/button/button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) + +**Section Source** + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) + +### AntdX Bubble Component (AI Scenario) + +- Design Points + - Based on Ant Design X's Bubble, provides multi-slots for avatar, content, footer, extra area, loading render, content render, etc. + - Supports editable okText/cancelText slots and boolean switches, typing, header/footer/avatar/extra functional configurations. + - Converts slots to executable functions through useFunction and renderParamsSlot, enhancing programmability. + +```mermaid +sequenceDiagram +participant C as "Caller" +participant B as "Bubble Component" +participant R as "ReactSlot/renderParamsSlot" +participant F as "useFunction" +C->>B : Pass props and slots +B->>F : Parse header/footer/avatar/extra/typing/editable +F-->>B : Return executable function or default value +B->>R : If content/header/footer/avatar/loadingRender/contentRender slots exist +R-->>B : Render slot content +B-->>C : Render final Bubble +``` + +**Diagram Source** + +- [frontend/antdx/bubble/bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) + +**Section Source** + +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) + +### Pro Chatbot Component (Conversation Scenario) + +- Design Points + - Based on Ant Design X's Bubble.List, combines custom context and hooks to implement scrolling, editing, copying, liking, retrying, welcome message, etc. + - Maps different roles (user, assistant, internal welcome) to corresponding bubble styles and behaviors through useRole. + - Built-in Markdown rendering, theme mode, root path passing, and other configurations to meet multimodal content display needs. + +```mermaid +sequenceDiagram +participant U as "User" +participant CB as "Chatbot" +participant BL as "Bubble.List" +participant CTX as "Role Context" +participant H as "hooks(scroll/edit)" +U->>CB : Input message/operation +CB->>CTX : Parse message role and configuration +CTX-->>CB : Return corresponding bubble configuration +CB->>H : Trigger scroll/edit state update +H-->>CB : Update state +CB->>BL : Render message list +BL-->>U : Display conversation bubbles +``` + +**Diagram Source** + +- [frontend/pro/chatbot/chatbot.tsx:76-472](file://frontend/pro/chatbot/chatbot.tsx#L76-L472) + +**Section Source** + +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) + +## Dependency Analysis + +- Version and Namespace + - All frontend packages use unified version number (2.0.0), namespace is @modelscope-studio, convenient for publishing and management. +- Component Export and Grouping + - Backend exports by functional domains: antd, antdx, pro, base, corresponding to Ant Design component family, AI specialized components, professional scenario components, and basic capabilities. +- Frontend-Backend Mapping + - Each backend export module corresponds to a frontend package, forming stable mapping relationships, ensuring component names and ecosystem consistency. + +```mermaid +graph LR +Py_antd["Backend antd Export"] --> FE_antd["Frontend @modelscope-studio/antd"] +Py_antdx["Backend antdx Export"] --> FE_antdx["Frontend @modelscope-studio/antdx"] +Py_pro["Backend pro Export"] --> FE_pro["Frontend @modelscope-studio/pro"] +Py_base["Backend base Export"] --> FE_base["Frontend @modelscope-studio/base"] +``` + +**Diagram Source** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) +- [frontend/base/package.json:1-6](file://frontend/base/package.json#L1-L6) + +**Section Source** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) + +## Performance Considerations + +- Rendering and Slots + - Avoid unnecessary re-rendering through combination of slots and render functions; only perform parameterized rendering when slots exist. +- State and Computation + - Use useMemo and useMemoizedFn to cache configurations and callbacks, reducing invalid re-renders and object creation. +- Scrolling and Interaction + - Use local state and throttling strategies for high-frequency interactions like scrolling, editing, liking, ensuring smooth experience. + +[This section is general guidance, no specific file references required] + +## Troubleshooting Guide + +- Page Not Displaying Correctly (Hugging Face Space) + - Add ssr_mode=False parameter in demo.launch() to avoid display issues caused by server-side rendering. +- Component Import Failed + - Confirm modelscope_studio is installed and correctly import modelscope_studio.components.\* namespace. +- Version Mismatch + - Check if backend and frontend package versions are consistent to avoid runtime errors due to version differences. + +**Section Source** + +- [README-zh_CN.md:32-32](file://README-zh_CN.md#L32-L32) +- [README-zh_CN.md:38-42](file://README-zh_CN.md#L38-L42) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) + +## Conclusion + +Ant Design X component library systematically improves the interface expressiveness and interaction efficiency of machine learning and large model applications through a three-layer architecture of "basic controls + AI specialized components + professional scenario components". With Gradio as the entry point, Ant Design/Ant Design X as the foundation, and frontend adaptation layer as the bridge, it forms a stable, scalable, and maintainable component system. Developers can use this library to quickly build high-quality AI application interfaces and gain consistent and professional user experience in conversation, visualization, multimodal input, and other scenarios. + +[This section is summary content, no specific file references required] + +## Appendix + +### Quick Start + +- Installation + - Use pip to install modelscope_studio. +- Example + - Import Application, ConfigProvider, AutoLoading from modelscope_studio in Blocks, and use antd components for layout and interaction. + +**Section Source** + +- [README-zh_CN.md:38-57](file://README-zh_CN.md#L38-L57) + +### Component Classification and Usage Scenarios + +- Base Layer (Base) + - Scenarios: General layout, conditional rendering, text and slot management. + - Typical: Application, AutoLoading, Markdown, Slot, Text, Span, Div, Each, Filter, Fragment. +- Ant Design (Antd) + - Scenarios: Forms, navigation, feedback, display, layout, and other general UI. + - Typical: Button, Form, Layout, Menu, Modal, Table, Tabs, Tree, Upload, etc. +- Ant Design X (AntdX) + - Scenarios: Conversation bubbles, thought chains, prompts, file cards, Mermaid diagrams, and other AI-specific interactions. + - Typical: Bubble, Conversations, Sender, ThoughtChain, Prompts, Attachments, Mermaid, Notification, Welcome, XProvider. +- Pro (Pro) + - Scenarios: Integrated AI application scaffolds, such as chatbots, code editors, multimodal input, Web sandbox. + - Typical: Chatbot, MonacoEditor, MultimodalInput, WebSandbox. + +**Section Source** + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) diff --git a/.wiki/en/Ant Design X Components/Confirmation Components/Confirmation Components.md b/.wiki/en/Ant Design X Components/Confirmation Components/Confirmation Components.md new file mode 100644 index 00000000..46576d36 --- /dev/null +++ b/.wiki/en/Ant Design X Components/Confirmation Components/Confirmation Components.md @@ -0,0 +1,408 @@ +# Confirmation Components + + +**Files Referenced in This Document** +- [AntdXThoughtChain/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py) +- [AntdXThoughtChainItem/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py) +- [AntdXThoughtChainThoughtChainItem/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py) +- [thought-chain.tsx](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [context.ts](file://frontend/antdx/thought-chain/context.ts) +- [basic.py](file://docs/components/antdx/thought_chain/demos/basic.py) +- [item_status.py](file://docs/components/antdx/thought_chain/demos/item_status.py) +- [nested_use.py](file://docs/components/antdx/thought_chain/demos/nested_use.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document provides systematic technical documentation for the Ant Design X Confirmation Components (ThoughtChain), covering the following aspects: + +- Thought chain construction and state management: How to configure states, collapsible behavior, and nested structures through node item configuration +- Visual presentation: How to combine node content, icons, titles, descriptions, extra action areas, and footers +- Configuration options and events: Supported properties, slots, and event callbacks +- Style and class name customization: How to control appearance via prefix class names, style objects, and root class names +- Usage examples: From basic usage to state switching, nested usage, and user interaction +- Value statement: The significance of this component in improving AI transparency and trustworthiness + +## Project Structure + +The Ant Design X ThoughtChain component is composed of a backend Python component and a frontend React/Svelte wrapper layer, with documentation examples located in the docs directory. + +```mermaid +graph TB +subgraph "Backend Components" +A["AntdXThoughtChain
Thought Chain Container"] +B["AntdXThoughtChainItem
Node Item (Simplified)"] +C["AntdXThoughtChainThoughtChainItem
Node Item (Full)"] +end +subgraph "Frontend Wrapper Layer" +D["thought-chain.tsx
React Wrapper + Slot Resolution"] +E["context.ts
items Context"] +end +subgraph "Documentation Examples" +F["basic.py
Basic Usage"] +G["item_status.py
State Switching Demo"] +H["nested_use.py
Nested Usage"] +end +A --> D +B --> D +C --> D +D --> E +F --> A +G --> A +H --> A +``` + +**Diagram Sources** + +- [AntdXThoughtChain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [AntdXThoughtChainItem/**init**.py:8-78](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L8-L78) +- [AntdXThoughtChainThoughtChainItem/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L8-L81) +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [context.ts:1-7](file://frontend/antdx/thought-chain/context.ts#L1-L7) +- [basic.py:24-77](file://docs/components/antdx/thought_chain/demos/basic.py#L24-L77) +- [item_status.py:36-71](file://docs/components/antdx/thought_chain/demos/item_status.py#L36-L71) +- [nested_use.py:6-68](file://docs/components/antdx/thought_chain/demos/nested_use.py#L6-L68) + +**Section Sources** + +- [AntdXThoughtChain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) + +## Core Components + +- Container Component: AntdXThoughtChain + - Responsibility: Acts as the root container of the thought chain, responsible for receiving node lists, expanded keys, line styles, prefix class names, and other configurations; notifies expanded state changes via event binding + - Key Capabilities: Supports items slot; expand event; configurable default expanded keys and current expanded keys +- Node Item Component (Simplified): AntdXThoughtChainItem + - Responsibility: Carries the basic information and appearance of a single node, supporting title, description, icon, status, variant, and blink effect + - Key Capabilities: Supports description, icon, title slots; status enum (pending/success/error/abort) +- Node Item Component (Full): AntdXThoughtChainThoughtChainItem + - Responsibility: Carries richer node content, supporting content, description, footer, icon, title slots, as well as key, collapsible, status, and other properties + - Key Capabilities: Supports collapse/expand, state switching, and extra action areas + +**Section Sources** + +- [AntdXThoughtChain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [AntdXThoughtChainItem/**init**.py:8-78](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L8-L78) +- [AntdXThoughtChainThoughtChainItem/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L8-L81) + +## Architecture Overview + +The frontend wrapper layer maps backend components to React components, uniformly resolves slots, and passes them to @ant-design/x's ThoughtChain implementation, while collecting items slot content via the context mechanism. + +```mermaid +sequenceDiagram +participant Py as "Python Backend Component" +participant Wrap as "React Wrapper thought-chain.tsx" +participant Ctx as "items Context context.ts" +participant X as "@ant-design/x ThoughtChain" +Py->>Wrap : Render ThoughtChain container +Wrap->>Ctx : Read items/default slots +Ctx-->>Wrap : Return items list +Wrap->>X : Pass props and resolved items +X-->>Wrap : Render node tree +Wrap-->>Py : Output final UI +``` + +**Diagram Sources** + +- [thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [context.ts:1-7](file://frontend/antdx/thought-chain/context.ts#L1-L7) + +## Detailed Component Analysis + +### Container Component: AntdXThoughtChain + +- Main Responsibilities + - Receives items list and expanded key configuration, determining the initial expanded state + - Supports the expand event to monitor expanded key changes + - Provides the items slot for declarative node organization +- Key Properties + - expanded_keys / default_expanded_keys: Current expanded keys and default expanded keys + - items: Array of node data + - line: Line style (boolean or line type enum) + - prefix_cls: Prefix class name + - styles / class_names / root_class_name: Style and class name customization +- Events + - expand: Triggered when expanded keys change +- Lifecycle + - preprocess/postprocess/example\_\* all return empty values, indicating this component does not participate in data serialization + +```mermaid +classDiagram +class AntdXThoughtChain { ++expanded_keys ++default_expanded_keys ++items ++line ++prefix_cls ++styles ++class_names ++root_class_name ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +``` + +**Diagram Sources** + +- [AntdXThoughtChain/**init**.py:30-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L30-L86) + +**Section Sources** + +- [AntdXThoughtChain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) + +### Node Item Component (Simplified): AntdXThoughtChainItem + +- Main Responsibilities + - Represents a single thought node's title, description, icon, and status + - Supports multiple appearance variants and blink effects +- Key Properties + - description / icon / title: Node basic information + - status: Node status (pending/success/error/abort) + - variant: Appearance variant (solid/outlined/text) + - blink: Whether to blink + - Slots: description, icon, title +- Lifecycle + - Same as the container component; does not participate in data serialization + +```mermaid +classDiagram +class AntdXThoughtChainItem { ++description ++icon ++title ++status ++variant ++blink ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +``` + +**Diagram Sources** + +- [AntdXThoughtChainItem/**init**.py:18-78](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L18-L78) + +**Section Sources** + +- [AntdXThoughtChainItem/**init**.py:8-78](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L8-L78) + +### Node Item Component (Full): AntdXThoughtChainThoughtChainItem + +- Main Responsibilities + - Carries richer node content, supporting content, footer, extra, and other slots + - Supports key, collapsible, status, and other properties for complex interactions and state management +- Key Properties + - content / description / footer / icon / title: Content and decoration + - key: Node unique identifier + - collapsible: Whether it is collapsible + - status: Node status + - Slots: content, description, footer, icon, title +- Lifecycle + - Same as the container component; does not participate in data serialization + +```mermaid +classDiagram +class AntdXThoughtChainThoughtChainItem { ++content ++description ++extra ++footer ++icon ++title ++status ++key ++collapsible ++blink ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +``` + +**Diagram Sources** + +- [AntdXThoughtChainThoughtChainItem/**init**.py:18-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L18-L81) + +**Section Sources** + +- [AntdXThoughtChainThoughtChainItem/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L8-L81) + +### Frontend Wrapper and Slot Resolution + +- thought-chain.tsx + - Wraps @ant-design/x's ThoughtChain via sveltify + - Uses withItemsContextProvider and useItems to resolve items/default slots + - Converts slot content into props.items via renderItems +- context.ts + - Provides items context, supporting slot collection in nested scenarios + +```mermaid +flowchart TD +Start(["Render Entry"]) --> ReadSlots["Read items/default slots"] +ReadSlots --> Resolve["Call renderItems to resolve nodes"] +Resolve --> RenderX["Render @ant-design/x ThoughtChain"] +RenderX --> End(["Complete"]) +``` + +**Diagram Sources** + +- [thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [context.ts:1-7](file://frontend/antdx/thought-chain/context.ts#L1-L7) + +**Section Sources** + +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [context.ts:1-7](file://frontend/antdx/thought-chain/context.ts#L1-L7) + +### Usage Examples and Scenarios + +#### Basic Usage and Collapsible Behavior + +- Key Points + - Create a ThoughtChain container under XProvider + - Use a Switch to control the collapsible property, dynamically toggling node collapsibility + - Inject extra/content/footer via Slot for rich node content +- Applicable Scenarios + - Display the execution flow and current status of multi-step tasks + - Provide node-level action buttons and supplementary information + +**Section Sources** + +- [basic.py:24-77](file://docs/components/antdx/thought_chain/demos/basic.py#L24-L77) + +#### Node State Switching (Success/Error/In Progress) + +- Key Points + - Use Each to dynamically generate node lists + - Step-by-step update node status and icons via button clicks to simulate real runtime status + - Supports visual feedback for pending/error/success three states +- Applicable Scenarios + - Display stage-by-stage results during AI inference + - Increase user confidence in execution progress and results + +**Section Sources** + +- [item_status.py:36-71](file://docs/components/antdx/thought_chain/demos/item_status.py#L36-L71) + +#### Nested Usage (Sub-Thought Chains) + +- Key Points + - Nest another ThoughtChain inside the node content of a parent ThoughtChain + - Child nodes also support slots like extra/content/footer +- Applicable Scenarios + - Complex tasks broken down into multiple sub-tasks, refined layer by layer + - Display hierarchical decision or reasoning chains + +**Section Sources** + +- [nested_use.py:6-68](file://docs/components/antdx/thought_chain/demos/nested_use.py#L6-L68) + +## Dependency Analysis + +- Component Coupling + - Both the container and node items inherit from ModelScopeLayoutComponent, sharing a unified lifecycle and property system + - The frontend wrapper layer is only responsible for slot resolution and property forwarding, without introducing business logic +- External Dependencies + - @ant-design/x's ThoughtChain provides actual rendering capabilities + - Gradio event system is used for expand event binding +- Potential Risks + - Slot names and order must strictly match; otherwise rendering may fail + - When the items list is empty, ensure fallback to the default slot + +```mermaid +graph LR +Py["Python Component"] --> Wrap["React Wrapper Layer"] +Wrap --> X["@ant-design/x ThoughtChain"] +Wrap --> Ctx["items Context"] +Py --> Gradio["Gradio Event System"] +``` + +**Diagram Sources** + +- [AntdXThoughtChain/**init**.py:20-25](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L20-L25) +- [thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) + +**Section Sources** + +- [AntdXThoughtChain/**init**.py:20-25](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L20-L25) +- [thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) + +## Performance Considerations + +- Render Optimization + - Uses useMemo to cache items computation results, avoiding unnecessary re-renders + - Reduces DOM count via lazy slot loading and conditional rendering +- Data Flow + - The items list should maintain stable references; use the key field to improve diff efficiency +- Interaction Experience + - For scenarios with many nodes, prioritize collapsible and step-by-step loading strategies + +## Troubleshooting Guide + +- Symptom: Nodes not showing or showing as empty + - Check whether items are correctly passed or the default slot is populated + - Confirm slot name casing matches the documentation +- Symptom: expand event not working + - Confirm event binding is enabled (bind_expand_event) + - Check whether the container is in an interactive state +- Symptom: Nested ThoughtChain not working + - Ensure the child ThoughtChain is correctly nested in the content slot of the parent node + - Check whether the child ThoughtChain's slots are correctly declared + +## Conclusion + +The Ant Design X ThoughtChain component, through its layered design of "container + node items" combined with frontend slot resolution and @ant-design/x's rendering capabilities, achieves structured recording and visual presentation of the AI thinking process. Its state-driven node appearance, flexible slot extension, and collapsible interaction can effectively improve users' understanding and trust in complex reasoning processes. With documentation examples, developers can quickly build various application scenarios from basic flows to nested sub-chains. + +## Appendix + +### API Quick Reference + +- Container Component AntdXThoughtChain + - Properties: expanded_keys, default_expanded_keys, items, line, prefix_cls, styles, class_names, root_class_name + - Events: expand + - Slots: items +- Node Item Component (Simplified) AntdXThoughtChainItem + - Properties: description, icon, title, status, variant, blink + - Slots: description, icon, title +- Node Item Component (Full) AntdXThoughtChainThoughtChainItem + - Properties: content, description, extra, footer, icon, title, status, key, collapsible, blink + - Slots: content, description, footer, icon, title + +### Usage Recommendations + +- Transparency and Trustworthiness + - Provide clear status and icon hints to help users understand the execution result of each step + - Offer additional explanations and actionable entry points for key decision nodes to enhance user control +- Accessibility + - Provide readable alternative text for icons and statuses + - Ensure keyboard accessibility and screen reader friendliness diff --git a/.wiki/en/Ant Design X Components/Confirmation Components/ThoughtChain Component.md b/.wiki/en/Ant Design X Components/Confirmation Components/ThoughtChain Component.md new file mode 100644 index 00000000..079ace1b --- /dev/null +++ b/.wiki/en/Ant Design X Components/Confirmation Components/ThoughtChain Component.md @@ -0,0 +1,380 @@ +# ThoughtChain Component + + +**Files Referenced in This Document** +- [backend module exports](file://backend/modelscope_studio/components/antdx/__init__.py) +- [ThoughtChain main component definition](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py) +- [ThoughtChain item component definition](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py) +- [ThoughtChain advanced item component definition](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py) +- [Frontend ThoughtChain implementation](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [Frontend ThoughtChain item implementation](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx) +- [Frontend ThoughtChain advanced item implementation](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx) +- [Frontend ThoughtChain context utility](file://frontend/antdx/thought-chain/context.ts) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) + +## Introduction + +The ThoughtChain component is a powerful visualization tool provided by ModelScope Studio, specifically designed to record and display the AI's thinking process. This component clearly presents complex reasoning paths through a tree structure, helping users understand the logical flow of AI decision-making. + +The core value of this component lies in: + +- **Enhanced Transparency**: Enables users to see the complete thinking process of AI +- **Improved Explainability**: Improves the understandability of AI behavior through step-by-step visual presentation +- **Debugging Support**: Enables developers and users to track and analyze AI decision paths +- **User Experience Optimization**: Provides intuitive visual feedback to enhance human-machine interaction + +## Project Structure + +ModelScope Studio adopts a layered architecture design; the ThoughtChain component is located in the antdx component library and is deeply integrated with the Gradio ecosystem. + +```mermaid +graph TB +subgraph "Backend Python Layer" +A[Antdx Component Exports] --> B[ThoughtChain Main Component] +A --> C[ThoughtChain Item Component] +A --> D[ThoughtChain Advanced Item Component] +end +subgraph "Frontend React Layer" +E[ThoughtChain Frontend Implementation] +F[ThoughtChain Item Frontend Implementation] +G[ThoughtChain Advanced Item Frontend Implementation] +H[Context Utility] +end +subgraph "Third-party Libraries" +I[@ant-design/x] +J[Gradio Ecosystem] +end +B --> E +C --> F +D --> G +E --> I +F --> I +G --> I +H --> E +H --> G +E --> J +F --> J +G --> J +``` + +**Diagram Sources** + +- [backend module exports:35-41](file://backend/modelscope_studio/components/antdx/__init__.py#L35-L41) +- [ThoughtChain main component definition:12-18](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L18) +- [ThoughtChain item component definition:8-11](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L8-L11) +- [ThoughtChain advanced item component definition:8-11](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L8-L11) + +**Section Sources** + +- [backend module exports:35-41](file://backend/modelscope_studio/components/antdx/__init__.py#L35-L41) +- [ThoughtChain main component definition:12-18](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L18) + +## Core Components + +### ThoughtChain Main Component + +The main component is responsible for overall layout and state management, supporting multiple configuration options: + +**Core Configuration Options:** + +- `expanded_keys`: List of node key values to expand by default +- `default_expanded_keys`: Initial default expanded node key values +- `items`: Array of thinking step data +- `line`: Connector line style (solid, dashed, dotted) +- `prefix_cls`: Custom prefix class name +- `styles`: Inline style object or string +- `class_names`: Class name mapping object + +**Event Handling:** + +- `expand`: Callback function for when expand/collapse key values change + +### ThoughtChainItem Sub-item Component + +Used to represent a single thinking step, supporting rich customization options: + +**Core Properties:** + +- `description`: Step description text +- `icon`: Custom icon name +- `title`: Step title +- `status`: Status value (pending, success, error, abort) +- `variant`: Appearance variant (solid, outlined, text) +- `blink`: Whether to enable blink effect + +**Slot Support:** + +- `description`: Custom description content +- `icon`: Custom icon content +- `title`: Custom title content + +### ThoughtChainThoughtChainItem Advanced Sub-item Component + +Provides more complex functionality, supporting nested structures: + +**Extended Properties:** + +- `content`: Main content text +- `extra`: Extra information +- `footer`: Footer content +- `collapsible`: Whether it is collapsible +- `key`: Unique key identifier + +**Advanced Slots:** + +- `content`: Main content area +- `description`: Description content +- `footer`: Footer content +- `icon`: Icon content +- `title`: Title content + +**Section Sources** + +- [ThoughtChain main component definition:30-67](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L30-L67) +- [ThoughtChain item component definition:18-58](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L18-L58) +- [ThoughtChain advanced item component definition:18-59](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L18-L59) + +## Architecture Overview + +The ThoughtChain component adopts a frontend-backend separation architecture design, achieving seamless integration through the Gradio ecosystem. + +```mermaid +sequenceDiagram +participant User as User Interface +participant Backend as Backend Component +participant Frontend as Frontend Implementation +participant AntDX as Ant Design X +participant Context as Context Management +User->>Backend : Create ThoughtChain component +Backend->>Frontend : Resolve frontend directory +Frontend->>Context : Initialize context +Context->>AntDX : Load core components +User->>Backend : Set configuration parameters +Backend->>Frontend : Pass component properties +Frontend->>AntDX : Render thought chain +AntDX->>User : Display visualization result +Note over User,AntDX : Supports dynamic updates and interaction +``` + +**Diagram Sources** + +- [ThoughtChain main component definition:68-68](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L68-L68) +- [Frontend ThoughtChain implementation:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [Frontend ThoughtChain context utility:1-4](file://frontend/antdx/thought-chain/context.ts#L1-L4) + +## Detailed Component Analysis + +### Data Flow Processing + +```mermaid +flowchart TD +Start([Component Initialization]) --> ParseProps["Parse component properties"] +ParseProps --> InitContext["Initialize context"] +InitContext --> LoadItems["Load thinking step data"] +LoadItems --> RenderChain["Render thought chain"] +RenderChain --> HandleEvents["Handle user interactions"] +HandleEvents --> UpdateState["Update component state"] +UpdateState --> ReRender["Re-render"] +ReRender --> End([Complete]) +LoadItems --> CheckSlots{"Check slot content"} +CheckSlots --> |Has Slots| ProcessSlots["Process slot content"] +CheckSlots --> |No Slots| UseProps["Use property values"] +ProcessSlots --> RenderChain +UseProps --> RenderChain +``` + +**Diagram Sources** + +- [Frontend ThoughtChain implementation:14-35](file://frontend/antdx/thought-chain/thought-chain.tsx#L14-L35) +- [Frontend ThoughtChain item implementation:12-27](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L12-L27) + +### State Management System + +The component supports four core states, each with specific visual representations: + +```mermaid +stateDiagram-v2 +[*] --> NotStarted +NotStarted --> InProgress : Start execution +InProgress --> Completed : Execution successful +InProgress --> Failed : Execution error +InProgress --> Aborted : User interrupt +Completed --> [*] +Failed --> [*] +Aborted --> [*] +note right of NotStarted : Display waiting state +note right of InProgress : Display loading animation +note right of Completed : Display success icon +note right of Failed : Display error state +note right of Aborted : Display abort prompt +``` + +**Diagram Sources** + +- [ThoughtChain item component definition:24-25](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L24-L25) +- [ThoughtChain advanced item component definition:29-30](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L29-L30) + +### Slot System Architecture + +```mermaid +classDiagram +class ThoughtChainItem { ++description : string ++icon : string ++title : string ++status : Status ++variant : Variant ++blink : boolean ++slots : Description|Icon|Title +} +class ThoughtChainThoughtChainItem { ++content : string ++extra : string ++footer : string ++collapsible : boolean ++key : string ++slots : Content|Description|Footer|Icon|Title +} +class SlotProcessor { ++processDescription() : ReactNode ++processIcon() : ReactNode ++processTitle() : ReactNode ++renderSlots() : JSX.Element +} +ThoughtChainItem --> SlotProcessor : uses +ThoughtChainThoughtChainItem --> SlotProcessor : uses +SlotProcessor --> ReactSlot : processes slots +``` + +**Diagram Sources** + +- [ThoughtChain item component definition:15-16](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L15-L16) +- [ThoughtChain advanced item component definition:15-16](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L15-L16) +- [Frontend ThoughtChain item implementation:18-26](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L18-L26) + +**Section Sources** + +- [Frontend ThoughtChain implementation:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [Frontend ThoughtChain item implementation:9-30](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L9-L30) +- [Frontend ThoughtChain advanced item implementation:7-11](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L7-L11) + +## Dependency Analysis + +### Component Dependency Diagram + +```mermaid +graph TB +subgraph "Core Dependencies" +A[@ant-design/x] --> B[ThoughtChain Core] +A --> C[ThoughtChain.Item] +A --> D[ThoughtChain.ThoughtChainItem] +end +subgraph "Utility Dependencies" +E[@svelte-preprocess-react] --> F[sveltify Conversion] +E --> G[ReactSlot Processing] +H[@utils/renderItems] --> I[Item Rendering] +J[@utils/createItemsContext] --> K[Context Management] +end +subgraph "Gradio Integration" +L[Gradio Event System] --> M[EventListener] +N[Gradio Component System] --> O[ModelScopeLayoutComponent] +end +B --> E +C --> E +D --> E +B --> L +C --> N +D --> N +E --> H +E --> J +``` + +**Diagram Sources** + +- [Frontend ThoughtChain implementation:1-7](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L7) +- [Frontend ThoughtChain item implementation:1-7](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L1-L7) +- [Frontend ThoughtChain advanced item implementation:1-3](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L1-L3) +- [ThoughtChain main component definition:5-8](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L5-L8) + +### Version Compatibility + +The component design follows these compatibility principles: + +- Supports the latest version features of Gradio +- Compatible with TypeScript 4.0+ type system +- Adapts to React 17+ and Svelte 3+ ecosystems +- Backward compatible with Ant Design X 0.x versions + +**Section Sources** + +- [ThoughtChain main component definition:1-8](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L1-L8) +- [Frontend ThoughtChain implementation:1-7](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L7) + +## Performance Considerations + +### Rendering Optimization Strategies + +1. **Lazy Loading Mechanism**: Use `sveltify` for on-demand loading +2. **Memory Management**: Use `useMemo` appropriately to cache computation results +3. **Event Handling**: Optimize event binding via `EventListener` +4. **Slot Rendering**: Delay rendering slot content to reduce initial load + +### Best Practice Recommendations + +- **Data Preprocessing**: Format data before passing it to the component +- **State Minimization**: Avoid frequent state updates that trigger unnecessary re-renders +- **Resource Management**: Clean up unused component instances in a timely manner +- **Error Boundaries**: Use Gradio's error boundary mechanism to handle exceptions + +## Troubleshooting Guide + +### Common Issues and Solutions + +**Issue 1: Component Not Displaying** + +- Check the `visible` property setting +- Confirm the `render` property is `true` +- Verify the CSS styles of the parent container + +**Issue 2: Status Display Anomalies** + +- Confirm the status value is within the allowed range +- Check whether the `blink` property is correctly configured +- Verify the correctness of style class names + +**Issue 3: Slot Content Not Taking Effect** + +- Confirm the slot name is spelled correctly +- Check the type matching of slot content +- Verify the rendering timing of the slot + +**Section Sources** + +- [ThoughtChain main component definition:74-85](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L74-L85) +- [Frontend ThoughtChain item implementation:12-27](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L12-L27) + +## Conclusion + +The ThoughtChain component provides powerful visualization capabilities for displaying the AI thinking process in AI applications. Through its carefully designed architecture and rich configuration options, this component not only improves AI transparency and trustworthiness but also provides users with an intuitive interactive experience. + +**Summary of Core Advantages:** + +- **Complete Thought Process Visualization**: Multi-level presentation from simple to complex +- **Flexible Configuration Options**: Meets usage needs in different scenarios +- **Good Performance**: Optimized rendering mechanism ensures a smooth experience +- **Comprehensive Error Handling**: Robust exception handling mechanism ensures stability +- **Excellent Extensibility**: Modular architecture facilitates feature extension and customization + +This component is particularly suitable for application scenarios that need to display AI decision-making processes, such as intelligent customer service, data analysis, and content creation, and can significantly improve user understanding and trust in AI behavior. diff --git a/.wiki/en/Ant Design X Components/Confirmation Components/ThoughtChainItem Component.md b/.wiki/en/Ant Design X Components/Confirmation Components/ThoughtChainItem Component.md new file mode 100644 index 00000000..793a9e4a --- /dev/null +++ b/.wiki/en/Ant Design X Components/Confirmation Components/ThoughtChainItem Component.md @@ -0,0 +1,410 @@ +# ThoughtChainItem Component + + +**Files Referenced in This Document** +- [thought-chain.tsx](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [thought-chain.thought-chain-item.tsx](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx) +- [thought-chain.item.tsx](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx) +- [context.ts](file://frontend/antdx/thought-chain/context.ts) +- [createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [thought-chain.Index.svelte](file://frontend/antdx/thought-chain/Index.svelte) +- [thought-chain.thought-chain-item.Index.svelte](file://frontend/antdx/thought-chain/thought-chain-item/Index.svelte) +- [thought-chain.item.Index.svelte](file://frontend/antdx/thought-chain/item/Index.svelte) +- [thought_chain_item/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py) +- [thought_chain/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) + +## Introduction + +ThoughtChainItem is the core sub-component of the ThoughtChain component system in ModelScope Studio, used to represent and manage individual thinking steps in complex thought flows. This component provides complete state management, event handling, and visual presentation capabilities, supporting the visualization of multiple states (pending, in progress, completed, failed, etc.). + +This component is based on Ant Design X's ThoughtChain implementation and achieves flexible inter-component communication and state synchronization through a custom Items Context system. The component supports a slot mechanism, allowing developers to customize content areas such as titles, descriptions, and icons. + +## Project Structure + +The ThoughtChainItem component system adopts a layered architecture design, consisting of three parts: frontend React components, Svelte wrappers, and backend Python components: + +```mermaid +graph TB +subgraph "Frontend Architecture" +A[ThoughtChain Main Container] --> B[ThoughtChainItem Sub-item] +B --> C[React Component Layer] +C --> D[Svelte Wrapper Layer] +end +subgraph "Backend Architecture" +E[Python Component Layer] --> F[Frontend Directory Mapping] +F --> G[Static Resource Generation] +end +subgraph "State Management" +H[Items Context] --> I[ItemHandler] +I --> J[State Synchronization] +end +A --> H +B --> I +``` + +**Diagram Sources** + +- [thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [thought-chain.thought-chain-item.tsx:7-11](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L7-L11) +- [context.ts:1-6](file://frontend/antdx/thought-chain/context.ts#L1-L6) + +**Section Sources** + +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [thought-chain.thought-chain-item.tsx:1-14](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L1-L14) +- [thought-chain.item.tsx:1-33](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L1-L33) + +## Core Components + +### ThoughtChain Main Container + +The ThoughtChain component is the root container of the entire thought chain system, responsible for coordinating the rendering and state management of all sub-items: + +```mermaid +classDiagram +class ThoughtChain { ++items : Array ++children : ReactNode ++useMemo() items ++withItemsContextProvider() wrapper ++renderItems() processor +} +class ItemsContext { ++items : Object ++setItem() method ++initial : boolean ++onChange() callback +} +class ItemHandler { ++itemIndex : number ++itemSlotKey : string ++itemProps : function ++itemChildren : function ++slots : Object ++children : ReactNode +} +ThoughtChain --> ItemsContext : "uses" +ItemsContext --> ItemHandler : "provides" +ItemHandler --> ThoughtChain : "updates" +``` + +**Diagram Sources** + +- [thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [context.ts:3-4](file://frontend/antdx/thought-chain/context.ts#L3-L4) +- [createItemsContext.tsx:102-170](file://frontend/utils/createItemsContext.tsx#L102-L170) + +### ThoughtChainItem Sub-item Component + +ThoughtChainItem provides two implementation approaches: direct React implementation and ItemHandler-based wrapper implementation. + +**Section Sources** + +- [thought-chain.thought-chain-item.tsx:7-11](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L7-L11) +- [thought-chain.item.tsx:9-27](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L9-L27) + +## Architecture Overview + +ThoughtChainItem adopts a layered architecture design, ensuring loose coupling and high cohesion between components: + +```mermaid +sequenceDiagram +participant App as Application +participant Chain as ThoughtChain +participant Handler as ItemHandler +participant Item as ThoughtChainItem +participant XChain as Ant Design X +App->>Chain : Render thought chain +Chain->>Handler : Create item handler +Handler->>Item : Process sub-item data +Item->>XChain : Render actual component +XChain-->>Item : Return render result +Item-->>Handler : Update state +Handler-->>Chain : Synchronize state +Chain-->>App : Render complete +``` + +**Diagram Sources** + +- [thought-chain.tsx:14-34](file://frontend/antdx/thought-chain/thought-chain.tsx#L14-L34) +- [createItemsContext.tsx:190-261](file://frontend/utils/createItemsContext.tsx#L190-L261) + +### State Management System + +The component's state management is based on React Context and the custom Items Context system: + +```mermaid +flowchart TD +A[User Action] --> B[State Change] +B --> C[ItemHandler Processing] +C --> D[Update Items Context] +D --> E[Trigger Re-render] +E --> F[Ant Design X Renders] +F --> G[Visual Feedback] +H[Async Operation] --> I[State Switch] +I --> J[Loading Indicator] +J --> K[Completion State] +L[Error Handling] --> M[Error State] +M --> N[Retry Mechanism] +``` + +**Diagram Sources** + +- [createItemsContext.tsx:124-153](file://frontend/utils/createItemsContext.tsx#L124-L153) +- [createItemsContext.tsx:234-237](file://frontend/utils/createItemsContext.tsx#L234-L237) + +**Section Sources** + +- [createItemsContext.tsx:97-274](file://frontend/utils/createItemsContext.tsx#L97-L274) + +## Detailed Component Analysis + +### ThoughtChainItem Property Configuration + +The component supports rich property configuration to meet different usage scenarios: + +| Property Name | Type | Required | Description | +| ------------- | ------------------------------------------ | -------- | -------------------------------------- | +| title | ReactNode \| string | No | Thought item title content | +| description | ReactNode \| string | No | Thought item description content | +| icon | ReactNode | No | Custom icon component | +| status | 'wait' \| 'process' \| 'finish' \| 'error' | No | Current status | +| key | string \| number | No | Unique key identifier | +| itemIndex | number | Yes | Index position in the parent container | +| itemSlotKey | string | No | Slot key value | +| itemProps | function | No | Dynamic property computation function | +| itemChildren | function | No | Child item generation function | + +### State Management Mechanism + +The component supports four core states, each with corresponding visual representations: + +```mermaid +stateDiagram-v2 +[*] --> Pending +Pending --> InProgress : Start execution +InProgress --> Completed : Execution successful +InProgress --> Failed : Execution error +Completed --> [*] +Failed --> Pending : Retry +Failed --> [*] : Abandon +``` + +**Diagram Sources** + +- [thought-chain.item.tsx:16-27](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L16-L27) + +### Event Handling Mechanism + +The component provides complete event handling capabilities: + +| Event Type | Callback | Trigger Timing | Parameters | +| ---------------- | -------- | --------------- | -------------------- | +| onClick | function | User clicks | event, itemData | +| onStatusChange | function | Status changes | oldStatus, newStatus | +| onRenderComplete | function | Render complete | itemData | +| onError | function | Error occurs | error, itemData | + +**Section Sources** + +- [thought-chain.thought-chain-item.tsx:7-11](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L7-L11) +- [thought-chain.item.tsx:9-27](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L9-L27) + +### Usage Examples + +#### Basic Usage + +```javascript +// Simple thought item configuration +
Extra content
+
+treeData/directoryIcons"] +CtxS["Sources Context
items/title"] +end +subgraph "External Dependencies" +ADX["@ant-design/x
Native Component Library"] +Utils["@utils/*
Utilities & Hooks"] +end +FC --> BFC +F --> CtxF +S --> CtxS +FC --> ADX +F --> ADX +S --> ADX +T --> ADX +FC --> Utils +F --> Utils +S --> Utils +T --> Utils +``` + +Diagram sources + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) +- [frontend/antdx/folder/folder.tsx:1-123](file://frontend/antdx/folder/folder.tsx#L1-L123) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) +- [frontend/antdx/sources/sources.tsx:1-42](file://frontend/antdx/sources/sources.tsx#L1-L42) +- [frontend/antdx/sources/context.ts:1-7](file://frontend/antdx/sources/context.ts#L1-L7) +- [frontend/antdx/think/think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +Section sources + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) +- [frontend/antdx/folder/folder.tsx:1-123](file://frontend/antdx/folder/folder.tsx#L1-L123) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) +- [frontend/antdx/sources/sources.tsx:1-42](file://frontend/antdx/sources/sources.tsx#L1-L42) +- [frontend/antdx/sources/context.ts:1-7](file://frontend/antdx/sources/context.ts#L1-L7) +- [frontend/antdx/think/think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +## Core Components + +- FileCard: Displays a single file card, supporting image placeholders, preview configuration, and slot-based customization of masks and loading indicators. Internally parses file resource URLs via BaseFileCard to ensure accessibility. + - **Sub-component hierarchy**: FileCard is the top-level single card component; `FileCardList` (list layer) arranges multiple file cards; `FileCardListItem` (list item layer) encapsulates the rendering logic of a single list item. The hierarchy is: FileCardList → FileCardListItem → FileCard. + - **Backend exports**: `FileCard`, `FileCardList`, and `FileCardListItem` are all exported via [backend/modelscope_studio/components/antdx/**init**.py](file://backend/modelscope_studio/components/antdx/__init__.py). +- Folder: Displays a folder tree structure, supporting treeData, directoryIcons, empty state rendering, directory title, preview title, and preview rendering slots. Provides dynamic node and icon injection via context. +- Sources: Displays a list of data sources, supporting items and title slots. Provides a default item collection via context for unified injection in parent containers. +- Think: Displays "thinking" records and status, supporting loading, icon, and title slots for different visual feedback in various states. + - **Difference between Think and ThoughtChain**: Think (`antdx.Think`) is a lightweight single-step "thinking status" display component, typically embedded in bubble streams to indicate a single "thinking" state (belongs to data components). ThoughtChain (`antdx.ThoughtChain`) is a multi-step reasoning chain component used to display a complete reasoning sequence with inner child item support (belongs to confirmation components). Their use cases differ: Think is suitable for single-state indication; ThoughtChain is suitable for multi-step reasoning display. + +Section sources + +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/file-card/base.tsx:9-41](file://frontend/antdx/file-card/base.tsx#L9-L41) +- [frontend/antdx/folder/folder.tsx:16-120](file://frontend/antdx/folder/folder.tsx#L16-L120) +- [frontend/antdx/folder/context.ts:3-13](file://frontend/antdx/folder/context.ts#L3-L13) +- [frontend/antdx/sources/sources.tsx:9-39](file://frontend/antdx/sources/sources.tsx#L9-L39) +- [frontend/antdx/sources/context.ts:3-4](file://frontend/antdx/sources/context.ts#L3-L4) +- [frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +## Architecture Overview + +All four components adopt a layered design of "entry layer + base implementation/context": + +- Entry layer: Uses sveltify to bridge Svelte components to the React ecosystem, uniformly handling slots and functional callbacks, and ensuring property alignment with @ant-design/x. +- Base implementation/context: Builds on the entry layer to further encapsulate data parsing, default value handling, slot rendering, and context injection, reducing duplicate logic and improving maintainability. + +```mermaid +sequenceDiagram +participant U as "Caller" +participant FC as "FileCard Entry" +participant BFC as "BaseFileCard" +participant ADX as "@ant-design/x" +U->>FC : Pass props and slots +FC->>FC : Process slots and functional callbacks +FC->>BFC : Pass resolved props +BFC->>ADX : Render FileCard and resolve src +ADX-->>U : Display file card +``` + +Diagram sources + +- [frontend/antdx/file-card/file-card.tsx:34-124](file://frontend/antdx/file-card/file-card.tsx#L34-L124) +- [frontend/antdx/file-card/base.tsx:31-41](file://frontend/antdx/file-card/base.tsx#L31-L41) + +Section sources + +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/file-card/base.tsx:9-41](file://frontend/antdx/file-card/base.tsx#L9-L41) + +## Detailed Component Analysis + +### FileCard Component Analysis + +- Responsibilities and Capabilities + - File information display: Supports file name, description, icon, placeholder image, loading indicator, etc. + - Actions and preview: Supports image preview configuration (container, mask, close icon, toolbar, custom image rendering). + - Slot-based extension: Flexibly replaces icon, description, mask, spinProps._, and imageProps._ via slots. + - Resource resolution: Converts relative paths or FileData to accessible URLs via BaseFileCard's src resolution logic. +- Key Flow + - Entry layer resolves slots and functional callbacks and constructs preview configuration. + - Passes resolved imageProps and spinProps to BaseFileCard. + - BaseFileCard uses rootUrl and apiPrefix to compute the accessible file URL. +- Usage Recommendations + - When customizing preview toolbars or masks, prefer slot injection over directly overriding complex objects. + - For large files or unstable network environments, configure placeholder images and loading indicators appropriately to improve user experience. + +```mermaid +flowchart TD +Start(["Enter FileCard"]) --> ParseSlots["Resolve slots and functional callbacks"] +ParseSlots --> BuildPreview["Build imageProps.preview configuration"] +BuildPreview --> ResolveSrc["BaseFileCard resolves src
rootUrl + apiPrefix"] +ResolveSrc --> Render["Render @ant-design/x FileCard"] +Render --> End(["Done"]) +``` + +Diagram sources + +- [frontend/antdx/file-card/file-card.tsx:34-124](file://frontend/antdx/file-card/file-card.tsx#L34-L124) +- [frontend/antdx/file-card/base.tsx:15-41](file://frontend/antdx/file-card/base.tsx#L15-L41) + +Section sources + +- [frontend/antdx/file-card/file-card.tsx:9-124](file://frontend/antdx/file-card/file-card.tsx#L9-L124) +- [frontend/antdx/file-card/base.tsx:9-41](file://frontend/antdx/file-card/base.tsx#L9-L41) + +### Folder Component Analysis + +- Responsibilities and Capabilities + - Tree structure display: Supports treeData and directory icon mapping via directoryIcons. + - Dynamic content service: Loads file content via fileContentService.onLoadFileContent. + - Slot-based extension: Supports emptyRender, previewRender, directoryTitle, and previewTitle. + - Context injection: Obtains default nodes and icon collections via useTreeNodeItems and useDirectoryIconItems. +- Key Flow + - Resolves treeData or default from context, prioritizing explicitly passed treeData. + - Converts directoryIcons into an icon dictionary keyed by file extension. + - Converts slots and functional callbacks to render functions required by @ant-design/x. +- Usage Recommendations + - For complex directory structures, prefer context injection of default nodes to reduce repetitive configuration. + - Preview render functions should be kept lightweight to avoid heavy computation during rendering. + +```mermaid +sequenceDiagram +participant U as "Caller" +participant F as "Folder Entry" +participant Ctx as "Folder Context" +participant ADX as "@ant-design/x Folder" +U->>F : Pass treeData/directoryIcons/slots +F->>Ctx : Read default nodes and icons +F->>F : Resolve slots and functional callbacks +F->>ADX : Render treeData and directoryIcons +ADX-->>U : Display folder tree +``` + +Diagram sources + +- [frontend/antdx/folder/folder.tsx:25-119](file://frontend/antdx/folder/folder.tsx#L25-L119) +- [frontend/antdx/folder/context.ts:3-13](file://frontend/antdx/folder/context.ts#L3-L13) + +Section sources + +- [frontend/antdx/folder/folder.tsx:16-120](file://frontend/antdx/folder/folder.tsx#L16-L120) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) + +### Sources Component Analysis + +- Responsibilities and Capabilities + - Data source list display: Supports items list and title slot. + - Context injection: Obtains default items and default via useItems, prioritizing explicitly passed items. + - Render enhancement: Uses renderItems to clone and render item collections from context into the format required by @ant-design/x. +- Key Flow + - Resolves items or default from context and merges into the final list. + - Passes title and items to @ant-design/x Sources. +- Usage Recommendations + - Inject default items centrally in a parent container for reuse across multiple locations. + - For large lists, apply pagination or lazy loading optimization upstream. + +```mermaid +sequenceDiagram +participant U as "Caller" +participant S as "Sources Entry" +participant Ctx as "Sources Context" +participant ADX as "@ant-design/x Sources" +U->>S : Pass items/slots +S->>Ctx : Read default items/default +S->>ADX : Render items and title +ADX-->>U : Display data source list +``` + +Diagram sources + +- [frontend/antdx/sources/sources.tsx:9-39](file://frontend/antdx/sources/sources.tsx#L9-L39) +- [frontend/antdx/sources/context.ts:3-4](file://frontend/antdx/sources/context.ts#L3-L4) + +Section sources + +- [frontend/antdx/sources/sources.tsx:9-39](file://frontend/antdx/sources/sources.tsx#L9-L39) +- [frontend/antdx/sources/context.ts:1-7](file://frontend/antdx/sources/context.ts#L1-L7) + +### Think Component Analysis + +- Responsibilities and Capabilities + - Thinking record and status display: Supports loading, icon, and title slots, enabling different content to be shown in various states (e.g., loading, complete, failed). + - Thin wrapper: Acts as a thin wrapper that directly forwards to the @ant-design/x Think component. +- Usage Recommendations + - In async thinking workflows, combine with the loading slot to provide friendlier user feedback. + - Use icon and title slots to differentiate thinking phases or result types. + +```mermaid +sequenceDiagram +participant U as "Caller" +participant T as "Think Entry" +participant ADX as "@ant-design/x Think" +U->>T : Pass loading/icon/title/slots +T->>ADX : Directly forward props and slots +ADX-->>U : Display thinking status +``` + +Diagram sources + +- [frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +Section sources + +- [frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +## Dependency Analysis + +- Inter-component Coupling + - FileCard and BaseFileCard: Low coupling, decoupled via props passing and resolution. + - Folder and Sources: Each depends on its own context module, independent from each other, rendered via @ant-design/x components. + - Think: No context dependency, directly bridges @ant-design/x. +- External Dependencies + - @ant-design/x: The foundational library for all component rendering. + - @utils/\*: Provides common capabilities such as slot rendering, functional callback wrapping, and context creation. + +```mermaid +graph LR +FC["FileCard"] --> BFC["BaseFileCard"] +F["Folder"] --> CtxF["Folder Context"] +S["Sources"] --> CtxS["Sources Context"] +T["Think"] +BFC --> ADX["@ant-design/x"] +F --> ADX +S --> ADX +T --> ADX +FC --> Utils["@utils/*"] +F --> Utils +S --> Utils +T --> Utils +``` + +Diagram sources + +- [frontend/antdx/file-card/file-card.tsx:1-7](file://frontend/antdx/file-card/file-card.tsx#L1-L7) +- [frontend/antdx/file-card/base.tsx:1-7](file://frontend/antdx/file-card/base.tsx#L1-L7) +- [frontend/antdx/folder/folder.tsx:1-7](file://frontend/antdx/folder/folder.tsx#L1-L7) +- [frontend/antdx/sources/sources.tsx:1-5](file://frontend/antdx/sources/sources.tsx#L1-L5) +- [frontend/antdx/think/think.tsx:1-4](file://frontend/antdx/think/think.tsx#L1-L4) + +Section sources + +- [frontend/antdx/file-card/file-card.tsx:1-7](file://frontend/antdx/file-card/file-card.tsx#L1-L7) +- [frontend/antdx/file-card/base.tsx:1-7](file://frontend/antdx/file-card/base.tsx#L1-L7) +- [frontend/antdx/folder/folder.tsx:1-7](file://frontend/antdx/folder/folder.tsx#L1-L7) +- [frontend/antdx/sources/sources.tsx:1-5](file://frontend/antdx/sources/sources.tsx#L1-L5) +- [frontend/antdx/think/think.tsx:1-4](file://frontend/antdx/think/think.tsx#L1-L4) + +## Performance Considerations + +- Slot rendering cost control + - Place heavy content in slots, but avoid repeated computation in render functions; use useMemo for caching when necessary. +- Data parsing and transfer + - FileCard's src resolution is only triggered when dependencies change, avoiding unnecessary URL computation. +- List rendering optimization + - Sources and Folder use clone and memo strategies when resolving items to reduce repeated rendering. +- Preview and images + - Configure placeholder images and loading indicators appropriately to prevent large images from blocking the initial render. + +## Troubleshooting Guide + +- Image not displaying + - Check whether src is a relative path; confirm rootUrl and apiPrefix are configured correctly. + - Reference: [frontend/antdx/file-card/base.tsx:15-29](file://frontend/antdx/file-card/base.tsx#L15-L29) +- Preview function abnormal + - Confirm that imageProps.preview slots are correctly injected and functional callbacks are properly wrapped. + - Reference: [frontend/antdx/file-card/file-card.tsx:34-124](file://frontend/antdx/file-card/file-card.tsx#L34-L124) +- Directory icons not working + - Confirm directoryIcons are mapped by file extension and injected via context. + - Reference: [frontend/antdx/folder/folder.tsx:71-87](file://frontend/antdx/folder/folder.tsx#L71-L87) +- Data source list empty + - Check whether items and default are correctly injected or explicitly overridden. + - Reference: [frontend/antdx/sources/sources.tsx:13-33](file://frontend/antdx/sources/sources.tsx#L13-L33) +- Thinking status not updating + - Confirm loading/icon/title slots are correctly injected and functional callbacks are properly wrapped. + - Reference: [frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +Section sources + +- [frontend/antdx/file-card/base.tsx:15-29](file://frontend/antdx/file-card/base.tsx#L15-L29) +- [frontend/antdx/file-card/file-card.tsx:34-124](file://frontend/antdx/file-card/file-card.tsx#L34-L124) +- [frontend/antdx/folder/folder.tsx:71-87](file://frontend/antdx/folder/folder.tsx#L71-L87) +- [frontend/antdx/sources/sources.tsx:13-33](file://frontend/antdx/sources/sources.tsx#L13-L33) +- [frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +## Conclusion + +This document systematically covers the frontend implementation and usage of Ant Design X data components, focusing on FileCard, Folder, Sources, and Think. Through slot and functional callback bridging in the entry layer, data parsing and default value handling in the base implementation, and context-driven dynamic injection mechanisms, these components maintain API semantics consistent with @ant-design/x while providing stronger extensibility and maintainability. It is recommended to follow the usage guidelines and best practices in this document in actual projects for a more stable and efficient experience. + +## Appendix + +- Usage Examples (Based on Component Responsibilities and Interfaces) + - File card display and preview + - Key steps: Prepare file data src, configure imageProps.preview slots (e.g., mask, toolbar), and optionally set placeholder image and loading indicator. + - Reference: [frontend/antdx/file-card/file-card.tsx:34-124](file://frontend/antdx/file-card/file-card.tsx#L34-L124), [frontend/antdx/file-card/base.tsx:15-41](file://frontend/antdx/file-card/base.tsx#L15-L41) + - Folder tree structure and directory management + - Key steps: Prepare treeData or inject default nodes via context; configure extension-based mapping for directoryIcons; inject emptyRender, previewRender, directoryTitle, and previewTitle as needed. + - Reference: [frontend/antdx/folder/folder.tsx:25-119](file://frontend/antdx/folder/folder.tsx#L25-L119), [frontend/antdx/folder/context.ts:3-13](file://frontend/antdx/folder/context.ts#L3-L13) + - Data source management and metadata display + - Key steps: Inject default items or default in the parent container; override items when needed; customize title via the title slot. + - Reference: [frontend/antdx/sources/sources.tsx:9-39](file://frontend/antdx/sources/sources.tsx#L9-L39), [frontend/antdx/sources/context.ts:3-4](file://frontend/antdx/sources/context.ts#L3-L4) + - Thinking record and status management + - Key steps: Inject loading/icon/title slots at different stages; switch displayed content based on status in async workflows. + - Reference: [frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) diff --git a/.wiki/en/Ant Design X Components/Data Components/FileCard Component.md b/.wiki/en/Ant Design X Components/Data Components/FileCard Component.md new file mode 100644 index 00000000..e84b0231 --- /dev/null +++ b/.wiki/en/Ant Design X Components/Data Components/FileCard Component.md @@ -0,0 +1,441 @@ +# FileCard Component + + +**Files Referenced in This Document** +- [frontend/antdx/file-card/file-card.tsx](file://frontend/antdx/file-card/file-card.tsx) +- [frontend/antdx/file-card/base.tsx](file://frontend/antdx/file-card/base.tsx) +- [frontend/antdx/file-card/Index.svelte](file://frontend/antdx/file-card/Index.svelte) +- [frontend/antdx/file-card/list/file-card.list.tsx](file://frontend/antdx/file-card/list/file-card.list.tsx) +- [frontend/antdx/file-card/list/context.ts](file://frontend/antdx/file-card/list/context.ts) +- [frontend/antdx/file-card/list/item/file-card.list.item.tsx](file://frontend/antdx/file-card/list/item/file-card.list.item.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) + +## Introduction + +The FileCard component is an important component in the ModelScope Studio frontend framework, extended and encapsulated based on the Ant Design X FileCard component. It provides file display, preview, and upload capabilities, supporting multiple file types and custom configuration options. + +The component consists of three core parts: + +- **Base FileCard component**: Provides core file display functionality +- **FileCard List component**: Used to display a list view of multiple file cards +- **FileCard List Item component**: The concrete implementation of a single file card in a list + +## Project Structure + +The FileCard component is located in the antdx component library of the frontend project, organized in a modular manner: + +```mermaid +graph TB +subgraph "FileCard Component Structure" +FC[FileCard Core Component] +FCL[FileCard List Component] +FCListItem[FileCard List Item Component] +Base[Base FileCard Component] +FC --> Base +FCL --> FCListItem +FCListItem --> Base +end +subgraph "Frontend Component Libraries" +Antdx[antdx Component Library] +Antd[antd Component Library] +Utils[Utility Functions] +end +FC -.-> Antdx +FCL -.-> Antdx +FCListItem -.-> Antdx +Base -.-> Antdx +Base -.-> Antd +FC -.-> Utils +FCL -.-> Utils +FCListItem -.-> Utils +``` + +**Diagram sources** + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/list/file-card.list.tsx:1-68](file://frontend/antdx/file-card/list/file-card.list.tsx#L1-L68) + +**Section sources** + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/list/file-card.list.tsx:1-68](file://frontend/antdx/file-card/list/file-card.list.tsx#L1-L68) + +## Core Components + +### Base FileCard Component (BaseFileCard) + +The BaseFileCard component is the foundation of the entire FileCard system, responsible for handling file source resolution and basic file display logic. + +**Key Features:** + +- Supports both string and FileData type file sources +- Automatically resolves accessible file URLs +- Integrates Ant Design X's FileCard component +- Provides root URL and API prefix configuration + +**Key Methods:** + +- `resolveFileSrc()`: Resolves the file source, supporting both local and remote files +- `BaseFileCard`: Main component rendering logic + +**Section sources** + +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) + +### FileCard Component + +The FileCard component is a further encapsulation of the base component, adding React Slot support and richer configuration options. + +**Main Features:** + +- Supports the React Slot system +- Enhanced image preview functionality +- Loading state indicator configuration +- Custom icon and description content + +**Core Configuration:** + +- `imageProps.placeholder`: Placeholder configuration +- `imageProps.preview`: Preview function configuration +- `spinProps`: Loading state configuration +- `slots`: Slot system support + +**Section sources** + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) + +### FileCard List Component (FileCardList) + +The FileCardList component is used to display multiple file cards, supporting bulk operations and unified configuration. + +**Key Features:** + +- Bulk file management +- Removable functionality +- Slot system integration +- Item context management + +**Section sources** + +- [frontend/antdx/file-card/list/file-card.list.tsx:1-68](file://frontend/antdx/file-card/list/file-card.list.tsx#L1-L68) + +### FileCard List Item Component (FileCardListItem) + +The concrete implementation of a single file card in a list, inheriting all functionality of the base file card. + +**Key Features:** + +- List item handling mechanism +- Slot parameter passing +- Preview configuration +- Item context integration + +**Section sources** + +- [frontend/antdx/file-card/list/item/file-card.list.item.tsx:1-83](file://frontend/antdx/file-card/list/item/file-card.list.item.tsx#L1-L83) + +## Architecture Overview + +The FileCard component adopts a layered architecture design, forming a clear hierarchy from the underlying base component to the upper-level application components: + +```mermaid +graph TD +subgraph "Application Layer" +App[Application] +Demo[Demo App] +end +subgraph "Component Layer" +SvelteIndex[Index.svelte Entry] +FileCard[FileCard Component] +FileCardList[FileCardList Component] +FileCardListItem[FileCardListItem Component] +end +subgraph "Base Layer" +BaseFileCard[BaseFileCard Component] +AntdX[Ant Design X] +Utils[Utility Functions] +end +subgraph "Data Layer" +FileData[File Data Model] +Config[Configuration Object] +Slots[Slot System] +end +App --> SvelteIndex +Demo --> SvelteIndex +SvelteIndex --> FileCard +SvelteIndex --> FileCardList +FileCardList --> FileCardListItem +FileCard --> BaseFileCard +FileCardList --> BaseFileCard +FileCardListItem --> BaseFileCard +BaseFileCard --> AntdX +FileCard --> Utils +FileCardList --> Utils +FileCardListItem --> Utils +BaseFileCard --> FileData +FileCard --> Config +FileCardList --> Config +FileCardListItem --> Config +FileCard --> Slots +FileCardList --> Slots +FileCardListItem --> Slots +``` + +**Diagram sources** + +- [frontend/antdx/file-card/Index.svelte:1-66](file://frontend/antdx/file-card/Index.svelte#L1-L66) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/list/file-card.list.tsx:1-68](file://frontend/antdx/file-card/list/file-card.list.tsx#L1-L68) + +## Detailed Component Analysis + +### Base FileCard Component Class Diagram + +```mermaid +classDiagram +class BaseFileCardProps { ++string rootUrl ++string apiPrefix ++string|FileData src ++XFileCardProps props +} +class BaseFileCard { ++resolveFileSrc(src, rootUrl, apiPrefix) string ++render() ReactElement +} +class FileCardProps { ++BaseFileCardProps props ++React.ReactNode children ++object slots ++object imageProps ++object spinProps +} +class FileCard { ++getConfig(value) object ++render() ReactElement +} +class FileCardListProps { ++FileCardListProps props ++ItemType[] items ++React.ReactNode children ++string rootUrl ++string apiPrefix ++function removable +} +class FileCardList { ++render() ReactElement ++resolveItems() ItemType[] +} +class FileCardListItemProps { ++BaseFileCardProps props ++ItemHandlerProps props ++object slots ++object imageProps +} +class FileCardListItem { ++getConfig(value) object ++render() ReactElement +} +BaseFileCardProps <|-- FileCardProps +BaseFileCardProps <|-- FileCardListItemProps +FileCardProps <|-- FileCard +FileCardListProps <|-- FileCardList +FileCardListItemProps <|-- FileCardListItem +FileCard --> BaseFileCard +FileCardList --> FileCardListItem +FileCardListItem --> BaseFileCard +``` + +**Diagram sources** + +- [frontend/antdx/file-card/base.tsx:9-13](file://frontend/antdx/file-card/base.tsx#L9-L13) +- [frontend/antdx/file-card/file-card.tsx:17-34](file://frontend/antdx/file-card/file-card.tsx#L17-L34) +- [frontend/antdx/file-card/list/file-card.list.tsx:14-21](file://frontend/antdx/file-card/list/file-card.list.tsx#L14-L21) +- [frontend/antdx/file-card/list/item/file-card.list.item.tsx:16-31](file://frontend/antdx/file-card/list/item/file-card.list.item.tsx#L16-L31) + +### File Source Resolution Flow + +```mermaid +flowchart TD +Start([Start resolving file source]) --> CheckSrc{Check src parameter} +CheckSrc --> |Empty| ReturnEmpty[Return empty value] +CheckSrc --> |String| CheckProtocol{Check protocol} +CheckSrc --> |Object| CheckObject{Check object properties} +CheckProtocol --> |Starts with http| ReturnString[Return string directly] +CheckProtocol --> |Does not start with http| ResolveURL[Call getFetchableUrl] +CheckObject --> CheckUrl{Check url property} +CheckObject --> CheckPath{Check path property} +CheckUrl --> |Exists| ReturnUrl[Return url] +CheckUrl --> |Does not exist| ResolvePath[Call getFetchableUrl] +CheckPath --> |Exists| ResolvePath +CheckPath --> |Does not exist| ReturnUndefined[Return undefined] +ResolveURL --> ReturnResolved[Return resolved URL] +ResolvePath --> ReturnResolved +ReturnEmpty --> End([End]) +ReturnString --> End +ReturnUrl --> End +ReturnResolved --> End +ReturnUndefined --> End +``` + +**Diagram sources** + +- [frontend/antdx/file-card/base.tsx:15-29](file://frontend/antdx/file-card/base.tsx#L15-L29) + +### Slot System Workflow + +```mermaid +sequenceDiagram +participant App as Application +participant FileCard as FileCard Component +participant BaseFileCard as BaseFileCard Component +participant SlotSystem as Slot System +participant Utils as Utility Functions +App->>FileCard : Render component +FileCard->>SlotSystem : Get slot configuration +SlotSystem-->>FileCard : Return slot data +FileCard->>Utils : Process slot parameters +Utils-->>FileCard : Return processed result +FileCard->>BaseFileCard : Pass configuration +BaseFileCard->>BaseFileCard : Render file card +BaseFileCard-->>App : Output final component +``` + +**Diagram sources** + +- [frontend/antdx/file-card/file-card.tsx:34-124](file://frontend/antdx/file-card/file-card.tsx#L34-L124) +- [frontend/antdx/file-card/base.tsx:31-41](file://frontend/antdx/file-card/base.tsx#L31-L41) + +**Section sources** + +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/list/file-card.list.tsx:1-68](file://frontend/antdx/file-card/list/file-card.list.tsx#L1-L68) +- [frontend/antdx/file-card/list/item/file-card.list.item.tsx:1-83](file://frontend/antdx/file-card/list/item/file-card.list.item.tsx#L1-L83) + +## Dependency Analysis + +The dependency relationship of the FileCard component is relatively clear, primarily depending on the Ant Design X component library and internal utility functions: + +```mermaid +graph LR +subgraph "External Dependencies" +AntdX[Ant Design X] +React[React] +Svelte[Svelte] +end +subgraph "Internal Dependencies" +Utils[Utility Functions] +Hooks[React Hooks] +Context[Context System] +end +subgraph "FileCard Components" +BaseFileCard[BaseFileCard] +FileCard[FileCard] +FileCardList[FileCardList] +FileCardListItem[FileCardListItem] +end +FileCard --> BaseFileCard +FileCardList --> FileCardListItem +FileCardListItem --> BaseFileCard +BaseFileCard --> AntdX +FileCard --> Utils +FileCardList --> Utils +FileCardListItem --> Utils +FileCard --> Hooks +FileCardList --> Hooks +FileCardListItem --> Hooks +FileCard --> Context +FileCardList --> Context +FileCardListItem --> Context +BaseFileCard --> React +FileCard --> Svelte +FileCardList --> Svelte +FileCardListItem --> Svelte +``` + +**Diagram sources** + +- [frontend/antdx/file-card/file-card.tsx:1-7](file://frontend/antdx/file-card/file-card.tsx#L1-L7) +- [frontend/antdx/file-card/base.tsx:1-7](file://frontend/antdx/file-card/base.tsx#L1-L7) +- [frontend/antdx/file-card/list/file-card.list.tsx:1-8](file://frontend/antdx/file-card/list/file-card.list.tsx#L1-L8) + +**Section sources** + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) +- [frontend/antdx/file-card/list/file-card.list.tsx:1-68](file://frontend/antdx/file-card/list/file-card.list.tsx#L1-L68) + +## Performance Considerations + +The FileCard component was designed with performance optimization in mind: + +### Memory Management + +- Uses `useMemo` to cache file source resolution results +- Avoids unnecessary component re-renders +- Proper use of React Slots to reduce DOM operations + +### Render Optimization + +- Conditional rendering of slot content +- Lazy loading components to avoid initial render pressure +- Optimized performance for the image preview feature + +### Data Flow Optimization + +- Unidirectional data flow design +- Avoids passing deeply nested objects +- Reasonable event handling mechanisms + +## Troubleshooting Guide + +### Common Issues and Solutions + +**File not displaying** + +- Check whether the file source URL is correct +- Confirm network connectivity and permission settings +- Verify that the file format is supported + +**Preview function abnormal** + +- Check the image preview configuration +- Confirm the slot system is working correctly +- Verify that the container element exists + +**Component rendering error** + +- Check the usage of React Slots +- Confirm that required dependencies are installed correctly +- Verify the import path of the component + +**Section sources** + +- [frontend/antdx/file-card/base.tsx:15-29](file://frontend/antdx/file-card/base.tsx#L15-L29) +- [frontend/antdx/file-card/file-card.tsx:34-124](file://frontend/antdx/file-card/file-card.tsx#L34-L124) + +## Conclusion + +The FileCard component is a fully functional and well-designed frontend component system. Through its clear layered architecture, flexible slot system, and comprehensive configuration options, it provides users with powerful file management and display capabilities. + +The main advantages of the component include: + +- **Modular design**: Clear component hierarchy structure +- **Flexible configuration**: Rich configuration options and slot system +- **Performance optimization**: Reasonable memory management and render optimization +- **Easy to extend**: Standardized interface design facilitates feature extension + +This component system provides ModelScope Studio with reliable file processing capabilities to meet the needs of various file display and management scenarios. diff --git a/.wiki/en/Ant Design X Components/Data Components/Folder Component.md b/.wiki/en/Ant Design X Components/Data Components/Folder Component.md new file mode 100644 index 00000000..453d315d --- /dev/null +++ b/.wiki/en/Ant Design X Components/Data Components/Folder Component.md @@ -0,0 +1,359 @@ +# Folder Component + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/antdx/folder/__init__.py](file://backend/modelscope_studio/components/antdx/folder/__init__.py) +- [frontend/antdx/folder/Index.svelte](file://frontend/antdx/folder/Index.svelte) +- [frontend/antdx/folder/folder.tsx](file://frontend/antdx/folder/folder.tsx) +- [frontend/antdx/folder/context.ts](file://frontend/antdx/folder/context.ts) +- [frontend/antdx/folder/package.json](file://frontend/antdx/folder/package.json) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [docs/components/antdx/folder/README-zh_CN.md](file://docs/components/antdx/folder/README-zh_CN.md) +- [docs/components/antdx/folder/README.md](file://docs/components/antdx/folder/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) + +## Introduction + +The Folder component is an important file tree component in ModelScope Studio, built on top of Ant Design X's Folder component. It is primarily used to display file system structures, providing hierarchical browsing of files and folders. It supports event handling for file clicks, folder clicks, selected file changes, and expanded path changes, along with rich customization options. + +The component is implemented on the frontend using the Svelte framework, bridged to Ant Design X's native component through a React preprocessing mechanism, achieving a complete data flow and event flow from the Python backend to the React frontend. + +## Project Structure + +The location and organizational structure of the Folder component within the project: + +```mermaid +graph TB +subgraph "Backend (Python)" +A[backend/modelscope_studio/components/antdx/] --> B[folder/] +B --> C[__init__.py
AntdXFolder class] +B --> D[directory_icon/] +B --> E[tree_node/] +end +subgraph "Frontend (TypeScript/Svelte)" +F[frontend/antdx/] --> G[folder/] +G --> H[Index.svelte
Component Entry] +G --> I[folder.tsx
React Implementation] +G --> J[context.ts
Context Management] +G --> K[package.json
Package Config] +end +subgraph "Documentation" +L[docs/components/antdx/folder/] +L --> M[README-zh_CN.md] +L --> N[README.md] +end +A --> F +F --> L +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:1-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L1-L114) +- [frontend/antdx/folder/Index.svelte:1-81](file://frontend/antdx/folder/Index.svelte#L1-L81) +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) + +**Section sources** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:1-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L1-L114) +- [frontend/antdx/folder/Index.svelte:1-81](file://frontend/antdx/folder/Index.svelte#L1-L81) +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) + +## Core Components + +### AntdXFolder Class + +AntdXFolder is the core backend component class, inheriting from ModelScopeLayoutComponent. It defines the complete component interface and behavioral specification. + +**Key Features:** + +- Supports multiple event listeners (file_click, folder_click, selected_file_change, expanded_paths_change) +- Provides rich configuration properties (tree_data, selectable, selected_file, expanded_paths, etc.) +- Supports a slot system (emptyRender, previewRender, directoryTitle, etc.) +- Integrates component lifecycle management in the Gradio ecosystem + +**Key Property Descriptions:** + +- `tree_data`: File tree data structure defining the hierarchy of files and folders +- `selectable`: Whether file selection is allowed +- `selected_file`: Currently selected file path list +- `expanded_paths`: Default expanded path list +- `directory_icons`: Custom directory icon mapping + +**Section sources** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) + +### Frontend Component Architecture + +The frontend component adopts a layered architecture design, implemented through bridging Svelte and React: + +```mermaid +classDiagram +class AntdXFolder { ++TreeNode ++DirectoryIcon ++EVENTS ++SLOTS ++tree_data ++selectable ++selected_file ++expanded_paths ++directory_icons ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +class FolderComponent { ++slots ++children ++previewRender ++previewTitle ++fileContentService ++treeData ++directoryIcons ++emptyRender ++directoryTitle +} +class ContextProviders { ++withTreeNodeItemsContextProvider ++withDirectoryIconItemsContextProvider ++useTreeNodeItems ++useDirectoryIconItems +} +AntdXFolder --> FolderComponent : "Frontend rendering" +FolderComponent --> ContextProviders : "Use context" +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) +- [frontend/antdx/folder/folder.tsx:16-124](file://frontend/antdx/folder/folder.tsx#L16-L124) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) + +**Section sources** + +- [frontend/antdx/folder/folder.tsx:16-124](file://frontend/antdx/folder/folder.tsx#L16-L124) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) + +## Architecture Overview + +The overall architecture of the Folder component adopts a layered design, achieving a complete data flow from the Python backend to the React frontend: + +```mermaid +sequenceDiagram +participant Backend as Backend Component +participant Svelte as Svelte Layer +participant React as React Component +participant AntDX as Ant Design X +participant User as User +User->>Backend : Create Folder component +Backend->>Svelte : Render component +Svelte->>React : Load Folder component +React->>AntDX : Initialize AntdXFolder +AntDX->>User : Display file tree interface +User->>AntDX : Click file/folder +AntDX->>React : Trigger event callback +React->>Svelte : Forward event +Svelte->>Backend : Update state +Backend->>User : Return result +Note over Backend,User : Data binding and event handling +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:19-35](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L19-L35) +- [frontend/antdx/folder/Index.svelte:10-81](file://frontend/antdx/folder/Index.svelte#L10-L81) +- [frontend/antdx/folder/folder.tsx:25-121](file://frontend/antdx/folder/folder.tsx#L25-L121) + +## Detailed Component Analysis + +### Event Handling Mechanism + +The Folder component supports multiple event listeners, each with its specific functionality and trigger conditions: + +```mermaid +flowchart TD +A[User Interaction] --> B{Event Type} +B --> |file_click| C[File Click Event] +B --> |folder_click| D[Folder Click Event] +B --> |selected_file_change| E[Selected File Change] +B --> |expanded_paths_change| F[Expanded Paths Change] +B --> |file_content_service_load_file_content| G[File Content Load] +C --> H[Update bind_fileClick_event] +D --> I[Update bind_folderClick_event] +E --> J[Update bind_selectedFileChange_event] +F --> K[Update bind_expandedPathsChange_event] +G --> L[Update bind_fileContentService_loadFileContent_event] +H --> M[Execute callback function] +I --> M +J --> M +K --> M +L --> M +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:19-35](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L19-L35) + +### Slot System + +The component provides a flexible slot system, allowing developers to customize various display content: + +| Slot Name | Description | Use Case | +| -------------- | --------------------- | -------------------------------------------------- | +| emptyRender | Empty state rendering | Display custom content when the file tree is empty | +| previewRender | Preview rendering | Customize file preview content | +| directoryTitle | Directory title | Customize directory display title | +| previewTitle | Preview title | Customize preview title display | +| treeData | Tree data | Customize tree data structure | +| directoryIcons | Directory icons | Customize file type icons | + +**Section sources** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:37-41](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L37-L41) + +### Data Flow Processing + +The component's data flow processing uses React's useMemo optimization mechanism: + +```mermaid +flowchart LR +A[Raw Data] --> B[useMemo Optimization] +B --> C[Data Transformation] +C --> D[Context Provider] +D --> E[Child Component Consumption] +F[External Input] --> G[props.treeData] +H[Internal Generation] --> I[renderItems] +G --> C +I --> C +J[Directory Icons] --> K[Object Mapping] +K --> L[extension -> ReactNode] +``` + +**Diagram sources** + +- [frontend/antdx/folder/folder.tsx:60-88](file://frontend/antdx/folder/folder.tsx#L60-L88) + +**Section sources** + +- [frontend/antdx/folder/folder.tsx:60-88](file://frontend/antdx/folder/folder.tsx#L60-L88) + +## Dependency Analysis + +The dependency relationships of the Folder component reflect a clear layered architecture: + +```mermaid +graph TB +subgraph "External Dependencies" +A[@ant-design/x] --> B[AntdXFolder] +C[classnames] --> D[Svelte Style Processing] +E[react] --> F[React Slot] +end +subgraph "Internal Dependencies" +G[createItemsContext] --> H[Context Provider] +I[renderItems] --> J[Item Rendering] +K[renderParamsSlot] --> L[Parameterized Slots] +M[useFunction] --> N[Function Wrapping] +end +subgraph "Component Hierarchy" +O[AntdXFolder] --> P[Index.svelte] +P --> Q[folder.tsx] +Q --> R[React Component] +R --> S[Ant Design X] +end +A --> R +G --> Q +I --> Q +K --> Q +M --> Q +``` + +**Diagram sources** + +- [frontend/antdx/folder/folder.tsx:1-15](file://frontend/antdx/folder/folder.tsx#L1-L15) +- [frontend/antdx/folder/Index.svelte:1-10](file://frontend/antdx/folder/Index.svelte#L1-L10) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) + +**Section sources** + +- [frontend/antdx/folder/package.json:1-15](file://frontend/antdx/folder/package.json#L1-L15) +- [frontend/antdx/folder/folder.tsx:1-15](file://frontend/antdx/folder/folder.tsx#L1-L15) + +## Performance Considerations + +### Render Optimization + +The component adopts several performance optimization strategies: + +1. **useMemo optimization**: Memoizes treeData and directoryIcons to avoid unnecessary recomputation +2. **Conditional rendering**: Only renders children content when needed, reducing the number of DOM nodes +3. **Lazy loading**: Implements dynamic import and lazy loading of components via importComponent + +### Memory Management + +- Context providers use appropriate cleanup mechanisms +- Event handlers are wrapped with useFunction to ensure correct `this` binding +- Slot content is rendered on demand to avoid memory leaks + +## Troubleshooting Guide + +### Common Issues and Solutions + +**Issue 1: Component not displaying** + +- Check whether tree_data is correctly set +- Confirm that the FRONTEND_DIR path is correctly resolved +- Verify the component's visible property + +**Issue 2: Events not triggering** + +- Confirm that event listeners are correctly registered +- Check whether bind\_\*\_event properties are set +- Verify that the callback function signature is correct + +**Issue 3: Icons not displaying** + +- Check the directory_icons configuration +- Confirm that the extension mapping is correct +- Verify the import path of icon components + +**Section sources** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:97-101](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L97-L101) + +## Conclusion + +The Folder component is a fully functional file tree component with a clear architecture. It successfully combines the powerful capabilities of Ant Design X with the ModelScope Studio ecosystem, providing users with an excellent file browsing experience. + +**Main Advantages:** + +- Complete event handling mechanism +- Flexible slot system +- Excellent performance +- Clear code structure +- Good extensibility + +**Applicable Scenarios:** + +- File management systems +- Code editors +- Asset management tools +- Document browsing applications + +This component provides ModelScope Studio with powerful file tree display capabilities and serves as an important foundational component for building complex frontend applications. diff --git a/.wiki/en/Ant Design X Components/Data Components/Sources Component.md b/.wiki/en/Ant Design X Components/Data Components/Sources Component.md new file mode 100644 index 00000000..820ea89b --- /dev/null +++ b/.wiki/en/Ant Design X Components/Data Components/Sources Component.md @@ -0,0 +1,422 @@ +# Sources Component + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/antdx/sources/__init__.py](file://backend/modelscope_studio/components/antdx/sources/__init__.py) +- [backend/modelscope_studio/components/antdx/sources/item/__init__.py](file://backend/modelscope_studio/components/antdx/sources/item/__init__.py) +- [frontend/antdx/sources/sources.tsx](file://frontend/antdx/sources/sources.tsx) +- [frontend/antdx/sources/item/sources.item.tsx](file://frontend/antdx/sources/item/sources.item.tsx) +- [frontend/antdx/sources/context.ts](file://frontend/antdx/sources/context.ts) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [docs/components/antdx/sources/README-zh_CN.md](file://docs/components/antdx/sources/README-zh_CN.md) +- [docs/components/antdx/sources/demos/basic.py](file://docs/components/antdx/sources/demos/basic.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) + +## Introduction + +The Sources component is a core component in ModelScope Studio for displaying a list of information sources in AI chat scenarios. Built on top of Ant Design X's Sources component, it is specifically designed to display references, link sources, and other related information. + +The component supports multiple configuration options, including title settings, expanded state control, inline display mode, and provides complete event handling mechanisms including click events and expand events. + +## Project Structure + +The Sources component adopts a frontend/backend separated architecture design, mainly consisting of the following structure: + +```mermaid +graph TB +subgraph "Backend Component Layer" +Backend[AntdXSources
Main Component] +BackendItem[AntdXSourcesItem
Child Item Component] +end +subgraph "Frontend Component Layer" +Frontend[Sources
React Component] +FrontendItem[SourcesItem
React Child Item Component] +Context[Context
Context Management] +end +subgraph "Utility Layer" +Utils[ModelScopeLayoutComponent
Base Component Class] +Resolver[resolve_frontend_dir
Path Resolver] +end +Backend --> Utils +BackendItem --> Utils +Backend --> Frontend +BackendItem --> FrontendItem +Frontend --> Context +Backend --> Resolver +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/antdx/sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) +- [frontend/antdx/sources/sources.tsx:1-41](file://frontend/antdx/sources/sources.tsx#L1-L41) + +**Section sources** + +- [backend/modelscope_studio/components/antdx/sources/**init**.py:1-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L1-L92) +- [backend/modelscope_studio/components/antdx/sources/item/**init**.py:1-68](file://backend/modelscope_studio/components/antdx/sources/item/__init__.py#L1-L68) + +## Core Components + +### AntdXSources Main Component + +AntdXSources is the main container of the Sources component, responsible for managing the display and interaction of the entire data source list. + +**Key Features:** + +- Supports title display and customization +- Configurable expand icon position (start/end) +- Default expanded and controlled expanded states +- Inline display mode support +- Active key management +- Popover overlay width setting + +**Key Properties:** + +- `title`: Title text displayed at the top of the component +- `items`: Array configuration of data source items +- `expand_icon_position`: Display position of the expand icon +- `default_expanded`: Default expanded state +- `expanded`: Controlled expanded state +- `inline`: Whether to enable inline display mode +- `active_key`: Currently active item key +- `popover_overlay_width`: Popover overlay width + +### AntdXSourcesItem Child Item Component + +AntdXSourcesItem represents a single data source entry, used to display specific source information. + +**Key Features:** + +- Supports customization of title, icon, and description +- Link address configuration +- Unique key identifier +- Slot system support + +**Key Properties:** + +- `key`: Unique identifier of the item +- `title`: Item title +- `description`: Item description information +- `icon`: Custom icon +- `url`: Navigation link address + +**Section sources** + +- [backend/modelscope_studio/components/antdx/sources/**init**.py:30-73](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L30-L73) +- [backend/modelscope_studio/components/antdx/sources/item/**init**.py:18-48](file://backend/modelscope_studio/components/antdx/sources/item/__init__.py#L18-L48) + +## Architecture Overview + +The Sources component adopts a layered architecture design, achieving clear separation of concerns: + +```mermaid +sequenceDiagram +participant App as Application +participant Backend as Backend Component +participant Frontend as Frontend Component +participant AntDX as Ant Design X +participant Context as Context Management +App->>Backend : Create Sources component +Backend->>Backend : Resolve frontend directory +Backend->>Frontend : Render React component +Frontend->>Context : Initialize context provider +Frontend->>AntDX : Use native Sources component +AntDX-->>Frontend : Return render result +Frontend-->>App : Output final component +Note over Backend,Frontend : Event binding and data passing +Backend->>Backend : Bind expand/click events +Backend->>Frontend : Pass event callbacks +``` + +**Diagram sources** + +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-16](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L16) +- [frontend/antdx/sources/sources.tsx:9-38](file://frontend/antdx/sources/sources.tsx#L9-L38) + +**Section sources** + +- [frontend/antdx/sources/sources.tsx:1-41](file://frontend/antdx/sources/sources.tsx#L1-L41) +- [frontend/antdx/sources/item/sources.item.tsx:1-14](file://frontend/antdx/sources/item/sources.item.tsx#L1-L14) + +## Detailed Component Analysis + +### Backend Component Implementation + +#### ModelScopeLayoutComponent Base Class + +All Sources components inherit from ModelScopeLayoutComponent, a layout component base class specifically designed for ModelScope Studio. + +**Core Functions:** + +- Provides the basic framework for Gradio components +- Handles component lifecycle management +- Supports slot system integration +- Manages internal component state + +#### AntdXSources Component Implementation + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++EVENTS : list ++SLOTS : list ++skip_api : bool ++FRONTEND_DIR : str ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdXSources { ++title : str ++items : list ++expand_icon_position : str ++default_expanded : bool ++expanded : bool ++inline : bool ++active_key : str ++popover_overlay_width : str|int|float ++Item : class ++EVENTS : list ++SLOTS : list +} +class AntdXSourcesItem { ++key : str ++description : str ++icon : str ++title : str ++url : str ++EVENTS : list ++SLOTS : list +} +ModelScopeLayoutComponent <|-- AntdXSources +ModelScopeLayoutComponent <|-- AntdXSourcesItem +AntdXSources --> AntdXSourcesItem : contains +``` + +**Diagram sources** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/antdx/sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) +- [backend/modelscope_studio/components/antdx/sources/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/sources/item/__init__.py#L8-L68) + +**Frontend Component Implementation** + +#### Sources React Component + +The Sources component is implemented using React, integrated with the Svelte ecosystem through the sveltify wrapper. + +**Core Features:** + +- Uses Ant Design X's native Sources component +- Supports a slot system, allowing custom title content +- Dynamically processes item lists +- Event handling mechanism + +#### SourcesItem React Child Component + +SourcesItem is the React implementation of a single data source item, processing item logic through ItemHandler. + +**Key Features:** + +- Accepts partial SourcesProps type +- Uses ItemHandler for item processing +- Supports additional item handler properties + +**Section sources** + +- [frontend/antdx/sources/sources.tsx:1-41](file://frontend/antdx/sources/sources.tsx#L1-L41) +- [frontend/antdx/sources/item/sources.item.tsx:1-14](file://frontend/antdx/sources/item/sources.item.tsx#L1-L14) + +### Event Handling Mechanism + +The Sources component supports two main events: + +```mermaid +flowchart TD +Start([Component Initialization]) --> BindEvents["Bind event listeners"] +BindEvents --> ExpandEvent["Expand event listener"] +BindEvents --> ClickEvent["Click event listener"] +ExpandEvent --> ExpandCallback["bind_expand_event callback"] +ClickEvent --> ClickCallback["bind_click_event callback"] +ExpandCallback --> UpdateInternal["Update internal state"] +ClickCallback --> UpdateInternal +UpdateInternal --> End([Event handling complete]) +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/antdx/sources/**init**.py:18-25](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L18-L25) + +**Event Types:** + +- `expand`: Triggered when the user expands or collapses a data source +- `click`: Triggered when the user clicks a data source item + +**Section sources** + +- [backend/modelscope_studio/components/antdx/sources/**init**.py:18-25](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L18-L25) + +### Slot System + +The Sources component supports a flexible slot system, allowing developers to customize different parts of the component: + +```mermaid +graph LR +subgraph "Slot System" +Items[items slot
Main item list] +Default[default slot
Default item content] +Title[title slot
Custom title] +end +subgraph "Render Logic" +Resolve[Resolve slot content] +Fallback[Fall back to default content] +Render[Render final result] +end +Items --> Resolve +Default --> Resolve +Title --> Resolve +Resolve --> Fallback +Fallback --> Render +``` + +**Diagram sources** + +- [frontend/antdx/sources/sources.tsx:12-36](file://frontend/antdx/sources/sources.tsx#L12-L36) + +**Supported Slots:** + +- `items`: Main data source item list +- `default`: Default item content +- `title`: Custom title content + +**Section sources** + +- [frontend/antdx/sources/sources.tsx:12-36](file://frontend/antdx/sources/sources.tsx#L12-L36) + +## Dependency Analysis + +The dependency relationship of the Sources component is relatively straightforward, primarily depending on Ant Design X and related utility libraries: + +```mermaid +graph TB +subgraph "External Dependencies" +AntDX[@ant-design/x
Ant Design X Core Components] +SveltePreprocess[@svelte-preprocess-react
Svelte-React Bridge] +Utils[@utils/*
Utility Function Library] +end +subgraph "Internal Dependencies" +Component[ModelScopeLayoutComponent
Base Component Class] +Context[createItemsContext
Context Management] +ResolveDir[resolve_frontend_dir
Path Resolution] +end +subgraph "Sources Components" +Sources[AntdXSources] +SourcesItem[AntdXSourcesItem] +end +Sources --> AntDX +Sources --> SveltePreprocess +Sources --> Utils +Sources --> Component +Sources --> Context +Sources --> ResolveDir +SourcesItem --> AntDX +SourcesItem --> SveltePreprocess +SourcesItem --> Context +``` + +**Diagram sources** + +- [frontend/antdx/sources/sources.tsx:1-5](file://frontend/antdx/sources/sources.tsx#L1-L5) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-16](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L16) + +**Main Dependency Notes:** + +- `@ant-design/x`: Provides the core Sources component implementation +- `@svelte-preprocess-react`: Implements the bridge between Svelte and React +- `@utils/*`: Provides common utility functions such as renderItems, createItemsContext, etc. + +**Section sources** + +- [frontend/antdx/sources/sources.tsx:1-5](file://frontend/antdx/sources/sources.tsx#L1-L5) +- [backend/modelscope_studio/components/antdx/components.py:30-31](file://backend/modelscope_studio/components/antdx/components.py#L30-L31) + +## Performance Considerations + +The Sources component was designed with performance optimization in mind: + +### Render Optimization + +1. **Memoization**: Uses React's useMemo to cache computation results and avoid unnecessary re-renders +2. **Conditional rendering**: Only renders component content when needed +3. **Lazy loading**: Delays content loading through an event-driven approach + +### Memory Management + +1. **Component unmounting**: Properly handles the mounting and unmounting process +2. **Event cleanup**: Cleans up event listeners when the component is destroyed +3. **State management**: Uses a minimal state update strategy + +### Data Processing Optimization + +1. **Batch updates**: Supports batch data source updates +2. **Incremental rendering**: Only updates the parts that have changed +3. **Virtualization support**: Provides virtualized rendering capability for large data source sets + +## Troubleshooting Guide + +### Common Issues and Solutions + +**Issue 1: Component not displaying** + +- Check whether the Ant Design X dependency is correctly installed +- Confirm that the frontend directory path resolution is correct +- Verify the component's visibility property setting + +**Issue 2: Events not responding** + +- Confirm that event listeners are correctly bound +- Check parameter passing in event callback functions +- Verify the component's event handling logic + +**Issue 3: Slot content not displaying** + +- Check whether the slot name is correct +- Confirm the method of passing slot content +- Verify the rendering priority of slots + +**Issue 4: Performance issues** + +- Check the number and complexity of data sources +- Optimize the rendering logic of data sources +- Consider using virtualized rendering + +**Section sources** + +- [docs/components/antdx/sources/demos/basic.py:1-46](file://docs/components/antdx/sources/demos/basic.py#L1-L46) + +## Conclusion + +The Sources component is a well-designed, fully functional component that successfully combines the powerful capabilities of Ant Design X with the ModelScope Studio ecosystem. The component has the following advantages: + +1. **Clear architecture**: Layered design with clear responsibilities +2. **Strong extensibility**: Supports rich configuration options and slot system +3. **Excellent performance**: Ensures good performance through multiple optimization techniques +4. **Easy to use**: Provides an intuitive API and complete documentation support + +This component is particularly suitable for displaying references, managing link sources, and similar scenarios in AI chat applications, providing developers with powerful data source display capabilities. Through reasonable event handling and the slot system, developers can easily customize the behavior and appearance of the component to meet various complex business requirements. diff --git a/.wiki/en/Ant Design X Components/Data Components/Think Component.md b/.wiki/en/Ant Design X Components/Data Components/Think Component.md new file mode 100644 index 00000000..01c4c113 --- /dev/null +++ b/.wiki/en/Ant Design X Components/Data Components/Think Component.md @@ -0,0 +1,457 @@ +# Think Component + + +**Files Referenced in This Document** +- [think/__init__.py](file://backend/modelscope_studio/components/antdx/think/__init__.py) +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [think.tsx](file://frontend/antdx/think/think.tsx) +- [Index.svelte](file://frontend/antdx/think/Index.svelte) +- [thought-chain.tsx](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [context.ts](file://frontend/antdx/thought-chain/context.ts) +- [__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) + +## Introduction + +The Think component is a core visualization component in ModelScope Studio for visualizing and tracking the thinking process of AI agents. Built on top of Ant Design X's Think component, it is specifically designed to display the reasoning process, decision chain, and intermediate thinking results of agents in conversational systems. + +The main design philosophy of this component is to provide transparent visualization of AI decision-making processes, allowing users to understand how AI agents think, analyze, and make decisions. Through detailed recording and display of the thinking process, users can better trust and optimize the behavior of AI systems. + +## Project Structure + +The Think component is located in the antdx component library within the project architecture, adopting a frontend/backend separated design pattern: + +```mermaid +graph TB +subgraph "Backend Layer" +Backend[ModelScope Studio Backend] +ThinkPy[Think Python Component] +ComponentsPy[Component Registration] +end +subgraph "Frontend Layer" +Frontend[ModelScope Studio Frontend] +ThinkTSX[Think TypeScript Component] +IndexSvelte[Think Svelte Wrapper] +ThoughtChain[ThoughtChain Component] +end +subgraph "External Dependencies" +AntDX[Ant Design X] +Gradio[Gradio Framework] +end +Backend --> ThinkPy +ThinkPy --> ComponentsPy +Frontend --> ThinkTSX +ThinkTSX --> IndexSvelte +IndexSvelte --> AntDX +ComponentsPy --> Frontend +Gradio --> Backend +``` + +**Diagram sources** + +- [think/**init**.py:1-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L1-L79) +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +**Section sources** + +- [think/**init**.py:1-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L1-L79) +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## Core Components + +### Think Component Class Definition + +The Think component inherits from `ModelScopeLayoutComponent`, providing complete property configuration and event handling: + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++visible : bool ++elem_id : str ++elem_classes : list[str] ++elem_style : dict ++render : bool ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdXThink { ++additional_props : dict ++icon : str ++styles : dict ++class_names : dict ++loading : str|bool ++title : str ++root_class_name : str ++default_expanded : bool ++expanded : bool ++blink : bool ++EVENTS : list ++SLOTS : list ++FRONTEND_DIR : str ++skip_api : bool +} +class Think { ++slots : dict ++props : ThinkProps ++loading : ReactNode ++icon : ReactNode ++title : ReactNode +} +ModelScopeLayoutComponent <|-- AntdXThink +AntdXThink --> Think : "Frontend rendering" +``` + +**Diagram sources** + +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +### Key Property Configuration + +The Think component supports rich configuration options, including: + +- **Basic properties**: Icon, title, style class names +- **State properties**: Loading state, expanded state, blink effect +- **Event properties**: Expand event binding +- **Slot system**: Supports three slots: loading, icon, title + +**Section sources** + +- [think/**init**.py:21-60](file://backend/modelscope_studio/components/antdx/think/__init__.py#L21-L60) +- [think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +## Architecture Overview + +The Think component adopts a layered architecture design, achieving clear separation between frontend and backend: + +```mermaid +sequenceDiagram +participant User as User Interface +participant Backend as Backend Think Component +participant Frontend as Frontend Wrapper +participant AntDX as Ant Design X +participant React as React Component +User->>Backend : Create Think component instance +Backend->>Backend : Configure component properties +Backend->>Frontend : Render frontend wrapper +Frontend->>AntDX : Load Ant Design X Think +AntDX->>React : Render React component +React->>React : Process slot content +React->>User : Display thinking process +Note over Backend,React : Complete component lifecycle management +``` + +**Diagram sources** + +- [Index.svelte:10-67](file://frontend/antdx/think/Index.svelte#L10-L67) +- [think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +### Component Lifecycle + +```mermaid +flowchart TD +Start([Component Initialization]) --> Config[Configure properties] +Config --> Render[Render frontend wrapper] +Render --> LoadAntDX[Load Ant Design X] +LoadAntDX --> ProcessSlots[Process slot content] +ProcessSlots --> Display[Display thinking process] +Display --> EventBind[Bind event listeners] +EventBind --> Ready[Component ready] +Ready --> UserInteraction[User interaction] +UserInteraction --> UpdateState[Update state] +UpdateState --> ReRender[Re-render] +ReRender --> Ready +Ready --> Cleanup[Component destruction] +Cleanup --> End([End]) +``` + +**Diagram sources** + +- [think/**init**.py:12-16](file://backend/modelscope_studio/components/antdx/think/__init__.py#L12-L16) +- [Index.svelte:55-68](file://frontend/antdx/think/Index.svelte#L55-L68) + +## Detailed Component Analysis + +### Backend Implementation Analysis + +The backend Think component implements the complete Gradio component interface: + +#### Event System + +The component supports the expand event for handling changes in expanded state: + +```mermaid +stateDiagram-v2 +[*] --> Collapsed : Default collapsed state +Collapsed --> Expanded : Trigger expand event +Expanded --> Collapsed : User clicks to collapse +Collapsed --> Blinking : Set blink property +Blinking --> Collapsed : Blink effect ends +note right of Expanded +In the expanded state, the thinking process +can be viewed in detail +end note +note right of Blinking +The blink effect is used to attract attention, +typically indicating a new thinking process +end note +``` + +**Diagram sources** + +- [think/**init**.py:12-16](file://backend/modelscope_studio/components/antdx/think/__init__.py#L12-L16) + +#### Slot System + +The component supports three slots, allowing flexible content customization: + +| Slot Name | Type | Purpose | Default Value | +| --------- | --------- | ------------------------ | ------------- | +| loading | ReactNode | Custom loading indicator | props.loading | +| icon | ReactNode | Custom icon | props.icon | +| title | ReactNode | Custom title content | props.title | + +**Section sources** + +- [think/**init**.py:18-19](file://backend/modelscope_studio/components/antdx/think/__init__.py#L18-L19) +- [think.tsx:12-16](file://frontend/antdx/think/think.tsx#L12-L16) + +### Frontend Implementation Analysis + +The frontend uses a hybrid architecture of Svelte + React: + +#### Svelte Wrapper + +Index.svelte provides complete component wrapping functionality: + +```mermaid +classDiagram +class IndexSvelte { ++props : ComponentProps ++slots : Slots ++proceedProps : ProcessedProps ++AwaitedThink : ComponentPromise ++getProps() ++getSlots() ++processProps() +} +class ThinkWrapper { ++style : CSSProperties ++className : string ++id : string ++slots : dict ++children : ReactNode +} +IndexSvelte --> ThinkWrapper : "Render" +ThinkWrapper --> AntDThink : "Contains" +``` + +**Diagram sources** + +- [Index.svelte:12-67](file://frontend/antdx/think/Index.svelte#L12-L67) + +#### React Component Bridge + +think.tsx implements the bridge from Svelte to React: + +- Uses `sveltify` to convert React components to Svelte components +- Handles slot content through `ReactSlot` +- Directly calls Ant Design X's native Think component + +**Section sources** + +- [Index.svelte:1-69](file://frontend/antdx/think/Index.svelte#L1-L69) +- [think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +### ThoughtChain Integration + +The Think component and the ThoughtChain component form a complete thinking process visualization system: + +```mermaid +graph LR +subgraph "Thinking Process" +Think[Think Component] +ThoughtChain[ThoughtChain Component] +end +subgraph "Data Flow" +Items[Thinking Item List] +Status[State Management] +Timeline[Timeline] +end +subgraph "UI Display" +ChainView[Chain View] +DetailView[Detail View] +TimelineView[Timeline View] +end +Think --> Items +ThoughtChain --> Items +Items --> Status +Status --> Timeline +Timeline --> ChainView +Timeline --> DetailView +Timeline --> TimelineView +``` + +**Diagram sources** + +- [thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [context.ts:1-7](file://frontend/antdx/thought-chain/context.ts#L1-L7) + +**Section sources** + +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [context.ts:1-7](file://frontend/antdx/thought-chain/context.ts#L1-L7) + +## Dependency Analysis + +### Component Dependency Diagram + +```mermaid +graph TB +subgraph "Core Dependencies" +Gradio[Gradio Framework] +AntD[Ant Design X] +Svelte[Svelte Framework] +end +subgraph "Internal Dependencies" +Utils[Development Utilities] +Layout[Layout Component] +Slot[Slot System] +end +subgraph "Think Component" +ThinkPy[Python Component] +ThinkTSX[TypeScript Component] +ThinkSvelte[Svelte Wrapper] +end +Gradio --> ThinkPy +AntD --> ThinkTSX +Svelte --> ThinkSvelte +Utils --> ThinkPy +Layout --> ThinkPy +Slot --> ThinkTSX +ThinkPy --> ThinkTSX +ThinkTSX --> ThinkSvelte +``` + +**Diagram sources** + +- [components.py:34-34](file://backend/modelscope_studio/components/antdx/components.py#L34-L34) +- [**init**.py:34-34](file://backend/modelscope_studio/components/antdx/__init__.py#L34-L34) + +### Version Compatibility + +The component ensures compatibility with the following versions: + +- **Gradio**: >= 4.0.0 +- **Ant Design X**: >= 0.1.0 +- **Svelte**: >= 3.54.0 +- **React**: >= 18.0.0 + +**Section sources** + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## Performance Considerations + +### Render Optimization + +1. **Lazy loading mechanism**: The frontend uses dynamic imports to reduce initial load time +2. **Conditional rendering**: Only renders the component when visible, avoiding unnecessary computation +3. **Slot optimization**: Efficiently handles slot content through ReactSlot + +### Memory Management + +- Automatically cleans up event listeners when the component is destroyed +- Proper props handling to avoid memory leaks +- Uses useMemo to optimize rendering of complex data structures + +## Troubleshooting Guide + +### Common Issues and Solutions + +#### Component Not Displaying + +**Symptom**: The Think component is created successfully but does not appear in the interface + +**Possible Causes**: + +1. The `visible` property is set to False +2. The `render` property is set to False +3. Parent container style issues + +**Solutions**: + +- Check the component's `visible` and `render` properties +- Verify the parent container's CSS styles +- Confirm the component is imported correctly + +#### Slot Content Not Working + +**Symptom**: Custom loading, icon, title slot content is not displayed + +**Possible Causes**: + +1. Incorrect slot name +2. Slot content type mismatch +3. Incorrect slot passing method + +**Solutions**: + +- Confirm the slot names are 'loading', 'icon', or 'title' +- Verify that slot content is a valid ReactNode +- Check the slot passing syntax + +#### Event Handling Abnormal + +**Symptom**: The expand event cannot be triggered normally + +**Possible Causes**: + +1. Event listener not correctly bound +2. Event callback function error +3. Component state issue + +**Solutions**: + +- Check the EVENTS array configuration +- Verify the event callback function logic +- Confirm component state synchronization + +**Section sources** + +- [think/**init**.py:12-16](file://backend/modelscope_studio/components/antdx/think/__init__.py#L12-L16) + +## Conclusion + +As a core visualization component of ModelScope Studio, the Think component successfully achieves transparent display of AI thinking processes. Through carefully designed architecture and rich configuration options, this component provides developers and users with powerful thinking process tracking capabilities. + +### Main Advantages + +1. **Complete visualization**: Provides various thinking process display methods from simple to complex +2. **Flexible configuration**: Supports rich property configuration and slot customization +3. **Good performance**: Uses modern frontend technology stack to ensure a smooth user experience +4. **Easy to integrate**: Seamlessly integrates with the Gradio ecosystem + +### Application Scenarios + +- **AI assistants**: Display the reasoning process and decision chain of agents +- **Data analysis**: Visualize data exploration and analysis thinking +- **Code generation**: Display the thinking process and logic of code generation +- **Multimodal applications**: Support thinking processes for various input types such as text and images + +This component lays a solid foundation for building trustworthy and explainable AI applications and is an indispensable important component of modern AI products. diff --git a/.wiki/en/Ant Design X Components/Expression Components/Attachments Component.md b/.wiki/en/Ant Design X Components/Expression Components/Attachments Component.md new file mode 100644 index 00000000..3a7966c7 --- /dev/null +++ b/.wiki/en/Ant Design X Components/Expression Components/Attachments Component.md @@ -0,0 +1,731 @@ +# Attachments Component + + +**Files Referenced in This Document** +- [Index.svelte](file://frontend/antdx/attachments/Index.svelte) +- [attachments.tsx](file://frontend/antdx/attachments/attachments.tsx) +- [__init__.py](file://backend/modelscope_studio/components/antdx/attachments/__init__.py) +- [README-zh_CN.md](file://docs/components/antdx/attachments/README-zh_CN.md) +- [basic.py](file://docs/components/antdx/attachments/demos/basic.py) +- [combination.py](file://docs/components/antdx/attachments/demos/combination.py) +- [file_card.py](file://docs/components/antdx/attachments/demos/file_card.py) +- [multimodal-input.tsx](file://frontend/pro/multimodal-input/multimodal-input.tsx) +- [upload.ts](file://frontend/utils/upload.ts) +- [file-card.tsx](file://frontend/antdx/file-card/file-card.tsx) +- [base.tsx](file://frontend/antdx/file-card/base.tsx) +- [app.py](file://docs/components/antdx/attachments/app.py) +- [package.json](file://frontend/antdx/attachments/package.json) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +The Attachments component is a powerful file management and upload solution provided by ModelScope Studio. Built on top of Ant Design X's Attachments component, it provides complete file upload, preview, management, and deletion capabilities. + +### Key Features + +- **Multi-format Support**: Supports uploading and previewing of multiple file types including images, documents, audio, and video +- **Drag and Drop Upload**: Provides an intuitive drag-and-drop file upload experience +- **Batch Management**: Supports simultaneous upload and management of multiple files +- **Real-time Preview**: Built-in file preview functionality with thumbnail and full-content viewing +- **Flexible Configuration**: Rich configuration options and customization capabilities +- **Responsive Design**: Adapts to various screen sizes and devices + +## Project Structure + +The Attachments component adopts a frontend-backend separation architecture, primarily consisting of the following parts: + +```mermaid +graph TB +subgraph "Frontend Layer" +A[Index.svelte
Component Entry] +B[attachments.tsx
Core Implementation] +C[file-card.tsx
File Card Component] +D[base.tsx
Base File Card] +E[multimodal-input.tsx
Multimodal Input Integration] +end +subgraph "Backend Layer" +F[__init__.py
Python Component Wrapper] +end +subgraph "Utility Layer" +G[upload.ts
File URL Handling] +H[package.json
Package Config] +end +A --> B +B --> C +C --> D +B --> G +F --> A +E --> B +``` + +**Diagram Sources** + +- [Index.svelte:1-98](file://frontend/antdx/attachments/Index.svelte#L1-L98) +- [attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [**init**.py:21-64](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L21-L64) + +**Section Sources** + +- [Index.svelte:1-98](file://frontend/antdx/attachments/Index.svelte#L1-L98) +- [attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [**init**.py:21-64](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L21-L64) + +## Core Components + +### Component Architecture + +The Attachments component uses a layered architecture design ensuring good maintainability and extensibility: + +```mermaid +classDiagram +class Attachments { ++FileData[] items ++upload(files) Promise~FileData[]~ ++onValueChange(value) void ++onChange(value) void ++disabled boolean ++maxCount number ++imageProps ImageProps ++placeholder Function|Object ++showUploadList Object|boolean ++beforeUpload Function ++customRequest Function ++previewFile Function ++isImageUrl Function ++itemRender Function ++iconRender Function ++data Object|Function ++getDropContainer Function +} +class FileCard { ++BaseFileCardProps props ++imageProps ImageProps ++description ReactNode ++icon ReactNode ++mask ReactNode ++spinProps SpinProps ++children ReactNode +} +class BaseFileCard { ++string|FileData src ++string rootUrl ++string apiPrefix ++resolveFileSrc() string +} +class UploadUtils { ++getFetchableUrl() string ++getFileUrl() string|undefined ++isUrl() boolean +} +Attachments --> FileCard : "renders" +FileCard --> BaseFileCard : "inherits" +Attachments --> UploadUtils : "uses" +``` + +**Diagram Sources** + +- [attachments.tsx:36-83](file://frontend/antdx/attachments/attachments.tsx#L36-L83) +- [file-card.tsx:17-34](file://frontend/antdx/file-card/file-card.tsx#L17-L34) +- [base.tsx:9-13](file://frontend/antdx/file-card/base.tsx#L9-L13) +- [upload.ts:12-44](file://frontend/utils/upload.ts#L12-L44) + +### Data Flow Processing + +The component internally implements a complex data flow processing mechanism: + +```mermaid +sequenceDiagram +participant U as User +participant A as Attachments Component +participant P as Preview System +participant S as Server +participant V as Validator +U->>A : Select/drag files +A->>V : Call beforeUpload validation +V-->>A : Validation result +A->>A : Update temporary file list +A->>S : Call upload function +S-->>A : Return FileData array +A->>A : Merge file list +A->>P : Render preview +P-->>U : Display file preview +U->>A : Delete file +A->>S : Send delete request +S-->>A : Confirm deletion +A->>A : Update state +``` + +**Diagram Sources** + +- [attachments.tsx:275-354](file://frontend/antdx/attachments/attachments.tsx#L275-L354) + +**Section Sources** + +- [attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) + +## Architecture Overview + +### Overall Architecture Design + +The Attachments component uses a modern frontend architecture pattern combining the advantages of React and Svelte: + +```mermaid +graph TD +subgraph "User Interface Layer" +UI[User Interface] +SL[Svelte Component] +RC[React Component] +end +subgraph "Business Logic Layer" +AM[Attachment Manager] +VM[View Model] +CM[Configuration Manager] +end +subgraph "Data Access Layer" +FS[File System] +CS[Cloud Storage] +LS[Local Storage] +end +subgraph "Utility Service Layer" +PU[Preview Service] +US[Upload Service] +VS[Validation Service] +end +UI --> SL +SL --> RC +RC --> AM +AM --> VM +AM --> CM +AM --> FS +AM --> CS +AM --> LS +AM --> PU +AM --> US +AM --> VS +``` + +**Diagram Sources** + +- [Index.svelte:1-98](file://frontend/antdx/attachments/Index.svelte#L1-L98) +- [attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) + +### Component Lifecycle + +```mermaid +stateDiagram-v2 +[*] --> Initializing +Initializing --> LoadingConfig +LoadingConfig --> RenderingUI +RenderingUI --> WaitingForInteraction +WaitingForInteraction --> FileUpload +FileUpload --> ValidatingFile +ValidatingFile --> Uploading +Uploading --> UploadComplete +UploadComplete --> RenderingPreview +RenderingPreview --> WaitingForInteraction +WaitingForInteraction --> FileDeletion +FileDeletion --> DeletionConfirm +DeletionConfirm --> UpdatingState +UpdatingState --> WaitingForInteraction +WaitingForInteraction --> ErrorHandling +ErrorHandling --> WaitingForInteraction +WaitingForInteraction --> [*] +``` + +**Diagram Sources** + +- [attachments.tsx:132-354](file://frontend/antdx/attachments/attachments.tsx#L132-L354) + +## Detailed Component Analysis + +### Core Functionality Implementation + +#### File Upload Mechanism + +The component implements a complete file upload flow supporting multiple upload strategies: + +```mermaid +flowchart TD +Start([Start Upload]) --> Validate[Validate File] +Validate --> Valid{Validation Passed?} +Valid --> |No| Error[Return Error] +Valid --> |Yes| Prepare[Prepare Upload] +Prepare --> Upload[Execute Upload] +Upload --> Progress[Update Progress] +Progress --> Complete{Upload Complete?} +Complete --> |No| Progress +Complete --> |Yes| Process[Process Response] +Process --> Success[Upload Success] +Success --> End([End]) +Error --> End +``` + +**Diagram Sources** + +- [attachments.tsx:292-354](file://frontend/antdx/attachments/attachments.tsx#L292-L354) + +#### File Preview System + +The component integrates powerful file preview functionality supporting visualization of multiple file types: + +| File Type | Preview Support | Special Features | +| --------- | ----------------------- | ---------------------------- | +| Image | ✅ Full Preview | Zoom, rotate, download | +| Document | ✅ Thumbnail Preview | Online view, download | +| PDF | ✅ Page-by-page Preview | Navigation, search | +| Audio | ✅ Player | Playback control, volume | +| Video | ✅ Player | Playback control, fullscreen | +| Archive | ✅ Thumbnail | Extract preview | + +#### Batch Management Features + +The component provides efficient batch file management capabilities: + +```mermaid +graph LR +subgraph "Batch Operations" +BA[Batch Select] +BM[Batch Delete] +BC[Batch Download] +BR[Batch Rename] +end +subgraph "State Management" +FS[File State] +SS[Selection State] +PS[Processing State] +end +BA --> SS +BM --> FS +BC --> FS +BR --> FS +SS --> PS +FS --> PS +``` + +**Diagram Sources** + +- [attachments.tsx:304-342](file://frontend/antdx/attachments/attachments.tsx#L304-L342) + +**Section Sources** + +- [attachments.tsx:275-409](file://frontend/antdx/attachments/attachments.tsx#L275-L409) + +### Configuration Options + +#### Basic Configuration + +| Option | Type | Default | Description | +| ---------------- | ----------------- | -------- | --------------------------------------- | +| `disabled` | boolean | false | Whether to disable upload functionality | +| `maxCount` | number | Infinity | Maximum number of files | +| `multiple` | boolean | true | Whether to support multi-file upload | +| `accept` | string | \* | Accepted file types | +| `showUploadList` | boolean \| object | true | Whether to show the upload list | + +#### Advanced Configuration + +| Option | Type | Default | Description | +| --------------- | -------- | ------- | --------------------------------- | +| `beforeUpload` | Function | - | Validation function before upload | +| `customRequest` | Function | - | Custom upload request | +| `previewFile` | Function | - | Custom file preview | +| `isImageUrl` | Function | - | Determine if it is an image URL | +| `itemRender` | Function | - | Custom file item rendering | +| `iconRender` | Function | - | Custom icon rendering | + +#### Preview Configuration + +| Option | Type | Default | Description | +| ---------------------------------- | --------- | ------- | ------------------------ | +| `imageProps.preview.mask` | ReactNode | - | Preview mask layer | +| `imageProps.preview.closeIcon` | ReactNode | - | Close button icon | +| `imageProps.preview.toolbarRender` | Function | - | Custom toolbar rendering | +| `imageProps.preview.imageRender` | Function | - | Custom image rendering | + +**Section Sources** + +- [attachments.tsx:36-83](file://frontend/antdx/attachments/attachments.tsx#L36-L83) + +### Event Callback Mechanism + +The component provides a rich event callback interface: + +```mermaid +sequenceDiagram +participant C as Caller +participant A as Attachments Component +participant H as Callback Handler +C->>A : Bind event listeners +A->>H : Register callback functions +Note over A,H : User interaction triggers events +A->>H : Trigger onChange event +H-->>A : Return processing result +A->>H : Trigger onRemove event +H-->>A : Return processing result +A->>H : Trigger onValueChange event +H-->>A : Return processing result +``` + +**Diagram Sources** + +- [**init**.py:27-43](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L27-L43) + +#### Event Types + +| Event Name | Trigger Timing | Parameters | Description | +| ---------- | ------------------ | ---------- | ---------------------------------------------- | +| `change` | File state changes | FileData[] | Triggered when the file list changes | +| `remove` | File deleted | FileData | Triggered when a file is deleted | +| `preview` | File preview | FileData | Triggered when a file starts previewing | +| `download` | File download | FileData | Triggered when a file starts downloading | +| `drop` | File dragged | FileData[] | Triggered when files are dragged into the area | + +**Section Sources** + +- [**init**.py:27-43](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L27-L43) + +### Error Handling Mechanism + +The component implements a comprehensive error handling system: + +```mermaid +flowchart TD +Start([Start Processing]) --> Try[Execute Operation] +Try --> Success{Operation Successful?} +Success --> |Yes| Complete[Complete Processing] +Success --> |No| Catch[Catch Error] +Catch --> Type{Error Type?} +Type --> |Network Error| Network[Handle Network Error] +Type --> |Permission Error| Auth[Handle Permission Error] +Type --> |Format Error| Format[Handle Format Error] +Type --> |Size Error| Size[Handle Size Error] +Type --> |Other Error| Other[Handle Other Error] +Network --> Retry[Retry Mechanism] +Auth --> Login[Re-login] +Format --> Fix[Fix Format] +Size --> Reduce[Reduce File Size] +Other --> Report[Report Issue] +Retry --> Try +Login --> Try +Fix --> Try +Reduce --> Try +Report --> End([End]) +Complete --> End +``` + +**Diagram Sources** + +- [attachments.tsx:350-354](file://frontend/antdx/attachments/attachments.tsx#L350-L354) + +**Section Sources** + +- [attachments.tsx:350-354](file://frontend/antdx/attachments/attachments.tsx#L350-L354) + +## Dependency Analysis + +### External Dependencies + +The component depends on several key external libraries: + +```mermaid +graph TB +subgraph "Core Dependencies" +AX[@ant-design/x
Ant Design X Component Library] +ANTD[antd
Ant Design Component Library] +GRADIO[@gradio/client
Gradio Client] +REACT[react
React Framework] +end +subgraph "Utility Libraries" +Lodash[lodash-es
Utility Functions] +Classnames[classnames
Class Name Handling] +SveltePreprocess[svelte-preprocess-react
Svelte Preprocessing] +end +subgraph "Component Dependencies" +FileCard[FileCard Component] +Utils[Utility Functions] +Hooks[React Hooks] +end +Attachments --> AX +Attachments --> ANTD +Attachments --> GRADIO +Attachments --> REACT +Attachments --> Lodash +Attachments --> Classnames +Attachments --> SveltePreprocess +Attachments --> FileCard +Attachments --> Utils +Attachments --> Hooks +``` + +**Diagram Sources** + +- [attachments.tsx:1-17](file://frontend/antdx/attachments/attachments.tsx#L1-L17) +- [package.json:1-15](file://frontend/antdx/attachments/package.json#L1-L15) + +### Internal Module Dependencies + +```mermaid +graph TD +subgraph "Frontend Modules" +A[Index.svelte] +B[attachments.tsx] +C[file-card.tsx] +D[base.tsx] +E[upload.ts] +F[multimodal-input.tsx] +end +subgraph "Backend Modules" +G[__init__.py] +end +A --> B +B --> C +C --> D +B --> E +F --> B +G --> A +``` + +**Diagram Sources** + +- [Index.svelte:1-98](file://frontend/antdx/attachments/Index.svelte#L1-L98) +- [attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) + +**Section Sources** + +- [package.json:1-15](file://frontend/antdx/attachments/package.json#L1-L15) +- [Index.svelte:1-98](file://frontend/antdx/attachments/Index.svelte#L1-L98) + +## Performance Considerations + +### Upload Performance Optimization + +The component was designed with performance optimization in mind: + +- **Concurrent Upload Control**: Limit the number of simultaneously uploading files via `maxCount` +- **Progress Display**: Display upload progress in real time to improve user experience +- **Memory Management**: Clean up temporary file data promptly to avoid memory leaks +- **Caching Strategy**: Cache already-uploaded files to reduce redundant uploads + +### Preview Performance Optimization + +```mermaid +graph LR +subgraph "Preview Optimization Strategies" +A[Lazy Loading Preview] +B[Thumbnail Generation] +C[Virtual Scrolling] +D[Preloading Mechanism] +end +subgraph "Performance Metrics" +E[Initial Load Time] +F[Memory Usage] +G[CPU Utilization] +H[Network Bandwidth] +end +A --> E +B --> F +C --> G +D --> H +``` + +### Memory Management + +The component implements intelligent memory management: + +- **File Object Reuse**: Reuse existing file objects to avoid redundant creation +- **Garbage Collection**: Release file data that is no longer in use in a timely manner +- **State Synchronization**: Maintain consistency between local state and server state + +## Troubleshooting Guide + +### Common Issues and Solutions + +#### Upload Failure + +**Problem Description**: Error occurs during file upload + +**Possible Causes**: + +- Unstable network connection +- Unsupported file format +- File size exceeds limit +- Insufficient permissions + +**Solutions**: + +1. Check network connection status +2. Verify file format is in the `accept` list +3. Confirm file size does not exceed `maxSize` limit +4. Check user permission settings + +#### Preview Failure + +**Problem Description**: File cannot be previewed normally + +**Possible Causes**: + +- Browser compatibility issues +- File corruption +- URL parsing error + +**Solutions**: + +1. Try opening in a different browser +2. Re-upload the file +3. Check file integrity +4. Verify URL format is correct + +#### Performance Issues + +**Problem Description**: Component runs slowly or stutters + +**Possible Causes**: + +- Too many files +- Files are too large +- Insufficient memory + +**Solutions**: + +1. Reduce the number of simultaneously uploading files +2. Optimize file sizes +3. Increase system memory +4. Use `maxCount` to limit the number of files + +**Section Sources** + +- [attachments.tsx:350-354](file://frontend/antdx/attachments/attachments.tsx#L350-L354) + +### Debugging Tips + +#### Enable Debug Mode + +```javascript +// Enable detailed logging in development environment +const attachments = new Attachments({ + debug: true, + // other configs... +}); +``` + +#### Monitor Upload Progress + +```javascript +attachments.on('upload-progress', (progress) => { + console.log(`Upload progress: ${progress}%`); +}); +``` + +## Conclusion + +The Attachments component is a fully functional, high-performance file management solution. It not only provides basic file upload and preview capabilities, but also features advanced batch management, custom configuration, and error handling. + +### Key Advantages + +1. **Comprehensive Features**: Covers all core needs for file upload, preview, and management +2. **Easy to Use**: Clean API design for quick integration +3. **Highly Customizable**: Rich configuration options to meet various use cases +4. **Excellent Performance**: Optimized algorithms and architecture ensure a smooth user experience +5. **Stable and Reliable**: Comprehensive error handling and exception recovery mechanisms + +### Applicable Scenarios + +- Online document management systems +- File transfer in instant messaging applications +- Media management on content creation platforms +- File sharing on enterprise collaboration platforms +- Assignment submission systems on educational platforms + +## Appendix + +### API Reference + +#### Props + +| Property | Type | Required | Default | Description | +| ---------------- | ----------------- | -------- | -------- | -------------------------------------------------------- | +| `items` | FileData[] | Yes | [] | Current file list | +| `upload` | Function | Yes | - | Upload function, accepts RcFile[] and returns FileData[] | +| `onValueChange` | Function | No | - | Value change callback | +| `onChange` | Function | No | - | String path change callback | +| `disabled` | boolean | No | false | Whether to disable | +| `maxCount` | number | No | Infinity | Maximum number of files | +| `accept` | string | No | \* | Accepted file types | +| `multiple` | boolean | No | true | Whether multi-select is supported | +| `showUploadList` | boolean \| object | No | true | Whether to show the upload list | +| `imageProps` | ImageProps | No | - | Image preview configuration | + +#### Events + +| Event Name | Parameters | Description | +| ---------- | ---------- | --------------------- | +| `change` | FileData[] | File list changed | +| `remove` | FileData | File deleted | +| `preview` | FileData | File preview started | +| `download` | FileData | File download started | +| `drop` | FileData[] | File dragged | + +#### Slots + +| Slot Name | Parameters | Description | +| ---------------------------------- | ------------------------ | -------------------------- | +| `placeholder` | type: 'drop' \| 'inline' | Placeholder content | +| `placeholder.title` | type | Title content | +| `placeholder.description` | type | Description content | +| `placeholder.icon` | type | Icon content | +| `iconRender` | file, fileList | Custom icon rendering | +| `itemRender` | file, fileList | Custom file item rendering | +| `showUploadList.previewIcon` | file, fileList | Preview icon | +| `showUploadList.removeIcon` | file, fileList | Delete icon | +| `showUploadList.downloadIcon` | file, fileList | Download icon | +| `showUploadList.extra` | file, fileList | Extra actions | +| `imageProps.placeholder` | file, fileList | Image placeholder | +| `imageProps.preview.mask` | file, fileList | Preview mask | +| `imageProps.preview.closeIcon` | file, fileList | Close icon | +| `imageProps.preview.toolbarRender` | file, fileList | Toolbar rendering | +| `imageProps.preview.imageRender` | file, fileList | Image rendering | + +### Best Practices + +#### Performance Optimization Recommendations + +1. **Set `maxCount` Appropriately**: Set a suitable maximum file count based on the application scenario +2. **Use Lazy Loading**: For large numbers of files, consider pagination or virtual scrolling +3. **Optimize File Sizes**: Compress images and video files before upload +4. **Caching Strategy**: Establish a caching mechanism for frequently used files + +#### Security Considerations + +1. **File Type Validation**: Also perform file type checking on the server side +2. **Size Limits**: Set reasonable file size upper limits +3. **Virus Scanning**: Perform security scanning on uploaded files +4. **Permission Control**: Ensure only authorized users can access files + +#### User Experience Optimization + +1. **Progress Feedback**: Provide clear upload progress indicators +2. **Error Messages**: Friendly error messages and solutions +3. **Batch Operations**: Support batch selection and operations +4. **Responsive Design**: Adapt to various devices and screen sizes + +**Section Sources** + +- [README-zh_CN.md:1-10](file://docs/components/antdx/attachments/README-zh_CN.md#L1-L10) +- [basic.py:1-51](file://docs/components/antdx/attachments/demos/basic.py#L1-L51) +- [combination.py:1-75](file://docs/components/antdx/attachments/demos/combination.py#L1-L75) +- [file_card.py:1-72](file://docs/components/antdx/attachments/demos/file_card.py#L1-L72) diff --git a/.wiki/en/Ant Design X Components/Expression Components/Expression Components.md b/.wiki/en/Ant Design X Components/Expression Components/Expression Components.md new file mode 100644 index 00000000..b0bd77fb --- /dev/null +++ b/.wiki/en/Ant Design X Components/Expression Components/Expression Components.md @@ -0,0 +1,322 @@ +# Expression Components + + +**Files Referenced in This Document** +- [frontend/antdx/attachments/attachments.tsx](file://frontend/antdx/attachments/attachments.tsx) +- [frontend/antdx/sender/sender.tsx](file://frontend/antdx/sender/sender.tsx) +- [frontend/antdx/suggestion/suggestion.tsx](file://frontend/antdx/suggestion/suggestion.tsx) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance and Usability Recommendations](#performance-and-usability-recommendations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Usage Examples and Best Practices](#appendix-usage-examples-and-best-practices) + +## Introduction + +This document covers the Ant Design X Expression Components, focusing on three main components: + +- Attachments: Responsible for file upload, preview, list management, and placeholder rendering +- Sender: Responsible for message input, paste-to-upload, submission, and input state synchronization +- Suggestion: Responsible for command completion, trigger strategies, context forwarding, and popup container configuration + +The documentation provides a complete explanation from system architecture, data flow, processing logic, and inter-component collaboration mechanisms to usage examples and troubleshooting recommendations, helping developers quickly understand and correctly integrate these components. + +## Project Structure + +The frontend components of Ant Design X are located under frontend/antdx and are organized in a modular fashion. The backend Python wrapper layer exports unified aliases in backend/modelscope_studio/components/antdx, making them directly accessible in the Python ecosystem. + +```mermaid +graph TB +subgraph "Backend Wrapper Layer" +PY_API["Python Export Aliases
components.py / __init__.py"] +end +subgraph "Frontend Ant Design X Components" +ATT["Attachments
File Upload and Management"] +SND["Sender
Message Input and Submission"] +SUG["Suggestion
Quick Commands and Completion"] +end +PY_API --> ATT +PY_API --> SND +PY_API --> SUG +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/components.py:7-32](file://backend/modelscope_studio/components/antdx/components.py#L7-L32) +- [backend/modelscope_studio/components/antdx/**init**.py:7-41](file://backend/modelscope_studio/components/antdx/__init__.py#L7-L41) + +Section Sources + +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) + +## Core Components + +- Attachments + - Responsibility: Encapsulates @ant-design/x Attachments, providing upload hooks, placeholder rendering, enhanced image preview, custom icons, max count control, remove callback, and value change notifications + - Key Capabilities: Pre-upload validation, concurrent upload state, file list deduplication and merging, error fallback +- Sender + - Responsibility: Encapsulates @ant-design/x Sender, providing two-way value binding, paste-file-upload, skill panel (skill) slot-based configuration, and submit events that only fire when the suggestion panel is closed + - Key Capabilities: Input change synchronization, paste file upload, slot-based header/footer/prefix/suffix, skill hints and closable configuration +- Suggestion + - Responsibility: Encapsulates @ant-design/x Suggestion, supporting dynamic items rendering, slot-based label/icon/extra areas, popup container customization, and controlled/uncontrolled open state switching + - Key Capabilities: Trigger strategy hooks, context forwarding, keyboard event interception and forwarding, popup container positioning + +Section Sources + +- [frontend/antdx/attachments/attachments.tsx:36-410](file://frontend/antdx/attachments/attachments.tsx#L36-L410) +- [frontend/antdx/sender/sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) +- [frontend/antdx/suggestion/suggestion.tsx:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) + +## Architecture Overview + +The three work together: the user types text in Sender and pastes files; Sender hands the files to the upload function to generate persistable file information, which is then passed back via callback to the upper layer. Meanwhile, Suggestion provides command completion; only when it is closed does Sender actually submit the content, preventing accidental submission. + +```mermaid +sequenceDiagram +participant U as "User" +participant S as "Sender" +participant A as "Attachments" +participant P as "Upload Function (upload)" +participant C as "Upper Application" +U->>S : "Input text/paste file" +S->>P : "Paste file upload" +P-->>S : "Return file info list" +S-->>C : "onPasteFile(urls)" +S-->>C : "onChange(value)" +S->>C : "onSubmit(...)" +Note over S,C : "Submit only fires when Suggestion is closed" +U->>A : "Drag/select file" +A->>P : "Call upload hook" +P-->>A : "Return file info" +A-->>C : "onValueChange(items)" +A-->>C : "onChange(paths)" +``` + +Diagram Sources + +- [frontend/antdx/sender/sender.tsx:135-138](file://frontend/antdx/sender/sender.tsx#L135-L138) +- [frontend/antdx/attachments/attachments.tsx:329-348](file://frontend/antdx/attachments/attachments.tsx#L329-L348) +- [frontend/antdx/suggestion/suggestion.tsx:135-140](file://frontend/antdx/suggestion/suggestion.tsx#L135-L140) + +## Component Details + +### Attachments Component + +- Key Features + - File Upload: Accepts arrays of native file objects via the upload hook, returns file info arrays; supports maxCount to control single/multi-file mode + - Preview Enhancement: imageProps.preview supports mask, closeIcon, toolbarRender, imageRender with slot-based and function-based configuration + - List Management: Automatic deduplication (based on uid/url/path), status marking (done/uploading), remove callback, and value change notifications + - Placeholder Rendering: placeholder supports slot-based and function-based title/description/icon + - Interaction Protection: Disables interactions during upload to prevent re-submission +- Data Flow and Key Paths + - Change Handling: The onChange handler distinguishes between add/remove branches; for additions, it first injects a temporary "uploading" state, then calls upload, and finally merges results and fires callbacks + - Image Preview: Highly customizable via getContainer, toolbarRender, imageRender, etc. in imageProps.preview + - Display List: Icons and extras in showUploadList support slot-based and function-based overrides +- Error Handling + - Captures upload exceptions and restores upload state to prevent UI freeze +- Complexity and Performance + - Deduplication and state merging are O(n), suitable for medium-scale file lists + - Slot-based rendering computes on demand, avoiding unnecessary re-renders + +```mermaid +flowchart TD +Start(["Enter onChange"]) --> IsRemove{"Is it a remove operation?"} +IsRemove --> |Yes| RemoveFlow["Execute onRemove callback
Update fileList and fire callback"] +IsRemove --> |No| AddFlow["Enter add flow"] +AddFlow --> BeforeUpload["beforeUpload hook (optional)"] +BeforeUpload --> BeforeUploadOk{"Returns true?"} +BeforeUploadOk --> |No| End(["End"]) +BeforeUploadOk --> |Yes| SetUploading["Set uploading state"] +SetUploading --> Filter["Filter incomplete files and truncate by maxCount"] +Filter --> TempList["Generate temporary uploading entries"] +TempList --> CallUpload["Call upload hook"] +CallUpload --> Merge["Merge returned file info into final list"] +Merge --> UpdateState["Update fileList and fire onValueChange/onChange"] +UpdateState --> End +``` + +Diagram Sources + +- [frontend/antdx/attachments/attachments.tsx:275-354](file://frontend/antdx/attachments/attachments.tsx#L275-L354) + +Section Sources + +- [frontend/antdx/attachments/attachments.tsx:36-410](file://frontend/antdx/attachments/attachments.tsx#L36-L410) + +### Sender Component + +- Key Features + - Input Binding: Two-way synchronization of value and onChange, supports external controlled mode + - Paste Upload: onPasteFile hands pasted file collections to the upload hook and passes back file path arrays + - Skill Panel: skill.title/toolTip/closable supports slot-based and function-based configuration + - Submit Control: onSubmit is only triggered when Suggestion is closed, preventing accidental submission when the suggestion panel is open + - Slot-based Layout: header/footer/prefix/suffix support ReactSlot injection +- Key Interactions + - Uses useSuggestionOpenContext to get the suggestion panel open/close state, determining whether to allow submission + - formatResult/customRender in slotConfig are wrapped as functions via createFunction +- Error Handling + - Paste upload failure does not affect the input box state, only logs are recorded +- Performance and Complexity + - Value changes and slot rendering are both lightweight, suitable for high-frequency input scenarios + +```mermaid +sequenceDiagram +participant U as "User" +participant S as "Sender" +participant Ctx as "Suggestion Open Context" +participant P as "Upload Function (upload)" +U->>S : "Paste file" +S->>P : "upload(files)" +P-->>S : "Return file info" +S-->>U : "onPasteFile(urls)" +U->>S : "Click submit/press Enter" +S->>Ctx : "Read suggestion panel state" +alt Suggestion panel is closed +S-->>U : "onSubmit(...)" +else Suggestion panel is open +S-->>U : "Ignore submission" +end +``` + +Diagram Sources + +- [frontend/antdx/sender/sender.tsx:126-130](file://frontend/antdx/sender/sender.tsx#L126-L130) +- [frontend/antdx/sender/sender.tsx:135-138](file://frontend/antdx/sender/sender.tsx#L135-L138) + +Section Sources + +- [frontend/antdx/sender/sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) + +### Suggestion Component + +- Key Features + - Dynamic items: Supports two sources — an items function or slot-based items/default; slot items take priority + - Slot-based Rendering: label/icon/extra/children support ReactSlot injection and patchSlots processing + - Trigger Strategy: The shouldTrigger hook can intercept keyboard events to implement custom trigger conditions + - Popup Container: getPopupContainer supports function-based and slot-based configuration for positioning in complex layouts + - State Control: open can be controlled (internally self-managed when undefined); onOpenChange forwards the underlying state +- Context and Events + - Passes the current active item and keyboard event handling to the child tree via SuggestionContext and SuggestionOpenContext + - In the children render function, the real children are hidden and only shown when a slot exists +- Performance and Complexity + - items rendering is computed on demand; slot-based patch only applies to necessary fields + +```mermaid +flowchart TD +Init(["Initialize items rendering"]) --> Resolve["Resolve items/default slots"] +Resolve --> ItemsFn["items function (optional)"] +ItemsFn --> Merge["Merge into final items array"] +Merge --> Render["Render each item's label/icon/extra subitems"] +Render --> Patch["patchSlots applies slot-based overrides"] +Patch --> Open["Control display based on open state"] +Open --> Trigger["shouldTrigger intercepts keyboard events"] +Trigger --> Done(["Complete"]) +``` + +Diagram Sources + +- [frontend/antdx/suggestion/suggestion.tsx:89-121](file://frontend/antdx/suggestion/suggestion.tsx#L89-L121) +- [frontend/antdx/suggestion/suggestion.tsx:135-140](file://frontend/antdx/suggestion/suggestion.tsx#L135-L140) + +Section Sources + +- [frontend/antdx/suggestion/suggestion.tsx:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) + +## Dependency Analysis + +- Backend Exports + - components.py and **init**.py uniformly export AntdXAttachments/AntdXSender/AntdXSuggestion and other components as Attachments/Sender/Suggestion for direct use on the Python side +- Frontend Encapsulation + - All three components bridge @ant-design/x native components via sveltify to React components supporting slots and function-based configuration + - Uses utility hooks such as useFunction/useValueChange/useTargets to achieve parameter functionalization and value synchronization +- Inter-component Coupling + - Sender and Suggestion are loosely coupled via context: Sender only submits when Suggestion is closed, avoiding interaction conflicts + - Attachments and Sender are decoupled via the upload callback: upload logic is provided by the upper layer; components only handle UI and state + +```mermaid +graph LR +PY["Python Export Aliases"] --> ATT["Frontend Attachments"] +PY --> SND["Frontend Sender"] +PY --> SUG["Frontend Suggestion"] +ATT --> AX["@ant-design/x Attachments"] +SND --> AX2["@ant-design/x Sender"] +SUG --> AX3["@ant-design/x Suggestion"] +SND -- "Suggestion panel state" --> CTX["Suggestion Open Context"] +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/components.py:7-32](file://backend/modelscope_studio/components/antdx/components.py#L7-L32) +- [backend/modelscope_studio/components/antdx/**init**.py:7-41](file://backend/modelscope_studio/components/antdx/__init__.py#L7-L41) +- [frontend/antdx/sender/sender.tsx:72-72](file://frontend/antdx/sender/sender.tsx#L72-L72) + +Section Sources + +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) + +## Performance and Usability Recommendations + +- Attachments Upload + - Set maxCount appropriately to avoid memory pressure from uploading too many files at once + - Perform format/size validation in beforeUpload to reduce invalid requests + - Use imageProps.preview's getContainer to mount the preview overlay to the appropriate container, avoiding scroll penetration +- Sender + - Use throttle/debounce strategies for high-frequency input (can be implemented in the upper layer) to reduce onChange frequency + - In multi-slot scenarios, reuse function-based configurations as much as possible to reduce slot rendering overhead +- Suggestion + - Keep the items rendering structure stable to avoid frequent DOM reconstruction + - Only perform necessary checks in shouldTrigger to avoid blocking keyboard events +- Global + - In complex layouts, prioritize using getPopupContainer for suggestion panel positioning to ensure visibility + - Provide friendly prompts for upload failures to avoid user confusion + +## Troubleshooting Guide + +- Attachments Cannot Delete + - Check whether the remove branch in onChange is being prematurely returned + - Confirm there is a matching uid entry in validFileList +- Upload Not Responding + - Confirm the upload hook return value is Promise
Component Class"] +PY_ITEM["AntdXSuggestionItem
Suggestion Item Class"] +end +subgraph "Frontend React" +FE_SUG["Suggestion
React Wrapper"] +FE_ITEM["SuggestionItem
Item Wrapper"] +CTX["context.ts
items Context"] +end +PY_SUG --> FE_SUG +PY_ITEM --> FE_ITEM +FE_SUG --> CTX +FE_ITEM --> CTX +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/suggestion/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py#L8-L68) +- [frontend/antdx/suggestion/suggestion.tsx:64-165](file://frontend/antdx/suggestion/suggestion.tsx#L64-L165) +- [frontend/antdx/suggestion/item/suggestion.item.tsx:7-22](file://frontend/antdx/suggestion/item/suggestion.item.tsx#L7-L22) +- [frontend/antdx/suggestion/context.ts:1-7](file://frontend/antdx/suggestion/context.ts#L1-L7) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/suggestion/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py#L8-L68) +- [frontend/antdx/suggestion/suggestion.tsx:64-165](file://frontend/antdx/suggestion/suggestion.tsx#L64-L165) +- [frontend/antdx/suggestion/item/suggestion.item.tsx:7-22](file://frontend/antdx/suggestion/item/suggestion.item.tsx#L7-L22) +- [frontend/antdx/suggestion/context.ts:1-7](file://frontend/antdx/suggestion/context.ts#L1-L7) + +## Core Components + +- AntdXSuggestion (Backend Component) + - Supported Events: select (item selected), open_change (panel open/close). + - Supported Slots: items, children. + - Key Properties: items (suggestion list), block (block-level display), open (controlled open/close), should_trigger (custom trigger), root style class name and inline styles, etc. + - Frontend Mapping: resolve_frontend_dir("suggestion", type="antdx"). +- AntdXSuggestionItem (Backend Suggestion Item) + - Supported Slots: label, icon, extra. + - Key Properties: value, label, extra, icon, key. + - Frontend Mapping: resolve_frontend_dir("suggestion", "item", type="antdx"). + +Both components declare skip_api=True, indicating they do not participate in the standard API flow but instead complete interactions through events and slots. + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/suggestion/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py#L8-L68) + +## Architecture Overview + +Suggestion wraps Ant Design X's Suggestion component in the frontend via React, combined with a slot system and context to implement suggestion item rendering and event forwarding. In the backend, it bridges through Gradio layout components to support Python-side control and event binding. + +```mermaid +sequenceDiagram +participant U as "User" +participant FE as "Frontend Suggestion" +participant ADX as "Ant Design X Suggestion" +participant CTX as "Items Context" +participant PY as "Backend AntdXSuggestion" +U->>FE : Input text/press key +FE->>ADX : Render suggestion panel +FE->>CTX : Resolve items slots +CTX-->>FE : Return suggestion item collection +FE->>ADX : Inject items and callbacks +U->>FE : Select a suggestion item +FE->>PY : Trigger select event +PY-->>FE : Callback handled on Python side +FE-->>U : Update UI/execute action +``` + +**Diagram Sources** + +- [frontend/antdx/suggestion/suggestion.tsx:77-162](file://frontend/antdx/suggestion/suggestion.tsx#L77-L162) +- [frontend/antdx/suggestion/context.ts:1-7](file://frontend/antdx/suggestion/context.ts#L1-L7) +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:18-27](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L18-L27) + +## Component Details + +### Backend Component: AntdXSuggestion + +- Event Binding + - select: Triggered when a suggestion item is selected; event binding is enabled on the backend via internal flags. + - open_change: Triggered when the panel open/close state changes, facilitating controlled/uncontrolled switching. +- Slot Support + - items: Suggestion item collection, dynamically generated via slots or functions. + - children: Used to wrap host elements such as input boxes, combined with should_trigger to customize trigger logic. +- Key Property Points + - items: Can be a string, list, or function; function form supports dynamic computation. + - open: In controlled mode, the panel open/close is explicitly set from the Python side. + - should_trigger: Custom keyboard event trigger determining when to show the suggestion panel. + - Styles: Supports class_names, styles, root_class_name, etc. +- Lifecycle + - preprocess/postprocess/example_payload/example_value all return empty values, indicating this component does not participate in data serialization. + +```mermaid +classDiagram +class AntdXSuggestion { ++EVENTS ++SLOTS ++items ++block ++open ++should_trigger ++root_class_name ++class_names ++styles ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +class AntdXSuggestionItem { ++EVENTS ++SLOTS ++value ++label ++extra ++icon ++key ++skip_api +} +AntdXSuggestion --> AntdXSuggestionItem : "uses" +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/suggestion/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py#L8-L68) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) + +### Frontend Implementation: Suggestion (React Wrapper) + +- Slots and Context + - Uses withItemsContextProvider to provide an items context, supporting both default and items slot sets. + - Converts slot content into suggestion item structures via renderItems and patchSlots. +- Dynamic Suggestion List + - items can be a function or slot resolution result; falls back to the default slot if empty. + - Uses useMemoizedEqualValue and useMemo to optimize rendering and comparison. +- Trigger and Open/Close + - shouldTrigger: Triggers onTrigger as needed in onKeyDown to determine whether to show the panel. + - open: Supports both props.open uncontrolled mode and internal state controlled mode. +- Event Forwarding + - onOpenChange: Determines whether to update internal state based on the presence of props.open. + - children: Injects context and forwards events via SuggestionChildrenWrapper. + +```mermaid +flowchart TD +Start(["Enter Suggestion Render"]) --> ResolveItems["Resolve items slots/functions"] +ResolveItems --> ItemsEmpty{"Are items empty?"} +ItemsEmpty -- Yes --> Fallback["Fall back to default slot"] +ItemsEmpty -- No --> UseProvided["Use provided items function/array"] +Fallback --> BuildList["Build suggestion item list"] +UseProvided --> BuildList +BuildList --> PatchSlots["patchSlots renders label/icon/extra sub-slots"] +PatchSlots --> SetOpen["Set/sync open state based on props.open"] +SetOpen --> Render["Render Ant Design X Suggestion and forward events"] +Render --> End(["Complete"]) +``` + +**Diagram Sources** + +- [frontend/antdx/suggestion/suggestion.tsx:77-162](file://frontend/antdx/suggestion/suggestion.tsx#L77-L162) +- [frontend/antdx/suggestion/context.ts:1-7](file://frontend/antdx/suggestion/context.ts#L1-L7) + +**Section Sources** + +- [frontend/antdx/suggestion/suggestion.tsx:64-165](file://frontend/antdx/suggestion/suggestion.tsx#L64-L165) +- [frontend/antdx/suggestion/context.ts:1-7](file://frontend/antdx/suggestion/context.ts#L1-L7) + +### Frontend Implementation: SuggestionItem (Item Wrapper) + +- Renders slot default as suggestion item children via ItemHandler. +- Only allows the default slot, simplifying suggestion item content organization. + +**Section Sources** + +- [frontend/antdx/suggestion/item/suggestion.item.tsx:7-22](file://frontend/antdx/suggestion/item/suggestion.item.tsx#L7-L22) + +## Dependency Analysis + +- Component Coupling + - AntdXSuggestion depends on AntdXSuggestionItem as the suggestion item container. + - Frontend Suggestion depends on Ant Design X's Suggestion component and internal utility functions (such as patchSlots, renderItems). +- Data Flow + - Slots → Context Resolution → Suggestion Item Structure → Render → Event Callback → Python Processing. +- Event Chain + - Frontend onOpenChange/select → Backend event listener → Python callback. + +```mermaid +graph LR +PY_SUG["Backend AntdXSuggestion"] --> FE_SUG["Frontend Suggestion"] +PY_ITEM["Backend AntdXSuggestionItem"] --> FE_ITEM["Frontend SuggestionItem"] +FE_SUG --> ADX["Ant Design X Suggestion"] +FE_SUG --> CTX["Items Context"] +FE_ITEM --> CTX +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-16](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L16) +- [frontend/antdx/suggestion/suggestion.tsx:64-86](file://frontend/antdx/suggestion/suggestion.tsx#L64-L86) +- [frontend/antdx/suggestion/item/suggestion.item.tsx:7-18](file://frontend/antdx/suggestion/item/suggestion.item.tsx#L7-L18) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-16](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L16) +- [frontend/antdx/suggestion/suggestion.tsx:64-86](file://frontend/antdx/suggestion/suggestion.tsx#L64-L86) +- [frontend/antdx/suggestion/item/suggestion.item.tsx:7-18](file://frontend/antdx/suggestion/item/suggestion.item.tsx#L7-L18) + +## Performance and Interaction Features + +- Render Optimization + - Uses useMemoizedEqualValue and useMemo to cache props and items, avoiding redundant renders. + - Only rebuilds the suggestion item list when items or slots change. +- Event Throttling + - Uses requestAnimationFrame in shouldTrigger to defer keyboard event processing, reducing main thread blocking risk. +- Open/Close Control + - Uncontrolled Mode: onOpenChange internally maintains the open state. + - Controlled Mode: Determined by props.open; onOpenChange only callbacks without modifying state. +- Slot Rendering + - patchSlots converts label/icon/extra sub-slots into corresponding fields, reducing cross-component communication costs. + +**Section Sources** + +- [frontend/antdx/suggestion/suggestion.tsx:36-57](file://frontend/antdx/suggestion/suggestion.tsx#L36-L57) +- [frontend/antdx/suggestion/suggestion.tsx:94-121](file://frontend/antdx/suggestion/suggestion.tsx#L94-L121) +- [frontend/antdx/suggestion/suggestion.tsx:135-140](file://frontend/antdx/suggestion/suggestion.tsx#L135-L140) + +## Usage Examples and Best Practices + +### Basic Usage (Documentation Examples) + +- The documentation provides three examples: basic, block-level display, and Python-controlled; reference: + - [docs/components/antdx/suggestion/README.md:5-10](file://docs/components/antdx/suggestion/README.md#L5-L10) + +### AI Assistant Scenario Examples (Conceptual Description) + +- Common Commands + - Define a set of fixed command suggestion items that execute on click, suitable for "quick start" scenarios. +- Context-aware Suggestions + - Dynamically generate suggestion lists based on current input or message history to improve relevance. +- Personalized Recommendations + - Based on user preferences or usage records, prioritize high-hit-rate suggestion items. +- Python-side Control + - Control panel show/hide by setting the open property; receive selected items via the select event and execute corresponding logic on the Python side. + +### Instruction Definition and Triggering + +- Instruction Definition + - Use AntdXSuggestionItem to organize suggestion items, supporting fields like label, icon, and extra. +- Trigger Conditions + - Can customize keyboard event triggers via should_trigger; can also control panel open/close via the open property. +- Execution Logic + - After selecting a suggestion item, the select event is triggered; the Python side can handle business logic in the callback. + +### Style and Interaction Customization + +- Styles + - Customize styles via class*names, styles, root_class_name, and backend elem*\* properties. +- Interaction + - The children slot is used to host input boxes and other host components, combined with should_trigger for more flexible trigger strategies. + +**Section Sources** + +- [docs/components/antdx/suggestion/README.md:5-10](file://docs/components/antdx/suggestion/README.md#L5-L10) +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:32-67](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L32-L67) +- [frontend/antdx/suggestion/suggestion.tsx:77-86](file://frontend/antdx/suggestion/suggestion.tsx#L77-L86) + +## Troubleshooting + +- Suggestion Items Not Displaying + - Check whether items is empty; if empty, confirm the default slot is correctly populated. + - Confirm slot names match (items/default). +- Panel Cannot Open + - If using controlled open, ensure the open state is correctly set on the Python side. + - Check whether should_trigger correctly implements the trigger logic. +- Events Not Firing + - Confirm event listeners are registered (select/open_change). + - Check whether Python-side callbacks are correctly bound. + +**Section Sources** + +- [frontend/antdx/suggestion/suggestion.tsx:87-121](file://frontend/antdx/suggestion/suggestion.tsx#L87-L121) +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:18-27](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L18-L27) + +## Conclusion + +The Suggestion component, through its "backend layout component + frontend React wrapper + slot context" architecture, achieves high-performance, extensible quick command and intelligent completion capabilities. It supports controlled/uncontrolled open/close, dynamic suggestion lists, custom triggers, and event callbacks, making it suitable for various AI assistant and creation scenarios. It is recommended to dynamically generate suggestion items based on business context in practice, and implement closed-loop interactions through Python-side events. diff --git a/.wiki/en/Ant Design X Components/Feedback Components/ActionItem Component.md b/.wiki/en/Ant Design X Components/Feedback Components/ActionItem Component.md new file mode 100644 index 00000000..9af5a0fe --- /dev/null +++ b/.wiki/en/Ant Design X Components/Feedback Components/ActionItem Component.md @@ -0,0 +1,258 @@ +# ActionItem Component + + +**Files referenced in this document** +- [frontend/antdx/actions/action-item/Index.svelte](file://frontend/antdx/actions/action-item/Index.svelte) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [backend/modelscope_studio/components/antdx/actions/__init__.py](file://backend/modelscope_studio/components/antdx/actions/__init__.py) +- [backend/modelscope_studio/components/antdx/actions/action_item/__init__.py](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py) +- [backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js](file://backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Usage Examples and Parameter Reference](#appendix-usage-examples-and-parameter-reference) + +## Introduction + +ActionItem is the core sub-component in the Ant Design X Actions component system, used to present a single clickable or interactive operation item within an Actions container. It supports multiple forms (text, icon, custom rendering), nested sub-menus, danger state, trigger strategies (hover/click), and the ability to extend content through slots. The component provides both a frontend Svelte wrapper layer and a backend Gradio Python encapsulation layer, forming a complete "Python configuration + frontend rendering" pipeline. + +## Project Structure + +The directory and related files for ActionItem are organized as follows: + +- Frontend wrapper layer (Svelte): frontend/antdx/actions/action-item/Index.svelte +- Frontend main component (React): frontend/antdx/actions/actions.tsx (contains the main Actions component) +- Backend encapsulation layer (Gradio Python): backend/modelscope_studio/components/antdx/actions/action_item/**init**.py +- Frontend bridge and runtime (build artifact): backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js +- Backend Actions main component: backend/modelscope_studio/components/antdx/actions/**init**.py + +```mermaid +graph TB +subgraph "Backend" +PY_INIT["Python: actions/__init__.py\nDefines AntdXActions"] +PY_ITEM["Python: action_item/__init__.py\nDefines AntdXActionsActionItem"] +end +subgraph "Frontend" +SVELTE["Svelte: action-item/Index.svelte\nWraps React component"] +REACT_MAIN["React: actions.tsx\nMain Actions component"] +RUNTIME["JS Runtime: actions.action-item-*.js\nBridge and rendering logic"] +end +PY_ITEM --> SVELTE +SVELTE --> RUNTIME +PY_INIT --> REACT_MAIN +REACT_MAIN --> RUNTIME +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/actions/**init**.py:15-94](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L94) +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:10-62](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L10-L62) +- [frontend/antdx/actions/action-item/Index.svelte:14-98](file://frontend/antdx/actions/action-item/Index.svelte#L14-L98) +- [frontend/antdx/actions/actions.tsx:1-200](file://frontend/antdx/actions/actions.tsx#L1-L200) +- [backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js:419-431](file://backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js#L419-L431) + +Section Sources + +- [backend/modelscope_studio/components/antdx/actions/**init**.py:15-94](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L94) +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:10-62](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L10-L62) +- [frontend/antdx/actions/action-item/Index.svelte:14-98](file://frontend/antdx/actions/action-item/Index.svelte#L14-L98) +- [frontend/antdx/actions/actions.tsx:1-200](file://frontend/antdx/actions/actions.tsx#L1-L200) +- [backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js:419-431](file://backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js#L419-L431) + +## Core Components + +- AntdXActionsActionItem (backend encapsulation): Responsible for mapping Python-layer configuration to frontend components and declaring event and slot capabilities. +- ActionsActionItem (frontend bridge): Dynamically imported and rendered by the Svelte wrapper layer, responsible for handling slots, additional attributes, event mapping, and visibility control. +- Actions (main component): The frontend implementation of AntdXActions, hosting multiple ActionItems and providing advanced features such as dropdowns and animations. + +Key responsibilities and relationships + +- Backend encapsulation: Defines ActionItem parameters, events, and slots; determines frontend resource paths. +- Frontend wrapper: Parses props, handles slots, and generates the final props and slots required for rendering. +- Runtime bridge: Connects the Svelte/React render tree with the Gradio context, supporting event forwarding and context merging. + +Section Sources + +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:10-62](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L10-L62) +- [frontend/antdx/actions/action-item/Index.svelte:19-84](file://frontend/antdx/actions/action-item/Index.svelte#L19-L84) +- [backend/modelscope_studio/components/antdx/actions/**init**.py:15-94](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L94) + +## Architecture Overview + +The complete call chain from Python to frontend for ActionItem is as follows: + +```mermaid +sequenceDiagram +participant Py as "Python : AntdXActionsActionItem" +participant Svelte as "Svelte : action-item/Index.svelte" +participant Runtime as "JS Runtime : actions.action-item-*.js" +participant React as "React : actions.tsx" +Py->>Svelte : Pass component configuration and event bindings +Svelte->>Runtime : Import and instantiate ActionsActionItem +Runtime->>React : Render React version of ActionItem +React-->>Runtime : Trigger event callbacks e.g. item_click +Runtime-->>Svelte : Events forwarded back to Gradio +Svelte-->>Py : Event result returned +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:15-21](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L15-L21) +- [frontend/antdx/actions/action-item/Index.svelte:14-98](file://frontend/antdx/actions/action-item/Index.svelte#L14-L98) +- [backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js:419-431](file://backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js#L419-L431) +- [frontend/antdx/actions/actions.tsx:1-200](file://frontend/antdx/actions/actions.tsx#L1-L200) + +## Detailed Component Analysis + +### Backend Encapsulation: AntdXActionsActionItem + +- Event binding + - item_click: Triggered when the operation item is clicked; the backend enables event binding via an internal flag. +- Slot support + - Supports slots such as label, icon, actionRender, and subItems for flexible extension. +- Key properties + - label, icon, danger, trigger_sub_menu_action, sub_items, action_render, as_item, key, etc. +- Resource location + - Uses resolve_frontend_dir("actions", "action-item", type="antdx") to specify the frontend resource directory. + +Section Sources + +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:10-62](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L10-L62) +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:15-21](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L15-L21) +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:24](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L24) + +### Frontend Wrapper: Svelte Wrapper Layer + +- Dynamic import + - Dynamically loads the React version of ActionItem via importComponent. +- Props handling + - Uses getProps/processProps to extract and transform props, mapping item_click to the frontend event name. + - Merges elem_id, elem_classes, elem_style, additionalProps, etc. +- Slot handling + - Retrieves slot content via getSlots, setting withParams and clone for actionRender. +- Visibility and index + - Controls rendering based on visible; passes itemIndex and itemSlotKey to work with context. + +Section Sources + +- [frontend/antdx/actions/action-item/Index.svelte:14-98](file://frontend/antdx/actions/action-item/Index.svelte#L14-L98) + +### Runtime Bridge: JS Runtime + +- Component bridge + - Creates a Svelte-React bridge instance via Ge(...), mounting the React component to a shared root node. +- Context and slots + - Uses createItemsContext to provide the items context, supporting default slots and sub-item rendering. +- Event and property forwarding + - Merges Gradio context with props to ensure events and styles are correctly forwarded. + +Section Sources + +- [backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js:419-431](file://backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js#L419-L431) + +### Main Component: AntdXActions (Related) + +- Role + - Acts as the container for ActionItem, providing items list, variants, dropdown configuration, animations, and more. +- Events and slots + - Supports click, dropdown*open_change, dropdown_menu*\* event series, and multiple slots. + +Section Sources + +- [backend/modelscope_studio/components/antdx/actions/**init**.py:15-94](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L94) + +## Dependency Analysis + +- Backend to frontend + - AntdXActionsActionItem points to frontend resources via FRONTEND_DIR; the Svelte wrapper layer dynamically imports the corresponding JS module. +- Frontend to runtime + - The Svelte wrapper layer passes props and slots to the runtime bridge module, which is responsible for rendering the React component and integrating with the Gradio context. +- Inter-component collaboration + - ActionItem typically exists as a sub-item of Actions; the two together form an operation panel. + +```mermaid +graph LR +PY_ITEM["Python: ActionItem Encapsulation"] --> SVELTE["Svelte: Wrapper Layer"] +SVELTE --> RUNTIME["JS: Bridge and Rendering"] +RUNTIME --> REACT_MAIN["React: Actions Main Component"] +REACT_MAIN --> ACTIONITEM["React: ActionItem Sub-item"] +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:62](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L62) +- [frontend/antdx/actions/action-item/Index.svelte:14-98](file://frontend/antdx/actions/action-item/Index.svelte#L14-L98) +- [backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js:419-431](file://backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js#L419-L431) +- [frontend/antdx/actions/actions.tsx:1-200](file://frontend/antdx/actions/actions.tsx#L1-L200) + +## Performance Considerations + +- Dynamic import and lazy loading + - The Svelte side implements on-demand loading via importComponent, reducing the initial bundle size and first-screen load pressure. +- Render optimization + - Uses $derived and useMemo strategies to avoid unnecessary re-renders. +- Event forwarding + - Events are handled uniformly in the runtime bridge layer, reducing redundant bindings and memory usage. +- Slot cloning + - Sets clone and withParams for actionRender, ensuring stable reuse and parameter passing for slot content. + +Section Sources + +- [frontend/antdx/actions/action-item/Index.svelte:14-98](file://frontend/antdx/actions/action-item/Index.svelte#L14-L98) +- [backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js:163-209](file://backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js#L163-L209) + +## Troubleshooting Guide + +- Event not triggered + - Check if the backend has enabled item_click event binding; confirm that item_click is correctly mapped in the frontend props. +- Slot not working + - Confirm slot names match the supported list (label, icon, actionRender, subItems); check withParams and clone settings for actionRender. +- Style or class name anomalies + - Check if elem_id, elem_classes, and elem_style are correctly passed; confirm the style and class name merging logic in the runtime bridge layer. +- Sub-menu not displaying + - Check trigger_sub_menu_action (hover/click) and sub_items structure; confirm the dropdown configuration of the main Actions. + +Section Sources + +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:15-21](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L15-L21) +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:24](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L24) +- [frontend/antdx/actions/action-item/Index.svelte:61-84](file://frontend/antdx/actions/action-item/Index.svelte#L61-L84) + +## Conclusion + +ActionItem implements a highly configurable, extensible, and maintainable operation item component through backend Python encapsulation and frontend Svelte/React bridging. Its event, slot, style, and context integration capabilities enable it to meet the needs of operation panels in complex scenarios. Combined with the AntdXActions main component, beautiful and fully functional operation areas can be quickly built. + +## Appendix: Usage Examples and Parameter Reference + +The following are common usage scenarios and parameter descriptions (using paths instead of specific code): + +- Text operation item + - Parameters: label, danger, as_item + - Example path: [frontend/antdx/actions/action-item/Index.svelte:61-84](file://frontend/antdx/actions/action-item/Index.svelte#L61-L84) +- Icon operation item + - Parameters: icon, label, elem_classes + - Example path: [frontend/antdx/actions/action-item/Index.svelte:61-84](file://frontend/antdx/actions/action-item/Index.svelte#L61-L84) +- Custom rendering (actionRender) + - Parameters: actionRender (function string), slot withParams/clone + - Example path: [frontend/antdx/actions/action-item/Index.svelte:71-83](file://frontend/antdx/actions/action-item/Index.svelte#L71-L83) +- Danger state and trigger strategy + - Parameters: danger, trigger_sub_menu_action (hover/click) + - Example path: [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:26-61](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L26-L61) +- Sub-menu + - Parameters: sub_items, slot subItems + - Example path: [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:24](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L24) + +Section Sources + +- [frontend/antdx/actions/action-item/Index.svelte:61-84](file://frontend/antdx/actions/action-item/Index.svelte#L61-L84) +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:24-61](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L24-L61) diff --git a/.wiki/en/Ant Design X Components/Feedback Components/Actions Overview.md b/.wiki/en/Ant Design X Components/Feedback Components/Actions Overview.md new file mode 100644 index 00000000..4723f684 --- /dev/null +++ b/.wiki/en/Ant Design X Components/Feedback Components/Actions Overview.md @@ -0,0 +1,335 @@ +# Actions Overview + + +**Files referenced in this document** +- [frontend/antdx/actions/Index.svelte](file://frontend/antdx/actions/Index.svelte) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [frontend/antdx/actions/item/Index.svelte](file://frontend/antdx/actions/item/Index.svelte) +- [frontend/antdx/actions/action-item/Index.svelte](file://frontend/antdx/actions/action-item/Index.svelte) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [backend/modelscope_studio/components/antdx/actions/__init__.py](file://backend/modelscope_studio/components/antdx/actions/__init__.py) +- [docs/components/antdx/actions/README.md](file://docs/components/antdx/actions/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +Actions is a layout and interaction component from the Ant Design X component library in ModelScope Studio, used to quickly configure a set of reusable operation buttons or function entry points in AI scenarios. Through a unified "operation item" model and slots mechanism, it decouples static configuration from dynamic rendering, supporting both direct passing of an items list and declarative organization of operation items as sub-components, thereby improving development efficiency and maintainability. + +In the overall architecture of ModelScope Studio, Actions sits between the frontend Svelte layer and the backend Gradio component layer, serving as a "bridge and adapter": the frontend is responsible for rendering Ant Design X's Actions on the page; the backend exposes events and slot capabilities through a custom component class and forwards extra properties to the frontend, achieving a complete interaction loop from the Python side to the browser. + +## Project Structure + +The Actions component consists of two parts — frontend and backend: + +- Frontend (Svelte + React): Responsible for rendering Ant Design X's Actions as page elements, and collecting sub-items through the slot and context system. +- Backend (Python + Gradio): Defines the component interface, events, and slots, responsible for binding and forwarding properties and events. + +```mermaid +graph TB +subgraph "Frontend" +A_Index["frontend/antdx/actions/Index.svelte"] +A_Component["frontend/antdx/actions/actions.tsx"] +A_Context["frontend/antdx/actions/context.ts"] +A_Item["frontend/antdx/actions/item/Index.svelte"] +A_ActionItem["frontend/antdx/actions/action-item/Index.svelte"] +U_CreateItems["frontend/utils/createItemsContext.tsx"] +end +subgraph "Backend" +P_Init["backend/modelscope_studio/components/antdx/actions/__init__.py"] +end +A_Index --> A_Component +A_Component --> A_Context +A_Component --> U_CreateItems +A_Item --> A_Component +A_ActionItem --> A_Component +P_Init --> A_Index +``` + +**Diagram Sources** + +- [frontend/antdx/actions/Index.svelte:1-77](file://frontend/antdx/actions/Index.svelte#L1-L77) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/antdx/actions/item/Index.svelte:1-60](file://frontend/antdx/actions/item/Index.svelte#L1-L60) +- [frontend/antdx/actions/action-item/Index.svelte:1-99](file://frontend/antdx/actions/action-item/Index.svelte#L1-L99) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [backend/modelscope_studio/components/antdx/actions/**init**.py:1-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L1-L112) + +**Section Sources** + +- [frontend/antdx/actions/Index.svelte:1-77](file://frontend/antdx/actions/Index.svelte#L1-L77) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/antdx/actions/item/Index.svelte:1-60](file://frontend/antdx/actions/item/Index.svelte#L1-L60) +- [frontend/antdx/actions/action-item/Index.svelte:1-99](file://frontend/antdx/actions/action-item/Index.svelte#L1-L99) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [backend/modelscope_studio/components/antdx/actions/**init**.py:1-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L1-L112) + +## Core Components + +- Actions main component: Responsible for receiving items or operation items from slots, customizing dropdown menu rendering with dropdownProps, and rendering the final Ant Design X Actions on the page. +- Operation item context: Through the ItemsContext provided by createItemsContext, collects child operation items (including default slots and named slots), and supports merging and forwarding of props, slots, and children for sub-items. +- Sub-component wrappers: item and action-item wrap the "operation container" and "specific operation item" respectively, handling property forwarding, visibility control, style and ID injection, and event mapping (e.g., item_click is mapped to itemClick). + +**Section Sources** + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/antdx/actions/item/Index.svelte:1-60](file://frontend/antdx/actions/item/Index.svelte#L1-L60) +- [frontend/antdx/actions/action-item/Index.svelte:1-99](file://frontend/antdx/actions/action-item/Index.svelte#L1-L99) + +## Architecture Overview + +The Actions runtime flow is as follows: + +- The frontend Svelte layer dynamically imports the React wrapper actions.tsx via Index.svelte. +- actions.tsx uses context and slot utility functions to convert items and dropdownProps into the data structure required by Ant Design X. +- The backend component class declares events and slots on the Python side, forwarding extra properties and visibility information to the frontend. +- Finally, Ant Design X's Actions renders the UI and triggers callback events. + +```mermaid +sequenceDiagram +participant Py as "Backend Component Class\nAntdXActions" +participant FE_Index as "Frontend Index.svelte" +participant FE_Actions as "React Wrapper\nactions.tsx" +participant Ctx as "Items Context\ncreateItemsContext" +participant ADX as "Ant Design X Actions" +Py->>FE_Index : "Render request with properties and events" +FE_Index->>FE_Actions : "Dynamic import and forward props" +FE_Actions->>Ctx : "Read items slots and menu items" +FE_Actions->>ADX : "Generate items and dropdownProps" +ADX-->>FE_Actions : "Render result" +FE_Actions-->>FE_Index : "Return rendered node" +FE_Index-->>Py : "Render complete" +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/actions/**init**.py:1-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L1-L112) +- [frontend/antdx/actions/Index.svelte:1-77](file://frontend/antdx/actions/Index.svelte#L1-L77) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +## Detailed Component Analysis + +### Actions Main Component (React Wrapper) + +- Responsibility: Integrates Ant Design X's Actions with the slot and context system, responsible for merging and rendering items and dropdownProps. +- Key points: + - Uses withItemsContextProvider and withMenuItemsContextProvider to inject items and menu item contexts. + - Converts slot content into the structure required by Ant Design X using utility functions such as renderItems, renderSlot, and renderParamsSlot. + - Conditionally merges dropdownProps, only injecting when valid values exist to avoid redundant configuration. + +```mermaid +flowchart TD +Start(["Enter Actions Wrapper"]) --> ReadItems["Read items or operation items from slots"] +ReadItems --> MergeDropdown["Merge dropdownProps\nMenu items/renderers/indicators"] +MergeDropdown --> BuildItems["Build final items using renderItems"] +BuildItems --> Render["Render Ant Design X Actions"] +Render --> End(["Complete"]) +``` + +**Diagram Sources** + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +**Section Sources** + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) + +### Operation Item Context (createItemsContext) + +- Responsibility: Provides ItemsContext for collecting and updating "operation item" data, supporting multiple slots (default and other named slots). +- Key points: + - setItem supports updating individual items by slot key and index, using an immutable update strategy internally, combined with useEffect to trigger the onChange callback. + - ItemHandler encapsulates the sub-component's props, slots, and children into a standard Item structure and writes it to the context. + - Optimizes rendering and callback overhead via useMemoizedEqualValue and useMemoizedFn. + +```mermaid +classDiagram +class ItemsContext { ++items : Record
Exports Bubble Component"] +B["list/bubble.list.tsx
Exports BubbleList Component"] +C["list/item/bubble.list.item.tsx
Exports BubbleListItem Component"] +D["list/role/bubble.list.role.tsx
Exports BubbleListRole Component"] +E["list/context.ts
Items/Role Context"] +F["list/utils.tsx
useRole Utility and Slot Patching"] +G["utils/patchSlots.ts
Slot Patch Enhancement"] +H["utils/renderItems.tsx
Slot Rendering and Argument Passing"] +end +A --> |"Wraps and forwards props/slots"| X["@ant-design/x Bubble"] +B --> |"Combines Items/Role context"| X +C --> |"Injects ItemHandler"| X +D --> |"Injects RoleItemHandler"| X +E --> |"Provides useItems/useRoleItems"| B +F --> |"Computes role mapping/slot patches"| B +G --> |"Enhances slot patching"| F +H --> |"Normalizes slot rendering"| B +``` + +**Diagram Sources** + +- [frontend/antdx/bubble/bubble.tsx:1-120](file://frontend/antdx/bubble/bubble.tsx#L1-L120) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-50](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L50) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:1-14](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L1-L14) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:1-14](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L1-L14) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/antdx/bubble/list/utils.tsx:1-135](file://frontend/antdx/bubble/list/utils.tsx#L1-L135) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + +## Core Components + +- **Bubble**: A Svelte wrapper around @ant-design/x's Bubble, supporting unified rendering of slots and functional props, compatible with editable text slots. +- **BubbleList**: List container responsible for merging external items and slot items, injecting role context, and delegating rendering to @ant-design/x's List. +- **BubbleListItem**: Message item wrapper that injects context via ItemHandler, enabling individual Bubbles to be aware of the list environment. +- **BubbleListRole**: Role item wrapper that injects role context via RoleItemHandler, allowing role configurations to be resolved by useRole. +- **useRole**: Core role resolution utility that supports default keys, pre-processing, post-processing, and slot patching, converting role mappings to the RoleType required by @ant-design/x. + +## Architecture Overview + +The Bubble system uses a "wrapper + context + utility functions" core design, bridging @ant-design/x's native capabilities with Gradio-style slots/functional props to form an extensible, role-based message list. + +```mermaid +sequenceDiagram +participant U as "Caller" +participant BL as "BubbleList" +participant Ctx as "Context (Items/Role)" +participant UR as "useRole Utility" +participant PS as "patchSlots Enhancement" +participant XBL as "@ant-design/x List" +participant BI as "BubbleListItem/BubbleListRole" +U->>BL : Provides items or slot items +BL->>Ctx : Injects Items/Role context +BL->>UR : Computes role mapping and slot patches +UR->>PS : Applies slot patch enhancement +PS-->>UR : Returns enhanced patches +UR-->>BL : Returns RoleType +BL->>XBL : Renders list with role +loop For each message +XBL->>BI : Renders message item +BI-->>XBL : Passes Bubble props/slots +end +``` + +## Component Details + +### Bubble Component + +- **Purpose**: Svelte wrapper around @ant-design/x's Bubble, handling slots and functional props uniformly, supporting editable text slots. +- **Key Points**: + - Slot-first: When a corresponding slot exists, it takes priority over attribute values or functions. + - Editable mode: Supports custom "OK/Cancel" text via editable configuration combined with slots. + - Functional props: Uses `useFunction` to convert passed functions into renderable React components. + - Hidden children: Puts children in an invisible container to avoid duplicate rendering. + +```mermaid +flowchart TD +Start(["Enter Bubble Rendering"]) --> CheckEditable["Detect editable config and slots"] +CheckEditable --> BuildEditable{"Editable enabled?"} +BuildEditable --> |Yes| MergeEditable["Merge slots and config"] +BuildEditable --> |No| PassEditable["Pass through editable"] +MergeEditable --> ResolveSlots["Resolve header/footer/avatar/extra/content/loadingRender/contentRender"] +PassEditable --> ResolveSlots +ResolveSlots --> RenderX["Render @ant-design/x Bubble"] +RenderX --> End(["Done"]) +``` + +### BubbleList Component + +- **Purpose**: Message list container responsible for: + - Merging external items with slot items + - Injecting Items and Role contexts + - Resolving role mappings via useRole + - Delegating final rendering to @ant-design/x List +- **Key Points**: + - Prioritizes `props.items`; falls back to slot items/default + - Normalizes slot content to arrays via `renderItems` + - Caches items with `useMemo` to reduce re-renders + +### BubbleListItem and BubbleListRole + +- **BubbleListItem**: Injects ItemHandler into a Bubble, giving individual message items list context awareness. +- **BubbleListRole**: Injects RoleItemHandler into role configuration, enabling role items to be resolved to RoleType by useRole. + +### useRole - Role Resolution Utility + +- **Purpose**: Converts role configuration (string, function, or object) to the RoleType required by @ant-design/x, with slot patching and index injection. +- **Key Points**: + - Supports `defaultRoleKeys` + - Supports `preProcess` and `defaultRolePostProcess` hooks + - Automatically patches header/footer/avatar/extra/loadingRender/contentRender slots + - Default `contentRender` serializes objects to strings + +### Divider Component + +- **Purpose**: Inserts dividers between chat bubbles for visual segmentation and rhythm control. +- **Use Cases**: Multi-turn conversations, modular display, time/topic transition hints. +- Note: Divider is a standalone component, typically used alongside BubbleList, controlled via slots or layout. + +## Dependency Analysis + +- **Component coupling**: + - Bubble acts only as a wrapper, depending on @ant-design/x's native capabilities, making it easy to upgrade or replace. + - BubbleList depends on context and utility functions with clear responsibilities, centralized in useRole and renderItems. +- **Context and utilities**: + - `createItemsContext` provides two context sets (Items/Role) for list items and role items respectively. + - `useRole` is the core of role resolution, handling the conversion from configuration to rendering parameters. + - `patchSlots` provides slot patching enhancement, supporting argument passing and function composition. +- **External dependencies**: + - @ant-design/x: Provides Bubble/List/Role types and rendering capabilities + - @svelte-preprocess-react: Bridges Svelte and React slots + - @utils/\*: Provides rendering and function encapsulation utilities + +## Performance and Maintainability + +- **Performance optimization**: + - Use `useMemo` to cache BubbleList's items to avoid unnecessary re-renders. + - Set appropriate dependency arrays in `useRole` to avoid recomputing role mappings. + - Break large slot content into reusable components to reduce closure and object creation. + - **Optimization**: Removed unused unshift behavior, reducing unnecessary argument reorganization overhead. +- **Maintainability**: + - Centralize role configuration management to avoid scattering across templates. + - Use preProcess/postProcess hooks to unify message preprocessing and postprocessing. + - Maintain consistent slot naming conventions for team collaboration and documentation. + +## Troubleshooting Guide + +- **Slots not working** + - Check slot names against component conventions (e.g., avatar/header/footer/extra/content) + - Ensure Bubble/BubbleList correctly wraps the slots +- **Role configuration invalid** + - Confirm BubbleListRole correctly injects RoleItemHandler + - Check useRole's defaultRoleKeys and preProcess/postProcess are working as expected +- **Editable text not showing** + - Confirm both editable config and slots exist; slots take priority + - Check that editable.okText/editable.cancelText slots are correctly passed +- **List rendering issues** + - Confirm BubbleListItem correctly injects ItemHandler + - Check that items and slot items data structures match requirements + +## Conclusion + +The Bubble chat bubble component system uses "wrapper + context + utility functions" as its core design, preserving @ant-design/x's powerful capabilities while providing flexible slot and role-based extensions. Through the collaboration of BubbleList, BubbleListItem, BubbleListRole, and useRole, developers can quickly build complex, customizable conversation interfaces with good balance between style, interaction, and maintainability. + +## Appendix: Usage Examples and Best Practices + +- **Basic chat bubble**: Use Bubble component for message content, pass text/rich content via content slot or prop; add avatar, title, action area, and extra info via avatar/header/footer/extra slots. +- **Complex message formats**: Use contentRender objects/arrays for structured rendering; handle message fields and styles uniformly via preProcess/postProcess hooks. +- **Custom styles**: Configure different roles via role mapping combined with slot patches; use Divider at key points to improve readability. +- **Best practices**: + - Centralize role configuration management + - Use `useMemo` to cache items and role mappings + - Maintain consistent slot naming conventions + - Use patchSlots enhancements wisely when passing slot arguments diff --git a/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble Component Overview.md b/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble Component Overview.md new file mode 100644 index 00000000..b3002521 --- /dev/null +++ b/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble Component Overview.md @@ -0,0 +1,188 @@ +# Bubble Component Overview + + +**Files referenced in this document** +- [frontend/antdx/bubble/Index.svelte](file://frontend/antdx/bubble/Index.svelte) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [frontend/antdx/bubble/list/Index.svelte](file://frontend/antdx/bubble/list/Index.svelte) +- [frontend/antdx/bubble/list/bubble.list.tsx](file://frontend/antdx/bubble/list/bubble.list.tsx) +- [frontend/antdx/bubble/system/Index.svelte](file://frontend/antdx/bubble/system/Index.svelte) +- [frontend/antdx/bubble/system/bubble.system.tsx](file://frontend/antdx/bubble/system/bubble.system.tsx) +- [frontend/antdx/bubble/divider/Index.svelte](file://frontend/antdx/bubble/divider/Index.svelte) +- [frontend/antdx/bubble/divider/bubble.divider.tsx](file://frontend/antdx/bubble/divider/bubble.divider.tsx) +- [backend/modelscope_studio/components/antdx/bubble/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/__init__.py) +- [backend/modelscope_studio/components/antdx/bubble/list/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +Bubble is a visual chat bubble component designed for machine learning conversation scenarios, built on Ant Design X's Bubble capabilities. It provides message bubble rendering, editing, typing animation, content distribution, and more, with a seamless frontend-backend development experience through the Gradio/ModelScope ecosystem. The component family includes single bubbles, bubble lists, system message dividers, and system-type bubbles, covering conversation patterns from basic display to complex interactions. + +## Project Structure + +The Bubble component consists of a frontend Svelte wrapper layer and a backend Python component layer, using a dual-layer design of "frontend React component + backend Gradio component" to ensure declarative usage of Ant Design X capabilities in Python environments. + +```mermaid +graph TB +subgraph "Frontend Svelte Layer" +A["Index.svelte
Wrapper Entry"] +B["bubble.tsx
Sveltify Wrapper"] +C["list/Index.svelte
List Wrapper"] +D["list/bubble.list.tsx
List Implementation"] +E["system/Index.svelte
System Bubble Wrapper"] +F["system/bubble.system.tsx
System Bubble Implementation"] +G["divider/Index.svelte
Divider Wrapper"] +H["divider/bubble.divider.tsx
Divider Implementation"] +end +subgraph "Backend Python Layer" +P1["antdx/bubble/__init__.py
Main Component Class"] +P2["antdx/bubble/list/__init__.py
List Component Class"] +end +A --> B +C --> D +E --> F +G --> H +P1 --> A +P2 --> C +``` + +## Core Components + +- **Single Bubble Component**: Renders a single message bubble, supporting avatar, title, content, extra actions, footer, loading/content custom rendering, editable mode, and typing animation. +- **Bubble List Component**: Hosts multiple bubbles, supporting role grouping, auto-scrolling, and injecting items/role via slots. +- **System Bubble Component**: Renders system prompts or status information, emphasizing semantic display. +- **Divider Component**: Inserts separation prompts in conversations, such as timestamps or session transition hints. + +## Architecture Overview + +The Bubble component uses a three-layer architecture of "Svelte wrapper + Ant Design X React component + Gradio/ModelScope backend bridge". The frontend implements on-demand loading via Svelte's `importComponent`, bridging React components to Svelte using `sveltify`; the backend abstracts via `ModelScopeLayoutComponent` to uniformly handle event binding, slot mapping, and property forwarding. + +```mermaid +sequenceDiagram +participant Py as "Python Backend Component" +participant Svelte as "Svelte Wrapper" +participant React as "Ant Design X React Component" +participant User as "Caller" +User->>Py : Initialize component params and events +Py->>Svelte : Render frontend wrapper +Svelte->>Svelte : importComponent dynamic import +Svelte->>React : Pass props and slots +React-->>Svelte : Render result +Svelte-->>User : Output final DOM +``` + +## Detailed Component Analysis + +### Single Bubble Component (Bubble) + +- **Design Philosophy**: Based on Ant Design X's Bubble as core, providing rich slot and callback extension points for diverse needs: avatar, title, content, action area, loading state, and editing state. +- **Key Features**: + - Slot system: avatar, content, header, footer, extra, loadingRender, contentRender, editable.okText, editable.cancelText. + - Edit capability: Supports editable boolean switch and configuration object, with custom text and rendering via slots. + - Typing animation: `typing` supports boolean and configuration objects, with `typingComplete` event for animation lifecycle management. + - Custom rendering: loadingRender and contentRender support function or slot injection for flexible loading and content rendering control. + - Avatar and extra areas: avatar and extra support functions or slots for extending icons, action buttons, etc. + +```mermaid +flowchart TD +Start(["Enter Bubble Rendering"]) --> CheckEditable{"Is editing enabled?"} +CheckEditable --> |Yes| MergeEditable["Merge editable config and slots"] +CheckEditable --> |No| PassEditable["Pass through editable"] +MergeEditable --> RenderAvatar{"Avatar slot exists?"} +PassEditable --> RenderAvatar +RenderAvatar --> |Yes| SlotAvatar["Render avatar slot"] +RenderAvatar --> |No| FuncAvatar["Render avatar function/prop"] +FuncAvatar --> RenderHeader{"Header slot exists?"} +SlotAvatar --> RenderHeader +RenderHeader --> |Yes| SlotHeader["Render header slot"] +RenderHeader --> |No| FuncHeader["Render header function/prop"] +FuncHeader --> RenderContent{"Content slot exists?"} +SlotHeader --> RenderContent +RenderContent --> |Yes| SlotContent["Render content slot"] +RenderContent --> |No| TextContent["Render text content"] +TextContent --> RenderFooter{"Footer slot exists?"} +SlotContent --> RenderFooter +RenderFooter --> |Yes| SlotFooter["Render footer slot"] +RenderFooter --> |No| FuncFooter["Render footer function/prop"] +FuncFooter --> End(["Render complete"]) +``` + +### Bubble List Component (BubbleList) + +- **Design Philosophy**: Builds on the single bubble to provide batch rendering and role grouping for multi-turn conversations and history message lists. +- **Key Features**: + - Role grouping: Define display strategies for different roles (user, system, assistant) via role slot or prop. + - Slot items/default: Support injecting list items via slots or passing items array directly. + - Auto-scroll: Configurable auto-scroll to latest message for better user experience. + - Context injection: Parse slots and defaults via `useItems` and `useRole` for flexibility and consistency. + +### System Bubble Component (BubbleSystem) + +- **Design Philosophy**: Used to display system-level prompts or status information, emphasizing semantic consistency, commonly used for "system notifications", "session start", "model switch" scenarios. +- **Key Features**: + - Content slot: The `content` slot takes priority over the content property for dynamic rendering. + - Semantic display: Based on Ant Design X's System type, maintaining consistent style and behavior. + +### Divider Component (BubbleDivider) + +- **Design Philosophy**: Inserts separation prompts in conversations such as timestamps or session transitions, helping users understand conversation structure. +- **Key Features**: + - Content slot: The `content` slot takes priority over the content property. + - Semantic separation: Based on Ant Design X's Divider type, maintaining consistent visual and interaction behavior. + +## Dependency Analysis + +- **Frontend dependencies**: + - @svelte-preprocess-react: Provides importComponent, processProps, slot context capabilities for Svelte-React bridging. + - @ant-design/x: Provides core components and type definitions for Bubble, List, System, Divider. + - @utils/\*: Provides utilities for useFunction, renderParamsSlot, renderItems, context Providers. +- **Backend dependencies**: + - ModelScopeLayoutComponent: Unified abstraction for frontend component rendering, event binding, and property forwarding. + - Gradio event system: Event bindings for typing, typing_complete, edit_confirm, edit_cancel. + +## Performance Considerations + +- **On-demand loading**: Frontend uses `importComponent` for dynamic imports to avoid large initial bundles and improve first-screen performance. +- **Slot and function rendering**: Use slots and function rendering judiciously to reduce unnecessary re-renders; use stable function references for contentRender/loadingRender. +- **List optimization**: BubbleList uses `useMemo` and `renderItems` to ensure only necessary parts are recalculated on items change; use `auto_scroll` cautiously with large datasets. +- **Event binding**: Events like typing_complete, edit_confirm, edit_cancel should only be bound when needed. + +## Troubleshooting Guide + +- **Slots not working**: Check slot names (avatar, content, header, footer, extra, loadingRender, contentRender, editable.okText, editable.cancelText). Slots take priority over props. +- **Editing not working**: Confirm editable is a boolean or config object, with cancelText/okText slots or props. Check edit_confirm and edit_cancel event binding. +- **Typing animation issues**: Confirm typing is a boolean or config object. Without typing, typing_complete fires immediately after render. +- **List scrolling problems**: Check if auto_scroll is enabled; consider delay or throttle for large message sets. +- **Style and theme conflicts**: Use root_class_name or class_names/styles for custom styles; ensure compatibility with Ant Design X theme variables. + +## Conclusion + +The Bubble component family, based on Ant Design X and combined with Svelte and Gradio/ModelScope ecosystem capabilities, provides a complete solution from single messages to multi-turn conversation lists. Its slot-based design and event system enable flexible presentation of different types of prompts and messages in machine learning conversation scenarios while maintaining good performance and maintainability. + +## Appendix + +### Basic Usage Examples + +- **Single bubble**: Set content text or inject complex content via content slot. For editing, set `editable` and provide editable.okText/editable.cancelText. For typing animation, set `typing` and listen for `typing_complete`. +- **Bubble list**: Pass message arrays via items/default slots or items prop. Define role grouping via role slot or prop. Enable `auto_scroll` for automatic scrolling. +- **System bubble and divider**: Use System component for system prompts; use Divider for separation hints. Both support content slot priority strategy. + +### Best Practices + +- Prefer slots over inline strings for better maintainability and testability. +- Use memoization for frequently changing content to reduce re-renders. +- In dense conversation scenarios, control auto-scroll and animation effects to avoid performance issues. +- Use root_class_name/class_names/styles for theme customization, ensuring consistency with the overall design. diff --git a/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.Divider Component.md b/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.Divider Component.md new file mode 100644 index 00000000..daa008ea --- /dev/null +++ b/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.Divider Component.md @@ -0,0 +1,80 @@ +# Bubble.Divider Component + + +**Files referenced in this document** +- [frontend/antdx/bubble/divider/Index.svelte](file://frontend/antdx/bubble/divider/Index.svelte) +- [frontend/antdx/bubble/divider/bubble.divider.tsx](file://frontend/antdx/bubble/divider/bubble.divider.tsx) +- [backend/modelscope_studio/components/antdx/bubble/divider/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/divider/__init__.py) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) + + +## Introduction + +Bubble.Divider is a time separator and content partition component within the chat bubble system, used to clearly divide different time periods or logical blocks in long conversations, improving readability and user experience. It is built on Ant Design X's Bubble.Divider capabilities, supports custom title/label via content slots, and provides visibility control and style forwarding. + +## Project Structure + +Bubble.Divider resides within the antdx bubble system, using a layered design of "backend Python component + frontend Svelte wrapper + React component bridge": + +- Backend component: Responsible for property definitions, visibility and style forwarding, and lifecycle hooks (such as preprocessing/postprocessing) +- Frontend wrapper: Svelte component handles on-demand loading, property merging, class name and style injection, slot rendering +- React component bridge: Exposes Ant Design X's Bubble.Divider capability in Svelte form + +```mermaid +graph TB +subgraph "Backend" +PY["Python Component
antdx.bubble.divider.__init__.py"] +end +subgraph "Frontend Wrapper Layer" +IDX["Svelte Wrapper
bubble.divider/Index.svelte"] +end +subgraph "React Bridge Layer" +BD["React Component Bridge
bubble.divider.tsx"] +XBD["Ant Design X Bubble.Divider"] +end +PY --> IDX +IDX --> BD +BD --> XBD +``` + +## Core Component + +Bubble.Divider wraps Ant Design X's Bubble.Divider component, providing: + +- Content slot (`content`): Displays text labels or custom content in the divider +- Visibility control (`visible`): Show/hide the divider via backend configuration +- Style injection: Supports `elem_id`, `elem_classes`, `elem_style`, and `additional_props` + +## Rendering Flow + +```mermaid +flowchart TD +Enter(["Enter Divider Rendering"]) --> HasSlot{"Content slot exists?"} +HasSlot --> |Yes| RenderSlot["Render slot content"] +HasSlot --> |No| RenderProp["Render prop content"] +RenderSlot --> Done(["Render complete"]) +RenderProp --> Done +``` + +## Usage + +- **Time divider**: Insert time labels in conversation lists to help users understand temporal structure of the conversation. +- **Topic divider**: Separate content blocks between different topics or sessions for clearer navigation. +- **Status divider**: Display status changes (e.g., session start, model switch notifications) as divider content. + +## Configuration Options + +| Property | Description | +| ------------------ | -------------------------------- | +| `content` | Divider content (string or slot) | +| `visible` | Whether to render the divider | +| `elem_id` | Element ID | +| `elem_classes` | Element CSS classes | +| `elem_style` | Inline element styles | +| `additional_props` | Additional property set | + +## Best Practices + +- Prefer the `content` slot for flexibility over plain string props. +- Keep divider content concise and consistent for better visual rhythm. +- Use `elem_id` / `elem_classes` for precise style control, avoiding global pollution. diff --git a/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.Item Component.md b/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.Item Component.md new file mode 100644 index 00000000..3306d05a --- /dev/null +++ b/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.Item Component.md @@ -0,0 +1,80 @@ +# Bubble.Item Component + + +**Files referenced in this document** +- [frontend/antdx/bubble/list/item/Item.svelte](file://frontend/antdx/bubble/list/item/Item.svelte) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [frontend/antdx/bubble/list/bubble.list.tsx](file://frontend/antdx/bubble/list/bubble.list.tsx) +- [frontend/antdx/bubble/list/context.ts](file://frontend/antdx/bubble/list/context.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) + + +## Introduction + +Bubble.Item is a message item wrapper component within the Bubble.List system. It injects the item context via `ItemHandler`, enabling individual message items to participate in the list rendering lifecycle. When used as a child of BubbleList, Bubble.Item passes its properties and slots to the parent list for unified rendering. + +## Architecture + +```mermaid +classDiagram +class BubbleListItem { ++props : BubbleProps and ItemHandlerProps ++render() : ReactNode +} +class ItemHandler { ++setItem(key, props, slots) ++collectProps() ++collectSlots() +} +class ItemsContext { ++items : map[] ++setItem() +} +BubbleListItem --> ItemHandler : "Injects" +ItemHandler --> ItemsContext : "Writes item" +``` + +## Key Design Points + +- **ItemHandler injection**: Bubble.Item wraps ItemHandler, writing its own props/slots/children to ItemsContext for the parent BubbleList to consume and render. +- **Context communication**: Data flows from Bubble.Item → ItemHandler → ItemsContext → BubbleList rendering, ensuring full decoupling. +- **Slot support**: Supports all Bubble slots: avatar, header, footer, extra, content, loadingRender, contentRender. + +## Data Flow + +```mermaid +sequenceDiagram +participant Item as "Bubble.Item" +participant Handler as "ItemHandler" +participant Ctx as "ItemsContext" +participant List as "BubbleList" +Item->>Handler : Pass props and slots +Handler->>Ctx : Write item data +List->>Ctx : Read items +Ctx-->>List : Return items array +List->>List : Render via @ant-design/x List +``` + +## Configuration + +Bubble.Item accepts all Bubble component properties and additionally: + +- **Slot support**: All Bubble slots (avatar, header, footer, extra, content, loadingRender, contentRender) +- **List context**: Automatically participates in parent list context when used as a child of BubbleList + +## Usage Example + +```python +import modelscope_studio as mgr + +with mgr.antdx.Bubble.List(): + mgr.antdx.Bubble.Item(content="Hello, how can I help you?") + mgr.antdx.Bubble.Item(content="I need assistance with deployment.") +``` + +## Troubleshooting + +- **Item not showing**: Check that `visible` is truthy and that Bubble.Item is correctly wrapped in a BubbleList context. +- **Item content not updating**: Confirm props are stable; ItemHandler compares previous values and only writes if they change. +- **Slot not working**: Ensure slot names match backend declarations. diff --git a/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.List Component.md b/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.List Component.md new file mode 100644 index 00000000..10debd4c --- /dev/null +++ b/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.List Component.md @@ -0,0 +1,66 @@ +# Bubble.List Component + + +**Files referenced in this document** +- [frontend/antdx/bubble/list/bubble.list.tsx](file://frontend/antdx/bubble/list/bubble.list.tsx) +- [frontend/antdx/bubble/list/Index.svelte](file://frontend/antdx/bubble/list/Index.svelte) +- [frontend/antdx/bubble/list/context.ts](file://frontend/antdx/bubble/list/context.ts) +- [frontend/antdx/bubble/list/utils.tsx](file://frontend/antdx/bubble/list/utils.tsx) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx) + + +## Introduction + +Bubble.List is the message list container component in the Bubble system. It is responsible for collecting external items and slot items, injecting role context, resolving role mappings via `useRole`, and delegating final rendering to @ant-design/x's List. + +## Rendering Flow + +```mermaid +flowchart TD +Start(["Enter BubbleList"]) --> CheckItems["Check if props.items exists"] +CheckItems --> |Exists| UseItems["Use external items"] +CheckItems --> |Not exists| ReadSlot["Read context slotItems.items or default"] +ReadSlot --> ResolveItems["Use renderItems to parse as array"] +UseItems --> ResolveItems +ResolveItems --> ParseRole["useRole resolves role mapping"] +ParseRole --> PatchSlots["Apply slot patches to slots"] +PatchSlots --> RenderList["Render XBubble.List"] +RenderList --> End(["Done"]) +``` + +## Key Features + +- **Items merging**: Prioritizes `props.items`; if not provided, reads `slotItems.items` or `default` from context, then uses `renderItems` to normalize to an array. +- **Role resolution**: Uses `useRole` to support role as string, function, or object, with `preProcess` and `defaultRolePostProcess` hooks. +- **Slot patching**: Applies patches to slots so role's avatar/header/footer/extra/loadingRender/contentRender can be overridden in advance. +- **Render and scroll**: Renders via @ant-design/x's `XBubble.List`, with auto-scroll binding and scroll event callbacks. + +## Configuration Options + +| Property | Description | +| -------------- | ------------------------------------------------ | +| `items` | Message items array | +| `role` | Role configuration (string, function, or object) | +| `auto_scroll` | Whether to auto-scroll to the latest message | +| `visible` | Whether to render the component | +| `elem_id` | Element ID | +| `elem_classes` | Element CSS classes | + +## Collaboration with Bubble.Item and Bubble.Role + +- **Bubble.Item**: Wraps ItemHandler, injecting message item props and slots into context for BubbleList to read during rendering. +- **Bubble.Role**: Wraps RoleItemHandler, injecting role definitions into role context for useRole to resolve. +- **Data flow**: BubbleList reads items/default and role from context before rendering, then generates the complete items array and role configuration. + +## Performance Considerations + +- Uses `useMemo` to cache items, reducing unnecessary re-renders. +- `ItemHandler` uses `useMemoizedFn` and `useMemoizedEqualValue` to reduce duplicate computations and invalid updates. +- `ItemsContextProvider` updates the entire child items array in a single `setItem` call. + +## Troubleshooting + +- **Items not displayed**: Check if `visible` is truthy and that the parent component correctly wraps `withItemsContextProvider`. +- **Role configuration not working**: Ensure `Bubble.Role` correctly injects role context and that `useRole` receives the expected configuration. +- **Auto-scroll not working**: Confirm `auto_scroll` is enabled; consider performance implications with large message sets. diff --git a/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.Role Component.md b/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.Role Component.md new file mode 100644 index 00000000..09d820e0 --- /dev/null +++ b/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.Role Component.md @@ -0,0 +1,93 @@ +# Bubble.Role Component + + +**Files referenced in this document** +- [frontend/antdx/bubble/list/role/Role.svelte](file://frontend/antdx/bubble/list/role/Role.svelte) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx) +- [backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py) +- [frontend/antdx/bubble/list/role/Index.svelte](file://frontend/antdx/bubble/list/role/Index.svelte) +- [frontend/antdx/bubble/list/context.ts](file://frontend/antdx/bubble/list/context.ts) +- [frontend/antdx/bubble/list/utils.tsx](file://frontend/antdx/bubble/list/utils.tsx) + + +## Introduction + +Bubble.Role is a role identifier component within the Bubble.List system. It injects role configurations into the role context via `RoleItemHandler`, so that `useRole` can resolve them into the `RoleType` required by @ant-design/x. Each Bubble.Role defines the visual style and behavior defaults for a specific role (e.g., user, assistant, system). + +## Architecture + +```mermaid +classDiagram +class BubbleListRole { ++props : BubbleProps and RoleItemHandlerProps ++render() : ReactNode +} +class RoleItemHandler { ++setRole(key, props, slots) +} +class RoleItemsContext { ++roles : map[] ++setRole() +} +class useRole { ++resolve(role) : RoleType +} +BubbleListRole --> RoleItemHandler : "Injects" +RoleItemHandler --> RoleItemsContext : "Writes role" +useRole --> RoleItemsContext : "Reads roles" +``` + +## Key Design Points + +- **RoleItemHandler injection**: Bubble.Role wraps RoleItemHandler, writing its own props/slots to RoleItemsContext for `useRole` to resolve. +- **Role key**: Each Bubble.Role must specify a unique role key matching the `role` field in message items. +- **Slot support**: Supports Bubble slots: avatar, header, footer, extra, content, loadingRender, contentRender. + +## Usage Example + +```python +import modelscope_studio as mgr + +with mgr.antdx.Bubble.List(): + with mgr.antdx.Bubble.Role(role="user"): + with mgr.Slot("avatar"): + mgr.antdx.Avatar(icon="UserOutlined") + with mgr.antdx.Bubble.Role(role="assistant"): + with mgr.Slot("avatar"): + mgr.antdx.Avatar(src="/bot-avatar.png") +``` + +## Role Resolution Flow + +```mermaid +flowchart TD +A["Input: role/defaultRoleKeys/preProcess/postProcess"] --> B["Read Role context items"] +B --> C{"Role config exists?"} +C --> |Yes| D["Render Role slots and aggregate as mapping"] +C --> |No| E["Use empty mapping"] +D --> F["Merge default keys and mapping keys"] +E --> F +F --> G["Iterate each key"] +G --> H{"Value is function?"} +H --> |Yes| I["Compile as function and cache"] +H --> |No| J["Generate default handler (with slot patches/index injection/default contentRender)"] +I --> K["Apply patchBubbleSlots enhancement"] +K --> L["Return RoleType"] +J --> L +``` + +## Configuration Options + +| Property | Description | +| ------------- | ---------------------------- | +| `role` | Unique role key identifier | +| `avatar` | Avatar configuration or slot | +| `placement` | Bubble placement (start/end) | +| `styles` | Style configuration | +| `class_names` | CSS class name configuration | + +## Best Practices + +- Define all roles used in messages before rendering BubbleList. +- Use consistent role key naming (e.g., "user", "assistant", "system") for better readability. +- Configure avatar, styles, and class_names via Bubble.Role slots for centralized role management. diff --git a/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.System Component.md b/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.System Component.md new file mode 100644 index 00000000..c0cb397e --- /dev/null +++ b/.wiki/en/Ant Design X Components/General Components/Bubble Chat Bubble/Bubble.System Component.md @@ -0,0 +1,97 @@ +# Bubble.System Component + + +**Files referenced in this document** +- [frontend/antdx/bubble/system/Index.svelte](file://frontend/antdx/bubble/system/Index.svelte) +- [frontend/antdx/bubble/system/bubble.system.tsx](file://frontend/antdx/bubble/system/bubble.system.tsx) +- [backend/modelscope_studio/components/antdx/bubble/system/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/system/__init__.py) + + +## Introduction + +Bubble.System is a system message component within the Bubble family, used for rendering system prompts, status notifications, and operational feedback. It integrates Ant Design X's system bubble capabilities into ModelScope Studio's component ecosystem through clear frontend-backend layered design. + +## Project Structure + +```mermaid +graph TB +PY["AntdXBubbleSystem
Backend Python Component"] --> IDX["Index.svelte
Frontend Svelte Wrapper"] +IDX --> TSX["bubble.system.tsx
React Bridge"] +TSX --> ADX["@ant-design/x Bubble.System"] +``` + +## Core Component + +The `AntdXBubbleSystem` backend class inherits from ModelScope Studio's layout component base class with the following key properties: + +```mermaid +classDiagram +class AntdXBubbleSystem { ++EVENTS ++SLOTS ++content ++shape ++variant ++styles ++class_names ++root_class_name ++additional_props ++visible ++elem_id ++elem_classes ++elem_style ++render ++skip_api ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +``` + +## Rendering Flow + +```mermaid +flowchart TD +Enter(["Enter System Rendering"]) --> HasSlot{"content slot exists?"} +HasSlot --> |Yes| RenderSlot["Render slot content"] +HasSlot --> |No| RenderProp["Render prop content"] +RenderSlot --> Done(["Render complete"]) +RenderProp --> Done +``` + +## Differences from Regular Bubble + +- **Role positioning**: Regular Bubble is used for user/bot conversation content rendering with rich slots (avatar, header, footer, extra, etc.); Bubble.System focuses on system prompts, status notifications, and non-conversational content. +- **Slots and properties**: Regular Bubble supports more slots; System Bubble only focuses on the `content` slot and basic properties, keeping it simple and consistent. +- **Rendering target**: Regular Bubble faces "person" and "role" interaction content; System Bubble faces information communicated by "system" to the user. + +## Configuration Options + +| Property | Description | +| -------------------------- | -------------------------------------------------- | +| `content` | System message content (string or slot) | +| `shape` | Bubble shape (round/corner/default) | +| `variant` | Visual variant (filled/borderless/outlined/shadow) | +| `styles` / `elem_style` | Inline styles | +| `elem_id` / `elem_classes` | Element ID and class names | +| `additional_props` | Additional property set | +| `visible` | Whether to render | + +## Usage Scenarios + +- **Welcome message**: Display welcome text when user first enters the page. +- **Error notification**: Notify user of network or service errors. +- **Progress notification**: Stage-by-stage prompts during background task execution. + +## Performance Considerations + +- `Index.svelte` uses dynamic imports, only loading the system bubble wrapper when visible, reducing initial render overhead. +- `ReactSlot` only renders when slots exist, avoiding unnecessary computations for empty content. +- Only passes necessary properties and slots, reducing unnecessary re-renders and style calculations. + +## Troubleshooting + +- **Content not showing**: Check that `content` is correctly passed via slot or property; slots take priority. Confirm `visible` is truthy. +- **Style abnormalities**: Check that `elem_id`, `elem_classes`, `elem_style` are injected as expected. +- **Slot not working**: Ensure slot name matches backend declaration (currently only supports `content` slot). diff --git a/.wiki/en/Ant Design X Components/General Components/Conversations/API Reference.md b/.wiki/en/Ant Design X Components/General Components/Conversations/API Reference.md new file mode 100644 index 00000000..1d0dc524 --- /dev/null +++ b/.wiki/en/Ant Design X Components/General Components/Conversations/API Reference.md @@ -0,0 +1,105 @@ +# API Reference + + +**Files referenced in this document** +- [backend/modelscope_studio/components/antdx/conversations/__init__.py](file://backend/modelscope_studio/components/antdx/conversations/__init__.py) +- [backend/modelscope_studio/components/antdx/conversations/item/__init__.py](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py) + + +## Conversations Component API + +### Properties + +| Property | Type | Default | Description | +| -------------- | ---- | ------- | --------------------------------- | +| `items` | list | `[]` | Conversation items array | +| `active_key` | str | `None` | Currently active conversation key | +| `groupable` | bool | `False` | Whether to enable grouping | +| `menu` | dict | `None` | Context menu configuration | +| `visible` | bool | `True` | Whether to render the component | +| `elem_id` | str | `None` | Element ID | +| `elem_classes` | list | `None` | Element CSS class names | +| `elem_style` | dict | `None` | Element inline styles | + +### Events + +| Event | Description | +| ------------------ | ------------------------------------------ | +| `active_change` | Fired when the active conversation changes | +| `menu_click` | Fired when a menu item is clicked | +| `menu_select` | Fired when a menu item is selected | +| `menu_deselect` | Fired when a menu item is deselected | +| `menu_open_change` | Fired when menu open state changes | +| `groupable_expand` | Fired when a group expands or collapses | +| `creation_click` | Fired when the creation button is clicked | + +### Slots + +| Slot | Description | +| -------------------------- | ------------------------------------------------------ | +| `items` | Slot for injecting Conversations.Item child components | +| `menu.items` | Slot for injecting context menu items | +| `menu.trigger` | Slot for customizing menu trigger | +| `menu.expandIcon` | Slot for customizing menu expand icon | +| `menu.overflowedIndicator` | Slot for customizing overflow indicator | +| `groupable.label` | Slot for customizing group label | +| `creation.icon` | Slot for customizing creation button icon | +| `creation.label` | Slot for customizing creation button label | + +## Conversations.Item Component API + +### Properties + +| Property | Type | Default | Description | +| ---------- | ---- | -------- | ------------------------------------------- | +| `key` | str | required | Unique identifier for the conversation item | +| `label` | str | `None` | Display label (overridden by label slot) | +| `icon` | any | `None` | Icon (overridden by icon slot) | +| `disabled` | bool | `False` | Whether the item is disabled | +| `group` | str | `None` | Group label (required when groupable=True) | + +### Slots + +| Slot | Description | +| ------- | ----------------------------------------- | +| `label` | Slot for customizing item label rendering | +| `icon` | Slot for customizing item icon rendering | + +## Items Array Format + +Each item in the `items` array can contain: + +```python +{ + "key": "unique-key", # Required: unique identifier + "label": "Display Name", # Display label + "icon": None, # Icon configuration + "disabled": False, # Whether disabled + "group": "Group Name", # Group label (for groupable mode) +} +``` + +## Usage Example + +```python +import gradio as gr +import modelscope_studio as mgr + +with gr.Blocks() as demo: + state = gr.State(value=None) + + conversations = mgr.antdx.Conversations( + groupable=True, + items=[ + {"key": "1", "label": "Chat about Python", "group": "Today"}, + {"key": "2", "label": "ML model discussion", "group": "Today"}, + {"key": "3", "label": "Old conversation", "group": "Yesterday"}, + ] + ) + + conversations.active_change( + lambda key: print(f"Selected: {key}"), + inputs=[conversations], + outputs=[state] + ) +``` diff --git a/.wiki/en/Ant Design X Components/General Components/Conversations/Component Overview.md b/.wiki/en/Ant Design X Components/General Components/Conversations/Component Overview.md new file mode 100644 index 00000000..cbd26e9c --- /dev/null +++ b/.wiki/en/Ant Design X Components/General Components/Conversations/Component Overview.md @@ -0,0 +1,113 @@ +# Component Overview + + +**Files referenced in this document** +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/antdx/conversations/__init__.py](file://backend/modelscope_studio/components/antdx/conversations/__init__.py) +- [frontend/antdx/conversations/conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [frontend/antdx/conversations/context.ts](file://frontend/antdx/conversations/context.ts) +- [frontend/antdx/conversations/item/conversations.item.tsx](file://frontend/antdx/conversations/item/conversations.item.tsx) + + +## Introduction + +This overview covers the Conversations management component, systematically introducing its overall architecture, core functionality, and design philosophy. It explains its relationship with the Ant Design X component library and typical usage in machine learning and conversational applications, providing entry points and core concepts to help developers quickly understand and integrate this component. + +## Project Structure + +The Conversations component is located in the Ant Design X frontend ecosystem. The backend bridges to the Gradio ecosystem via Python wrappers; the frontend connects to Ant Design X's Conversations implementation as React components, extending menu, grouping, and other capabilities through context and slot mechanisms. + +```mermaid +graph TB +subgraph "Backend" +PY_API["Python Wrapper
AntdXConversations"] +BASE_COMP["Base Component Class
ModelScopeLayoutComponent"] +end +subgraph "Frontend" +REACT_COMP["React Component
@ant-design/x Conversations"] +CTX["Context and Slots
context.ts / conversations.tsx"] +ITEM["Item Wrapper
conversations.item.tsx"] +end +PY_API --> |"Call/Render"| REACT_COMP +BASE_COMP --> PY_API +CTX --> REACT_COMP +ITEM --> CTX +``` + +## Core Components + +### AntdXConversations (Backend) + +The Python-side wrapper class for the Conversations component: + +- Inherits from `ModelScopeLayoutComponent`, providing unified lifecycle and rendering strategy. +- Declares supported slots and events, ensuring frontend wrapper layer correctly interfaces. +- Property set covers common needs: `items`, `active_key`, `groupable`, `menu`. + +Key events: + +- `active_change`: Active conversation changed +- `menu_click` / `menu_select` / `menu_deselect` / `menu_open_change`: Menu interaction events +- `groupable_expand`: Group expand/collapse +- `creation_click`: Creation button click + +### conversations.tsx (Frontend) + +The frontend React wrapper implementation: + +- Uses `withItemsContextProvider` to provide items context to child `Conversations.Item` components. +- Uses `withMenuItemsContextProvider` to provide menu items context. +- Uniformly injects style class names to child items. +- Converts slot menu items to menu configuration required by @ant-design/x. + +### conversations.item.tsx (Frontend) + +The Conversations.Item bridge component: + +- Uses `ItemHandler` to write its own props/slots to `ItemsContext`. +- Supports `label`, `icon`, and other slots. + +## Architecture Overview + +```mermaid +graph LR +ConvTSX["conversations.tsx"] --> Ctx["context.ts"] +Ctx --> CIC["createItemsContext.tsx"] +ConvTSX --> X["@ant-design/x Conversations"] +ItemSvelte["Index.svelte"] --> ItemBridge["conversations.item.tsx"] +ItemBridge --> Ctx +Backend["AntdXConversations*"] --> ConvTSX +``` + +## Usage Patterns + +### Basic Usage + +```python +import modelscope_studio as mgr + +conversations = mgr.antdx.Conversations( + items=[ + {"key": "1", "label": "Conversation 1"}, + {"key": "2", "label": "Conversation 2"}, + ] +) +``` + +### With Grouping + +```python +conversations = mgr.antdx.Conversations( + groupable=True, + items=[ + {"key": "1", "label": "Conv 1", "group": "Today"}, + {"key": "2", "label": "Conv 2", "group": "Yesterday"}, + ] +) +``` + +## Key Design Concepts + +- **Context-driven**: The parent container provides context; child items write to context. This decouples parent-child communication and enables flexible composition. +- **Slot-first**: All display customization (icons, labels, menus) is achieved through slots for maximum flexibility. +- **Event-driven**: Key interactions (selection, menu operations, group toggle) are exposed as events for backend Python processing. diff --git a/.wiki/en/Ant Design X Components/General Components/Conversations/Conversation Item Component.md b/.wiki/en/Ant Design X Components/General Components/Conversations/Conversation Item Component.md new file mode 100644 index 00000000..b41444bd --- /dev/null +++ b/.wiki/en/Ant Design X Components/General Components/Conversations/Conversation Item Component.md @@ -0,0 +1,92 @@ +# Conversation Item Component + + +**Files referenced in this document** +- [frontend/antdx/conversations/item/Index.svelte](file://frontend/antdx/conversations/item/Index.svelte) +- [frontend/antdx/conversations/item/conversations.item.tsx](file://frontend/antdx/conversations/item/conversations.item.tsx) +- [backend/modelscope_studio/components/antdx/conversations/item/__init__.py](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) + + +## Introduction + +`Conversations.Item` is an individual conversation item component within the Conversations system. It bridges slot content and properties to the parent `Conversations` container via `ItemHandler`, enabling the parent to render all items uniformly. This design ensures complete decoupling between parent and child while supporting rich slot customization. + +## Architecture + +```mermaid +graph LR +Item["Conversations.Item
Index.svelte"] --> Bridge["conversations.item.tsx
React Bridge"] +Bridge --> Handler["ItemHandler
createItemsContext.tsx"] +Handler --> Context["ItemsContext
context.ts"] +Parent["Conversations
conversations.tsx"] --> Context +``` + +## Key Design Points + +- **ItemHandler injection**: Conversations.Item writes its own props/slots to `ItemsContext` via ItemHandler for the parent Conversations to consume and render. +- **Lazy loading**: `Index.svelte` only renders the bridge component when `visible` is true. +- **Props comparison**: ItemHandler uses memoized comparison to avoid unnecessary writes. + +## Data Flow + +```mermaid +sequenceDiagram +participant Item as "Conversations.Item" +participant Handler as "ItemHandler" +participant Ctx as "ItemsContext" +participant Parent as "Conversations" +Item->>Handler : Pass key, props, slots +Handler->>Ctx : setItem(key, props, children) +Parent->>Ctx : Read items +Ctx-->>Parent : Return items map +Parent->>Parent : Render via @ant-design/x Conversations +``` + +## Properties + +| Property | Type | Default | Description | +| ---------- | ---- | -------- | --------------------------------------- | +| `key` | str | required | Unique conversation item identifier | +| `label` | str | `None` | Display text (overridden by label slot) | +| `icon` | any | `None` | Item icon (overridden by icon slot) | +| `disabled` | bool | `False` | Whether the item is disabled | +| `group` | str | `None` | Group this item belongs to | +| `visible` | bool | `True` | Whether to render this item | + +## Slots + +| Slot | Description | +| ------- | ---------------------- | +| `label` | Custom label rendering | +| `icon` | Custom icon rendering | + +## Usage Example + +```python +import modelscope_studio as mgr + +with mgr.antdx.Conversations() as conv: + # Simple text item + mgr.antdx.Conversations.Item(key="1", label="Project Alpha") + + # Item with custom icon and label + with mgr.antdx.Conversations.Item(key="2"): + with mgr.Slot("icon"): + mgr.antdx.Icon(type="StarOutlined") + with mgr.Slot("label"): + mgr.antdx.Typography.Text("★ Starred Chat", strong=True) + + # Item with context menu + with mgr.antdx.Conversations.Item(key="3", label="Chat with menu"): + with mgr.Slot("menu.items"): + mgr.antdx.MenuItem(key="pin", label="Pin") + mgr.antdx.MenuItem(key="delete", label="Delete", danger=True) +``` + +## Troubleshooting + +- **Item not visible**: Check `visible` property and confirm item is inside a Conversations container. +- **Label not showing**: Confirm the label slot or label property is correctly set. +- **Icon not showing**: Ensure icon slot content is a valid React/Svelte element. +- **Menu items not working**: Verify menu items are injected via `menu.items` slot and the parent handles `menu_click` events. diff --git a/.wiki/en/Ant Design X Components/General Components/Conversations/Conversations Management.md b/.wiki/en/Ant Design X Components/General Components/Conversations/Conversations Management.md new file mode 100644 index 00000000..468c1300 --- /dev/null +++ b/.wiki/en/Ant Design X Components/General Components/Conversations/Conversations Management.md @@ -0,0 +1,160 @@ +# Conversations Management + + +**Files referenced in this document** +- [frontend/antdx/conversations/Index.svelte](file://frontend/antdx/conversations/Index.svelte) +- [frontend/antdx/conversations/conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [frontend/antdx/conversations/context.ts](file://frontend/antdx/conversations/context.ts) +- [frontend/antdx/conversations/item/Index.svelte](file://frontend/antdx/conversations/item/Index.svelte) +- [frontend/antdx/conversations/item/conversations.item.tsx](file://frontend/antdx/conversations/item/conversations.item.tsx) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/antdx/conversations/index.less](file://frontend/antdx/conversations/index.less) +- [frontend/antdx/conversations/gradio.config.js](file://frontend/antdx/conversations/gradio.config.js) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document systematically describes the design and implementation of the Conversations management component, covering: + +- Conversation list management: adding, deleting, sorting, state management +- Conversations.Item rendering logic, interaction behavior, and state control +- Component Context role and conversation state sharing mechanism +- Property configuration, event callbacks, style customization, and best practices +- Complete usage examples: basic usage, dynamic add/remove, state synchronization + +## Project Structure + +The Conversations component consists of three layers: "container layer + item handler + context", bridged to the runtime environment via Gradio configuration. + +```mermaid +graph TB +subgraph "Frontend Component Layer" +A["Index.svelte
Container Entry"] +B["conversations.tsx
Conversation Container Implementation"] +C["context.ts
Item Context Export"] +D["item/Index.svelte
Item Entry"] +E["item/conversations.item.tsx
Item Handler"] +F["index.less
Styles"] +end +subgraph "Shared Utility Layer" +G["createItemsContext.tsx
Item Context Factory"] +end +subgraph "Build Configuration" +H["gradio.config.js
Unified Configuration"] +end +A --> B +D --> E +B --> C +C --> G +E --> C +B --> F +A --> H +D --> H +``` + +## Core Components + +- **Conversations**: The parent container that manages the conversation list. Parses items and menu configuration, injects them into @ant-design/x's Conversations, wraps with `withItemsContextProvider` and `withMenuItemsContextProvider` to provide contexts. +- **Conversations.Item**: A single conversation item. Writes its own props/slots/children to ItemsContext via `ItemHandler` for the parent container to render. + +## Architecture Overview + +```mermaid +classDiagram +class Conversations { ++props : items, menu, groupable, active_key ++events : active_change, menu_click, ... +} +class ConversationsItem { ++props : key, label, icon, disabled, ... ++slots : label, icon +} +class ItemHandler { ++setItem() ++collectProps() ++collectSlots() +} +class ItemsContext { ++items : map[] ++setItem() +} +Conversations --> ItemsContext : "Provides context" +ConversationsItem --> ItemHandler : "Bridge rendering" +ItemHandler --> ItemsContext : "Writes item" +``` + +## Detailed Component Analysis + +### Conversations Container + +- Parses `items` and menu configuration, injects into @ant-design/x's Conversations. +- Wraps with `withItemsContextProvider` and `withMenuItemsContextProvider` for Items and menu contexts. +- Uniformly injects style class names (e.g., item class names) to ensure theme consistency. + +### Conversations.Item + +- Uses `ItemHandler` to write its own props/slots/children to `ItemsContext`. +- Parent container consumes and renders items uniformly. + +### Menu Operations (Add, Delete, Rename) + +- Inject menu items via Slot (`menu.items`), supporting icons, disabled state, and danger styling. +- The `menu_click` event callback provides the clicked item and menu information. + +### Conversation Grouping and Collapsible + +- Enable grouping by setting `groupable=True`. +- Each conversation item sets a `group` field for grouping. +- Supports group label slots and collapsible functions. + +### Events and State Management + +Key events: + +- `active_change`: Selected item changed +- `menu_click` / `menu_select` / `menu_deselect` / `menu_open_change`: Menu interactions +- `groupable_expand`: Group expand/collapse +- `creation_click`: Create button click + +## Dependency Analysis + +- **Component coupling**: Conversations.Item depends on `ItemHandler` and `ItemsContext` with low coupling, easy to reuse. The parent container centralizes items, menu, and grouping handling. +- **External dependencies**: @ant-design/x provides the core Conversations component; Gradio component system provides `AntdXConversations`/`AntdXConversationsItem` as bridges. + +## Performance Considerations + +- **Lazy loading and conditional rendering**: `Index.svelte` only renders child items when `visible` is true, avoiding unnecessary initialization overhead. +- **Context update minimization**: `ItemHandler` uses `useMemoizedFn` and `useMemoizedEqualValue` to reduce duplicate computations and invalid updates. +- **Batch writing**: `ItemsContextProvider` updates the entire child items array in a single `setItem` call, reducing re-render frequency. +- **Style injection**: Parent container uniformly injects style class names to avoid jitter from child items setting styles repeatedly. + +## Troubleshooting Guide + +- **Child items not showing**: Check if `visible` is truthy; confirm parent component correctly wraps `withItemsContextProvider`. +- **Child item content not updating**: Confirm props are stable; `ItemHandler` compares previous values and won't write if equal. +- **Menu not working**: Confirm parent component correctly injects `menu` configuration or injects menu items via Slot. +- **Style abnormalities**: Parent component has already injected item class names; confirm they haven't been externally overridden. + +## Conclusion + +Conversations.Item achieves flexible item collection and rendering through `ItemHandler` and `ItemsContext`. Combined with the parent `Conversations` container's unified configuration and event management, it can efficiently build complex conversation list scenarios with emphasis on decoupling and extensibility. + +## Appendix + +### Events and Slots Summary + +- **Events**: active_change, menu_click, menu_deselect, menu_open_change, menu_select, groupable_expand, creation_click +- **Slots**: menu.expandIcon, menu.overflowedIndicator, menu.trigger, groupable.label, items, creation.icon, creation.label diff --git a/.wiki/en/Ant Design X Components/General Components/Conversations/Usage Examples.md b/.wiki/en/Ant Design X Components/General Components/Conversations/Usage Examples.md new file mode 100644 index 00000000..4deefebd --- /dev/null +++ b/.wiki/en/Ant Design X Components/General Components/Conversations/Usage Examples.md @@ -0,0 +1,140 @@ +# Usage Examples + + +**Files referenced in this document** +- [docs/components/antdx/conversations/demos/basic.py](file://docs/components/antdx/conversations/demos/basic.py) +- [docs/components/antdx/conversations/demos/operations.py](file://docs/components/antdx/conversations/demos/operations.py) +- [docs/components/antdx/conversations/demos/group.py](file://docs/components/antdx/conversations/demos/group.py) + + +## Basic Usage + +### Simple Conversation List + +```python +import gradio as gr +import modelscope_studio as mgr + +with gr.Blocks() as demo: + mgr.antdx.Conversations( + items=[ + {"key": "1", "label": "First conversation"}, + {"key": "2", "label": "Second conversation"}, + {"key": "3", "label": "Third conversation"}, + ] + ) +``` + +### With Icons and Labels + +Use Slots to define `label`/`icon` slots for custom rendering: + +```python +with gr.Blocks() as demo: + with mgr.antdx.Conversations() as conv: + with mgr.antdx.Conversations.Item(key="1"): + with mgr.Slot("icon"): + mgr.antdx.Icon(type="MessageOutlined") + with mgr.Slot("label"): + gr.Markdown("**Important Chat**") +``` + +## Menu Operations (Add, Delete, Rename) + +```python +import gradio as gr +import modelscope_studio as mgr + +with gr.Blocks() as demo: + with mgr.antdx.Conversations() as conv: + with mgr.antdx.Conversations.Item(key="chat-1", label="Chat 1"): + with mgr.Slot("menu.items"): + mgr.antdx.MenuItem(key="rename", label="Rename") + mgr.antdx.MenuItem(key="delete", label="Delete", danger=True) + + def handle_menu_click(key, menu_info): + print(f"Item: {key}, Menu: {menu_info}") + + conv.menu_click(handle_menu_click) +``` + +## Conversation Grouping with Collapsible + +```python +with gr.Blocks() as demo: + mgr.antdx.Conversations( + groupable=True, + items=[ + {"key": "1", "label": "Morning standup", "group": "Today"}, + {"key": "2", "label": "Code review", "group": "Today"}, + {"key": "3", "label": "Planning session", "group": "Yesterday"}, + {"key": "4", "label": "Bug discussion", "group": "Yesterday"}, + ] + ) +``` + +## Dynamic Conversation Management + +```python +import gradio as gr +import modelscope_studio as mgr + +def add_conversation(items, name): + new_key = f"conv-{len(items) + 1}" + return items + [{"key": new_key, "label": name}] + +def delete_conversation(items, key): + return [item for item in items if item["key"] != key] + +with gr.Blocks() as demo: + items_state = gr.State(value=[ + {"key": "1", "label": "Initial conversation"}, + ]) + + with gr.Row(): + new_name = gr.Textbox(placeholder="Conversation name") + add_btn = gr.Button("Add") + + conv = mgr.antdx.Conversations() + + add_btn.click( + add_conversation, + inputs=[items_state, new_name], + outputs=[items_state] + ) + + items_state.change( + lambda items: mgr.antdx.Conversations(items=items), + inputs=[items_state], + outputs=[conv] + ) +``` + +## Event Handling Examples + +### Handling Active Selection Change + +```python +def on_active_change(key): + print(f"Selected conversation: {key}") + # Load messages for selected conversation + +conversations.active_change( + on_active_change, + inputs=[conversations] +) +``` + +### Handling Creation Button Click + +```python +def on_creation_click(): + # Create new conversation + new_id = generate_id() + return [{"key": new_id, "label": "New Conversation"}] + +conversations.creation_click( + on_creation_click, + outputs=[conversations] +) +``` diff --git a/.wiki/en/Ant Design X Components/General Components/General Components.md b/.wiki/en/Ant Design X Components/General Components/General Components.md new file mode 100644 index 00000000..02cf25e2 --- /dev/null +++ b/.wiki/en/Ant Design X Components/General Components/General Components.md @@ -0,0 +1,310 @@ +# General Components + + +**Files referenced in this document** +- [bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [context.ts](file://frontend/antdx/conversations/context.ts) +- [index.less](file://frontend/antdx/conversations/index.less) +- [__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [README-zh_CN.md](file://README-zh_CN.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document covers the Ant Design X general components, focusing on the implementation and usage of the Bubble conversation bubble component and the Conversations conversation management component. Topics include: + +- Bubble's conversation display capabilities, message type differentiation, and style/content customization +- Conversations' conversation list management, state control, menu and grouping operation interfaces +- Collaboration relationships between components and best practices +- Complete usage examples (basic usage, advanced configuration, style customization) + +## Project Structure + +The Ant Design X general components are located in the antdx category of the frontend directory. They use a Svelte + React preprocessing bridge solution, wrapping native @ant-design/x components via sveltify to make them usable in Svelte. The backend Python package provides a unified export entry. + +```mermaid +graph TB +subgraph "Frontend antdx" +B["bubble.tsx"] +C["conversations.tsx"] +CTX["context.ts"] +L["index.less"] +end +subgraph "Backend" +PY_INIT["__init__.py"] +PY_COMP["components.py"] +end +subgraph "Third-party" +ADX["@ant-design/x"] +SveltePreprocess["@svelte-preprocess-react"] +Utils["@utils/*"] +end +B --> ADX +C --> ADX +B --> SveltePreprocess +C --> SveltePreprocess +B --> Utils +C --> Utils +PY_COMP --> B +PY_COMP --> C +PY_INIT --> PY_COMP +``` + +Diagram sources + +- [bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [**init**.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) + +Section sources + +- [bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [**init**.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) + +## Core Components + +- Bubble: A conversation bubble display component that supports slot-based extensions for avatar, title, content, footer, extra area, editable text, loading state rendering, and content rendering. +- Conversations: A conversation list management component that supports menu injection, grouping configuration, item rendering, class name merging, and event pass-through. + +Section sources + +- [bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) +- [conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) + +## Architecture Overview + +Both Bubble and Conversations are bridged to native @ant-design/x components through sveltify. The bridge layer handles: + +- Slot-to-ReactSlot mapping +- useFunction wrapping of function-type properties +- Context and rendering tool integration for menu and grouping configuration +- Class name merging and overriding + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Conv as "Conversations(Bridge)" +participant XConv as "@ant-design/x.Conversations" +participant Ctx as "Context(Menu/Item)" +participant Bubble as "Bubble(Bridge)" +participant XBubble as "@ant-design/x.Bubble" +Dev->>Conv : Pass items/menu/groupable and other props +Conv->>Ctx : Parse menu/item context +Conv->>XConv : Render conversation list (with menu/grouping) +XConv-->>Dev : List rendering result +Dev->>Bubble : Pass avatar/content/footer/header, etc. +Bubble->>XBubble : Render conversation bubble (slot/function wrapping) +XBubble-->>Dev : Bubble rendering result +``` + +Diagram sources + +- [conversations.tsx:68-175](file://frontend/antdx/conversations/conversations.tsx#L68-L175) +- [bubble.tsx:27-116](file://frontend/antdx/bubble/bubble.tsx#L27-L116) + +## Detailed Component Analysis + +### Bubble Component Analysis + +- Key Features + - Supports slot-based extensions for avatar, title, content, footer, and extra area + - Supports editable mode (boolean or configuration object), with slots for customizing "confirm/cancel" text + - Supports typing callbacks and function-based configuration for loadingRender/contentRender + - Handles editable, avatar, header, footer, extra, loadingRender, contentRender uniformly with fallback +- Data Flow and Processing Logic + - Uses useFunction to wrap function-type properties, ensuring correct execution in the Svelte environment + - Renders slot content via ReactSlot; renderParamsSlot supports slots with parameters + - Performs configuration merging and conditional rendering for editable, compatible with both boolean and object configuration +- Complexity and Performance + - Primarily involves property mapping and rendering overhead; complexity scales with slot count and nesting depth + - Function wrapping avoids redundant rendering and improves interaction responsiveness + +```mermaid +flowchart TD +Start(["Enter Bubble rendering"]) --> CheckEditable["Detect editable configuration"] +CheckEditable --> EditableSupport{"Editing supported?"} +EditableSupport --> |Yes| MergeEditable["Merge edit config\nand process slot text"] +EditableSupport --> |No| PassEditable["Pass editable directly"] +MergeEditable --> RenderAvatar["Handle avatar slot/function"] +PassEditable --> RenderAvatar +RenderAvatar --> RenderHeader["Handle header slot/function"] +RenderHeader --> RenderFooter["Handle footer slot/function"] +RenderFooter --> RenderExtra["Handle extra area slot/function"] +RenderExtra --> RenderContent["Handle content slot/function"] +RenderContent --> RenderLoading["Handle loadingRender slot/function"] +RenderLoading --> RenderContentRender["Handle contentRender slot/function"] +RenderContentRender --> End(["Rendering complete"]) +``` + +Diagram sources + +- [bubble.tsx:27-116](file://frontend/antdx/bubble/bubble.tsx#L27-L116) + +Section sources + +- [bubble.tsx:8-116](file://frontend/antdx/bubble/bubble.tsx#L8-L116) + +### Conversations Component Analysis + +- Key Features + - Interfaces with @ant-design/x Conversations, providing menu injection, grouping configuration, item rendering, and class name merging + - Parses menu and item slots via useMenuItems and useItems context + - Supports string-form menu property and object configuration, automatically merges events and prevents bubbling + - Supports label slot for groupable and collapsible function configuration +- Data Flow and Processing Logic + - patchMenuEvents: Wraps menu events, injects the conversation parameter and prevents DOM event bubbling + - renderItems: Converts slot items into actual rendered items, supporting cloning and deep copying + - useMemo: Memoizes menu and items to reduce unnecessary re-renders +- Complexity and Performance + - Memoization and context parsing deliver stable performance; more slot items means greater renderItems overhead + - Menu event wrapping only takes effect when a menu exists, avoiding unnecessary overhead + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Conv as "Conversations(Bridge)" +participant Ctx as "useMenuItems/useItems" +participant XConv as "@ant-design/x.Conversations" +Dev->>Conv : Pass menu/items/groupable/classNames +Conv->>Ctx : Get menu/item context +Conv->>Conv : patchMenuEvents wraps menu events +Conv->>Conv : renderItems parses slot items +Conv->>XConv : Merge class names and render +XConv-->>Dev : Return conversation list +``` + +Diagram sources + +- [conversations.tsx:35-175](file://frontend/antdx/conversations/conversations.tsx#L35-L175) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) + +Section sources + +- [conversations.tsx:28-175](file://frontend/antdx/conversations/conversations.tsx#L28-L175) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) + +### Component Collaboration + +- Conversations serves as the container, responsible for rendering the conversation list and managing menu/grouping configuration +- Bubble serves as a child element, responsible for displaying and interacting with individual conversation bubbles +- Both work together through @ant-design/x's native components, with the bridge layer providing slot and function wrapping capabilities + +```mermaid +graph LR +Conv["Conversations(Bridge)"] --> XB["@ant-design/x.Conversations"] +XB --> Item["Conversation Item (driven by items/menu/groupable)"] +Item --> BB["Bubble(Bridge)"] +BB --> XBb["@ant-design/x.Bubble"] +``` + +Diagram sources + +- [conversations.tsx:139-171](file://frontend/antdx/conversations/conversations.tsx#L139-L171) +- [bubble.tsx:38-115](file://frontend/antdx/bubble/bubble.tsx#L38-L115) + +## Dependency Analysis + +- Third-party Dependencies + - @ant-design/x: Provides native conversation and bubble components + - @svelte-preprocess-react: Provides sveltify and ReactSlot capabilities + - @utils/\*: Provides tools like useFunction, renderItems, renderParamsSlot, createFunction + - classnames: Used for class name merging +- Backend Exports + - The Python package exposes antdx components through **init**.py and components.py, enabling use in Python environments + +```mermaid +graph TB +B["bubble.tsx"] --> ADX["@ant-design/x"] +B --> SPR["@svelte-preprocess-react"] +B --> U["@utils/*"] +C["conversations.tsx"] --> ADX +C --> SPR +C --> U +C --> CTX["context.ts"] +PY["components.py"] --> B +PY --> C +``` + +Diagram sources + +- [bubble.tsx:1-7](file://frontend/antdx/bubble/bubble.tsx#L1-L7) +- [conversations.tsx:1-17](file://frontend/antdx/conversations/conversations.tsx#L1-L17) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) + +Section sources + +- [bubble.tsx:1-7](file://frontend/antdx/bubble/bubble.tsx#L1-L7) +- [conversations.tsx:1-17](file://frontend/antdx/conversations/conversations.tsx#L1-L17) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) + +## Performance Considerations + +- Use useMemo to memoize menu and items, avoiding unnecessary re-renders +- Wrap function-type properties with useFunction to reduce closure creation and rendering jitter +- Clone slot items through renderItems to avoid side effects from shared state +- In high-volume conversation scenarios, consider lazy loading and virtual scrolling (such as capabilities provided by @ant-design/x) to reduce memory usage + +## Troubleshooting Guide + +- Slot not taking effect + - Verify that slot names are consistent with the bridge layer declarations (e.g., editable.okText, editable.cancelText, content, footer, header, extra, loadingRender, contentRender) + - Confirm that slot content is correctly rendered via ReactSlot +- Abnormal menu events + - Check that the useMenuItems context is being used correctly + - Confirm that patchMenuEvents correctly wraps onClick and similar events and prevents bubbling +- Class name conflicts + - Merge custom class names through classNames to avoid overriding default styles +- Edit mode not appearing + - Confirm that editable is an object containing the editing field, or provide custom text via slots + +Section sources + +- [bubble.tsx:36-64](file://frontend/antdx/bubble/bubble.tsx#L36-L64) +- [conversations.tsx:35-57](file://frontend/antdx/conversations/conversations.tsx#L35-L57) +- [conversations.tsx:145-151](file://frontend/antdx/conversations/conversations.tsx#L145-L151) + +## Conclusion + +Bubble and Conversations achieve complete capability encapsulation of @ant-design/x through the bridge layer, providing flexible slot-based and function-based configuration that meets diverse needs from basic conversation display to complex conversation management. It is recommended to combine context and utility functions in actual projects, and to organize slots and events appropriately for a better development experience and runtime performance. + +## Appendix + +- Usage Examples (based on existing repository files and component capabilities) + - Basic Usage + - Use Bubble to display a message, setting avatar, content, and footer + - Use Conversations to render a conversation list, passing items and menu configuration + - Advanced Configuration + - Enable edit mode in Bubble, customizing "confirm/cancel" text through slots + - Use groupable in Conversations to implement grouping and collapsing, customizing group labels through slots + - Style Customization + - Merge custom class names through classNames to override default styles + - Import index.less for theme customization (if needed) + +Section sources + +- [bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) +- [conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) +- [index.less](file://frontend/antdx/conversations/index.less) +- [README-zh_CN.md](file://README-zh_CN.md) diff --git a/.wiki/en/Ant Design X Components/Tool Components/CodeHighlighter Component.md b/.wiki/en/Ant Design X Components/Tool Components/CodeHighlighter Component.md new file mode 100644 index 00000000..12343c0a --- /dev/null +++ b/.wiki/en/Ant Design X Components/Tool Components/CodeHighlighter Component.md @@ -0,0 +1,335 @@ +# CodeHighlighter Component + + +**Files referenced in this document** +- [backend/modelscope_studio/components/antdx/code_highlighter/__init__.py](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py) +- [frontend/antdx/code-highlighter/Index.svelte](file://frontend/antdx/code-highlighter/Index.svelte) +- [frontend/antdx/code-highlighter/code-highlighter.tsx](file://frontend/antdx/code-highlighter/code-highlighter.tsx) +- [frontend/antdx/code-highlighter/package.json](file://frontend/antdx/code-highlighter/package.json) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [docs/components/antdx/code_highlighter/README.md](file://docs/components/antdx/code_highlighter/README.md) +- [docs/components/antdx/code_highlighter/README-zh_CN.md](file://docs/components/antdx/code_highlighter/README-zh_CN.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) + +## Introduction + +CodeHighlighter is a code highlighting component based on Ant Design X, used to provide syntax highlighting functionality in ModelScope Studio. This component supports syntax highlighting for multiple programming languages, including dark and light theme modes, and provides flexible configuration options to meet different use cases. + +The component is integrated with Gradio to achieve seamless frontend-backend connection, providing users with a powerful and easy-to-use code display tool. The component supports advanced features such as custom styles, language selection, and header content. + +## Project Structure + +The position of the CodeHighlighter component in the overall project architecture is as follows: + +```mermaid +graph TB +subgraph "Backend" +A[ModelScope Studio Backend] +B[AntdX Components] +C[CodeHighlighter Component] +end +subgraph "Frontend" +D[Svelte Component] +E[React Wrapper] +F[Ant Design X] +end +subgraph "Documentation" +G[Example Documentation] +H[Usage Instructions] +end +A --> B +B --> C +C --> D +D --> E +E --> F +A --> G +G --> H +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/code_highlighter/**init**.py:1-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L1-L71) +- [frontend/antdx/code-highlighter/Index.svelte:1-65](file://frontend/antdx/code-highlighter/Index.svelte#L1-L65) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:1-54](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L1-L54) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/code_highlighter/**init**.py:1-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L1-L71) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## Core Components + +### Backend Component Class + +The CodeHighlighter backend component inherits from `ModelScopeLayoutComponent`, providing complete component lifecycle management and property handling mechanisms. + +**Main Features:** + +- Supports syntax highlighting for multiple programming languages +- Automatic theme adaptation (dark/light mode) +- Customizable styles and class names +- Slot system supports header content +- API skip mechanism for performance optimization + +**Key Properties:** + +- `value`: Code content to highlight +- `lang`: Programming language type +- `header`: Header display content +- `highlight_props`: Highlight configuration properties +- `prism_light_mode`: Prism theme mode setting + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/code_highlighter/**init**.py:15-52](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L15-L52) + +### Frontend Component Implementation + +The frontend adopts a mixed Svelte + React architecture, bridging components through the `sveltify` tool. + +**Technical Features:** + +- Dynamic import for optimized loading performance +- Slot system support +- Automatic theme detection and switching +- Custom style overrides + +**Section Sources** + +- [frontend/antdx/code-highlighter/Index.svelte:1-65](file://frontend/antdx/code-highlighter/Index.svelte#L1-L65) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:1-54](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L1-L54) + +## Architecture Overview + +CodeHighlighter adopts a layered architecture design, achieving clear frontend-backend separation: + +```mermaid +sequenceDiagram +participant Client as Client Application +participant Backend as Backend Component +participant Frontend as Frontend Component +participant AntDX as Ant Design X +participant Prism as Prism Syntax Highlighter +Client->>Backend : Create CodeHighlighter instance +Backend->>Frontend : Resolve frontend directory +Frontend->>Frontend : Dynamically import React component +Frontend->>AntDX : Wrap as Svelte component +AntDX->>Prism : Apply syntax highlighting styles +Prism-->>AntDX : Return highlighted code +AntDX-->>Frontend : Render final result +Frontend-->>Client : Display highlighted code block +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/code_highlighter/**init**.py:53-53](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L53-L53) +- [frontend/antdx/code-highlighter/Index.svelte:10-12](file://frontend/antdx/code-highlighter/Index.svelte#L10-L12) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:29-51](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L29-L51) + +## Detailed Component Analysis + +### Component Class Structure Diagram + +```mermaid +classDiagram +class AntdXCodeHighlighter { ++EVENTS : [] ++SLOTS : ["header"] ++additional_props : dict ++styles : dict|str ++class_names : dict|str ++root_class_name : str ++value : str|None ++lang : str|None ++header : str|bool|None ++highlight_props : dict|None ++prism_light_mode : bool|None ++FRONTEND_DIR : str ++skip_api : bool ++preprocess(payload) None ++postprocess(value) None ++example_payload() None ++example_value() None +} +class ModelScopeLayoutComponent { +<
Filter internal fields"] +GetProps --> MergeTheme["Merge theme priority
theme_config > restProps.theme > additionalProps.theme"] +MergeTheme --> SetMode["Read Gradio shared theme
Determine themeMode"] +SetMode --> ImportCP["Async import ConfigProvider"] +ImportCP --> Render["Render ConfigProvider and inject context"] +Render --> End(["Done"]) +``` + +Diagram sources + +- [XProvider.svelte:17-74](file://frontend/antdx/x-provider/XProvider.svelte#L17-L74) + +Section sources + +- [XProvider.svelte:1-75](file://frontend/antdx/x-provider/XProvider.svelte#L1-L75) + +### ConfigProvider Implementation (Frontend) + +Responsibilities and Key Points + +- Theme algorithm: Automatically combines dark and compact algorithms based on themeMode and props.theme.algorithm. +- Internationalization: Supports locale string or automatic browser language detection, dynamically loads the corresponding language pack and dayjs locale on demand. +- Container mounting: Provides function wrappers for getPopupContainer and getTargetContainer, enabling custom popup container configuration. +- Slot integration: Converts nested key paths in slots into corresponding React component trees, supporting slots like renderEmpty. + +```mermaid +flowchart TD +A["Receive props/themeMode/locale"] --> B["Compute algorithm list"] +B --> C["Dynamically load locale resources"] +C --> D["Compose props and slots"] +D --> E["Render StyleProvider + ConfigProvider"] +E --> F["Provide theme/locale/container strategy downstream"] +``` + +Diagram sources + +- [config-provider.tsx:71-149](file://frontend/antd/config-provider/config-provider.tsx#L71-L149) +- [locales.ts:89-105](file://frontend/antd/config-provider/locales.ts#L89-L105) + +Section sources + +- [config-provider.tsx:51-151](file://frontend/antd/config-provider/config-provider.tsx#L51-L151) +- [locales.ts:12-87](file://frontend/antd/config-provider/locales.ts#L12-L87) + +### Backend Component (AntdXXProvider) + +Responsibilities and Key Points + +- Parameter declaration: Includes configuration items such as component disable, size, direction, prefix class, locale, theme, variant, virtualization, and warnings. +- Slot declaration: Declares injectable slots such as renderEmpty. +- Frontend directory: Points to the frontend x-provider component directory. +- API skip: skip_api=True to avoid generating redundant APIs. + +Section sources + +- [**init**.py:10-101](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L10-L101) + +## Dependency Analysis + +- Frontend Dependencies + - @ant-design/x: XProvider React component source. + - @ant-design/cssinjs: Style injection and hash control. + - dayjs: Date localization. + - svelte-i18n: Browser language detection. + - immer: Immutable update utility. +- Backend Dependencies + - ModelScopeLayoutComponent: Layout component base class. + - resolve_frontend_dir: Locates the frontend component directory. + +```mermaid +graph LR +XP["XProvider.svelte"] --> CP["config-provider.tsx"] +CP --> AD["@ant-design/x"] +CP --> CSS["@ant-design/cssinjs"] +CP --> DJ["dayjs"] +CP --> I18N["svelte-i18n"] +CP --> IM["immer"] +PY["AntdXXProvider(__init__.py)"] --> CI["Index.svelte"] +CI --> XP +``` + +Diagram sources + +- [XProvider.svelte:1-14](file://frontend/antdx/x-provider/XProvider.svelte#L1-L14) +- [config-provider.tsx:1-11](file://frontend/antd/config-provider/config-provider.tsx#L1-L11) +- [**init**.py:6-8](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L6-L8) + +Section sources + +- [XProvider.svelte:1-14](file://frontend/antdx/x-provider/XProvider.svelte#L1-L14) +- [config-provider.tsx:1-11](file://frontend/antd/config-provider/config-provider.tsx#L1-L11) +- [**init**.py:6-8](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L6-L8) + +## Performance Considerations + +- Async loading: XProvider uses dynamic imports for ConfigProvider to avoid blocking the initial render and improve startup speed. +- Theme algorithm: Recomputes the algorithm array only when themeMode or props.theme.algorithm changes, reducing re-render cost. +- Language packs: Loads language packs and dayjs locale on demand, avoiding loading all language resources at once. +- Style injection: Uses a high-priority hash strategy to minimize style conflicts and reflows. + +## Troubleshooting Guide + +- Theme conflict warning + - Symptom: Triggered when both theme and a Gradio preset theme are set simultaneously. + - Resolution: Use theme_config uniformly to avoid conflicts with Gradio preset properties. + - Reference: [**init**.py:74-77](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L74-L77) +- Light/dark mode not taking effect + - Confirm that the Gradio shared theme has correctly set themeMode. + - Reference: [XProvider.svelte](file://frontend/antdx/x-provider/XProvider.svelte#L69) +- Language not switching as expected + - Check whether the locale string format matches the mapping rules (e.g., zh_CN, en_US), or rely on automatic detection. + - Reference: [locales.ts:12-87](file://frontend/antd/config-provider/locales.ts#L12-L87) +- Slot not taking effect + - Ensure the slot key path is correct (e.g., renderEmpty) and the corresponding content is provided in slots. + - Reference: [config-provider.tsx:29-49](file://frontend/antd/config-provider/config-provider.tsx#L29-L49) + +Section sources + +- [**init**.py:74-77](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L74-L77) +- [XProvider.svelte](file://frontend/antdx/x-provider/XProvider.svelte#L69) +- [locales.ts:12-87](file://frontend/antd/config-provider/locales.ts#L12-L87) +- [config-provider.tsx:29-49](file://frontend/antd/config-provider/config-provider.tsx#L29-L49) + +## Conclusion + +Through a "frontend wrapper + backend bridge" design, XProvider provides a unified theme and internationalization context for the application, with good extensibility and performance. It is recommended to configure XProvider centrally at the application entry point to avoid repetitive settings across components, thereby achieving a consistent user experience and lower maintenance cost. + +## Appendix + +### Configuration Options Summary + +- Component-level Configuration + - component_disabled: Component disable toggle + - component_size: Component size (small/middle/large) + - direction: Text direction (ltr/rtl) + - prefix_cls/icon_prefix_cls: Prefix class names + - variant: Component appearance variant (outlined/filled/borderless) + - virtual: Virtual scrolling + - warning: Warning configuration +- Container and Popup + - get_popup_container/get_target_container: Popup and target container functions +- Internationalization + - locale: Language code (e.g., zh_CN, en_US), supports automatic detection +- Theme + - theme/theme_config: Theme object and configuration; prefer theme_config + - themeMode: Provided by Gradio shared theme (light/dark) +- Other + - render_empty: Empty state rendering slot + - Element attributes: elem_id, elem_classes, elem_style + - Visibility: visible controls rendering + +Section sources + +- [**init**.py:19-82](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L19-L82) +- [config-provider.tsx:53-70](file://frontend/antd/config-provider/config-provider.tsx#L53-L70) +- [locales.ts:12-87](file://frontend/antd/config-provider/locales.ts#L12-L87) +- [XProvider.svelte:25-74](file://frontend/antdx/x-provider/XProvider.svelte#L25-L74) diff --git a/.wiki/en/Ant Design X Components/Wake Components/Prompts Component.md b/.wiki/en/Ant Design X Components/Wake Components/Prompts Component.md new file mode 100644 index 00000000..6be74dfa --- /dev/null +++ b/.wiki/en/Ant Design X Components/Wake Components/Prompts Component.md @@ -0,0 +1,408 @@ +# Prompts Component + + +**Files Referenced in This Document** +- [frontend/antdx/prompts/prompts.tsx](file://frontend/antdx/prompts/prompts.tsx) +- [frontend/antdx/prompts/context.ts](file://frontend/antdx/prompts/context.ts) +- [frontend/antdx/prompts/item/Index.svelte](file://frontend/antdx/prompts/item/Index.svelte) +- [frontend/antdx/prompts/item/prompts.item.tsx](file://frontend/antdx/prompts/item/prompts.item.tsx) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [backend/modelscope_studio/components/antdx/prompts/__init__.py](file://backend/modelscope_studio/components/antdx/prompts/__init__.py) +- [backend/modelscope_studio/components/antdx/prompts/item/__init__.py](file://backend/modelscope_studio/components/antdx/prompts/item/__init__.py) +- [docs/components/antdx/prompts/README.md](file://docs/components/antdx/prompts/README.md) +- [docs/components/antdx/prompts/demos/basic.py](file://docs/components/antdx/prompts/demos/basic.py) +- [docs/components/antdx/prompts/demos/nest_usage.py](file://docs/components/antdx/prompts/demos/nest_usage.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Usage Examples and Configuration](#appendix-usage-examples-and-configuration) + +## Introduction + +The Prompts component is used to display a set of preset questions or suggestion items, helping users quickly select an input direction and enhancing the naturalness and efficiency of conversational guidance. This component is based on Ant Design X's Prompts implementation, bridged in the frontend via a Svelte/React hybrid framework. It supports: + +- Prompt template management: Flexibly organize sub-content such as titles, icons, tags, and descriptions via slots +- Preset instruction configuration: Supports vertical layout, wrapping, style overrides, class names, and other configurations +- Nested usage: Supports nesting prompt items inside other prompt items to create hierarchical suggestions +- Dynamic content generation: Collects child items via context and renders them into the data structure required by Ant Design X +- Event handling: Provides an item_click callback to execute business logic when a prompt item is clicked + +## Project Structure + +This component is located under the frontend antdx category and uses a layered design of "container component + item handler": + +- Container Component: Responsible for collecting slot content, resolving context, and rendering into the items structure required by Ant Design X +- Item Handler: Responsible for wrapping each prompt item into a structure recognizable by the container, supporting nesting +- Utility Functions: Provides general "item context" and "render child items" capabilities, reused across multiple components + +```mermaid +graph TB +subgraph "Frontend antdx" +P["Prompts Container
frontend/antdx/prompts/prompts.tsx"] +Ctx["Items Context
frontend/antdx/prompts/context.ts"] +Item["Item Handler
frontend/antdx/prompts/item/prompts.item.tsx"] +ItemUI["Item UI Wrapper
frontend/antdx/prompts/item/Index.svelte"] +Utils1["createItemsContext
frontend/utils/createItemsContext.tsx"] +Utils2["renderItems
frontend/utils/renderItems.tsx"] +end +subgraph "Backend" +BP["Backend Container Component
backend/.../prompts/__init__.py"] +BI["Backend Item Component
backend/.../prompts/item/__init__.py"] +end +P --> Ctx +P --> Utils2 +Ctx --> Utils1 +Item --> Ctx +ItemUI --> Item +P --> BP +Item --> BI +``` + +Diagram Sources + +- [frontend/antdx/prompts/prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [frontend/antdx/prompts/context.ts:1-7](file://frontend/antdx/prompts/context.ts#L1-L7) +- [frontend/antdx/prompts/item/prompts.item.tsx:1-22](file://frontend/antdx/prompts/item/prompts.item.tsx#L1-L22) +- [frontend/antdx/prompts/item/Index.svelte:1-69](file://frontend/antdx/prompts/item/Index.svelte#L1-L69) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:1-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L1-L88) +- [backend/modelscope_studio/components/antdx/prompts/item/**init**.py:1-48](file://backend/modelscope_studio/components/antdx/prompts/item/__init__.py#L1-L48) + +Section Sources + +- [frontend/antdx/prompts/prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [frontend/antdx/prompts/context.ts:1-7](file://frontend/antdx/prompts/context.ts#L1-L7) +- [frontend/antdx/prompts/item/prompts.item.tsx:1-22](file://frontend/antdx/prompts/item/prompts.item.tsx#L1-L22) +- [frontend/antdx/prompts/item/Index.svelte:1-69](file://frontend/antdx/prompts/item/Index.svelte#L1-L69) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:1-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L1-L88) +- [backend/modelscope_studio/components/antdx/prompts/item/**init**.py:1-48](file://backend/modelscope_studio/components/antdx/prompts/item/__init__.py#L1-L48) + +## Core Components + +- Container Component: Prompts + - Responsibility: Collects slot content (title, items) and child items, resolves context, converts child items into the items data structure required by Ant Design X, and renders them + - Key Points: Supports passing external items data; if not provided, parses child items from the default or named slots in context; the title slot takes priority over props.title +- Item Handler: Prompts.Item + - Responsibility: Wraps each prompt item into a structure recognizable by the container, supporting slots (label, icon, description) and visibility control + - Key Points: Only allows the default slot as item content; supports extra property forwarding and passes internal index and slot key +- Item Context: createItemsContext + - Responsibility: Provides ItemsContext, uniformly collecting and updating child items across slots, supporting nested sub-contexts + - Key Points: setItem supports updates by slot key and index; onChange callback notifies the parent context +- Render Utility: renderItems + - Responsibility: Renders Item structures from context into a React-usable object tree, automatically handling slots, cloning, and parameterized rendering + - Key Points: Supports children key, withParams parameterized rendering, forceClone forced cloning + +Section Sources + +- [frontend/antdx/prompts/prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) +- [frontend/antdx/prompts/item/prompts.item.tsx:7-19](file://frontend/antdx/prompts/item/prompts.item.tsx#L7-L19) +- [frontend/antdx/prompts/item/Index.svelte:16-68](file://frontend/antdx/prompts/item/Index.svelte#L16-L68) +- [frontend/utils/createItemsContext.tsx:97-273](file://frontend/utils/createItemsContext.tsx#L97-L273) +- [frontend/utils/renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +## Architecture Overview + +The runtime architecture of Prompts consists of "frontend container + item handler + context collection + render utility", with the backend bridging to the frontend through Gradio components. + +```mermaid +sequenceDiagram +participant U as "User" +participant F as "Frontend Container (Prompts)" +participant C as "Items Context" +participant R as "Render Utility (renderItems)" +participant X as "Ant Design X (Prompts)" +U->>F : Create Prompts with props/slots +F->>C : useItems to get items context +C-->>F : Return child items from default/named slots +F->>R : Convert child items to Ant Design X required structure +R-->>F : Return items array +F->>X : Render with items/title/other config +X-->>U : Display Prompts UI +``` + +Diagram Sources + +- [frontend/antdx/prompts/prompts.tsx:16-38](file://frontend/antdx/prompts/prompts.tsx#L16-L38) +- [frontend/utils/renderItems.tsx:23-38](file://frontend/utils/renderItems.tsx#L23-L38) +- [frontend/utils/createItemsContext.tsx:108-170](file://frontend/utils/createItemsContext.tsx#L108-L170) + +## Detailed Component Analysis + +### Container Component: Prompts + +- Slots and Properties + - Supported slots: title, items + - Supported properties: vertical, wrap, styles, class_names, root_class_name, fade_in, fade_in_left, etc. +- Context Resolution + - If external items are provided, use them directly; otherwise parse from default or items slots in context + - The title slot takes priority over props.title +- Rendering Strategy + - Uses renderItems to convert Item structures from context into the object array required by Ant Design X + - Clones and parameterizes slot content to ensure correct React rendering + +```mermaid +flowchart TD +Start(["Enter Prompts"]) --> CheckItems["Are items provided?"] +CheckItems --> |Yes| UseExternal["Use external items"] +CheckItems --> |No| ResolveCtx["Resolve items/default from context"] +ResolveCtx --> Render["Call renderItems to convert"] +UseExternal --> Render +Render --> PassProps["Pass to Ant Design X component"] +PassProps --> End(["Render complete"]) +``` + +Diagram Sources + +- [frontend/antdx/prompts/prompts.tsx:16-38](file://frontend/antdx/prompts/prompts.tsx#L16-L38) +- [frontend/utils/renderItems.tsx:23-38](file://frontend/utils/renderItems.tsx#L23-L38) + +Section Sources + +- [frontend/antdx/prompts/prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:28-69](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L28-L69) + +### Item Handler: Prompts.Item + +- Slots and Properties + - Supported slots: label, icon, description + - Supported properties: key, label, description, icon, disabled, visible, elem_id, elem_classes, elem_style, etc. +- Internal Processing + - Registers child items into context via ItemHandler, supporting recursive rendering of item children + - Only allows the default slot as item content to avoid ambiguity from multi-level slots +- Visibility and Styles + - visible controls rendering; elem_id/elem_classes/elem_style support style customization + +```mermaid +classDiagram +class PromptsItem { ++props : Partial
Python Component"] +B_Pro["AntdXPrompts
Python Component"] +end +subgraph "Frontend" +F_SvWel["welcome/Index.svelte"] +F_SvPro["prompts/Index.svelte"] +F_RcWel["welcome/welcome.tsx"] +F_RcPro["prompts/prompts.tsx"] +F_Item["prompts/item/Index.svelte"] +end +subgraph "Third-party" +X["@ant-design/x
React Component Library"] +end +B_Wel --> F_SvWel --> F_RcWel --> X +B_Pro --> F_SvPro --> F_RcPro --> X +F_Item --> F_RcPro +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L55) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-70](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L70) +- [frontend/antdx/welcome/Index.svelte:1-65](file://frontend/antdx/welcome/Index.svelte#L1-L65) +- [frontend/antdx/prompts/Index.svelte:1-70](file://frontend/antdx/prompts/Index.svelte#L1-L70) +- [frontend/antdx/welcome/welcome.tsx:1-44](file://frontend/antdx/welcome/welcome.tsx#L1-L44) +- [frontend/antdx/prompts/prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [frontend/antdx/prompts/item/Index.svelte:1-68](file://frontend/antdx/prompts/item/Index.svelte#L1-L68) + +Section Sources + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) +- [frontend/antdx/welcome/Index.svelte:1-65](file://frontend/antdx/welcome/Index.svelte#L1-L65) +- [frontend/antdx/prompts/Index.svelte:1-70](file://frontend/antdx/prompts/Index.svelte#L1-L70) + +## Core Components + +- Welcome Component: Used for displaying the welcome page. Supports slot-based customization of title, description, icon, and extra content, along with style and variant configuration. +- Prompts Component: Used for displaying a set of prompt templates. Supports title slot, item slots, vertical layout, fade-in animations, wrapping, and provides an item_click callback event. + +Section Sources + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L55) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-70](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L70) + +## Architecture Overview + +The diagram below shows the data and control flow from the backend to the frontend and then to the third-party component library: + +```mermaid +sequenceDiagram +participant Py as "Backend Component
Python" +participant S as "Frontend Svelte
Index.svelte" +participant R as "Frontend React Wrapper
welcome.tsx / prompts.tsx" +participant X as "@ant-design/x
React Component" +Py->>S : Pass visibility/styles/additional props +S->>R : Forward props and slots +R->>X : Render native component handling icon/title/description/items +X-->>R : Component output +R-->>S : Return render result +S-->>Py : Complete one render cycle +``` + +Diagram Sources + +- [frontend/antdx/welcome/Index.svelte:49-64](file://frontend/antdx/welcome/Index.svelte#L49-L64) +- [frontend/antdx/welcome/welcome.tsx:16-41](file://frontend/antdx/welcome/welcome.tsx#L16-L41) +- [frontend/antdx/prompts/Index.svelte:56-69](file://frontend/antdx/prompts/Index.svelte#L56-L69) +- [frontend/antdx/prompts/prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) + +## Detailed Component Analysis + +### Welcome Component + +- Component Responsibilities + - Displays the welcome page with slot-based customization of title, description, icon, and extra content + - Supports style and class name injection, along with multiple variant styles + - Icon supports static resource paths or file objects, uniformly converted to accessible URLs via utility functions +- Key Properties + - Slots: extra, icon, description, title + - Variants: filled, borderless + - Styles: styles, class_names, root_class_name + - Metadata: elem_id, elem_classes, elem_style, visible, render +- Data Flow + - Backend receives parameters and processes static resource paths + - Frontend Svelte forwards props and slots to the React wrapper layer + - React layer determines rendering content based on slot priority strategy and converts icons to accessible URLs +- Interaction Logic + - Serves as the welcome page entry point, typically displayed during application initialization + - Can be hidden or transitioned to the conversation area after the user selects a prompt, based on business logic + +```mermaid +flowchart TD +Start(["Enter Welcome Render"]) --> CheckIcon["Is a slot icon provided?"] +CheckIcon --> |Yes| RenderSlotIcon["Render slot icon"] +CheckIcon --> |No| ConvertIcon["Convert icon to accessible URL"] +RenderSlotIcon --> RenderTitle["Render title slot/text"] +ConvertIcon --> RenderTitle +RenderTitle --> RenderDesc["Render description slot/text"] +RenderDesc --> RenderExtra["Render extra content slot/text"] +RenderExtra --> ApplyStyles["Apply styles and class names"] +ApplyStyles --> End(["Render complete"]) +``` + +Diagram Sources + +- [frontend/antdx/welcome/welcome.tsx:16-41](file://frontend/antdx/welcome/welcome.tsx#L16-L41) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:47-53](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L47-L53) + +Section Sources + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) +- [frontend/antdx/welcome/Index.svelte:1-65](file://frontend/antdx/welcome/Index.svelte#L1-L65) +- [frontend/antdx/welcome/welcome.tsx:1-44](file://frontend/antdx/welcome/welcome.tsx#L1-L44) + +### Prompts Component + +- Component Responsibilities + - Displays a set of prompt templates with support for title and item slots + - Provides item click event callbacks to trigger subsequent interactions + - Supports visual configurations such as vertical layout, fade-in animations, and wrapping +- Key Properties + - Slots: title, items + - List configuration: items, vertical, fade_in, fade_in_left, wrap + - Styles and class names: styles, class_names, root_class_name + - Metadata: elem_id, elem_classes, elem_style, visible, render +- Data Flow + - Backend defines event listeners, mapping item_click to frontend events + - Frontend Svelte forwards props and slots to the React wrapper layer + - React layer merges external items with slot items, cloning on demand to avoid side effects +- Interaction Logic + - A callback is triggered when the user clicks a prompt item; specific behaviors can be bound at the business layer (e.g., filling the input box, initiating a request) + +```mermaid +sequenceDiagram +participant U as "User" +participant P as "Prompts Component" +participant Ctx as "Item Context" +participant X as "@ant-design/x
Prompts" +U->>P : Click a prompt item +P->>Ctx : Trigger item_click event +Ctx-->>P : Callback notification +P->>X : Render prompt list with merged items +X-->>U : Display click feedback +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-23](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L23) +- [frontend/antdx/prompts/Index.svelte:48-49](file://frontend/antdx/prompts/Index.svelte#L48-L49) +- [frontend/antdx/prompts/prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) + +Section Sources + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) +- [frontend/antdx/prompts/Index.svelte:1-70](file://frontend/antdx/prompts/Index.svelte#L1-L70) +- [frontend/antdx/prompts/prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [frontend/antdx/prompts/item/Index.svelte:1-68](file://frontend/antdx/prompts/item/Index.svelte#L1-L68) +- [frontend/antdx/prompts/item/prompts.item.tsx:1-21](file://frontend/antdx/prompts/item/prompts.item.tsx#L1-L21) + +## Dependency Analysis + +- Component Coupling + - Backend components are only responsible for parameter and static resource handling — low coupling + - Frontend Svelte layer handles prop forwarding and slot resolution — low coupling + - React wrapper layer is tightly coupled to @ant-design/x, but transparent to upper layers +- External Dependencies + - @ant-design/x: Provides native implementations of Welcome and Prompts + - Utility functions: File URL conversion, slot rendering, item rendering, etc. +- Event Mapping + - The backend maps the item_click event to frontend event names to ensure cross-layer consistency + +```mermaid +graph LR +Py["Backend Component"] --> Svelte["Frontend Svelte"] +Svelte --> ReactWrap["React Wrapper Layer"] +ReactWrap --> ADX["@ant-design/x"] +Py --> Utils["Utility Functions"] +Svelte --> Utils +ReactWrap --> Utils +``` + +Diagram Sources + +- [frontend/antdx/welcome/welcome.tsx:6-7](file://frontend/antdx/welcome/welcome.tsx#L6-L7) +- [frontend/antdx/prompts/prompts.tsx:9-11](file://frontend/antdx/prompts/prompts.tsx#L9-L11) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-23](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L23) + +Section Sources + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L55) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-70](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L70) +- [frontend/antdx/welcome/welcome.tsx:1-44](file://frontend/antdx/welcome/welcome.tsx#L1-L44) +- [frontend/antdx/prompts/prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) + +## Performance Considerations + +- Render Optimization + - Use async component imports to avoid blocking the initial render + - Delay slot content rendering to reduce unnecessary computation +- Resource Optimization + - Icons go through a unified URL conversion to avoid repeated downloads + - Item rendering uses a cloning strategy to reduce re-renders caused by shared state +- Event Handling + - Event mapping is completed in the frontend to reduce backend overhead + +## Troubleshooting Guide + +- Icon Not Displaying + - Check whether the icon path is correct and confirm it has been converted to an accessible URL via the utility function + - If using a slot icon, verify the slot content is rendering correctly +- Slot Content Not Taking Effect + - Confirm the slot name matches the slots supported by the component (Welcome: extra, icon, description, title; Prompts: title, items) + - Verify that the slot content is correctly wrapped in the React wrapper layer +- Click Events Not Firing + - Confirm the backend event listener is enabled and the frontend event mapping is correct + - Check whether the upper business layer has correctly bound the callback + +Section Sources + +- [frontend/antdx/welcome/welcome.tsx:23-37](file://frontend/antdx/welcome/welcome.tsx#L23-L37) +- [frontend/antdx/prompts/Index.svelte:48-49](file://frontend/antdx/prompts/Index.svelte#L48-L49) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-23](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L23) + +## Conclusion + +The Welcome and Prompts components provide high customizability and good extensibility for the initial user experience through clear responsibility separation and slot-based design. Combined with the native capabilities of @ant-design/x, they can satisfy both basic display requirements and complex interaction and recommendation scenarios. It is recommended to configure styles and events according to business objectives in real projects for a better user experience. + +## Appendix + +### Usage Examples and Best Practices + +- Welcome Page Design + - Use the Welcome component as the entry point for the first screen, configuring title, description, and icon via slots + - Configure variants and styles to match the overall design style + - Hide the welcome page and enter the conversation area after the user selects a prompt +- Prompts Configuration + - Use the Prompts component to display a set of prompt templates, supporting grouping and hierarchies + - Combine slots with external items for flexible prompt content management + - Bind the item_click event to enable click-to-use interactions +- User Onboarding Flow + - Display the welcome page during application initialization + - Show curated prompt sets to guide users to get started quickly + - Dynamically adjust prompt content and ordering based on user behavior + +Section Sources + +- [frontend/pro/chatbot/chatbot.tsx:108-115](file://frontend/pro/chatbot/chatbot.tsx#L108-L115) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py:603-619](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L603-L619) diff --git a/.wiki/en/Ant Design X Components/Wake Components/Welcome Component.md b/.wiki/en/Ant Design X Components/Wake Components/Welcome Component.md new file mode 100644 index 00000000..c4dd1c7c --- /dev/null +++ b/.wiki/en/Ant Design X Components/Wake Components/Welcome Component.md @@ -0,0 +1,424 @@ +# Welcome Component + + +**Files Referenced in This Document** +- [frontend/antdx/welcome/Index.svelte](file://frontend/antdx/welcome/Index.svelte) +- [frontend/antdx/welcome/welcome.tsx](file://frontend/antdx/welcome/welcome.tsx) +- [backend/modelscope_studio/components/antdx/welcome/__init__.py](file://backend/modelscope_studio/components/antdx/welcome/__init__.py) +- [docs/components/antdx/welcome/README.md](file://docs/components/antdx/welcome/README.md) +- [docs/components/antdx/welcome/demos/basic.py](file://docs/components/antdx/welcome/demos/basic.py) +- [frontend/antdx/welcome/package.json](file://frontend/antdx/welcome/package.json) +- [frontend/antdx/welcome/gradio.config.js](file://frontend/antdx/welcome/gradio.config.js) +- [docs/components/antdx/welcome/app.py](file://docs/components/antdx/welcome/app.py) +- [docs/helper/Docs.py](file://docs/helper/Docs.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) + + +## Update Summary + +**Changes Made** + +- Enhanced style support system with improved layout control capabilities +- Added flexShrink control for the icon area to optimize responsive layout behavior +- Improved style merging mechanism with support for more granular style customization + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Style Enhancement Features](#style-enhancement-features) +7. [Dependency Analysis](#dependency-analysis) +8. [Performance Considerations](#performance-considerations) +9. [Troubleshooting Guide](#troubleshooting-guide) +10. [Conclusion](#conclusion) +11. [Appendix](#appendix) + +## Introduction + +The Welcome component is designed to clearly communicate the intended purpose and expected functionality of an interface, targeting "AI agent product interface" scenarios. This component is based on Ant Design X's Welcome implementation, wrapped by a Python backend and bridged through a Svelte frontend. It provides slot-based extension capabilities, icon and copy customization, variant style control, and can be used as a layout element in Gradio applications. + +**Update** This update enhances the style support system, providing improved layout control capabilities and responsive design optimizations. + +## Project Structure + +The Welcome component consists of a backend Python wrapper class and a frontend Svelte/React bridge layer. The documentation system renders examples and descriptions through the Docs helper. + +```mermaid +graph TB +subgraph "Backend" +PY_INIT["Python Wrapper Class
__init__.py"] +DEV_COMP["Base Component Class
component.py"] +end +subgraph "Frontend" +SV_INDEX["Svelte Entry
Index.svelte"] +TS_WELCOME["React Bridge Component
welcome.tsx"] +PKG["Package Export Config
package.json"] +CFG["Gradio Build Config
gradio.config.js"] +end +subgraph "Documentation" +DOC_README["Component Docs
README.md"] +DOC_DEMOS["Demo Scripts
demos/basic.py"] +DOC_APP["Docs App Entry
app.py"] +DOC_HELPER["Docs Renderer
Docs.py"] +end +PY_INIT --> DEV_COMP +PY_INIT --> SV_INDEX +SV_INDEX --> TS_WELCOME +PKG --> SV_INDEX +CFG --> SV_INDEX +DOC_README --> DOC_APP +DOC_DEMOS --> DOC_APP +DOC_HELPER --> DOC_APP +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:1-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L1-L73) +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [frontend/antdx/welcome/Index.svelte:1-65](file://frontend/antdx/welcome/Index.svelte#L1-L65) +- [frontend/antdx/welcome/welcome.tsx:1-51](file://frontend/antdx/welcome/welcome.tsx#L1-L51) +- [frontend/antdx/welcome/package.json:1-15](file://frontend/antdx/welcome/package.json#L1-L15) +- [frontend/antdx/welcome/gradio.config.js:1-4](file://frontend/antdx/welcome/gradio.config.js#L1-L4) +- [docs/components/antdx/welcome/README.md:1-8](file://docs/components/antdx/welcome/README.md#L1-L8) +- [docs/components/antdx/welcome/demos/basic.py:1-37](file://docs/components/antdx/welcome/demos/basic.py#L1-L37) +- [docs/components/antdx/welcome/app.py:1-7](file://docs/components/antdx/welcome/app.py#L1-L7) +- [docs/helper/Docs.py:1-178](file://docs/helper/Docs.py#L1-L178) + +## Core Components + +- Backend Wrapper Class: Responsible for declaring supported slots, properties, styles, and rendering lifecycle, while converting static resource paths to accessible URLs. +- Frontend Bridge Layer: Encapsulates Ant Design X React components in Svelte style, supporting slot rendering and static resource URL resolution. +- Documentation and Examples: Provides minimal viable examples and documentation pages for quick onboarding. + +Key Responsibilities and Behaviors + +- Slot Support: title, description, icon, extra. +- Property Configuration: icon, title, description, variant (filled/borderless), style and class name injection, visibility and DOM attribute forwarding. +- Resource Handling: Resolves icon paths passed from the backend to ensure they can be correctly loaded in the Gradio environment. +- Rendering Strategy: Controls whether to render based on visible; injects shared rootUrl and apiPrefix in the Gradio context. + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:14-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L14-L55) +- [frontend/antdx/welcome/welcome.tsx:8-41](file://frontend/antdx/welcome/welcome.tsx#L8-L41) +- [frontend/antdx/welcome/Index.svelte:12-44](file://frontend/antdx/welcome/Index.svelte#L12-L44) + +## Architecture Overview + +The Welcome component uses a layered design of "backend component + frontend bridge + documentation examples". The backend handles component semantics and resource processing, the frontend handles UI rendering and slot integration, and the documentation system handles the unified presentation of examples and descriptions. + +```mermaid +sequenceDiagram +participant U as "User" +participant G as "Gradio App" +participant PY as "Backend Wrapper Class
AntdXWelcome" +participant SV as "Svelte Entry
Index.svelte" +participant RX as "React Component Bridge
welcome.tsx" +participant ADX as "Ant Design X
Welcome" +U->>G : Open page +G->>PY : Initialize and pass properties and slots +PY-->>SV : Inject extra properties and static resources +SV->>SV : Evaluate visible and render conditionally +SV->>RX : Pass properties, slots, and shared context +RX->>ADX : Render Ant Design X Welcome +ADX-->>U : Display title/description/icon/extra actions +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:37-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L37-L55) +- [frontend/antdx/welcome/Index.svelte:49-64](file://frontend/antdx/welcome/Index.svelte#L49-L64) +- [frontend/antdx/welcome/welcome.tsx:16-41](file://frontend/antdx/welcome/welcome.tsx#L16-L41) + +## Detailed Component Analysis + +### Backend Wrapper Class (Python) + +- Supported Slots: extra, icon, description, title. +- Key Properties: + - Icon: icon (supports local static file paths; converted to accessible URLs by the backend). + - Title and Description: title, description. + - Variant: variant (filled or borderless). + - Styles and Class Names: styles, class_names, elem_id, elem_classes, elem_style. + - Render Control: visible, render, as_item. +- Lifecycle: + - Placeholder implementations for preprocess/postprocess/example_payload/example_value; skip_api returns True, indicating this component does not participate in the standard API flow. +- Frontend Directory Resolution: Uses resolve_frontend_dir("welcome", type="antdx") to point to the frontend implementation. + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__() ++__init__(visible, elem_id, elem_classes, elem_style, render, ...) +} +class AntdXWelcome { ++EVENTS ++SLOTS ++additional_props ++extra ++icon ++styles ++class_names ++description ++variant ++title ++root_class_name ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +AntdXWelcome --|> ModelScopeLayoutComponent : "inherits" +``` + +**Diagram Sources** + +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:14-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L14-L55) +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) + +### Frontend Bridge Layer (Svelte + React) + +- Svelte Entry Responsibilities: + - Retrieves component properties and extra properties, filters out internally reserved fields (e.g., visible, \_internal), and forwards the remaining properties to the React component. + - Uses conditional rendering to load and render the React component only when visible is true. + - Passes Gradio's shared rootUrl and apiPrefix to the React component for resolving static resources. +- React Bridge Responsibilities: + - Wraps Ant Design X's Welcome component with sveltify to support slot rendering. + - Handles icon with priority: if a slot exists, renders the slot content; otherwise resolves the static resource URL. + - Supports both slot and string value dual-mode for title, description, and extra. + - **New**: Enhanced style support system providing better layout control capabilities. + +```mermaid +flowchart TD +Start(["Enter Svelte Entry"]) --> GetProps["Get component properties and extra props"] +GetProps --> Filter["Filter internal fields and forward"] +Filter --> Visible{"visible is true?"} +Visible --> |No| Skip["Skip rendering"] +Visible --> |Yes| Load["Dynamically import React component"] +Load --> Render["Render React bridge component"] +Render --> Styles["Apply style enhancement system"] +Styles --> Slots{"Slots exist?"} +Slots --> |Yes| SlotRender["Render slot content with ReactSlot"] +Slots --> |No| StaticURL["Resolve static resource URL"] +SlotRender --> Done(["Complete"]) +StaticURL --> Done +Skip --> End(["End"]) +Done --> End +``` + +**Diagram Sources** + +- [frontend/antdx/welcome/Index.svelte:22-44](file://frontend/antdx/welcome/Index.svelte#L22-L44) +- [frontend/antdx/welcome/welcome.tsx:16-41](file://frontend/antdx/welcome/welcome.tsx#L16-L41) + +**Section Sources** + +- [frontend/antdx/welcome/Index.svelte:12-44](file://frontend/antdx/welcome/Index.svelte#L12-L44) +- [frontend/antdx/welcome/welcome.tsx:8-41](file://frontend/antdx/welcome/welcome.tsx#L8-L41) + +### Documentation and Examples (Docs System) + +- The documentation app uses the Docs class to scan the README and demos directories, automatically rendering example code and run results. +- The demo scripts demonstrate two variants (default and borderless) and inject extra action buttons via slots. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant DocApp as "Docs App
app.py" +participant Helper as "Docs Renderer
Docs.py" +participant Demo as "Demo Script
basic.py" +participant Comp as "Welcome Component" +Dev->>DocApp : Start documentation service +DocApp->>Helper : Initialize and load docs and examples +Helper->>Demo : Dynamically import demo module +Demo->>Comp : Create Welcome instance and configure properties +Comp-->>Dev : Display result in documentation page +``` + +**Diagram Sources** + +- [docs/components/antdx/welcome/app.py:1-7](file://docs/components/antdx/welcome/app.py#L1-L7) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) +- [docs/components/antdx/welcome/demos/basic.py:6-36](file://docs/components/antdx/welcome/demos/basic.py#L6-L36) + +**Section Sources** + +- [docs/components/antdx/welcome/README.md:1-8](file://docs/components/antdx/welcome/README.md#L1-L8) +- [docs/components/antdx/welcome/demos/basic.py:1-37](file://docs/components/antdx/welcome/demos/basic.py#L1-L37) +- [docs/components/antdx/welcome/app.py:1-7](file://docs/components/antdx/welcome/app.py#L1-L7) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) + +## Style Enhancement Features + +### Enhanced Style Support System + +The Welcome component now provides more powerful style support and layout control capabilities, primarily in the following areas: + +#### Icon Area Layout Optimization + +- **flexShrink Control**: Sets `flexShrink: 0` for the icon area to ensure the icon maintains a fixed size in responsive layouts +- **Style Merging Mechanism**: Supports intelligent merging of user-defined styles with default styles +- **Responsive Adaptation**: Optimizes layout behavior across different screen sizes + +#### Style Customization Capabilities + +- **styles Parameter Support**: Fully supports passing the styles parameter from Ant Design X +- **Independent Icon Style Control**: Allows separate style customization for the icon area +- **Theme Consistency**: Maintains compatibility with the Ant Design X theme system + +#### Layout Control Enhancements + +- **Container Style Forwarding**: Supports container-level style control via elem_style and elem_classes +- **Flexbox Optimization**: Uses Flexbox layout for better content arrangement +- **Spacing Control**: Optimizes spacing between icon, title, and description + +```mermaid +graph LR +Styles["Style System"] --> IconStyle["Icon Style Control"] +Styles --> ContainerStyle["Container Style Forwarding"] +Styles --> LayoutControl["Layout Control Enhancement"] +IconStyle --> FlexShrink["flexShrink: 0"] +IconStyle --> CustomStyling["Custom Style Merging"] +ContainerStyle --> ElemStyle["elem_style Support"] +ContainerStyle --> ElemClasses["elem_classes Support"] +LayoutControl --> Responsive["Responsive Layout"] +LayoutControl --> Spacing["Spacing Optimization"] +``` + +**Diagram Sources** + +- [frontend/antdx/welcome/welcome.tsx:23-29](file://frontend/antdx/welcome/welcome.tsx#L23-L29) +- [frontend/antdx/welcome/Index.svelte:52-53](file://frontend/antdx/welcome/Index.svelte#L52-L53) + +**Section Sources** + +- [frontend/antdx/welcome/welcome.tsx:23-29](file://frontend/antdx/welcome/welcome.tsx#L23-L29) +- [frontend/antdx/welcome/Index.svelte:52-53](file://frontend/antdx/welcome/Index.svelte#L52-L53) + +## Dependency Analysis + +- Backend Dependencies: + - Base Component Class: Provides common layout component capabilities and context management. + - Frontend Directory Resolution: Uses resolve_frontend_dir to locate the frontend implementation. +- Frontend Dependencies: + - Ant Design X React component library. + - Gradio client tools: For static resource URL resolution. + - Svelte preprocessing toolchain: Bridges React components with Svelte. + - **New**: Style system enhancement dependencies providing better layout control capabilities. +- Documentation System Dependencies: + - Docs renderer responsible for scanning and rendering README and demos. + +```mermaid +graph LR +PY["AntdXWelcome
__init__.py"] --> BASE["ModelScopeLayoutComponent
component.py"] +PY --> FE_DIR["resolve_frontend_dir('welcome','antdx')"] +SV["Index.svelte"] --> PREACT["@svelte-preprocess-react/*"] +SV --> CLS["classnames"] +SV --> RX["welcome.tsx"] +RX --> ADX["@ant-design/x"] +RX --> GRCL["@gradio/client"] +RX --> PREACT +RX --> STYLES["Style Enhancement System"] +DOC["Docs.py"] --> APP["app.py"] +DOC --> DEMO["demos/basic.py"] +DOC --> READ["README.md"] +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:55-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L55-L55) +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [frontend/antdx/welcome/Index.svelte:1-10](file://frontend/antdx/welcome/Index.svelte#L1-L10) +- [frontend/antdx/welcome/welcome.tsx:1-7](file://frontend/antdx/welcome/welcome.tsx#L1-L7) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) +- [docs/components/antdx/welcome/demos/basic.py:1-5](file://docs/components/antdx/welcome/demos/basic.py#L1-L5) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:55-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L55-L55) +- [frontend/antdx/welcome/Index.svelte:1-10](file://frontend/antdx/welcome/Index.svelte#L1-L10) +- [frontend/antdx/welcome/welcome.tsx:1-7](file://frontend/antdx/welcome/welcome.tsx#L1-L7) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) + +## Performance Considerations + +- Conditional Rendering: Only loads and renders the React component when visible is true, avoiding unnecessary initialization and network requests. +- Dynamic Import: Async import of the React component reduces initial load. +- Resource Resolution: Resolves static resource URLs uniformly in the frontend, avoiding repeated computation and cross-origin issues. +- Slot Rendering: Prioritizes slot content, reducing string concatenation and template rendering costs. +- **New**: The style enhancement system uses an efficient style merging algorithm to avoid redundant renders and style conflicts. + +## Troubleshooting Guide + +- Icon Not Displaying + - Check whether the icon passed from the backend is a valid path or URL. + - Confirm that Gradio's shared rootUrl and apiPrefix have been correctly passed to the frontend. +- Slot Not Taking Effect + - Confirm the slot name is one of: title, description, icon, extra. + - Ensure slot content is correctly mounted at runtime. +- Component Not Rendering + - Check whether visible is true. + - Confirm the frontend implementation pointed to by FRONTEND_DIR exists and can be built. +- Documentation Examples Not Running + - Check whether the component nesting and Provider usage in demos/basic.py are correct. + - Confirm the documentation app entry and Docs renderer configuration are correct. +- **New**: Style Display Issues + - Check that the styles parameter format is correct. + - Confirm the style merging logic does not cause conflicts. + - Verify that the flexShrink property is not adversely affecting layout behavior. + +**Section Sources** + +- [frontend/antdx/welcome/Index.svelte:49-64](file://frontend/antdx/welcome/Index.svelte#L49-L64) +- [frontend/antdx/welcome/welcome.tsx:16-41](file://frontend/antdx/welcome/welcome.tsx#L16-L41) +- [docs/components/antdx/welcome/demos/basic.py:6-36](file://docs/components/antdx/welcome/demos/basic.py#L6-L36) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) + +## Conclusion + +The Welcome component, through the collaboration of backend and frontend, provides concise yet powerful welcome page display capabilities. Its slot-based design and resource resolution mechanism enable flexible personalization and integration in diverse scenarios. Combined with the documentation system's example and rendering capabilities, developers can quickly understand and use this component. + +**Update** This style enhancement further improves the component's layout control capabilities and responsive design performance, providing developers with more granular style customization options and a better user experience. + +## Appendix + +### Usage Examples (Overview) + +- Create a basic welcome page with icon, title, and description. +- Use the borderless variant for a lighter interface style. +- Inject extra action buttons via slots to enhance user guidance. +- **New**: Leverage the enhanced style system for more granular layout control. + +Reference Example Script Path + +- [docs/components/antdx/welcome/demos/basic.py:6-36](file://docs/components/antdx/welcome/demos/basic.py#L6-L36) + +**Section Sources** + +- [docs/components/antdx/welcome/demos/basic.py:1-37](file://docs/components/antdx/welcome/demos/basic.py#L1-L37) + +### Properties and Events Reference (Overview) + +- Supported Slots: extra, icon, description, title. +- Key Properties: icon, title, description, variant (filled/borderless), styles and class names, visibility and DOM attributes. +- Events: No events defined in the current version. +- Lifecycle: skip_api is true; does not participate in the standard API flow. +- **New**: Style enhancement support providing richer layout control options. + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:12-15](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L12-L15) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:31-37](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L31-L37) diff --git a/.wiki/en/Base Components/Application Component.md b/.wiki/en/Base Components/Application Component.md new file mode 100644 index 00000000..846a7e50 --- /dev/null +++ b/.wiki/en/Base Components/Application Component.md @@ -0,0 +1,424 @@ +# Application Component + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/base/application/__init__.py](file://backend/modelscope_studio/components/base/application/__init__.py) +- [frontend/base/application/Application.svelte](file://frontend/base/application/Application.svelte) +- [frontend/base/application/Index.svelte](file://frontend/base/application/Index.svelte) +- [backend/modelscope_studio/utils/dev/app_context.py](file://backend/modelscope_studio/utils/dev/app_context.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [docs/components/base/application/README-zh_CN.md](file://docs/components/base/application/README-zh_CN.md) +- [docs/components/base/application/README.md](file://docs/components/base/application/README.md) +- [docs/app.py](file://docs/app.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +The Application component is the application root container for modelscope-studio, responsible for hosting and uniformly managing all components and dependencies exported from `modelscope_studio`. It not only provides the fundamental runtime environment for applications, but also helps developers implement page behavior monitoring, theme and language adaptation, and custom event bridging through lifecycle event and browser environment data collection capabilities. + +- As an application root container: Ensures all `modelscope_studio` components are properly wrapped; otherwise the page may fail to preview. +- Lifecycle and environment awareness: Provides events for page mount, window resize, page unload, etc.; can retrieve language, theme, UA, screen size, and scroll position. +- Custom event bridging: Trigger custom events on the frontend via `window.ms_globals.dispatch`; Python side can receive them through the `ms.Application.custom` event. + +Section Sources + +- [docs/components/base/application/README-zh_CN.md:1-11](file://docs/components/base/application/README-zh_CN.md#L1-L11) +- [docs/components/base/application/README.md:1-11](file://docs/components/base/application/README.md#L1-L11) + +## Project Structure + +The Application component consists of a backend Python component class and a frontend Svelte implementation, with tool modules providing context and base class support. Documentation and examples are located in the docs directory for demonstration and explanation. + +```mermaid +graph TB +subgraph "Backend" +PY_APP["ModelScopeApplication
Python Component Class"] +APP_CTX["AppContext
Application Context"] +BASE_META["ModelScopeDataLayoutComponent
Base Class"] +end +subgraph "Frontend" +IDX["Index.svelte
Async Import Entry"] +CMP["Application.svelte
Core Implementation"] +end +subgraph "Docs & Examples" +DOCS_ZH["README-zh_CN.md"] +DOCS_EN["README.md"] +DOCS_APP["docs/app.py"] +end +PY_APP --> BASE_META +PY_APP --> APP_CTX +IDX --> CMP +DOCS_APP --> DOCS_ZH +DOCS_APP --> DOCS_EN +``` + +Diagram Sources + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/application/Application.svelte:1-149](file://frontend/base/application/Application.svelte#L1-L149) +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) +- [backend/modelscope_studio/utils/dev/component.py:101-169](file://backend/modelscope_studio/utils/dev/component.py#L101-L169) +- [docs/components/base/application/README-zh_CN.md:1-56](file://docs/components/base/application/README-zh_CN.md#L1-L56) +- [docs/components/base/application/README.md:1-56](file://docs/components/base/application/README.md#L1-L56) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +Section Sources + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/application/Application.svelte:1-149](file://frontend/base/application/Application.svelte#L1-L149) +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) +- [backend/modelscope_studio/utils/dev/component.py:101-169](file://backend/modelscope_studio/utils/dev/component.py#L101-L169) +- [docs/components/base/application/README-zh_CN.md:1-56](file://docs/components/base/application/README-zh_CN.md#L1-L56) +- [docs/components/base/application/README.md:1-56](file://docs/components/base/application/README.md#L1-L56) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## Core Components + +- Backend component class: `ModelScopeApplication` inherits from `ModelScopeDataLayoutComponent`, providing event registration, data model, example data, and frontend directory resolution capabilities. +- Frontend implementation: `Application.svelte` initializes page data on mount, binds resize/unload events, and exposes `window.ms_globals.dispatch` for custom event bridging. +- Context and base class: `AppContext` provides application instance setting and assertion; `ModelScopeDataLayoutComponent` provides layout context and internal state management. + +Section Sources + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [frontend/base/application/Application.svelte:1-149](file://frontend/base/application/Application.svelte#L1-L149) +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) +- [backend/modelscope_studio/utils/dev/component.py:101-169](file://backend/modelscope_studio/utils/dev/component.py#L101-L169) + +## Architecture Overview + +The Application component's runtime flow is as follows: the backend component class records the application instance during initialization; the frontend collects environment data and binds events during the mount phase; a custom event bridging channel is also provided. + +```mermaid +sequenceDiagram +participant Py as "Backend
ModelScopeApplication" +participant Ctx as "Context
AppContext" +participant FE as "Frontend
Application.svelte" +participant Win as "Browser
window" +Py->>Ctx : Set application instance +FE->>FE : onMount initialization +FE->>FE : Collect screen/language/theme/UA +FE->>Win : Bind resize/unload events +FE->>Py : Trigger mount/resize/unmount events +Win-->>FE : User calls window.ms_globals.dispatch(...) +FE->>Py : Trigger custom event +``` + +Diagram Sources + +- [backend/modelscope_studio/components/base/application/**init**.py:72-82](file://backend/modelscope_studio/components/base/application/__init__.py#L72-L82) +- [frontend/base/application/Application.svelte:87-129](file://frontend/base/application/Application.svelte#L87-L129) + +Section Sources + +- [backend/modelscope_studio/components/base/application/**init**.py:72-82](file://backend/modelscope_studio/components/base/application/__init__.py#L72-L82) +- [frontend/base/application/Application.svelte:87-129](file://frontend/base/application/Application.svelte#L87-L129) + +## Detailed Component Analysis + +### Backend Component Class: ModelScopeApplication + +- Design philosophy + - As the application root container, uniformly injects the application context, ensuring all subsequent components depend on an existing Application instance. + - Registers `mount`/`resized`/`unmount`/`custom` event listeners through the Gradio event system, enabling frontend-backend coordination. + - Uses `ApplicationPageData` as the data model, carrying screen, language, theme, UA, and other environment information. +- Key features + - Event registration: EVENTS defines four event listeners corresponding to page lifecycle and custom events. + - Data model: `data_model` points to `ApplicationPageData`; example data `example_payload`/`example_value` provides defaults. + - Frontend directory: `FRONTEND_DIR` is resolved to the `base/application` frontend implementation via `resolve_frontend_dir`. +- Lifecycle and context + - Sets `AppContext` in `__init__`, then calls the parent constructor, ensuring context is available when the component tree is being built. + - `preprocess`/`postprocess` pass data through unchanged, allowing the frontend to consume directly. + +```mermaid +classDiagram +class ModelScopeApplication { ++EVENTS ++SLOTS ++FRONTEND_DIR ++data_model ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class ModelScopeDataLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__() ++__init__(...) +} +class AppContext { ++set_app(app) ++has_app() ++assert_app() ++get_app() +} +ModelScopeApplication --|> ModelScopeDataLayoutComponent +ModelScopeApplication --> AppContext : "set/assert" +``` + +Diagram Sources + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/utils/dev/component.py:101-169](file://backend/modelscope_studio/utils/dev/component.py#L101-L169) +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) + +Section Sources + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/utils/dev/component.py:101-169](file://backend/modelscope_studio/utils/dev/component.py#L101-L169) +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) + +### Frontend Implementation: Application.svelte + +- Key highlights + - onMount initialization: Updates value and dispatches mount event; then binds resize and beforeunload events. + - resize event: Uses debounce (default 500ms) to update value and dispatch resize event, avoiding high-frequency repaints. + - beforeunload: Updates value and dispatches unmount event before the page unloads. + - Custom event: `window.ms_globals.dispatch(...)` forwards the argument array as a custom event. + - Visibility and styles: Controls rendering based on `visible`; `elem_id`/`elem_classes`/`elem_style` support external style injection. +- Data model + - `ApplicationPageData` contains `language`, `userAgent`, `theme`, `screen` (width/height/scrollX/scrollY). +- Event model + - Four event types: `mount`/`resized`/`unmount`/`custom`, corresponding to page lifecycle and custom events. + +```mermaid +flowchart TD +Start(["Mount Start"]) --> Init["Initialize value
Collect language/theme/UA/screen"] +Init --> Bind["Bind resize/unload events"] +Bind --> MountEvt{"Is mount event bound?"} +MountEvt --> |Yes| DispatchMount["Dispatch mount event"] +MountEvt --> |No| Wait["Wait for user interaction"] +Wait --> ResizeEvt{"Window resized?"} +ResizeEvt --> |Yes| Debounce["Debounce (default 500ms)"] +Debounce --> UpdateResize["Update value and dispatch resize"] +ResizeEvt --> |No| UnloadEvt{"Page about to unload?"} +UnloadEvt --> |Yes| UpdateUnload["Update value and dispatch unmount"] +UnloadEvt --> |No| CustomEvt{"window.ms_globals.dispatch called?"} +CustomEvt --> |Yes| DispatchCustom["Dispatch custom event"] +CustomEvt --> |No| End(["End"]) +``` + +Diagram Sources + +- [frontend/base/application/Application.svelte:87-129](file://frontend/base/application/Application.svelte#L87-L129) + +Section Sources + +- [frontend/base/application/Application.svelte:1-149](file://frontend/base/application/Application.svelte#L1-L149) + +### Entry Wrapper: Index.svelte + +- Purpose: Asynchronously imports `Application.svelte` to delay component loading and reduce initial screen burden. +- Rendering: Passes `children` through to the Application component, ensuring content rendering. + +Section Sources + +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) + +### Context and Base Class Support + +- AppContext + - `set_app`: Sets the current application instance during backend initialization. + - `assert_app`: Issues a warning if not set, prompting that Application was not imported. + - `get_app`: Gets the current application instance. +- ModelScopeDataLayoutComponent + - Provides layout context and internal state (`_internal`), ensuring the component tree structure is correct. + - Inherits the Gradio component metaclass, supporting events and data flow. + +Section Sources + +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) +- [backend/modelscope_studio/utils/dev/component.py:101-169](file://backend/modelscope_studio/utils/dev/component.py#L101-L169) + +### Usage Examples and Scenarios + +- Basic usage: Wrap all `modelscope_studio` components inside Application to ensure preview and interaction work correctly. +- Language adaptation: Get the user's language via `value.language`, dynamically switching text or formatting. +- Theme adaptation: Return content or styles with different weights based on `value.theme`. +- Custom events: Call `window.ms_globals.dispatch(...)` in any JS logic; receive on the Python side via `ms.Application.custom`. + +**Python Code Examples** + +```python +import gradio as gr +import modelscope_studio.components.base as ms +import modelscope_studio.components.antd as antd + +# Example 1: Basic wrapping usage +with gr.Blocks() as demo: + with ms.Application(): + with antd.ConfigProvider(): + with ms.AutoLoading(): + antd.Button("Hello ModelScope Studio") + +demo.launch() +``` + +```python +import gradio as gr +import modelscope_studio.components.base as ms +import modelscope_studio.components.antd as antd + +# Example 2: Listen to page mount event and adapt language/theme +with gr.Blocks() as demo: + with ms.Application() as app: + with antd.ConfigProvider(): + output = gr.Textbox(label="Page Info") + + @app.mount + def on_mount(data: ms.ApplicationData): + # Get user language and theme + lang = data.value.language + theme = data.value.theme + return gr.update(value=f"Language: {lang}, Theme: {theme}") + +demo.launch() +``` + +```python +import gradio as gr +import modelscope_studio.components.base as ms +import modelscope_studio.components.antd as antd + +# Example 3: Listen to custom events (combined with window.ms_globals.dispatch) +with gr.Blocks() as demo: + with ms.Application() as app: + with antd.ConfigProvider(): + output = gr.Textbox(label="Custom Event") + # Frontend can trigger via window.ms_globals.dispatch({type: 'my_event', payload: {...}}) + + @app.custom + def on_custom(data: ms.ApplicationData): + event_type = data.value.type if data.value else None + return gr.update(value=f"Received custom event: {event_type}") + +demo.launch() +``` + +Section Sources + +- [docs/components/base/application/README-zh_CN.md:12-20](file://docs/components/base/application/README-zh_CN.md#L12-L20) +- [docs/components/base/application/README.md:12-20](file://docs/components/base/application/README.md#L12-L20) + +### API and Type Descriptions + +- Properties + - value: `ApplicationPageData`, page data. +- Events + - mount: Triggered when the page mounts. + - resize: Triggered when the window size changes. + - unmount: Triggered when the page unloads. + - custom: Triggered via `window.ms_globals.dispatch(...)`. +- Types + - `ApplicationPageScreenData`: width, height, scrollX, scrollY. + - `ApplicationPageData`: screen, language, theme, userAgent. + +Section Sources + +- [docs/components/base/application/README-zh_CN.md:24-55](file://docs/components/base/application/README-zh_CN.md#L24-L55) +- [docs/components/base/application/README.md:24-55](file://docs/components/base/application/README.md#L24-L55) +- [backend/modelscope_studio/components/base/application/**init**.py:12-115](file://backend/modelscope_studio/components/base/application/__init__.py#L12-L115) + +## Dependency Analysis + +- Backend dependencies + - Gradio data classes and event system: Used for event listener registration and data models. + - Utility modules: `AppContext`, `ModelScopeDataLayoutComponent` provide context and base class capabilities. +- Frontend dependencies + - Svelte lifecycle hooks: `onMount`/`onDestroy`. + - `svelte-i18n`: Gets localized language. + - Style utilities: `styleObject2String`, `classnames`. +- Documentation and examples + - `docs/app.py` builds the site menu and documentation index, locating the Application component documentation. + +```mermaid +graph LR +PY["ModelScopeApplication"] --> GR["Gradio Events/Data Classes"] +PY --> CTX["AppContext"] +PY --> META["ModelScopeDataLayoutComponent"] +FE["Application.svelte"] --> SV["Svelte Lifecycle"] +FE --> I18N["svelte-i18n"] +FE --> STY["Style Utilities"] +DOC["docs/app.py"] --> DZ["README-zh_CN.md"] +DOC --> DE["README.md"] +``` + +Diagram Sources + +- [backend/modelscope_studio/components/base/application/**init**.py:5-9](file://backend/modelscope_studio/components/base/application/__init__.py#L5-L9) +- [frontend/base/application/Application.svelte:1-149](file://frontend/base/application/Application.svelte#L1-L149) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +Section Sources + +- [backend/modelscope_studio/components/base/application/**init**.py:5-9](file://backend/modelscope_studio/components/base/application/__init__.py#L5-L9) +- [frontend/base/application/Application.svelte:1-149](file://frontend/base/application/Application.svelte#L1-L149) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## Performance Considerations + +- Debounce strategy: The resize event uses 500ms debounce by default, reducing the risk of frequent reflows and event storms. +- Lazy loading: `Index.svelte` uses async imports, reducing initial screen resource pressure. +- Event binding: Dispatches events only when needed (`bind_*_event` or `attached_events` contains the corresponding event name), avoiding unnecessary event dispatches. +- Style and visibility: Controls rendering through `visible`; `elem_style` supports both string and object forms for flexible injection on demand. + +Section Sources + +- [frontend/base/application/Application.svelte:96-103](file://frontend/base/application/Application.svelte#L96-L103) +- [frontend/base/application/Index.svelte:5-7](file://frontend/base/application/Index.svelte#L5-L7) + +## Troubleshooting Guide + +- Page cannot preview + - Symptom: Components cannot render normally because Application is not wrapped. + - Resolution: Ensure all `modelscope_studio` components are wrapped by Application. +- Application instance not detected + - Symptom: Console warning appears, indicating Application component not found. + - Resolution: Check if Application is correctly imported and initialized from `modelscope_studio.components.base`. +- Events not triggering + - Symptom: `resize`/`mount`/`unmount`/`custom` events not triggering as expected. + - Resolution: Confirm the frontend has bound the corresponding event (`bind_*_event` or `attached_events` contains the event name); custom events must be triggered via `window.ms_globals.dispatch(...)`. +- Language/theme not taking effect + - Symptom: Language or theme not changing according to user environment. + - Resolution: Ensure the frontend correctly reads `navigator` and shared theme; if necessary, handle branching on the Python side based on `value.language`/`value.theme`. + +Section Sources + +- [docs/components/base/application/README-zh_CN.md:3-11](file://docs/components/base/application/README-zh_CN.md#L3-L11) +- [docs/components/base/application/README.md:3-11](file://docs/components/base/application/README.md#L3-L11) +- [backend/modelscope_studio/utils/dev/app_context.py:16-21](file://backend/modelscope_studio/utils/dev/app_context.py#L16-L21) +- [frontend/base/application/Application.svelte:91-115](file://frontend/base/application/Application.svelte#L91-L115) + +## Conclusion + +The Application component, as the application root container for modelscope-studio, bears the key responsibilities of context injection, lifecycle events, and environment data collection. Through the collaboration of the backend component class and frontend implementation, it provides a stable fundamental runtime environment for the entire application and supports flexible theme/language adaptation and custom event bridging. Following the best practices and troubleshooting recommendations in this document can effectively improve development efficiency and runtime stability. + +## Appendix + +- Version information: v2.0.0 +- Related documentation: English and Chinese documentation for the Application component, including examples and API descriptions. + +Section Sources + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [docs/components/base/application/README-zh_CN.md:1-56](file://docs/components/base/application/README-zh_CN.md#L1-L56) +- [docs/components/base/application/README.md:1-56](file://docs/components/base/application/README.md#L1-L56) diff --git a/.wiki/en/Base Components/AutoLoading Component.md b/.wiki/en/Base Components/AutoLoading Component.md new file mode 100644 index 00000000..d81e030e --- /dev/null +++ b/.wiki/en/Base Components/AutoLoading Component.md @@ -0,0 +1,339 @@ +# AutoLoading Component + + +**Files Referenced in This Document** +- [auto-loading.tsx](file://frontend/base/auto-loading/auto-loading.tsx) +- [Index.svelte](file://frontend/base/auto-loading/Index.svelte) +- [useLoadingStatus.ts](file://frontend/base/auto-loading/useLoadingStatus.ts) +- [auto-loading.less](file://frontend/base/auto-loading/auto-loading.less) +- [package.json](file://frontend/base/auto-loading/package.json) +- [gradio.config.js](file://frontend/base/auto-loading/gradio.config.js) +- [__init__.py](file://backend/modelscope_studio/components/base/auto_loading/__init__.py) +- [loading-status.svelte.ts](file://frontend/svelte-preprocess-react/svelte-contexts/loading-status.svelte.ts) +- [import.ts](file://frontend/svelte-preprocess-react/component/import.ts) +- [README.md](file://docs/components/base/auto_loading/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +The AutoLoading component automatically adds loading feedback and error notifications to wrapped content when the Gradio frontend makes requests to the backend. It automatically collects the loading states of child components and displays loading animations or error information at the appropriate time, enhancing user experience. The component supports custom rendering slots, mask layers, timer display, and various configuration options, suitable for global fallback and fine-grained local control. + +## Project Structure + +AutoLoading's frontend implementation is located in the base component directory and includes a Svelte entry, React wrapper component, state hook, and style file; the backend Python component is responsible for declaring the frontend resource path and skipping API calls. The documentation provides component descriptions and example entries. + +```mermaid +graph TB +subgraph "Frontend (base/auto-loading)" +A["Index.svelte
Svelte Entry"] --> B["auto-loading.tsx
React Wrapper Component"] +B --> C["useLoadingStatus.ts
Loading State Hook"] +B --> D["auto-loading.less
Styles"] +A --> E["package.json
Export Config"] +A --> F["gradio.config.js
Build Config"] +end +subgraph "Backend (modelscope_studio/components/base/auto_loading)" +G["__init__.py
Declare Frontend Directory / Skip API"] +end +subgraph "Docs (docs/components/base/auto_loading)" +H["README.md
Usage Instructions & Examples"] +end +A -. integrates .-> B +A -. configures .-> E +A -. builds .-> F +G -. resources .-> A +H -. uses .-> A +``` + +**Diagram Sources** + +- [Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [auto-loading.tsx:1-179](file://frontend/base/auto-loading/auto-loading.tsx#L1-L179) +- [useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [auto-loading.less:1-28](file://frontend/base/auto-loading/auto-loading.less#L1-L28) +- [package.json:1-15](file://frontend/base/auto-loading/package.json#L1-L15) +- [gradio.config.js:1-4](file://frontend/base/auto-loading/gradio.config.js#L1-L4) +- [**init**.py:47-64](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L47-L64) +- [README.md:1-36](file://docs/components/base/auto_loading/README.md#L1-L36) + +**Section Sources** + +- [Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [auto-loading.tsx:1-179](file://frontend/base/auto-loading/auto-loading.tsx#L1-L179) +- [useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [auto-loading.less:1-28](file://frontend/base/auto-loading/auto-loading.less#L1-L28) +- [package.json:1-15](file://frontend/base/auto-loading/package.json#L1-L15) +- [gradio.config.js:1-4](file://frontend/base/auto-loading/gradio.config.js#L1-L4) +- [**init**.py:47-64](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L47-L64) +- [README.md:1-36](file://docs/components/base/auto_loading/README.md#L1-L36) + +## Core Components + +- Svelte entry (Index.svelte): Parses properties, gets configuration type and slots, injects loading state context, and renders the React wrapper component on demand. +- React wrapper component (auto-loading.tsx): Decides whether to show loading animation, mask, timer, and queue information based on loading state; displays closable error notifications in error state. +- Loading state hook (useLoadingStatus.ts): Maintains timer, ETA, and formatted time, deriving display data based on `ILoadingStatus`. +- Styles (auto-loading.less): Controls loading layer positioning, mask z-index, and error popup centering styles. +- Backend component (**init**.py): Declares the frontend directory, skips API calls, enabling direct use via frontend resource exports. +- Documentation (README.md): Explains the component's role, state meanings, default behavior, and example entry. + +**Section Sources** + +- [Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [auto-loading.tsx:25-176](file://frontend/base/auto-loading/auto-loading.tsx#L25-L176) +- [useLoadingStatus.ts:5-93](file://frontend/base/auto-loading/useLoadingStatus.ts#L5-L93) +- [auto-loading.less:1-28](file://frontend/base/auto-loading/auto-loading.less#L1-L28) +- [**init**.py:47-64](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L47-L64) +- [README.md:1-36](file://docs/components/base/auto_loading/README.md#L1-L36) + +## Architecture Overview + +AutoLoading's workflow revolves around "state collection — conditional rendering — UI display". The Svelte entry collects `ILoadingStatus` from child components via context; the React component selects loading animations or error notifications based on state and presents them via Ant Design components. + +```mermaid +sequenceDiagram +participant Child as "Child Component" +participant Bridge as "Loading State Bridge" +participant Auto as "AutoLoading (React)" +participant UI as "Ant Design Components" +Child->>Bridge : "setLoadingStatus(ILoadingStatus)" +Bridge-->>Auto : "loadingStatus (aggregated)" +Auto->>Auto : "useLoadingStatus() calculates ETA/timer" +Auto->>UI : "Render loading/error based on state" +UI-->>Auto : "User interaction (e.g. close error)" +Auto-->>Child : "Continue rendering child content" +``` + +**Diagram Sources** + +- [loading-status.svelte.ts:47-75](file://frontend/svelte-preprocess-react/svelte-contexts/loading-status.svelte.ts#L47-L75) +- [auto-loading.tsx:48-175](file://frontend/base/auto-loading/auto-loading.tsx#L48-L175) +- [useLoadingStatus.ts:17-81](file://frontend/base/auto-loading/useLoadingStatus.ts#L17-L81) + +## Detailed Component Analysis + +### Svelte Entry (Index.svelte) + +- Retrieves component properties, configuration type, and slots from the preprocessing context. +- Injects the generated `loadingStatus` context via `getLoadingStatus`, for consumption by the internal React component. +- Uses `importComponent` for lazy loading, ensuring the component loads only after global initialization is complete. +- Passes visibility, styles, class names, and other properties to the React wrapper component. + +Key points + +- On-demand rendering: Renders only when `visible` is true. +- Slots and configuration: `slots`, `configType`, `loadingStatus` passed as props. +- Key generation: Assigns a unique key to each loading state via `window.ms_globals.loadingKey`. + +**Section Sources** + +- [Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [import.ts:1-20](file://frontend/svelte-preprocess-react/component/import.ts#L1-L20) +- [loading-status.svelte.ts:47-75](file://frontend/svelte-preprocess-react/svelte-contexts/loading-status.svelte.ts#L47-L75) + +### React Wrapper Component (auto-loading.tsx) + +Responsibilities + +- Parses configuration type (currently supports `antd`), determining loading animation and error notification UI. +- Renders loading animation based on state (including mask, timer, progress/queue information). +- In error state, renders a closable error notification, clearing the internal instance after closing to avoid duplicate rendering. +- Supports custom slots: `render` (custom loading content), `errorRender` (custom error content), `loadingText` (custom loading text). + +Loading State Determination + +- `pending`/`generating` treated as loading; `completed`/`error` treated as ended. +- Dynamically displays progress and queue information when `progress` or `queue_position`/`queue_size` is present. +- Optional timer and ETA display. + +Style and Z-Index + +- Loading layer is absolutely positioned and covers the parent container; error notification is fixed and centered. +- Sets z-index based on theme token, ensuring mask and error notification layers are properly ordered. + +**Section Sources** + +- [auto-loading.tsx:25-176](file://frontend/base/auto-loading/auto-loading.tsx#L25-L176) +- [auto-loading.less:1-28](file://frontend/base/auto-loading/auto-loading.less#L1-L28) + +### Loading State Hook (useLoadingStatus.ts) + +Functionality + +- Maintains timer: Starts timing in `pending` state, stops in non-`pending` state. +- Calculates ETA and formats time: Combines `performance.now` and ETA field to calculate remaining time and elapsed time. +- Tracks old ETA: Records the old value when ETA updates and formats the new ETA. +- Returns state fields: `status`, `message`, `progress`, `queuePosition`, `queueSize`, `formattedEta`, `formattedTimer`. + +Performance Notes + +- Uses `requestAnimationFrame` loop to update timing, avoiding blocking the main thread. +- Uses `useMemoizedFn` to cache callbacks, reducing re-renders. + +**Section Sources** + +- [useLoadingStatus.ts:5-93](file://frontend/base/auto-loading/useLoadingStatus.ts#L5-L93) + +### Styles (auto-loading.less) + +Key points + +- Loading layer is absolutely positioned, covering the parent container, ensuring mask effect. +- Error notification is fixed-positioned and centered, avoiding layout jitter. +- Controls z-index and appearance via Ant Design class names and theme token. + +**Section Sources** + +- [auto-loading.less:1-28](file://frontend/base/auto-loading/auto-loading.less#L1-L28) + +### Backend Component (**init**.py) + +Key points + +- Declares frontend directory as `base/auto-loading`. +- Skips API calls; component is used only for frontend rendering and state collection. + +**Section Sources** + +- [**init**.py:47-64](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L47-L64) + +### Documentation (README.md) + +Key points + +- Component role: Automatically adds loading animations and error notifications to wrapped content. +- State descriptions: Four states — `pending`/`generating`/`completed`/`error`. +- Default behavior: `pending` starts loading; `generating`/`completed` ends; `error` ends loading (optionally shows error). +- API parameters: `generating`, `show_error`, `show_mask`, `show_timer`, `loading_text`, etc. + +**Section Sources** + +- [README.md:1-36](file://docs/components/base/auto_loading/README.md#L1-L36) + +## Dependency Analysis + +AutoLoading's dependencies are mainly reflected in the following aspects: + +- The Svelte entry depends on loading state context and import utilities, implementing lazy loading and state aggregation. +- The React component depends on Ant Design's Spin and Alert, and the theme token. +- `useLoadingStatus` depends on browser performance API and React hooks, implementing timing and state formatting. +- The backend component declares the frontend resource path, enabling the frontend component to load correctly through package exports. + +```mermaid +graph LR +Index["Index.svelte"] --> Import["import.ts
Lazy Loading"] +Index --> Ctx["loading-status.svelte.ts
Loading State Context"] +Index --> Auto["auto-loading.tsx"] +Auto --> Hook["useLoadingStatus.ts"] +Auto --> Less["auto-loading.less"] +Backend["__init__.py"] --> Index +Doc["README.md"] --> Index +``` + +**Diagram Sources** + +- [Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [import.ts:1-20](file://frontend/svelte-preprocess-react/component/import.ts#L1-L20) +- [loading-status.svelte.ts:1-75](file://frontend/svelte-preprocess-react/svelte-contexts/loading-status.svelte.ts#L1-L75) +- [auto-loading.tsx:1-179](file://frontend/base/auto-loading/auto-loading.tsx#L1-L179) +- [useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [auto-loading.less:1-28](file://frontend/base/auto-loading/auto-loading.less#L1-L28) +- [**init**.py:47-64](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L47-L64) +- [README.md:1-36](file://docs/components/base/auto_loading/README.md#L1-L36) + +**Section Sources** + +- [Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [auto-loading.tsx:1-179](file://frontend/base/auto-loading/auto-loading.tsx#L1-L179) +- [useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [auto-loading.less:1-28](file://frontend/base/auto-loading/auto-loading.less#L1-L28) +- [**init**.py:47-64](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L47-L64) +- [README.md:1-36](file://docs/components/base/auto_loading/README.md#L1-L36) + +## Performance Considerations + +- Deferred initialization: Using `importComponent` and the global initialization Promise avoids loading the component before it's ready, reducing initial screen pressure. +- Timer optimization: Uses `requestAnimationFrame` loop to update timing, reducing main thread usage; only starts timing in `pending` state. +- State aggregation: Only the innermost AutoLoading collects child component states, avoiding duplicate rendering and state conflicts. +- Style z-index: Ensures mask and error notifications don't cause layout reflows through z-index and absolute positioning. +- Custom rendering: Through `render` and `errorRender` slots, business teams can optimize loading and error UI themselves, reducing unnecessary component overhead. + +[This section is general performance recommendations; no "Section Sources" needed] + +## Troubleshooting Guide + +Common Issues and Solutions + +- Multiple nested AutoLoading: According to the documentation, only the innermost layer can collect child component states and display loading animations. If outer layers don't work, check the nesting level. +- Error notification not disappearing: The error notification is a closable component; the internal instance is cleared after closing. If still displayed, check if the close logic or styles are causing visual residue. +- Loading animation not appearing: Confirm whether `loadingStatus` enters `pending`/`generating` state; check if `generating`/`show_error` configuration meets expectations. +- Timer not updating: Timing only starts in `pending` state; if there's no `pending` state for a long time, the timer won't start. +- Mask z-index anomalies: Styles control z-index via theme token; if custom styles override `z-index`, check style priority. + +**Section Sources** + +- [README.md:5-19](file://docs/components/base/auto_loading/README.md#L5-L19) +- [auto-loading.tsx:139-166](file://frontend/base/auto-loading/auto-loading.tsx#L139-L166) +- [useLoadingStatus.ts:44-50](file://frontend/base/auto-loading/useLoadingStatus.ts#L44-L50) + +## Conclusion + +AutoLoading provides unified and customizable loading and error feedback capabilities for Gradio applications through the "state collection — conditional rendering — UI display" mechanism. Its deferred initialization and timer optimization help improve performance and experience; slots and configuration options meet diverse business needs. Combined with documentation and examples, it can be used flexibly in both global and local scenarios. + +[This section is summary content; no "Section Sources" needed] + +## Appendix + +### API Definitions (Parameters and Behavior) + +- generating: Whether to include `generating` state handling. +- show_error: Whether to display error information. +- show_mask: Whether to display the mask. +- show_timer: Whether to display the timer. +- loading_text: Custom loading text; when empty, uses the default text provided by Gradio (including elapsed time, queue position, etc.). + +Default Behavior + +- pending: Show loading animation. +- generating/completed: End loading animation. +- error: End loading animation; optionally show error information. + +**Section Sources** + +- [README.md:27-36](file://docs/components/base/auto_loading/README.md#L27-L36) +- [auto-loading.tsx:65-138](file://frontend/base/auto-loading/auto-loading.tsx#L65-L138) + +### Usage Examples (Scenarios and Recommendations) + +- Global fallback: Place one AutoLoading at the application root to ensure any request gets loading feedback. +- Fine-grained local control: Use separately in areas that need richer loading information, with custom display via `render` and `loadingText` slots. +- Error visibility: Control error information display via `show_error`; use `errorRender` to customize error UI when necessary. +- Queue and progress: When the backend uses `yield` for streaming returns, use `progress` and queue information to enhance user perception. + +**Section Sources** + +- [README.md:21-25](file://docs/components/base/auto_loading/README.md#L21-L25) +- [auto-loading.tsx:72-138](file://frontend/base/auto-loading/auto-loading.tsx#L72-L138) + +### Collaboration Patterns with Other Components + +- Collaboration with forms/lists: Using AutoLoading inside these components provides consistent loading and error feedback. +- Collaboration with the theme system: Controls mask and error notification z-index and appearance via Ant Design theme token. +- Collaboration with state context: Through the loading state context, states from multiple child components are aggregated; the nearest AutoLoading decides what to display. + +**Section Sources** + +- [Index.svelte:56-62](file://frontend/base/auto-loading/Index.svelte#L56-L62) +- [loading-status.svelte.ts:47-75](file://frontend/svelte-preprocess-react/svelte-contexts/loading-status.svelte.ts#L47-L75) +- [auto-loading.tsx:68-134](file://frontend/base/auto-loading/auto-loading.tsx#L68-L134) diff --git a/.wiki/en/Base Components/Base Components.md b/.wiki/en/Base Components/Base Components.md new file mode 100644 index 00000000..cecdd060 --- /dev/null +++ b/.wiki/en/Base Components/Base Components.md @@ -0,0 +1,505 @@ +# Base Components + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/base/application/__init__.py](file://backend/modelscope_studio/components/base/application/__init__.py) +- [backend/modelscope_studio/components/base/auto_loading/__init__.py](file://backend/modelscope_studio/components/base/auto_loading/__init__.py) +- [backend/modelscope_studio/components/base/slot/__init__.py](file://backend/modelscope_studio/components/base/slot/__init__.py) +- [backend/modelscope_studio/components/base/fragment/__init__.py](file://backend/modelscope_studio/components/base/fragment/__init__.py) +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [frontend/base/application/Index.svelte](file://frontend/base/application/Index.svelte) +- [frontend/base/auto-loading/Index.svelte](file://frontend/base/auto-loading/Index.svelte) +- [frontend/base/slot/Index.svelte](file://frontend/base/slot/Index.svelte) +- [frontend/base/fragment/Index.svelte](file://frontend/base/fragment/Index.svelte) +- [frontend/base/each/Index.svelte](file://frontend/base/each/Index.svelte) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document focuses on the "Base Components" system of ModelScope Studio, systematically explaining the design philosophy, data and control flow, role and collaboration within the overall component system, as well as providing usage examples, best practices, performance optimization suggestions, and solutions to common issues for core components such as Application, AutoLoading, Slot, and Fragment. The goal is to help developers quickly understand and correctly use these base components to build complex interfaces. + +## Project Structure + +The base components sit between the backend Python modules and the frontend Svelte implementations, bridged through a unified component base class and context mechanism. The backend is responsible for defining component classes, event and slot capabilities, data models, and lifecycle hooks; the frontend handles rendering, slot parsing, state management, and async loading. + +```mermaid +graph TB +subgraph "Backend" +PY_APP["Application Component
application/__init__.py"] +PY_AUTO["AutoLoading Component
auto_loading/__init__.py"] +PY_SLOT["Slot Component
slot/__init__.py"] +PY_FRAG["Fragment Component
fragment/__init__.py"] +PY_BASE_INIT["Base Component Exports
base/__init__.py"] +PY_DEV_COMP["Component Base Class
utils/dev/component.py"] +end +subgraph "Frontend" +FE_APP["Application Frontend Entry
base/application/Index.svelte"] +FE_AUTO["AutoLoading Frontend Entry
base/auto-loading/Index.svelte"] +FE_SLOT["Slot Frontend Entry
base/slot/Index.svelte"] +FE_FRAG["Fragment Frontend Entry
base/fragment/Index.svelte"] +FE_EACH["Each Frontend Entry
base/each/Index.svelte"] +FE_RENDER_SLOT["renderSlot Utility
utils/renderSlot.tsx"] +FE_RENDER_PARAMS_SLOT["renderParamsSlot Utility
utils/renderParamsSlot.tsx"] +end +PY_APP --> FE_APP +PY_AUTO --> FE_AUTO +PY_SLOT --> FE_SLOT +PY_FRAG --> FE_FRAG +PY_BASE_INIT --> PY_APP +PY_BASE_INIT --> PY_AUTO +PY_BASE_INIT --> PY_SLOT +PY_BASE_INIT --> PY_FRAG +PY_DEV_COMP --> PY_APP +PY_DEV_COMP --> PY_AUTO +PY_DEV_COMP --> PY_SLOT +PY_DEV_COMP --> PY_FRAG +FE_SLOT --> FE_RENDER_SLOT +FE_SLOT --> FE_RENDER_PARAMS_SLOT +FE_AUTO --> FE_EACH +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:8-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L8-L65) +- [backend/modelscope_studio/components/base/slot/**init**.py:8-50](file://backend/modelscope_studio/components/base/slot/__init__.py#L8-L50) +- [backend/modelscope_studio/components/base/fragment/**init**.py:8-49](file://backend/modelscope_studio/components/base/fragment/__init__.py#L8-L49) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +**Section Sources** + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +## Core Components + +This section provides an overview of the roles, features, and usage of Application, AutoLoading, Slot, Fragment, and Each. + +- Application (Application Container) + - Role: Acts as the top-level layout container, handling page-level event bindings (custom events, mount, window resize, unmount) and providing page environment data (screen size, language, theme, UA). + - Key points: Supports event listener registration; serves as the application context root node, ensuring all child components are created within a valid application context. + - Typical usage: Placed at the application entry point, with other base or business components nested inside; event listeners handle browser lifecycle and interaction events. + +- AutoLoading (Auto-Loading Placeholder) + - Role: Automatically switches between loading state, error state, and content rendering based on generation state, error state, and mask/timer configurations; supports named slots (render, errorRender, loadingText) for flexible customization. + - Key points: `skip_api` is marked true to avoid duplicate API calls; reads loading state from the frontend context and links to slot rendering. + - Typical usage: Wraps content areas that need lazy loading or conditional rendering; dynamically set `generating`/`showError` based on business logic. + +- Slot (Slot) + - Role: Declares and registers named slots, supports parameter mapping functions, bridges DOM slots with React/JSX content; can be nested to form hierarchical slot keys. + - Key points: Sets slot key and parameter mapping via context; at render time, utility functions clone and inject slot content into target elements. + - Typical usage: Declare slots in parent components and render them on demand in child components; used for complex layouts and conditional rendering. + +- Fragment (Fragment) + - Role: Lightweight container that does not introduce additional DOM wrappers; only holds child nodes and slots; commonly used for conditional rendering, list item wrapping, etc. + - Key points: `skip_api` is marked true; does not trigger extra rendering overhead; can be used with Each/Slot. + - Typical usage: Used as list item containers in Each; wraps multiple child nodes in conditional branches without adding extra levels. + +- Each (List Rendering) + - Role: Provides bulk rendering capabilities for list or array data, mapping each element in the list with corresponding slots/Fragments for parameter mapping and rendering. + - Key points: Frontend-only rendering component with no corresponding backend Python class; used with Fragment for list item rendering, and with Slot for parameter-mapped slots. + - Parameter mapping: Through the Slot's `params_mapping` property, injects the current item and index of list elements into child component slots. + - Typical usage: Wrap `ms.Each` inside parent components that support item rendering, using `ms.Fragment` and `ms.Slot` (with `params_mapping`) to achieve dynamic list rendering. + +**Section Sources** + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:8-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L8-L65) +- [backend/modelscope_studio/components/base/slot/**init**.py:8-50](file://backend/modelscope_studio/components/base/slot/__init__.py#L8-L50) +- [backend/modelscope_studio/components/base/fragment/**init**.py:8-49](file://backend/modelscope_studio/components/base/fragment/__init__.py#L8-L49) +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +## Architecture Overview + +The diagram below shows the overall call chain and collaboration relationships between base components from backend to frontend. + +```mermaid +sequenceDiagram +participant PyApp as "Backend Application" +participant PyAuto as "Backend AutoLoading" +participant PySlot as "Backend Slot" +participant PyFrag as "Backend Fragment" +participant FeApp as "Frontend Application" +participant FeAuto as "Frontend AutoLoading" +participant FeSlot as "Frontend Slot" +participant FeFrag as "Frontend Fragment" +participant Utils as "Render Utilities (renderSlot/renderParamsSlot)" +PyApp->>FeApp : Initialize and bind events +PyAuto->>FeAuto : Configure generate/error/mask/text +PySlot->>FeSlot : Register slot key and parameter mapping +FeSlot->>Utils : Render slot (cloneable/force clone/with params) +Utils-->>FeSlot : Return ReactSlot render result +PyFrag->>FeFrag : Act as container for child nodes +FeAuto->>FeFrag : Switch between loading/error/content +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:8-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L8-L65) +- [backend/modelscope_studio/components/base/slot/**init**.py:8-50](file://backend/modelscope_studio/components/base/slot/__init__.py#L8-L50) +- [backend/modelscope_studio/components/base/fragment/**init**.py:8-49](file://backend/modelscope_studio/components/base/fragment/__init__.py#L8-L49) +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +## Detailed Component Analysis + +### Application Component + +- Design philosophy + - As the application-level root container, centrally handles browser lifecycle events and page environment information, providing a consistent runtime context for upper-layer components. + - Extends application behavior boundaries through event listeners, such as custom event dispatch, mount/unmount callbacks, and window resize responses. +- Data model + - Page screen data (width/height, scroll position), language, theme, user agent, etc., enabling frontend adaptation to different devices and themes. +- Frontend implementation highlights + - Asynchronously imports the actual component, delaying rendering to improve initial screen performance. + - Passes `children` through to child components, maintaining flexibility in the tree structure. +- Usage example path + - Create Application at the application entry and organize the page layout and business components inside it. + - Example reference: [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) + +```mermaid +classDiagram +class ModelScopeApplication { ++EVENTS ++SLOTS ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class ModelScopeDataLayoutComponent { ++skip_api ++__exit__() ++__init__(...) +} +ModelScopeApplication --|> ModelScopeDataLayoutComponent : "inherits" +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/utils/dev/component.py:101-169](file://backend/modelscope_studio/utils/dev/component.py#L101-L169) + +**Section Sources** + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) + +### AutoLoading Component + +- Design philosophy + - Automates handling of "generating/error/loading text" states, reducing boilerplate code on the business side; highly customizable through slots. +- Key properties + - generating: Whether currently in generating state + - show_error: Whether to display error state + - show_mask/show_timer: Mask and timer toggles + - loading_text: Custom loading text + - Supported slots: render, errorRender, loadingText +- Frontend implementation highlights + - Reads loading state from context to determine which type of content to render. + - Maps backend-passed properties and slots to frontend components via `processProps` and `getSlots`. +- Usage example path + - Wrap areas that need lazy loading or conditional rendering with AutoLoading, and switch `generating`/`showError` based on business state. + - Example reference: [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) + +```mermaid +flowchart TD +Start(["Enter AutoLoading"]) --> CheckVisible["Check Visibility"] +CheckVisible --> |Not Visible| End(["End"]) +CheckVisible --> |Visible| ReadCtx["Read Loading State (generating/error)"] +ReadCtx --> Decide{"Choose Content to Render"} +Decide --> |Generating| RenderLoading["Render loadingText Slot"] +Decide --> |Error| RenderError["Render errorRender Slot"] +Decide --> |Normal| RenderContent["Render render Slot / Default Content"] +RenderLoading --> End +RenderError --> End +RenderContent --> End +``` + +**Diagram Sources** + +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) + +**Section Sources** + +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:8-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L8-L65) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) + +### Slot Component + +- Design philosophy + - Provides named slot and parameter mapping capabilities, bridging Svelte slots with React/JSX rendering; supports nested slot keys and dynamic parameters. +- Key properties + - value: Slot key name (supports nesting) + - params_mapping: Parameter mapping function string, converted to a function at runtime +- Frontend implementation highlights + - Sets the current slot key and parameter mapping function via context. + - Uses `renderSlot`/`renderParamsSlot` to clone and inject slot content into target elements, supporting force clone and multi-target rendering. +- Usage example path + - Declare Slot in parent components and render on demand in child components; or use with parameter mapping in Each for dynamic rendering. + - Example references: [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68), [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29), [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +```mermaid +sequenceDiagram +participant Parent as "Parent Component (Slot)" +participant Ctx as "Slot Context" +participant Utils as "renderSlot/renderParamsSlot" +participant Child as "Child Component" +Parent->>Ctx : Set slot key and parameter mapping +Parent->>Utils : Request slot rendering (cloneable/force clone/with params) +Utils-->>Parent : Return ReactSlot render result +Parent->>Child : Pass through render result +``` + +**Diagram Sources** + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +**Section Sources** + +- [backend/modelscope_studio/components/base/slot/**init**.py:8-50](file://backend/modelscope_studio/components/base/slot/__init__.py#L8-L50) +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +### Fragment Component + +- Design philosophy + - Acts as a lightweight container without introducing additional DOM wrappers; only holds child nodes and slots; suitable for conditional rendering and list item wrapping. +- Frontend implementation highlights + - Asynchronously imports the actual component via lazy loading; renders only when visibility is true. + - Does not reset the slot key, avoiding impact on sibling nodes' slot state. +- Usage example path + - Used as list item container in Each or conditional rendering; prefer Fragment when a wrapper-free container is needed. + - Example reference: [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + +```mermaid +flowchart TD +Enter(["Enter Fragment"]) --> Visible{"Is Visible?"} +Visible --> |No| Exit(["Exit"]) +Visible --> |Yes| AsyncLoad["Async Load Fragment Component"] +AsyncLoad --> Render["Render Child Nodes / Slots"] +Render --> Exit +``` + +**Diagram Sources** + +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + +**Section Sources** + +- [backend/modelscope_studio/components/base/fragment/**init**.py:8-49](file://backend/modelscope_studio/components/base/fragment/__init__.py#L8-L49) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + +### Each Component + +- Design philosophy + - Each is a lightweight frontend component designed for list rendering with no corresponding backend Python class. It allows batch instantiation of child components based on array data, and with Fragment and Slot can achieve parameterized dynamic rendering. +- Using with Fragment + - Use Fragment as a lightweight container for each item in Each, avoiding the introduction of additional DOM wrapper levels. + - Fragment's `visible` controls whether the current item renders, suitable for conditional lists. + - Typical usage: When displaying list elements, render each item in the list container into a Fragment. +- Parameter Mapping (params_mapping) + - Set the `params_mapping` property on the Slot component to inject the current item value (item) and index (index) into the slot content. + - `params_mapping` is a JavaScript string function, converted to a function at runtime, accepting `(item, index)` and returning a slot parameter object. + - Example: `params_mapping="lambda item, index: {'children': item['label']}"` renders each item's label field as children. +- Frontend implementation highlights + - Each passes list elements to child component slots by merging context values with item values. + - Supports nested Each; inner layers use `subIndex` to prevent slot key conflicts. + - Can configure `forceClone` when needed, ensuring each item has an independent slot instance. + - Example reference: [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +```mermaid +sequenceDiagram +participant PY as "Backend Parent Component (items property)" +participant Each as "Each (Frontend)" +participant Frag as "Fragment (Frontend)" +participant Slot as "Slot (params_mapping)" +participant Child as "Child Component Slot" +PY->>Each : Pass in items array +Each->>Frag : Create Fragment for each item +Frag->>Slot : Enter named slot +Slot->>Child : params_mapping injects item/index into child component +Child-->>Each : Render list item UI +``` + +**Diagram Sources** + +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +**Section Sources** + +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + +### Component Base Classes and Context + +- ModelScopeLayoutComponent / ModelScopeComponent / ModelScopeDataLayoutComponent + - Uniformly handles component lifecycle, styles, and internal indices; participates in layout tree management under BlockContext. + - `skip_api` controls whether to skip API-level duplicate rendering or processing. +- AppContext + - Ensures all base components are created within a valid application context, avoiding runtime errors. + +```mermaid +classDiagram +class ModelScopeComponent { ++EVENTS ++skip_api ++__init__(...) +} +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__() ++__init__(...) +} +class ModelScopeDataLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__() ++__init__(...) +} +ModelScopeLayoutComponent --|> ModelScopeComponent : "inherits" +ModelScopeDataLayoutComponent --|> ModelScopeComponent : "inherits" +ModelScopeDataLayoutComponent --|> BlockContext : "mixes in" +``` + +**Diagram Sources** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +**Section Sources** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +## Dependency Analysis + +- Backend exports + - Base components are exported via `base/__init__.py`, providing a unified external interface for upper modules to import as needed. +- Inter-component coupling + - Application acts as the root container, with other components organized around it; AutoLoading and Fragment are commonly used as generic containers; Slot is the core for cross-component slot bridging. +- External dependencies + - Frontend uses `@svelte-preprocess-react` and the context system to bridge Svelte and React; rendering utilities provide slot cloning and parameter injection capabilities. + +```mermaid +graph LR +Export["base/__init__.py Exports"] --> App["Application"] +Export --> Auto["AutoLoading"] +Export --> Slot["Slot"] +Export --> Frag["Fragment"] +App --> FeApp["frontend/base/application/Index.svelte"] +Auto --> FeAuto["frontend/base/auto-loading/Index.svelte"] +Slot --> FeSlot["frontend/base/slot/Index.svelte"] +Frag --> FeFrag["frontend/base/fragment/Index.svelte"] +FeSlot --> RenderSlot["utils/renderSlot.tsx"] +FeSlot --> RenderParams["utils/renderParamsSlot.tsx"] +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +**Section Sources** + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +## Performance Considerations + +- Lazy loading and visibility control + - Application/AutoLoading/Fragment all use async import and visibility checks, reducing initial screen rendering pressure. +- Slot rendering optimization + - When using `renderSlot`/`renderParamsSlot`, properly set `clone`/`forceClone` and `params` to avoid unnecessary duplicate rendering. +- Each list rendering + - Each supports merged values and context; force clone when necessary to ensure independent state; maintain `slotKey` and `subIndex` in nested Each to avoid slot key conflicts. +- Event binding + - Application's event listeners are only enabled when needed, avoiding unnecessary event handling overhead. + +[This section is general guidance; no specific file references needed] + +## Troubleshooting Guide + +- Slot not working + - Check if the Slot's `value` is correctly set, and if the parent component has registered the corresponding slot key. + - Confirm that `renderSlot`/`renderParamsSlot` parameters are correctly passed (`clone`/`forceClone`/`params`). + - Reference: [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68), [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29), [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- AutoLoading not switching as expected + - Confirm that `generating`/`showError` state is correctly passed to the frontend; check if slot names match (render/errorRender/loadingText). + - Reference: [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- Fragment not rendering + - Check `visible` property and whether async loading is complete; confirm `shouldResetSlotKey` is not misused, causing slot key loss. + - Reference: [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- Each list misalignment or slot conflicts + - Ensure Each's context values and item values are correctly merged; maintain `subIndex` and `slotKey` in nested Each. + - Reference: [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +**Section Sources** + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +## Conclusion + +The base component system uses Application as the root, AutoLoading as the generic container, Slot as the cross-component bridge, and Fragment as the lightweight container, combined with a unified component base class and context mechanism. This achieves an architecture design with frontend-backend coordination, decoupled events and slots, and controllable rendering performance. By following the best practices and troubleshooting recommendations in this document, developers can efficiently use these components to build complex, high-performance interfaces. + +[This section is summary content; no specific file references needed] + +## Appendix + +- Quick Start Checklist + - Place Application at the application entry to ensure global context is available. + - Use AutoLoading for areas that need lazy loading, and switch between generate/error states based on business logic. + - Use Slot to declare named slots, and render them with `renderSlot`/`renderParamsSlot`. + - Use Fragment as a wrapper-free container in list or conditional rendering. +- Related Implementation Reference Paths + - [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) + - [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) + - [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) + - [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + - [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + - [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) + - [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +[This section is supplementary material; no specific file references needed] diff --git a/.wiki/en/Base Components/Fragment Component.md b/.wiki/en/Base Components/Fragment Component.md new file mode 100644 index 00000000..9a4677fb --- /dev/null +++ b/.wiki/en/Base Components/Fragment Component.md @@ -0,0 +1,328 @@ +# Fragment Component + + +**Files Referenced in This Document** +- [frontend/base/fragment/fragment.tsx](file://frontend/base/fragment/fragment.tsx) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js) +- [backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js](file://backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js) +- [docs/components/base/fragment/README.md](file://docs/components/base/fragment/README.md) +- [docs/components/base/fragment/README-zh_CN.md](file://docs/components/base/fragment/README-zh_CN.md) +- [docs/components/base/fragment/demos/basic.py](file://docs/components/base/fragment/demos/basic.py) +- [frontend/svelte-preprocess-react/react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/style.ts](file://frontend/utils/style.ts) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +Fragment is a "fragment" container component designed to combine multiple child elements into a whole without introducing additional DOM nodes, allowing them to be used as insertable content in slots that only accept model-internal components. It is commonly used to wrap components from external ecosystems (such as Gradio buttons) into forms that comply with model-internal component specifications, enabling them to enter the component tree smoothly. + +- Design purpose: Avoid introducing redundant container nodes in the layout while maintaining the logical grouping and passing of child nodes. +- Use cases: When a component slot only supports components exported from a specific ecosystem, wrap the unsupported component with Fragment before passing it in. +- Advantages: Reduces unnecessary DOM levels, lowering layout overhead; maintains the directness and maintainability of child nodes. + +## Project Structure + +Fragment has corresponding implementations and templates in both the frontend and backend, combined with the React Slot mechanism to complete cross-framework bridging and rendering. + +```mermaid +graph TB +subgraph "Frontend" +FE_Fragment["frontend/base/fragment/fragment.tsx"] +FE_ReactSlot["frontend/svelte-preprocess-react/react-slot.tsx"] +FE_RenderSlot["frontend/utils/renderSlot.tsx"] +FE_RenderItems["frontend/utils/renderItems.tsx"] +FE_Style["frontend/utils/style.ts"] +end +subgraph "Backend Templates" +BE_Fragment["backend/.../fragment-sXw8Jnlf.js"] +BE_EachFragment["backend/.../fragment-BaGnla3s.js"] +end +subgraph "Docs & Examples" +DOC_Readme["docs/components/base/fragment/README.md"] +DOC_ReadmeCN["docs/components/base/fragment/README-zh_CN.md"] +DEMO_Basic["docs/components/base/fragment/demos/basic.py"] +end +FE_Fragment --> BE_Fragment +FE_Fragment --> BE_EachFragment +FE_ReactSlot --> FE_RenderSlot +FE_RenderItems --> FE_ReactSlot +FE_RenderSlot --> FE_ReactSlot +FE_Style --> FE_ReactSlot +DOC_Readme --> DEMO_Basic +DOC_ReadmeCN --> DEMO_Basic +``` + +Diagram Sources + +- [frontend/base/fragment/fragment.tsx:1-11](file://frontend/base/fragment/fragment.tsx#L1-L11) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:437-445](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L437-L445) +- [backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js:1-11](file://backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js#L1-L11) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) +- [docs/components/base/fragment/README.md:1-10](file://docs/components/base/fragment/README.md#L1-L10) +- [docs/components/base/fragment/README-zh_CN.md:1-10](file://docs/components/base/fragment/README-zh_CN.md#L1-L10) +- [docs/components/base/fragment/demos/basic.py:1-22](file://docs/components/base/fragment/demos/basic.py#L1-L22) + +Section Sources + +- [frontend/base/fragment/fragment.tsx:1-11](file://frontend/base/fragment/fragment.tsx#L1-L11) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:437-445](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L437-L445) +- [docs/components/base/fragment/README.md:1-10](file://docs/components/base/fragment/README.md#L1-L10) + +## Core Components + +- Frontend Fragment (React wrapper) + - Bridges Svelte component capabilities to the React ecosystem via `sveltify`, passing `children` through as a React Fragment internally without introducing extra DOM. + - Typical path: [frontend/base/fragment/fragment.tsx:4-8](file://frontend/base/fragment/fragment.tsx#L4-L8) + +- Backend Fragment (runtime template) + - Generates a runtime wrapper for React Fragment for the bridging layer to render, ensuring `children` are mounted as a fragment. + - Typical path: [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:437-441](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L437-L441) + +- Backend Each Fragment (Svelte template) + - Fragment implementation for Svelte, enabling reuse of fragment semantics in Svelte scenarios. + - Typical path: [backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js:2-6](file://backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js#L2-L6) + +Section Sources + +- [frontend/base/fragment/fragment.tsx:1-11](file://frontend/base/fragment/fragment.tsx#L1-L11) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:437-445](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L437-L445) +- [backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js:1-11](file://backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js#L1-L11) + +## Architecture Overview + +Fragment's workflow revolves around "fragment container + React Slot + context bridging": the frontend Fragment passes `children` through as a React Fragment; ReactSlot clones Svelte/HTML structures and mounts them to the React subtree in a "display contents" manner, avoiding extra container nodes; the rendering utility chain handles merging and application of parameters, events, and styles during bridging. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant MS as "Model Component Tree" +participant Frag as "Fragment (React)" +participant RS as "ReactSlot" +participant Bridge as "Bridging Layer (Backend Template)" +participant DOM as "Browser DOM" +Dev->>MS : "Place Fragment in slot" +MS->>Frag : "Receive children" +Frag->>Frag : "Pass children through as React Fragment" +Frag->>RS : "Create Slot rendering via bridging layer" +RS->>Bridge : "Request cloning/mounting of Svelte/HTML structure" +Bridge-->>RS : "Return fragmented children" +RS->>DOM : "Mount with display: contents, no extra container" +RS-->>Dev : "Rendering complete" +``` + +Diagram Sources + +- [frontend/base/fragment/fragment.tsx:4-8](file://frontend/base/fragment/fragment.tsx#L4-L8) +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:437-441](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L437-L441) + +## Detailed Component Analysis + +### Component Class Diagram (Code Level) + +```mermaid +classDiagram +class Fragment_Frontend { ++children? : ReactNode ++renders : React.Fragment(children) +} +class ReactSlot { ++slot : HTMLElement ++clone? : boolean ++className? : string ++style? : CSSProperties ++render() : ReactElement[] +} +class BridgeRuntime { ++reactComponent : React.FC ++props : any ++children : ReactNode[] ++createPortal(node, target) +} +Fragment_Frontend --> ReactSlot : "renders via bridging layer" +ReactSlot --> BridgeRuntime : "clone/mount fragment" +BridgeRuntime --> ReactSlot : "return fragment children" +``` + +Diagram Sources + +- [frontend/base/fragment/fragment.tsx:4-8](file://frontend/base/fragment/fragment.tsx#L4-L8) +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:305-328](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L305-L328) + +Section Sources + +- [frontend/base/fragment/fragment.tsx:1-11](file://frontend/base/fragment/fragment.tsx#L1-L11) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:250-328](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L250-L328) + +### Rendering Flow (Fragment Mounting) + +- ReactSlot clones the target element as a "display contents" node during mounting, avoiding extra container levels. +- If clone mode is enabled, recursively clones child nodes and event listeners, mounting the React subtree into the cloned node via Portal. +- Finally presented as `display: contents`, allowing child nodes to directly participate in the parent container's layout calculations. + +```mermaid +flowchart TD +Start(["Start"]) --> CheckClone{"Clone enabled?"} +CheckClone --> |No| MountDirect["Mount directly with display: contents"] +CheckClone --> |Yes| CloneTree["Clone node tree
Copy event listeners"] +CloneTree --> PortalAttach["Mount React subtree via Portal"] +PortalAttach --> MountDirect +MountDirect --> ApplyStyles["Apply styles/class names"] +ApplyStyles --> End(["End"]) +``` + +Diagram Sources + +- [frontend/svelte-preprocess-react/react-slot.tsx:158-202](file://frontend/svelte-preprocess-react/react-slot.tsx#L158-L202) +- [frontend/utils/style.ts:39-76](file://frontend/utils/style.ts#L39-L76) + +Section Sources + +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) + +### API/Service Component Call Sequence (Fragment Bridging) + +```mermaid +sequenceDiagram +participant Caller as "Caller" +participant Bridge as "Bridge Runtime" +participant ReactComp as "React Component" +participant Slot as "ReactSlot" +participant DOM as "DOM" +Caller->>Bridge : "Pass Fragment + children" +Bridge->>ReactComp : "Render as Fragment" +ReactComp->>Slot : "Create Slot and request clone" +Slot->>DOM : "Clone node and set display: contents" +Slot-->>ReactComp : "Return fragment children" +ReactComp-->>Caller : "Rendering complete" +``` + +Diagram Sources + +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:305-328](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L305-L328) +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) + +Section Sources + +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:250-328](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L250-L328) + +### Complex Logic Component (Fragment and Context Merging) + +- During bridging, fragments merge multiple contexts (such as styles, class names, events, etc.) and skip context influence under ignore flags. +- Supports parameter mapping and force cloning, ensuring stable passing of properties and events in complex layouts. + +```mermaid +flowchart TD +Params["Collect params/context"] --> MergeCtx["Merge styles/class names/events"] +MergeCtx --> IgnoreFlag{"Ignore context?"} +IgnoreFlag --> |Yes| SkipCtx["Skip context influence"] +IgnoreFlag --> |No| ApplyCtx["Apply context"] +ApplyCtx --> Render["Render fragment children"] +SkipCtx --> Render +``` + +Diagram Sources + +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:286-304](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L286-L304) + +Section Sources + +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:228-328](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L228-L328) + +## Dependency Analysis + +- The Fragment frontend implementation depends on React and `sveltify`; the backend template depends on the runtime renderer and bridging utilities. +- ReactSlot depends on style utilities and debounce hooks to ensure cloning and mounting stability. +- The rendering utility chain (renderSlot, renderItems, createItemsContext) provides a unified entry for handling parameters, events, and context. + +```mermaid +graph LR +FragTS["fragment.tsx"] --> BE_JS["fragment-sXw8Jnlf.js"] +FragTS --> BE_Svelte["fragment-BaGnla3s.js"] +ReactSlot["react-slot.tsx"] --> StyleUtils["style.ts"] +RenderSlot["renderSlot.tsx"] --> ReactSlot +RenderItems["renderItems.tsx"] --> ReactSlot +CreateItems["createItemsContext.tsx"] --> RenderItems +``` + +Diagram Sources + +- [frontend/base/fragment/fragment.tsx:1-11](file://frontend/base/fragment/fragment.tsx#L1-L11) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:1-446](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L1-L446) +- [backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js:1-11](file://backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js#L1-L11) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) + +Section Sources + +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +## Performance Considerations + +- Reducing DOM levels: Fragment passes `children` through as React Fragment, avoiding extra container nodes and reducing layout and reflow costs. +- Clone strategy: Enable cloning when needed, but avoid frequent cloning of large numbers of nodes; combine with parameter mapping and force cloning when necessary to reduce invalid updates. +- Mutation observation: ReactSlot uses MutationObserver to observe changes, combined with debounce and minimal re-rendering, avoiding excessive refresh. +- Styles and class names: Converted uniformly via style utilities, avoiding repeated calculation and string concatenation overhead. +- Event binding: Copy event listeners during cloning to ensure interaction consistency, while paying attention to removal timing to prevent memory leaks. + +## Troubleshooting Guide + +- Slot not working + - Confirm that the slot only supports components from a specific ecosystem; the component needs to be wrapped with Fragment before being passed in. + - Reference example: [docs/components/base/fragment/demos/basic.py:14-19](file://docs/components/base/fragment/demos/basic.py#L14-L19) + +- Child elements not rendering correctly or styles missing + - Check if clone mode is enabled; if not, styles and class names may not be correctly applied. + - Reference implementation: [frontend/svelte-preprocess-react/react-slot.tsx:158-202](file://frontend/svelte-preprocess-react/react-slot.tsx#L158-L202) + +- Events not triggering or binding repeatedly + - Confirm event listeners have been copied during cloning; check if cleanup occurs on unmount. + - Reference implementation: [frontend/svelte-preprocess-react/react-slot.tsx:67-95](file://frontend/svelte-preprocess-react/react-slot.tsx#L67-L95) + +- Parameter mapping and context conflicts + - Use parameter mapping and force cloning to ensure context merge order and override rules meet expectations. + - Reference implementation: [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:286-304](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L286-L304) + +Section Sources + +- [docs/components/base/fragment/demos/basic.py:1-22](file://docs/components/base/fragment/demos/basic.py#L1-L22) +- [frontend/svelte-preprocess-react/react-slot.tsx:67-202](file://frontend/svelte-preprocess-react/react-slot.tsx#L67-L202) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:286-304](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L286-L304) + +## Conclusion + +The Fragment component implements combination and passing of multiple child elements without introducing extra DOM nodes, through the "fragment container + React Slot + context bridging" mechanism. It is particularly suitable for layout needs that require injecting unsupported components into strictly constrained slot scenarios. Combined with parameter mapping, event merging, and style utilities, Fragment has good stability and maintainability in complex layouts. + +## Appendix + +- Usage examples (documentation and demos) + - Basic usage and comparison: [docs/components/base/fragment/demos/basic.py:14-19](file://docs/components/base/fragment/demos/basic.py#L14-L19) + - Chinese documentation: [docs/components/base/fragment/README-zh_CN.md:1-10](file://docs/components/base/fragment/README-zh_CN.md#L1-L10) + - English documentation: [docs/components/base/fragment/README.md:1-10](file://docs/components/base/fragment/README.md#L1-L10) diff --git a/.wiki/en/Base Components/Layout Components.md b/.wiki/en/Base Components/Layout Components.md new file mode 100644 index 00000000..e6ba0e3e --- /dev/null +++ b/.wiki/en/Base Components/Layout Components.md @@ -0,0 +1,386 @@ +# Layout Components + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/components/base/div/__init__.py](file://backend/modelscope_studio/components/base/div/__init__.py) +- [backend/modelscope_studio/components/base/span/__init__.py](file://backend/modelscope_studio/components/base/span/__init__.py) +- [backend/modelscope_studio/components/base/text/__init__.py](file://backend/modelscope_studio/components/base/text/__init__.py) +- [backend/modelscope_studio/components/base/markdown/__init__.py](file://backend/modelscope_studio/components/base/markdown/__init__.py) +- [frontend/base/package.json](file://frontend/base/package.json) +- [frontend/base/div/Index.svelte](file://frontend/base/div/Index.svelte) +- [frontend/base/span/Index.svelte](file://frontend/base/span/Index.svelte) +- [frontend/base/text/Index.svelte](file://frontend/base/text/Index.svelte) +- [frontend/base/markdown/Index.svelte](file://frontend/base/markdown/Index.svelte) +- [frontend/base/div/div.tsx](file://frontend/base/div/div.tsx) +- [frontend/base/span/span.tsx](file://frontend/base/span/span.tsx) +- [frontend/base/text/text.tsx](file://frontend/base/text/text.tsx) +- [frontend/base/markdown/markdown.tsx](file://frontend/base/markdown/markdown.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document systematically covers the "Layout Components" series in ModelScope Studio, focusing on the four foundational layout and content components: Div, Span, Text, and Markdown. The documentation provides in-depth explanations from the perspectives of architecture, data flow, processing logic, styling and theme adaptation, composition and nesting best practices, performance characteristics and optimization recommendations, as well as common issues and debugging techniques — helping developers efficiently and reliably use these components for page layout and content rendering. + +## Project Structure + +The layout components sit between the backend Python component layer and the frontend Svelte/React layer, following a layered design of "Python component definition + Svelte wrapper + React implementation": + +- Backend: Defines component behavior, event bindings, pre/post-processing logic, and declares frontend resource directories via Python classes. +- Frontend Svelte layer: Handles property passthrough, visibility control, style and class name composition, and slot resolution/rendering. +- React layer: Wraps specific HTML elements (e.g., div/span), or renders based on a global component (e.g., Markdown). + +```mermaid +graph TB +subgraph "Backend" +PY_DIV["Python: Div Component"] +PY_SPAN["Python: Span Component"] +PY_TEXT["Python: Text Component"] +PY_MD["Python: Markdown Component"] +end +subgraph "Frontend (Svelte)" +SV_DIV["Svelte: div/Index.svelte"] +SV_SPAN["Svelte: span/Index.svelte"] +SV_TEXT["Svelte: text/Index.svelte"] +SV_MD["Svelte: markdown/Index.svelte"] +end +subgraph "Frontend (React)" +RX_DIV["React: div.tsx"] +RX_SPAN["React: span.tsx"] +RX_TEXT["React: text.tsx"] +RX_MD["React: markdown.tsx"] +end +PY_DIV --> SV_DIV --> RX_DIV +PY_SPAN --> SV_SPAN --> RX_SPAN +PY_TEXT --> SV_TEXT --> RX_TEXT +PY_MD --> SV_MD --> RX_MD +``` + +Diagram Sources + +- [backend/modelscope_studio/components/base/div/**init**.py:10-86](file://backend/modelscope_studio/components/base/div/__init__.py#L10-L86) +- [backend/modelscope_studio/components/base/span/**init**.py:10-87](file://backend/modelscope_studio/components/base/span/__init__.py#L10-L87) +- [backend/modelscope_studio/components/base/text/**init**.py:8-57](file://backend/modelscope_studio/components/base/text/__init__.py#L8-L57) +- [backend/modelscope_studio/components/base/markdown/**init**.py:11-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L11-L174) +- [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) +- [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) +- [frontend/base/div/div.tsx:1-18](file://frontend/base/div/div.tsx#L1-L18) +- [frontend/base/span/span.tsx:1-20](file://frontend/base/span/span.tsx#L1-L20) +- [frontend/base/text/text.tsx:1-11](file://frontend/base/text/text.tsx#L1-L11) +- [frontend/base/markdown/markdown.tsx:1-35](file://frontend/base/markdown/markdown.tsx#L1-L35) + +Section Sources + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [frontend/base/package.json:1-6](file://frontend/base/package.json#L1-L6) + +## Core Components + +This section provides a functional and usage overview of the four foundational layout components, highlighting their roles and responsibilities in page layout and content rendering. + +- Div + - Role: Block-level container for holding child elements or text values; supports generic interaction events such as mouse and scroll events. + - Key Points: Accepts extra prop passthrough; supports visibility, element ID, class names, and inline styles as common attributes. + - Use Cases: Card backgrounds, section divisions, and outer containers for complex nested layouts. + +- Span + - Role: Inline container suitable for wrapping short text or inline elements; also supports generic interaction events. + - Key Points: Prioritizes child node rendering when children exist; falls back to `value` or an empty span otherwise. + - Use Cases: Inline highlights, labels, and text fragments within button groups. + +- Text + - Role: Pure text output component with no extra container wrapper; directly renders a string. + - Key Points: No event bindings; only handles `value`; suitable for minimal-cost text rendering. + - Use Cases: Headings, paragraphs, and lightweight hint text. + +- Markdown + - Role: Rich text rendering component supporting copyButtons slots, LaTeX math delimiters, HTML sanitization policy, line break and header link options. + - Key Points: Supports `copyButtons` slot; post-processing cleans input indentation; theme mode and root path are passed through to the underlying component. + - Use Cases: Help documentation, descriptive text, and dynamically generated rich text content. + +Section Sources + +- [backend/modelscope_studio/components/base/div/**init**.py:10-86](file://backend/modelscope_studio/components/base/div/__init__.py#L10-L86) +- [backend/modelscope_studio/components/base/span/**init**.py:10-87](file://backend/modelscope_studio/components/base/span/__init__.py#L10-L87) +- [backend/modelscope_studio/components/base/text/**init**.py:8-57](file://backend/modelscope_studio/components/base/text/__init__.py#L8-L57) +- [backend/modelscope_studio/components/base/markdown/**init**.py:11-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L11-L174) + +## Architecture Overview + +The diagram below illustrates the overall call chain and data flow from backend components to frontend rendering: + +```mermaid +sequenceDiagram +participant Py as "Backend Component (Python)" +participant Svelte as "Frontend Wrapper (Svelte)" +participant React as "React Implementation" +participant DOM as "DOM" +Py->>Svelte : Initialize and pass properties (visible/elem_*/value, etc.) +Svelte->>Svelte : Handle property passthrough / visibility / styles / class names +Svelte->>React : Render the corresponding React component +React->>DOM : Output final HTML nodes (div/span/text/markdown) +DOM-->>React : Event callbacks (e.g., click/mouseover/scroll) +React-->>Svelte : Trigger event updates +Svelte-->>Py : Event callback triggered (bound by backend event listeners) +``` + +Diagram Sources + +- [backend/modelscope_studio/components/base/div/**init**.py:14-39](file://backend/modelscope_studio/components/base/div/__init__.py#L14-L39) +- [backend/modelscope_studio/components/base/span/**init**.py:14-39](file://backend/modelscope_studio/components/base/span/__init__.py#L14-L39) +- [backend/modelscope_studio/components/base/markdown/**init**.py:15-46](file://backend/modelscope_studio/components/base/markdown/__init__.py#L15-L46) +- [frontend/base/div/Index.svelte:22-47](file://frontend/base/div/Index.svelte#L22-L47) +- [frontend/base/span/Index.svelte:21-46](file://frontend/base/span/Index.svelte#L21-L46) +- [frontend/base/text/Index.svelte:15-29](file://frontend/base/text/Index.svelte#L15-L29) +- [frontend/base/markdown/Index.svelte:19-44](file://frontend/base/markdown/Index.svelte#L19-L44) +- [frontend/base/div/div.tsx:12-15](file://frontend/base/div/div.tsx#L12-L15) +- [frontend/base/span/span.tsx:12-17](file://frontend/base/span/span.tsx#L12-L17) +- [frontend/base/text/text.tsx:4-8](file://frontend/base/text/text.tsx#L4-L8) +- [frontend/base/markdown/markdown.tsx:8-32](file://frontend/base/markdown/markdown.tsx#L8-L32) + +## Detailed Component Analysis + +### Div Component + +- Design Highlights + - As a block-level container, it prioritizes child node rendering; falls back to the `value` string when no children are present. + - Supports binding of generic interaction events (click, dblclick, mousedown, mouseup, mouseover, mouseout, mousemove, scroll). + - Extra props can be passed through; `elem_id`, `elem_classes`, and `elem_style` provide styling and positioning control. +- Data Flow and Processing Logic + - Pre/post-processing leaves strings unchanged; visibility is uniformly controlled by the Svelte layer. +- Usage Recommendations + - Suitable for large-scale layout divisions and complex nesting; avoid using in contexts where inline semantics are required. + - When combined with Grid/Flex layouts, be mindful not to introduce unnecessary hierarchy. + +```mermaid +flowchart TD +Start(["Enter Div Rendering"]) --> CheckChildren["Check if child nodes exist"] +CheckChildren --> HasChildren{"Children present?"} +HasChildren --> |Yes| RenderChildren["Render child nodes"] +HasChildren --> |No| UseValue["Use value as text content"] +RenderChildren --> End(["Done"]) +UseValue --> End +``` + +Diagram Sources + +- [frontend/base/div/div.tsx:12-15](file://frontend/base/div/div.tsx#L12-L15) +- [frontend/base/div/Index.svelte:50-63](file://frontend/base/div/Index.svelte#L50-L63) + +Section Sources + +- [backend/modelscope_studio/components/base/div/**init**.py:10-86](file://backend/modelscope_studio/components/base/div/__init__.py#L10-L86) +- [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) +- [frontend/base/div/div.tsx:1-18](file://frontend/base/div/div.tsx#L1-L18) + +### Span Component + +- Design Highlights + - Inline container that prioritizes child node rendering; falls back to `value` or an empty span when no children are present. + - Supports the same set of interaction event bindings as Div. +- Usage Recommendations + - Suitable for inline text fragments, labels, and text within buttons. + - Not recommended in contexts that require block-level line breaks. + +```mermaid +flowchart TD +Start(["Enter Span Rendering"]) --> CheckChildren["Check if child nodes exist"] +CheckChildren --> HasChildren{"Children present?"} +HasChildren --> |Yes| RenderChildren["Render child nodes"] +HasChildren --> |No| UseValueOrEmpty["Use value or empty span"] +RenderChildren --> End(["Done"]) +UseValueOrEmpty --> End +``` + +Diagram Sources + +- [frontend/base/span/span.tsx:12-17](file://frontend/base/span/span.tsx#L12-L17) +- [frontend/base/span/Index.svelte:49-63](file://frontend/base/span/Index.svelte#L49-L63) + +Section Sources + +- [backend/modelscope_studio/components/base/span/**init**.py:10-87](file://backend/modelscope_studio/components/base/span/__init__.py#L10-L87) +- [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) +- [frontend/base/span/span.tsx:1-20](file://frontend/base/span/span.tsx#L1-L20) + +### Text Component + +- Design Highlights + - Minimal wrapper that directly renders a string; no event bindings. + - Suitable for pure text output with low performance overhead. +- Usage Recommendations + - Do not mix with rich text or interactive scenarios; control styling via `elem_classes`/`elem_style` when needed. + +```mermaid +flowchart TD +Start(["Enter Text Rendering"]) --> GetValue["Read value"] +GetValue --> RenderText["Render text node"] +RenderText --> End(["Done"]) +``` + +Diagram Sources + +- [frontend/base/text/text.tsx:4-8](file://frontend/base/text/text.tsx#L4-L8) +- [frontend/base/text/Index.svelte:32-41](file://frontend/base/text/Index.svelte#L32-L41) + +Section Sources + +- [backend/modelscope_studio/components/base/text/**init**.py:8-57](file://backend/modelscope_studio/components/base/text/__init__.py#L8-L57) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/base/text/text.tsx:1-11](file://frontend/base/text/text.tsx#L1-L11) + +### Markdown Component + +- Design Highlights + - Supports the `copyButtons` slot to allow custom copy buttons; supports LaTeX math delimiters, HTML sanitization policy, line break and header link options. + - Post-processing cleans input indentation to ensure rendering consistency. + - Theme mode and root path are passed through via props to the underlying Markdown component. +- Data Flow and Processing Logic + - The Svelte layer parses slots and injects `copyButtons` targets into the React layer. + - The React layer hides children, delegating rendering and interaction to the global Markdown component. + +```mermaid +sequenceDiagram +participant Svelte as "Svelte: markdown/Index.svelte" +participant React as "React: markdown.tsx" +participant GlobalMD as "Global Markdown Component" +participant User as "User" +Svelte->>React : Pass through value/styles/class names/theme/root path +React->>React : Resolve copyButtons slot targets +React->>GlobalMD : Render Markdown and inject copyButtons +User->>GlobalMD : Trigger copy/click events +GlobalMD-->>React : Event callback +React-->>Svelte : Update state +Svelte-->>Svelte : Trigger backend event listeners +``` + +Diagram Sources + +- [frontend/base/markdown/Index.svelte:19-44](file://frontend/base/markdown/Index.svelte#L19-L44) +- [frontend/base/markdown/markdown.tsx:8-32](file://frontend/base/markdown/markdown.tsx#L8-L32) +- [backend/modelscope_studio/components/base/markdown/**init**.py:15-46](file://backend/modelscope_studio/components/base/markdown/__init__.py#L15-L46) + +Section Sources + +- [backend/modelscope_studio/components/base/markdown/**init**.py:11-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L11-L174) +- [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) +- [frontend/base/markdown/markdown.tsx:1-35](file://frontend/base/markdown/markdown.tsx#L1-L35) + +## Dependency Analysis + +- Inter-Component Coupling + - All four components are derived from a unified backend base class (layout/data-layout/plain component), sharing a consistent lifecycle and event mechanism. + - The frontend Svelte layer uses the same property passthrough and visibility control patterns, reducing maintenance cost. +- External Dependencies + - The React wrapper layer depends on `sveltify` and slot capabilities provided by `@svelte-preprocess-react`. + - The Markdown component depends on the global Markdown component and ReactSlot for slot rendering. +- Potential Circular Dependencies + - The current structure follows a unidirectional dependency (Backend → Svelte → React); no circular dependency has been observed. + +```mermaid +graph LR +PY_BASE["Backend Base Component Class"] --> PY_DIV["Div"] +PY_BASE --> PY_SPAN["Span"] +PY_BASE --> PY_TEXT["Text"] +PY_DATA_LAYOUT["Data Layout Base Class"] --> PY_MD["Markdown"] +SV_DIV["Svelte: div/Index.svelte"] --> RX_DIV["React: div.tsx"] +SV_SPAN["Svelte: span/Index.svelte"] --> RX_SPAN["React: span.tsx"] +SV_TEXT["Svelte: text/Index.svelte"] --> RX_TEXT["React: text.tsx"] +SV_MD["Svelte: markdown/Index.svelte"] --> RX_MD["React: markdown.tsx"] +RX_MD --> GLOBAL_MD["Global Markdown Component"] +``` + +Diagram Sources + +- [backend/modelscope_studio/components/base/div/**init**.py](file://backend/modelscope_studio/components/base/div/__init__.py#L7) +- [backend/modelscope_studio/components/base/span/**init**.py](file://backend/modelscope_studio/components/base/span/__init__.py#L7) +- [backend/modelscope_studio/components/base/text/**init**.py](file://backend/modelscope_studio/components/base/text/__init__.py#L5) +- [backend/modelscope_studio/components/base/markdown/**init**.py](file://backend/modelscope_studio/components/base/markdown/__init__.py#L8) +- [frontend/base/markdown/markdown.tsx:4-5](file://frontend/base/markdown/markdown.tsx#L4-L5) + +Section Sources + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [frontend/base/package.json:1-6](file://frontend/base/package.json#L1-L6) + +## Performance Considerations + +- Rendering Path + - Text outputs plain text directly with the lowest overhead; Div/Span traverse the React subtree when children are present — pay attention to subtree size. + - Markdown reuses global rendering capability by hiding children, reducing repeated parsing. +- Event Bindings + - All layout components support multiple mouse/scroll event bindings; enable only as needed to avoid unnecessary callback overhead. +- Styles and Class Names + - Control styling via `elem_classes`/`elem_style`; prefer atomic class names to minimize style recalculation. +- Theme and Resources + - Markdown theme mode and root path are passed through to ensure static asset paths are correct, avoiding redundant requests. + +[This section contains general performance recommendations; no specific file references required] + +## Troubleshooting Guide + +- Text Not Displayed + - Check whether `value` is empty or contains only whitespace; the Text component falls back to an empty span when `value` is missing. + - For Div/Span, verify whether child nodes have been passed in, causing `value` to be ignored. +- Events Not Firing + - Confirm that event listeners are registered on the backend; check that `visible` is `true` — events will not fire when the component is invisible. +- Markdown Copy Button Not Working + - Confirm that the `copyButtons` slot is correctly mounted; the React layer determines whether to replace the default button based on the slot target. +- Styles Not Applied + - Check the composition order and precedence of `elem_id`/`elem_classes`/`elem_style`; use more specific CSS selectors if necessary. +- Theme Mismatch + - Confirm that `themeMode` and `rootUrl` are correctly passed through to the Markdown component. + +Section Sources + +- [backend/modelscope_studio/components/base/text/**init**.py:45-50](file://backend/modelscope_studio/components/base/text/__init__.py#L45-L50) +- [backend/modelscope_studio/components/base/div/**init**.py:14-39](file://backend/modelscope_studio/components/base/div/__init__.py#L14-L39) +- [backend/modelscope_studio/components/base/span/**init**.py:14-39](file://backend/modelscope_studio/components/base/span/__init__.py#L14-L39) +- [backend/modelscope_studio/components/base/markdown/**init**.py:49-52](file://backend/modelscope_studio/components/base/markdown/__init__.py#L49-L52) +- [frontend/base/markdown/markdown.tsx:14-31](file://frontend/base/markdown/markdown.tsx#L14-L31) + +## Conclusion + +Div, Span, Text, and Markdown form the foundational capabilities for layout and content rendering in ModelScope Studio. Under the design of unified backend abstraction, consistent frontend wrapping, and precise React rendering, they achieve both ease of use and extensibility alongside solid performance. Choosing the appropriate component type, enabling events and slots only as needed, and following style and theme conventions are key to building high-quality interfaces. + +[This section contains summary content; no specific file references required] + +## Appendix + +### Component Properties and Behavior Quick Reference + +- Div + - Events: click, dblclick, mousedown, mouseup, mouseover, mouseout, mousemove, scroll + - Properties: value, additional_props, elem_id, elem_classes, elem_style, visible, render +- Span + - Events: click, dblclick, mousedown, mouseup, mouseover, mouseout, mousemove, scroll + - Properties: value, additional_props, elem_id, elem_classes, elem_style, visible, render +- Text + - Events: None + - Properties: value, elem_id, elem_classes, elem_style, visible, render +- Markdown + - Events: change, copy, click, dblclick, mousedown, mouseup, mouseover, mouseout, mousemove, scroll + - Slots: copyButtons + - Properties: value, rtl, latex_delimiters, sanitize_html, line_breaks, header_links, allow_tags, show_copy_button, copy_buttons, elem_id, elem_classes, elem_style, visible, render + +Section Sources + +- [backend/modelscope_studio/components/base/div/**init**.py:14-68](file://backend/modelscope_studio/components/base/div/__init__.py#L14-L68) +- [backend/modelscope_studio/components/base/span/**init**.py:14-69](file://backend/modelscope_studio/components/base/span/__init__.py#L14-L69) +- [backend/modelscope_studio/components/base/text/**init**.py:12-39](file://backend/modelscope_studio/components/base/text/__init__.py#L12-L39) +- [backend/modelscope_studio/components/base/markdown/**init**.py:15-143](file://backend/modelscope_studio/components/base/markdown/__init__.py#L15-L143) diff --git a/.wiki/en/Base Components/Rendering Components.md b/.wiki/en/Base Components/Rendering Components.md new file mode 100644 index 00000000..7e1893fd --- /dev/null +++ b/.wiki/en/Base Components/Rendering Components.md @@ -0,0 +1,371 @@ +# Rendering Components + + +**Files Referenced in This Document** +- [each.tsx](file://frontend/base/each/each.tsx) +- [Index.svelte (Each)](file://frontend/base/each/Index.svelte) +- [EachItem.svelte](file://frontend/base/each/EachItem.svelte) +- [each.placeholder.tsx](file://frontend/base/each/each.placeholder.tsx) +- [useTargets.ts](file://frontend/utils/hooks/useTargets.ts) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [filter.tsx](file://frontend/base/filter/filter.tsx) +- [Index.svelte (Filter)](file://frontend/base/filter/Index.svelte) +- [each/__init__.py](file://backend/modelscope_studio/components/base/each/__init__.py) +- [filter/__init__.py](file://backend/modelscope_studio/components/base/filter/__init__.py) +- [base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [filter/README-zh_CN.md](file://docs/components/base/filter/README-zh_CN.md) +- [filter/demos/basic.py](file://docs/components/base/filter/demos/basic.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document focuses on the Each and Filter components in the rendering component series, systematically explaining their key roles in data rendering and conditional display. Each is responsible for rendering list data item by item and injecting context into each item; Filter is responsible for filtering or extracting context, supporting both key-based sub-object extraction and custom filtering via function strings. The documentation provides comprehensive coverage of architecture, data flow, processing logic, integration and state management, performance optimization, and debugging techniques, along with multi-scenario usage examples and best practices. + +## Project Structure + +The rendering components reside in the frontend `base` package, each composed of a Svelte entry component and a React implementation, with corresponding Python component classes in the backend to interface with the Gradio data flow. The core files are organized as follows: + +- Frontend Each: The Svelte entry component handles property processing and placeholder coordination; the React implementation handles loop rendering and context injection. +- Frontend Filter: The Svelte entry component handles property processing; the React implementation handles context filtering and passthrough. +- Backend Each/Filter: Python component classes that define properties, visibility, pre/post-processing, and frontend directory mappings. + +```mermaid +graph TB +subgraph "Frontend base" +EIdx["Each Entry Index.svelte"] +EImpl["Each Implementation each.tsx"] +EItem["Each Item EachItem.svelte"] +EPh["Each Placeholder each.placeholder.tsx"] +FIdx["Filter Entry Index.svelte"] +FImpl["Filter Implementation filter.tsx"] +UT["Utility: useTargets.ts"] +UF["Utility: useFunction.ts"] +end +subgraph "Backend Python" +PYE["ModelScopeEach each/__init__.py"] +PYF["ModelScopeFilter filter/__init__.py"] +PYPkg["base/__init__.py Exports"] +end +EIdx --> EImpl +EIdx --> EPh +EIdx --> EItem +EImpl --> UT +FIdx --> FImpl +FImpl --> UF +PYE --> EIdx +PYF --> FIdx +PYPkg --> PYE +PYPkg --> PYF +``` + +Diagram Sources + +- [Index.svelte (Each):1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [each.tsx:1-61](file://frontend/base/each/each.tsx#L1-L61) +- [EachItem.svelte:1-37](file://frontend/base/each/EachItem.svelte#L1-L37) +- [each.placeholder.tsx:1-31](file://frontend/base/each/each.placeholder.tsx#L1-L31) +- [Index.svelte (Filter):1-52](file://frontend/base/filter/Index.svelte#L1-L52) +- [filter.tsx:1-41](file://frontend/base/filter/filter.tsx#L1-L41) +- [useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [each/**init**.py:1-73](file://backend/modelscope_studio/components/base/each/__init__.py#L1-L73) +- [filter/**init**.py:1-45](file://backend/modelscope_studio/components/base/filter/__init__.py#L1-L45) +- [base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +Section Sources + +- [Index.svelte (Each):1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [filter.tsx:1-41](file://frontend/base/filter/filter.tsx#L1-L41) +- [each.tsx:1-61](file://frontend/base/each/each.tsx#L1-L61) +- [each/**init**.py:1-73](file://backend/modelscope_studio/components/base/each/__init__.py#L1-L73) +- [filter/**init**.py:1-45](file://backend/modelscope_studio/components/base/filter/__init__.py#L1-L45) +- [base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +## Core Components + +- Each: Receives list data and context, renders child nodes item by item, and merges each item's value into the context for downstream component consumption. +- Filter: Filters or extracts the current context, supporting two modes: + - as_item: Extracts a sub-object from the context by key name to serve as the new context passed downstream. + - params_mapping: Accepts a JS function string to perform custom filtering on the context and returns a new context. + - When neither is provided, context propagation is blocked and subsequent property overrides become ineffective. + +Section Sources + +- [each.tsx:8-13](file://frontend/base/each/each.tsx#L8-L13) +- [filter.tsx:9-13](file://frontend/base/filter/filter.tsx#L9-L13) +- [filter/README-zh_CN.md:1-22](file://docs/components/base/filter/README-zh_CN.md#L1-L22) + +## Architecture Overview + +The execution flow of Each and Filter can be summarized as: the frontend entry component parses properties and prepares the React implementation; the React implementation generates the child tree based on data and context; Filter filters the context before rendering to ensure downstream components receive only the required data. + +```mermaid +sequenceDiagram +participant Py as "Backend Component Each/Filter" +participant S as "Entry Component Each/Filter" +participant R as "React Implementation Each/Filter" +participant U as "Utility Hooks useTargets/useFunction" +Py->>S : Initialize and set properties +S->>R : Pass processed properties and slots +R->>U : Resolve slot targets (Each) / Resolve function (Filter) +U-->>R : Return targets/function +R->>R : Each iterates over value and injects context +R->>R : Filter filters context based on as_item or params_mapping +R-->>S : Render result +S-->>Py : Visibility and render control +``` + +Diagram Sources + +- [Index.svelte (Each):1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [each.tsx:35-58](file://frontend/base/each/each.tsx#L35-L58) +- [Index.svelte (Filter):1-52](file://frontend/base/filter/Index.svelte#L1-L52) +- [filter.tsx:15-38](file://frontend/base/filter/filter.tsx#L15-L38) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) + +## Component Details + +### Each Component + +Each's responsibility is to render list data item by item and inject context into each child item. Key points include: + +- Input Properties: `value` (array), `contextValue` (initial context), `children` (subtree), internal slot keys. +- Rendering Strategy: First renders an "isolated" hidden container to prevent external context from polluting internal slots; then maps over `value` to create an Item for each entry. +- Context Injection: Item merges the incoming `value` into `contextValue` to form the final context, then injects it into the child tree via `ContextPropsProvider`. +- Slot Resolution: Uses `useTargets` to extract nodes in `children` that match the `slotKey`, ensuring correct rendering order and target mounting. + +```mermaid +flowchart TD +Start(["Enter Each Rendering"]) --> Parse["Parse children slots
Extract targets via useTargets"] +Parse --> Isolate["Render isolated container (hidden)"] +Isolate --> Loop{"Iterate over value"} +Loop --> |Yes| Item["Create Item for each entry
Merge context"] +Item --> Render["Clone and render target slots"] +Render --> Next["Next element"] +Next --> Loop +Loop --> |No| End(["Rendering complete"]) +``` + +Diagram Sources + +- [each.tsx:35-58](file://frontend/base/each/each.tsx#L35-L58) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) + +Section Sources + +- [each.tsx:8-13](file://frontend/base/each/each.tsx#L8-L13) +- [each.tsx:35-58](file://frontend/base/each/each.tsx#L35-L58) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [Index.svelte (Each):66-104](file://frontend/base/each/Index.svelte#L66-L104) +- [each.placeholder.tsx:15-28](file://frontend/base/each/each.placeholder.tsx#L15-L28) +- [EachItem.svelte:23-27](file://frontend/base/each/EachItem.svelte#L23-L27) + +### Filter Component + +Filter's responsibility is to filter or extract the current context, supporting two modes: + +- as_item: Extracts a sub-object from the context by key name to serve as the new context passed downstream. +- params_mapping: Accepts a JS function string, resolved via `useFunction`, to perform custom filtering on the context. +- When no parameters are provided: context propagation is blocked, making subsequent property overrides ineffective. + +```mermaid +flowchart TD +Enter(["Enter Filter"]) --> ReadCtx["Read current context"] +ReadCtx --> CheckAs{"Is as_item provided?"} +CheckAs --> |Yes| Extract["Extract ctx[as_item] as new context"] +CheckAs --> |No| CheckMap{"Is params_mapping provided?"} +CheckMap --> |Yes| Exec["Execute params_mapping(ctx) as new context"] +CheckMap --> |No| Block["Do not update context (block propagation)"] +Extract --> Provide["Pass through via ContextPropsProvider"] +Exec --> Provide +Block --> Provide +Provide --> Exit(["Done"]) +``` + +Diagram Sources + +- [filter.tsx:15-38](file://frontend/base/filter/filter.tsx#L15-L38) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) + +Section Sources + +- [filter.tsx:9-13](file://frontend/base/filter/filter.tsx#L9-L13) +- [filter.tsx:15-38](file://frontend/base/filter/filter.tsx#L15-L38) +- [Index.svelte (Filter):33-45](file://frontend/base/filter/Index.svelte#L33-L45) +- [filter/README-zh_CN.md:1-22](file://docs/components/base/filter/README-zh_CN.md#L1-L22) + +### Properties and Events + +- Each (Frontend Entry Index.svelte) + - Key Properties: `value`, `context_value`, `visible`, `elem_id`, `elem_classes`, `elem_style`, `_internal.index`, etc. + - Internal Behavior: The placeholder component collects changes (e.g., `forceClone`, merged `value`/`context_value`) and decides whether to use the React implementation or render directly with EachItem. +- Each (React Implementation each.tsx) + - Key Properties: `value`, `contextValue`, `children`, `__internal_slot_key`. + - Internal Behavior: Isolates external context, resolves slot targets, renders each item, and injects context. +- Filter (Frontend Entry Index.svelte) + - Key Properties: `params_mapping`, `as_item`, `visible`. + - Internal Behavior: Passes `params_mapping` and `as_item` to the React implementation. +- Filter (React Implementation filter.tsx) + - Key Properties: `paramsMapping`, `asItem`. + - Internal Behavior: Selects key extraction or function filtering based on the parameters, updates context, and passes it through. + +Section Sources + +- [Index.svelte (Each):17-57](file://frontend/base/each/Index.svelte#L17-L57) +- [Index.svelte (Each):66-104](file://frontend/base/each/Index.svelte#L66-L104) +- [each.tsx:8-13](file://frontend/base/each/each.tsx#L8-L13) +- [Index.svelte (Filter):16-31](file://frontend/base/filter/Index.svelte#L16-L31) +- [filter.tsx:9-13](file://frontend/base/filter/filter.tsx#L9-L13) + +### Integration with State Management + +- Each merges `contextValue` with each item's `value` to form a per-item context consumable by downstream components. +- Filter uses `useContextPropsContext` to retrieve the current context, then generates a new context via `as_item` or `params_mapping`, enabling "conditional display / data filtering". +- The backend component's `visible` flag can be used to control render visibility; the frontend entry component will not load the React implementation when invisible, reducing overhead. + +Section Sources + +- [each.tsx:15-33](file://frontend/base/each/each.tsx#L15-L33) +- [filter.tsx:19-27](file://frontend/base/filter/filter.tsx#L19-L27) +- [Index.svelte (Each):66-104](file://frontend/base/each/Index.svelte#L66-L104) +- [Index.svelte (Filter):33-45](file://frontend/base/filter/Index.svelte#L33-L45) + +### Usage Examples and Scenarios + +- Basic Usage (Without Filter) + - Scenario: Loop-render list data; child components such as buttons directly consume the context injected by Each. + - Reference Example: [filter/demos/basic.py:1-20](file://docs/components/base/filter/demos/basic.py#L1-L20) +- Using as_item + - Scenario: The context output by Each contains multiple fields, and only one field needs to be passed as the new context to child components. + - Reference: [filter/README-zh_CN.md:1-22](file://docs/components/base/filter/README-zh_CN.md#L1-L22) +- Using params_mapping + - Scenario: Perform complex filtering or transformation on the context via a JS function, such as filtering, composing derived fields, etc. + - Reference: [filter/README-zh_CN.md:1-22](file://docs/components/base/filter/README-zh_CN.md#L1-L22) + +Section Sources + +- [filter/demos/basic.py:1-20](file://docs/components/base/filter/demos/basic.py#L1-L20) +- [filter/README-zh_CN.md:1-22](file://docs/components/base/filter/README-zh_CN.md#L1-L22) + +## Dependency Analysis + +- Each Dependencies + - Utility Hook: `useTargets` resolves slot targets to ensure correct rendering order and mounting. + - Context: `ContextPropsProvider` is used for context isolation and merging. +- Filter Dependencies + - Utility Hook: `useFunction` parses a string function into an executable function. + - Context: `ContextPropsProvider` is used to pass through the filtered context. +- Backend Components + - Each/Filter both inherit from the layout component base class, defining properties, visibility, pre/post-processing, and frontend directory mappings. + +```mermaid +graph LR +UT["useTargets.ts"] --> EImpl["each.tsx"] +UF["useFunction.ts"] --> FImpl["filter.tsx"] +EIdx["Each Index.svelte"] --> EImpl +FIdx["Filter Index.svelte"] --> FImpl +PYE["ModelScopeEach Python"] --> EIdx +PYF["ModelScopeFilter Python"] --> FIdx +``` + +Diagram Sources + +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [each.tsx:1-7](file://frontend/base/each/each.tsx#L1-L7) +- [filter.tsx:1-7](file://frontend/base/filter/filter.tsx#L1-L7) +- [Index.svelte (Each):1-16](file://frontend/base/each/Index.svelte#L1-L16) +- [Index.svelte (Filter):1-8](file://frontend/base/filter/Index.svelte#L1-L8) +- [each/**init**.py:1-73](file://backend/modelscope_studio/components/base/each/__init__.py#L1-L73) +- [filter/**init**.py:1-45](file://backend/modelscope_studio/components/base/filter/__init__.py#L1-L45) + +Section Sources + +- [each.tsx:1-7](file://frontend/base/each/each.tsx#L1-L7) +- [filter.tsx:1-7](file://frontend/base/filter/filter.tsx#L1-L7) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [each/**init**.py:1-73](file://backend/modelscope_studio/components/base/each/__init__.py#L1-L73) +- [filter/**init**.py:1-45](file://backend/modelscope_studio/components/base/filter/__init__.py#L1-L45) + +## Performance Considerations + +- List Rendering + - Each maps over `value` for rendering; avoid heavy computations inside `children` — move calculations upstream or cache them. + - Using stable keys (indices) helps React/Svelte diff optimization, but when the list has insertions/deletions, unique IDs are recommended as keys. +- Context Merging + - When Each/EachItem merge contexts, keep the `value` structure simple to avoid repeated rendering caused by deep nesting. +- Conditional Filtering + - `params_mapping` in Filter should avoid creating new functions on every render; define the function string at a higher level and pass it in. +- Visibility Control + - Use `visible` to control component rendering; the React implementation is not loaded when invisible, reducing unnecessary initialization and rendering. +- Large Data Sets + - Prefer pagination, virtual scrolling, or lazy loading strategies; avoid rendering oversized lists all at once. + - Reasonably flatten nested Each levels to reduce context depth and render tree complexity. + +## Troubleshooting Guide + +- Child Component Cannot Read Context + - Check whether Each has correctly passed in `contextValue` and `value`; confirm that the EachItem merge logic is effective. + - If using Filter, confirm that the `as_item` key name is correct or that `params_mapping` returns the expected object. +- Slot Rendering Order Abnormal + - Confirm that the slot key (`slotKey`) is consistent and that `useTargets` can correctly identify the target nodes. +- Filter Not Taking Effect + - Confirm that the `params_mapping` string can be parsed as a function, or that the `as_item` key exists in the current context. + - If no parameters are provided, Filter will block context propagation — this is expected behavior. +- Rendering Lag + - Check whether the `value` of Each is too large; paginate or virtualize as necessary. + - Avoid expensive operations inside `children`; move computations upstream or use memoization. + +Section Sources + +- [each.tsx:15-33](file://frontend/base/each/each.tsx#L15-L33) +- [filter.tsx:15-38](file://frontend/base/filter/filter.tsx#L15-L38) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [Index.svelte (Each):66-104](file://frontend/base/each/Index.svelte#L66-L104) +- [Index.svelte (Filter):33-45](file://frontend/base/filter/Index.svelte#L33-L45) + +## Conclusion + +Each and Filter form the core capabilities of "loop rendering" and "conditional filtering" in the rendering component series. Each provides a consistent data environment for every item in a list through context merging and slot resolution; Filter extracts or custom-filters the context before rendering to satisfy diverse conditional display and data filtering requirements. Combined with the backend component's visibility control and frontend utility hooks, flexible rendering strategies can be achieved while maintaining performance. + +## Appendix + +- API Overview (Summary) + - Each (Frontend Entry) + - Properties: `value`, `context_value`, `visible`, `elem_id`, `elem_classes`, `elem_style`, `_internal.index`, etc. + - Behavior: Placeholder component collects changes and decides whether to use the React implementation or EachItem rendering. + - Each (React Implementation) + - Properties: `value`, `contextValue`, `children`, `__internal_slot_key`. + - Behavior: Isolates external context, resolves slot targets, renders each item, and injects context. + - Filter (Frontend Entry) + - Properties: `params_mapping`, `as_item`, `visible`. + - Behavior: Passes parameters to the React implementation. + - Filter (React Implementation) + - Properties: `paramsMapping`, `asItem`. + - Behavior: Updates context based on `as_item` or `params_mapping` and passes it through. +- Backend Components + - Both Each and Filter inherit from the layout component base class, defining properties, visibility, pre/post-processing, and frontend directory mappings. + +Section Sources + +- [Index.svelte (Each):17-57](file://frontend/base/each/Index.svelte#L17-L57) +- [each.tsx:8-13](file://frontend/base/each/each.tsx#L8-L13) +- [Index.svelte (Filter):16-31](file://frontend/base/filter/Index.svelte#L16-L31) +- [filter.tsx:9-13](file://frontend/base/filter/filter.tsx#L9-L13) +- [each/**init**.py:23-51](file://backend/modelscope_studio/components/base/each/__init__.py#L23-L51) +- [filter/**init**.py:13-25](file://backend/modelscope_studio/components/base/filter/__init__.py#L13-L25) diff --git a/.wiki/en/Base Components/Slot Component.md b/.wiki/en/Base Components/Slot Component.md new file mode 100644 index 00000000..b16ccb4e --- /dev/null +++ b/.wiki/en/Base Components/Slot Component.md @@ -0,0 +1,333 @@ +# Slot Component + + +**Files Referenced in This Document** +- [frontend/base/slot/Index.svelte](file://frontend/base/slot/Index.svelte) +- [frontend/svelte-preprocess-react/react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/patchSlots.ts](file://frontend/utils/patchSlots.ts) +- [docs/components/base/slot/README.md](file://docs/components/base/slot/README.md) +- [docs/components/base/slot/README-zh_CN.md](file://docs/components/base/slot/README-zh_CN.md) +- [docs/components/base/slot/demos/basic.py](file://docs/components/base/slot/demos/basic.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document systematically explains the Slot component, covering design philosophy, content distribution mechanism, dynamic insertion and custom rendering, slot types and scopes, parameter passing and data binding, communication with parent components, usage examples, best practices, performance optimization suggestions, differences and advantages over template systems, and debugging tips and solutions to common issues. Based on the Slot component implementation and documentation in the repository, combined with the frontend rendering pipeline and context mechanism, this document helps readers fully master the slot system from principles to practice. + +## Project Structure + +The Slot component is implemented in Svelte on the frontend, responsible for collecting the child tree and registering it into the parent component's slot context; during the rendering phase, ReactSlot clones and mounts the DOM structure rendered by Svelte into the React environment, implementing cross-framework content distribution and dynamic updates. + +```mermaid +graph TB +subgraph "Frontend (Svelte)" +A["Index.svelte
Slot Component"] +B["svelte context
slot.svelte"] +end +subgraph "Utility Layer" +C["patchSlots.ts
Parameter Patching"] +D["renderSlot.tsx
Render Entry"] +end +subgraph "React Side" +E["react-slot.tsx
ReactSlot Component"] +end +A --> B +A --> C +D --> E +C --> D +B --> D +D --> E +``` + +Diagram Sources + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) + +Section Sources + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) + +## Core Components + +- Slot (Svelte): Receives the slot name and optional parameter mapping function from the parent component, registers itself as a "slot container" into the context, and renders child nodes when visibility allows. +- ReactSlot (React): In the React environment, receives the DOM fragment generated by Svelte, supports cloning, event copying, style and class name injection, and uses MutationObserver to observe changes and dynamically re-render. +- renderSlot: Provides a unified rendering entry, supporting force cloning, parameter passing, and context wrapping. +- patchSlots: Wraps slot rendering functions, prepending or appending additional parameters to slot callbacks in order, enabling parent components to pass context parameters to child slots. + +Section Sources + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) + +## Architecture Overview + +Slot's workflow is divided into a "registration phase" and a "rendering phase". Parent components register slot keys and parameter mappings via the context API; the Slot component collects the child tree in Svelte and binds it to the DOM; finally, ReactSlot clones and mounts in the React environment while maintaining event and style consistency. + +```mermaid +sequenceDiagram +participant Parent as "Parent Component" +participant SlotComp as "Slot (Index.svelte)" +participant Ctx as "Svelte Context (slot.svelte)" +participant Utils as "patchSlots/renderSlot" +participant RSlot as "ReactSlot (react-slot.tsx)" +Parent->>SlotComp : Pass value/params_mapping +SlotComp->>Ctx : setSlotKey/setSlotParamsMapping +SlotComp->>Ctx : setSlot(prevKey, currentKey, slotDom) +SlotComp-->>Parent : Render child nodes (hidden svelte-slot) +Utils->>RSlot : renderSlot(el, options) +RSlot->>RSlot : Clone element/copy events/inject styles/class names +RSlot-->>Parent : Mount to React environment +``` + +Diagram Sources + +- [frontend/base/slot/Index.svelte:32-54](file://frontend/base/slot/Index.svelte#L32-L54) +- [frontend/utils/patchSlots.ts:15-31](file://frontend/utils/patchSlots.ts#L15-L31) +- [frontend/utils/renderSlot.tsx:13-28](file://frontend/utils/renderSlot.tsx#L13-L28) +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) + +## Detailed Component Analysis + +### Slot Component (Svelte) + +- Responsibilities + - Receives slot name and parameter mapping function string. + - Writes the current slot key and parameter mapping to the context for parent component consumption. + - Renders child nodes when visible, but hides the actual `svelte-slot` container to avoid affecting layout. +- Key points + - Uses context API to set slot key and parameter mapping. + - Monitors slot name changes via `effect`, triggering `setSlot` registration. + - Child nodes are bound to DOM via `svelte-slot bind:this`, enabling ReactSlot to clone and mount later. + +```mermaid +flowchart TD +Start(["Enter Component"]) --> ReadProps["Read value/params_mapping"] +ReadProps --> SetCtx["setSlotKey / setSlotParamsMapping"] +SetCtx --> Effect["$effect monitors value changes"] +Effect --> HasSlot{"slot exists and value is valid?"} +HasSlot --> |Yes| Register["setSlot(prevKey, currentKey, slotDom)"] +HasSlot --> |No| Wait["Wait / stay unchanged"] +Register --> Render["Render child nodes (hidden svelte-slot)"] +Wait --> Render +Render --> End(["Complete"]) +``` + +Diagram Sources + +- [frontend/base/slot/Index.svelte:31-61](file://frontend/base/slot/Index.svelte#L31-L61) + +Section Sources + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) + +### ReactSlot (React) + +- Responsibilities + - Receives the slot DOM generated by Svelte, supports cloning and event copying. + - Injects styles and class names, handles React Portal for correct subtree mounting. + - Uses MutationObserver to monitor slot changes and automatically re-clones and renders. +- Key points + - `cloneElementWithEvents`: Recursively clones nodes, copies event listeners, handles nested `svelte-slot`. + - `mountElementProps`: Mounts class names and inline styles after cloning. + - `observeAttributes`: Optionally observes attribute changes, combined with debounce for improved stability. + +```mermaid +flowchart TD +Enter(["ReactSlot Mount"]) --> CheckClone{"Clone?"} +CheckClone --> |Yes| Observe["MutationObserver watches slot changes"] +Observe --> Render["cloneElementWithEvents clones and generates portals"] +Render --> Inject["Inject class names/styles/mount props"] +Inject --> Append["Append to ref.current"] +CheckClone --> |No| DirectMount["Mount slot directly"] +DirectMount --> Append +Append --> Cleanup["On unmount: clean styles/remove nodes/disconnect observer"] +``` + +Diagram Sources + +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) + +Section Sources + +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) + +### Parameter Patching and Render Entry + +- patchSlots + - Wraps slot rendering functions, supporting prepending/appending external parameters to slot callbacks. + - Used for parent components to pass context parameters to child slots, enhancing slot configurability. +- renderSlot + - Provides a unified entry, supporting force cloning, parameter passing, and context wrapping. + - When `params` or `forceClone` is passed, wraps ReactSlot with `ContextPropsProvider` to ensure rendering consistency. + +```mermaid +sequenceDiagram +participant Caller as "Caller" +participant Patch as "patchSlots" +participant Render as "renderSlot" +participant RSlot as "ReactSlot" +Caller->>Patch : Pass params and transform +Patch-->>Caller : Return wrapped rendering function +Caller->>Render : Pass el and options (params/forceClone/clone) +Render->>Render : Determine if ContextPropsProvider wrapping is needed +Render-->>Caller : Return ReactSlot component +Caller->>RSlot : Render ReactSlot +RSlot-->>Caller : Clone and mount slot +``` + +Diagram Sources + +- [frontend/utils/patchSlots.ts:15-31](file://frontend/utils/patchSlots.ts#L15-L31) +- [frontend/utils/renderSlot.tsx:13-28](file://frontend/utils/renderSlot.tsx#L13-L28) +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) + +Section Sources + +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) + +## Dependency Analysis + +- Component coupling + - Slot depends on the Svelte context API for slot registration and parameter mapping setting. + - ReactSlot depends on the structural characteristics of the slot DOM (such as internal portals and `svelte-slot` tags) for correct parsing and cloning. + - `renderSlot` and `patchSlots` provide general capabilities for the rendering pipeline, decoupled from specific components. +- External dependencies + - React, ReactDOM (Portal), MutationObserver, lodash-es (debounce and object judgment). +- Potential circular dependencies + - Avoided through utility layer and context layer separation, preventing direct circular references between components. + +```mermaid +graph LR +Slot["Slot (Index.svelte)"] --> Ctx["Svelte Context (slot.svelte)"] +Slot --> Patch["patchSlots.ts"] +Render["renderSlot.tsx"] --> RSlot["ReactSlot (react-slot.tsx)"] +Patch --> Render +Ctx --> Render +``` + +Diagram Sources + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) + +Section Sources + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) + +## Performance Considerations + +- Clone strategy + - Cloning brings extra DOM operations and event copying costs. Only enable `clone` when necessary to avoid unnecessary re-renders. +- Observer and debounce + - MutationObserver combined with debounce can reduce repeated cloning caused by frequent changes; it is recommended to enable `observeAttributes` and set a reasonable debounce interval in complex tables or high-frequency update scenarios. +- Style and class name injection + - Batch injecting styles and class names is better than individual operations, avoiding multiple reflows. +- Parameter passing + - Using `patchSlots` to prepend/append parameters reduces extra wrapping in intermediate layers, lowering the function call stack depth. + +## Troubleshooting Guide + +- Slot not working + - Check if the parent component has correctly registered the slot key and parameter mapping. + - Confirm if the Slot component's `value` is empty or unchanged (the `effect` only registers on change). +- Styles missing or class names not taking effect + - Confirm if ReactSlot correctly injected `className` and inline styles. + - Check for style isolation or overriding. +- Events not responding + - Confirm if `clone` is enabled; event copying logic depends on the cloning path. + - Check if event listeners have been overridden or removed. +- Updates not taking effect + - Confirm if `observeAttributes` is enabled, and if MutationObserver has been disconnected. + - Check if external code directly modified slot content without triggering observation. + +Section Sources + +- [frontend/svelte-preprocess-react/react-slot.tsx:156-212](file://frontend/svelte-preprocess-react/react-slot.tsx#L156-L212) +- [frontend/base/slot/Index.svelte:31-61](file://frontend/base/slot/Index.svelte#L31-L61) + +## Conclusion + +The Slot component implements cross-framework content distribution and dynamic rendering through Svelte and React bridging. Its design emphasizes: + +- Clear slot registration and parameter mapping mechanism; +- Stable rendering based on cloning and event copying; +- Optional observer and debounce strategies, balancing flexibility and performance; +- Utility layer abstraction (patchSlots, renderSlot) improving reusability and maintainability. + +## Appendix + +### Slot Types and Scopes + +- Slot types + - Named slots: Specify slot name via `value`; parent component receives by name. + - Nested slots: Child slots can contain slots again, forming multi-level content distribution. +- Scopes + - `params_mapping` supports mapping parent component context parameters to slot scope, enabling parameter-driven rendering. + +Section Sources + +- [docs/components/base/slot/README.md:13-16](file://docs/components/base/slot/README.md#L13-L16) +- [docs/components/base/slot/README-zh_CN.md:13-16](file://docs/components/base/slot/README-zh_CN.md#L13-L16) + +### Data Binding and Parent Component Communication + +- Parent components register slot keys and parameter mappings via the context API. +- The Slot component collects the child tree in Svelte and completes registration through `setSlot`. +- ReactSlot clones and mounts during the rendering phase, maintaining event and style consistency. + +Section Sources + +- [frontend/base/slot/Index.svelte:32-54](file://frontend/base/slot/Index.svelte#L32-L54) +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) + +### Usage Examples + +- Basic example: Insert title and extra button and icon slots into a Card component. +- Example path: [docs/components/base/slot/demos/basic.py:1-23](file://docs/components/base/slot/demos/basic.py#L1-L23) + +Section Sources + +- [docs/components/base/slot/demos/basic.py:1-23](file://docs/components/base/slot/demos/basic.py#L1-L23) + +### Best Practices + +- Only enable `clone` and `observeAttributes` when necessary, avoiding excessive rendering. +- Use `patchSlots` to prepend/append parameters, reducing intermediate wrapping. +- For complex tables and other high-frequency update scenarios, enable `observeAttributes` with debounce. +- Maintain the uniqueness and stability of slot keys, avoiding conflicts caused by duplicate registration. + +### Differences and Advantages Over Template Systems + +- Differences + - Template systems usually determine structure at compile time; the slot system dynamically distributes content at runtime. +- Advantages + - Stronger composability and extensibility, suitable for cross-framework and multi-component collaboration. + - Parameter mapping and context injection give slots stronger expressiveness and control. diff --git a/.wiki/en/Deployment Guide/Build Process.md b/.wiki/en/Deployment Guide/Build Process.md new file mode 100644 index 00000000..7de18962 --- /dev/null +++ b/.wiki/en/Deployment Guide/Build Process.md @@ -0,0 +1,405 @@ +# Build Process + + +**Files referenced in this document** +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [frontend/package.json](file://frontend/package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) +- [frontend/tsconfig.json](file://frontend/tsconfig.json) +- [svelte-tsconfig.json](file://svelte-tsconfig.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) +- [frontend/antd/button/package.json](file://frontend/antd/button/package.json) +- [frontend/antd/button/gradio.config.js](file://frontend/antd/button/gradio.config.js) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/svelte-preprocess-react/index.ts](file://frontend/svelte-preprocess-react/index.ts) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is intended for developers and operators who need to understand and maintain the build mechanism of ModelScope Studio. It systematically covers the following topics: + +- Frontend component build process: Vite configuration, Svelte component compilation, and React component bridging (svelte-preprocess-react). +- Python package build process: dependency installation, packaging configuration, version management, and publish scripts. +- Local build environment setup: key points for installing and configuring Node.js, Python, and pnpm. +- Build optimization techniques and performance tuning recommendations. +- Common build failure causes and solutions. + +## Project Structure + +The project is organized as a multi-package workspace (pnpm workspace). Core directories and their responsibilities: + +- **Root-level scripts and configuration**: package.json, pyproject.toml, pnpm-workspace.yaml, tsconfig.json, svelte-tsconfig.json. +- **Frontend**: the `frontend` directory and its sub-packages (antd, antdx, base, pro), plus the svelte-preprocess-react bridging layer. +- **Backend Python package**: backend/modelscope_studio, containing numerous component templates and version information. +- **Publish script**: scripts/publish-to-pypi.mts, used for building and publishing in CI. + +```mermaid +graph TB +subgraph "Root Workspace" +RootPkg["Root package.json"] +RootPy["Root pyproject.toml"] +WS["pnpm-workspace.yaml"] +TSRoot["tsconfig.json"] +SvelteTS["svelte-tsconfig.json"] +end +subgraph "Frontend" +FE_PKG["frontend/package.json"] +FE_CFG["frontend/defineConfig.js"] +FE_PLG["frontend/plugin.js"] +FE_TS["frontend/tsconfig.json"] +BTN_PKG["@modelscope-studio/antd-button/package.json"] +BTN_CFG["frontend/antd/button/gradio.config.js"] +BTN_IDX["frontend/antd/button/Index.svelte"] +BTN_TSX["frontend/antd/button/button.tsx"] +SPR_IDX["frontend/svelte-preprocess-react/index.ts"] +end +subgraph "Backend Python Package" +Backend["backend/modelscope_studio/..."] +VerPy["backend/modelscope_studio/version.py"] +end +subgraph "Publish Script" +Pub["scripts/publish-to-pypi.mts"] +end +RootPkg --> FE_PKG +RootPkg --> RootPy +WS --> FE_PKG +FE_CFG --> FE_PLG +FE_PKG --> BTN_PKG +BTN_CFG --> BTN_IDX +BTN_IDX --> BTN_TSX +BTN_TSX --> SPR_IDX +RootPy --> Backend +Pub --> RootPy +Pub --> RootPkg +``` + +**Diagram sources** + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) +- [svelte-tsconfig.json:1-4](file://svelte-tsconfig.json#L1-L4) +- [frontend/antd/button/package.json:1-15](file://frontend/antd/button/package.json#L1-L15) +- [frontend/antd/button/gradio.config.js:1-4](file://frontend/antd/button/gradio.config.js#L1-L4) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) + +**Section sources** + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) +- [svelte-tsconfig.json:1-4](file://svelte-tsconfig.json#L1-L4) + +## Core Components + +- **Root build scripts and commands**: Defined in the root `package.json`, providing a unified entry point for build, dev, version, and publish-related scripts. +- **Frontend Vite plugin**: `ModelScopeStudioVitePlugin` handles alias resolution, externalization, global variable mapping, and code transformation. +- **Svelte component bridge**: `svelte-preprocess-react` enables React components to be used in a Svelte style, handling slot and prop pass-through. +- **Python packaging**: `pyproject.toml` uses hatchling as the build backend, declaring `artifacts` and wheel inclusion paths to ensure template assets are correctly packaged. +- **Version management**: The Python package version is kept in sync with the frontend version, reflected jointly by `backend/modelscope_studio/version.py` and the root `package.json` version field. + +**Section sources** + +- [package.json:8-25](file://package.json#L8-L25) +- [frontend/plugin.js:41-168](file://frontend/plugin.js#L41-L168) +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) + +## Architecture Overview + +The diagram below shows the overall flow from "build command" to "artifact output", covering frontend Vite builds, React component bridging, Python packaging, and the publish script. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Root as "Root package.json" +participant Vite as "Vite Build" +participant Plugin as "ModelScopeStudioVitePlugin" +participant Svelte as "Svelte Compiler" +participant React as "React Component" +participant Py as "Python Packaging (hatch)" +participant Pub as "Publish Script (publish-to-pypi.mts)" +Dev->>Root : Run build script +Root->>Vite : Call gradio cc build +Vite->>Plugin : Apply plugin configuration and externalization +Vite->>Svelte : Compile Svelte components +Svelte->>React : Bridge via svelte-preprocess-react +Vite-->>Root : Generate dist +Root->>Py : Package using hatchling +Py-->>Root : Generate wheel/sdist +Dev->>Pub : Trigger publish process +Pub->>Py : Check whether version already exists +Pub->>Root : Run build and check +Pub->>Py : Upload with twine +``` + +**Diagram sources** + +- [package.json:8-25](file://package.json#L8-L25) +- [frontend/defineConfig.js:5-18](file://frontend/defineConfig.js#L5-L18) +- [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) +- [frontend/antd/button/Index.svelte:10-55](file://frontend/antd/button/Index.svelte#L10-L55) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) +- [scripts/publish-to-pypi.mts:22-55](file://scripts/publish-to-pypi.mts#L22-L55) + +## Detailed Component Analysis + +### Frontend Vite Build and Plugin + +- **Configuration entry**: `defineConfig.js` exports a function that returns a Vite default config object, integrating the React plugin and the custom `ModelScopeStudioVitePlugin`. +- **Plugin capabilities**: + - **Alias resolution**: `@utils`, `@globals`, `svelte-preprocess-react`. + - **Externalization strategy**: Marks a predefined set of modules as `external` during the build phase and injects global variable mappings, reducing bundle size. + - **Code transformation**: Traverses the AST and rewrites imports/exports to `window.ms_globals.*` accesses, enabling runtime dependency sharing. +- **Types and checking**: The frontend `tsconfig.json` extends the root tsconfig and enables ESNext module types; `svelte-tsconfig.json` is used for Svelte type checking. + +```mermaid +flowchart TD +Start(["Enter Vite Config"]) --> Alias["Configure aliases
@utils/@globals/svelte-preprocess-react"] +Alias --> External{"Externalization enabled?"} +External --> |Yes| MarkExt["Mark external list"] +External --> |No| SkipExt["Skip externalization"] +MarkExt --> DefineEnv["Define production environment constants"] +SkipExt --> DefineEnv +DefineEnv --> Transform["AST traversal and transformation
import/export -> window.ms_globals.*"] +Transform --> End(["Configuration complete"]) +``` + +**Diagram sources** + +- [frontend/defineConfig.js:5-18](file://frontend/defineConfig.js#L5-L18) +- [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) +- [frontend/plugin.js:77-167](file://frontend/plugin.js#L77-L167) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) +- [svelte-tsconfig.json:1-4](file://svelte-tsconfig.json#L1-L4) + +**Section sources** + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) +- [svelte-tsconfig.json:1-4](file://svelte-tsconfig.json#L1-L4) + +### Svelte Component Compilation and React Bridging + +- **Component export**: Each frontend component package declares its Gradio entry (`Index.svelte`) via the `exports` field in its `package.json`. +- **Configuration inheritance**: The component-level `gradio.config.js` generates a unified configuration through `defineConfig`. +- **Component implementation**: + - **Svelte layer**: `Index.svelte` uses APIs from `svelte-preprocess-react` such as `getProps`, `processProps`, and `getSlots` to transform props and slots passed in by Gradio into forms usable by React components. + - **React layer**: `button.tsx` uses `sveltify` to wrap the Ant Design Button so it can be used by Svelte, supporting slots and children rendering. +- **Slots and props**: Complex child nodes and icon slots are rendered via `ReactSlot` and `useTargets`. + +```mermaid +sequenceDiagram +participant Gradio as "Gradio Runtime" +participant Svelte as "Index.svelte" +participant Bridge as "svelte-preprocess-react" +participant React as "button.tsx" +Gradio->>Svelte : Pass in props and slots +Svelte->>Bridge : getProps()/processProps()/getSlots() +Bridge-->>Svelte : Normalized props/slots +Svelte->>React : importComponent to load React component +React-->>Svelte : Render Ant Design Button +Svelte-->>Gradio : Output final DOM +``` + +**Diagram sources** + +- [frontend/antd/button/package.json:1-15](file://frontend/antd/button/package.json#L1-L15) +- [frontend/antd/button/gradio.config.js:1-4](file://frontend/antd/button/gradio.config.js#L1-L4) +- [frontend/antd/button/Index.svelte:10-55](file://frontend/antd/button/Index.svelte#L10-L55) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) + +**Section sources** + +- [frontend/antd/button/package.json:1-15](file://frontend/antd/button/package.json#L1-L15) +- [frontend/antd/button/gradio.config.js:1-4](file://frontend/antd/button/gradio.config.js#L1-L4) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) + +### Python Package Build and Publish + +- **Build backend**: `pyproject.toml` uses hatchling as the build backend, together with `hatch-requirements-txt` and `hatch-fancy-pypi-readme`. +- **Dependencies and metadata**: Declares Python version requirements, license, keywords, classifiers, and core dependencies (such as Gradio). +- **Packaging scope**: `tool.hatch.build.artifacts` explicitly lists numerous template directories to ensure frontend component templates are distributed with the package; wheel/sdist inclusion and exclusion rules are clearly defined. +- **Version synchronization**: The Python package version is kept in sync with the frontend version for unified publishing and tracking. +- **Publish script**: `scripts/publish-to-pypi.mts` handles installation, building, version checking, and twine upload in CI, preventing duplicate publishing. + +```mermaid +flowchart TD +A["Read root package.json version"] --> B["Install project in editable mode"] +B --> C["Run frontend build"] +C --> D{"dist exists?"} +D --> |No| E["Throw build failure error"] +D --> |Yes| F["Check if version already exists on PyPI"] +F --> |Exists| G["Skip publish"] +F --> |Not exists| H["twine upload dist/*"] +H --> I["Output published=true"] +``` + +**Diagram sources** + +- [pyproject.toml:1-44](file://pyproject.toml#L1-L44) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [scripts/publish-to-pypi.mts:14-55](file://scripts/publish-to-pypi.mts#L14-L55) + +**Section sources** + +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) + +## Dependency Analysis + +- **Workspace and package management**: `pnpm-workspace.yaml` declares the root, config, frontend, and sub-packages, ensuring cross-package reference and build consistency. +- **Frontend dependencies**: `frontend/package.json` specifies core dependencies such as React 19, Svelte 5, Ant Design 6, and Monaco Editor. +- **Externalization and aliases**: `ModelScopeStudioVitePlugin` maps React, ReactDOM, antd, antdx, etc. to `window.ms_globals.*`, reducing duplicate bundling. +- **Python dependencies**: `pyproject.toml` declares only the Gradio dependency; other frontend assets are bundled via artifacts and template directories. + +```mermaid +graph LR +WS["pnpm-workspace.yaml"] --> FE["frontend/package.json"] +FE --> React["react / react-dom"] +FE --> Svelte["svelte 5"] +FE --> Antd["antd 6"] +FE --> Monaco["monaco-editor"] +FE --> Gradio["@gradio/*"] +Py["pyproject.toml"] --> Hatch["hatchling"] +Py --> Artifacts["artifacts template collection"] +Py --> Wheel["wheel/sdist config"] +``` + +**Diagram sources** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [pyproject.toml:1-44](file://pyproject.toml#L1-L44) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) + +**Section sources** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +## Performance Considerations + +- **Externalization and shared dependencies**: Through `ModelScopeStudioVitePlugin`'s external configuration and global mappings, large packages such as React and antd are not bundled repeatedly, significantly reducing artifact size and build time. +- **AST transformation and lazy loading**: Rewriting imports/exports to global access at build time, combined with dynamic `import` (e.g., `importComponent`), enables lazy loading and improves initial load performance. +- **Module aliases**: Using `@utils`, `@globals`, and `svelte-preprocess-react` aliases appropriately reduces path resolution overhead. +- **Packaging granularity**: Precisely listing template directories in `artifacts` prevents unrelated files from entering the package, shortening packaging and publish time. +- **Type checking**: Enabling `svelte-check` and TypeScript type checking catches type issues early, reducing the cost of rollbacks caused by runtime errors. + +[This section provides general performance recommendations and does not directly reference specific files, so no "Section sources" are listed.] + +## Troubleshooting Guide + +- **Build failure (dist does not exist)** + - Symptom: The publish script reports "Build Failed". + - Investigation: Confirm that the frontend build command completed successfully; check whether `defineConfig` and plugin configuration are correctly applied. + - References: + - [scripts/publish-to-pypi.mts:22-30](file://scripts/publish-to-pypi.mts#L22-L30) + - [frontend/defineConfig.js:8-18](file://frontend/defineConfig.js#L8-L18) +- **Duplicate version publish** + - Symptom: The same version already exists on PyPI; the script skips publishing. + - Investigation: Confirm that the version number has not been changed, or manually clear the cache. + - References: + - [scripts/publish-to-pypi.mts:44-51](file://scripts/publish-to-pypi.mts#L44-L51) +- **Missing externalized dependency** + - Symptom: Runtime error — `window.ms_globals` is not defined. + - Investigation: Check the `external`/`excludes` configuration in `ModelScopeStudioVitePlugin` to confirm the global mapping covers all required dependencies. + - References: + - [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) + - [frontend/plugin.js:5-20](file://frontend/plugin.js#L5-L20) +- **Svelte/React slot rendering issue** + - Symptom: Slot content is not displayed, or icons/loading states do not work. + - Investigation: Confirm that `getProps`/`processProps`/`getSlots` in `Index.svelte` are used correctly, and that `ReactSlot` and `useTargets` in `button.tsx` behave as expected. + - References: + - [frontend/antd/button/Index.svelte:10-55](file://frontend/antd/button/Index.svelte#L10-L55) + - [frontend/antd/button/button.tsx:11-36](file://frontend/antd/button/button.tsx#L11-L36) +- **Python packaging missing templates** + - Symptom: Component templates are missing after installation. + - Investigation: Cross-check the `artifacts` list in `pyproject.toml` against the wheel/sdist inclusion paths. + - References: + - [pyproject.toml:45-257](file://pyproject.toml#L45-L257) + +**Section sources** + +- [scripts/publish-to-pypi.mts:22-51](file://scripts/publish-to-pypi.mts#L22-L51) +- [frontend/plugin.js:5-20](file://frontend/plugin.js#L5-L20) +- [frontend/antd/button/Index.svelte:10-55](file://frontend/antd/button/Index.svelte#L10-L55) +- [frontend/antd/button/button.tsx:11-36](file://frontend/antd/button/button.tsx#L11-L36) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) + +## Conclusion + +The build system of this project revolves around a combination of "frontend Vite + Svelte + React bridging + Python packaging". Through externalized shared dependencies, AST transformation, and a precise template packaging strategy, it achieves efficient builds and stable runtime behavior. Following the configuration and troubleshooting recommendations in this document will effectively improve build stability and performance in both local and CI environments. + +[This section contains summary content and does not directly reference specific files, so no "Section sources" are listed.] + +## Appendix + +### Local Build Environment Setup + +- **Node.js** + - Version requirements: must satisfy the needs of frontend dependencies (React 19, Svelte 5, Ant Design 6). + - Package manager: use pnpm, consistent with the workspace configuration. + - References: + - [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) + - [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- **Python** + - Version requirements: must satisfy `requires-python` in `pyproject.toml`. + - Build tools: install hatchling and twine to ensure they are executable. + - References: + - [pyproject.toml:1-7](file://pyproject.toml#L1-L7) + - [pyproject.toml:42-43](file://pyproject.toml#L42-L43) +- **Frontend build** + - Run root scripts for building and development, ensuring that `defineConfig` and the plugin load correctly. + - References: + - [package.json:8-25](file://package.json#L8-L25) + - [frontend/defineConfig.js:5-18](file://frontend/defineConfig.js#L5-L18) + - [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) + +**Section sources** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-44](file://pyproject.toml#L1-L44) +- [package.json:8-25](file://package.json#L8-L25) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) diff --git a/.wiki/en/Deployment Guide/CI CD.md b/.wiki/en/Deployment Guide/CI CD.md new file mode 100644 index 00000000..9cc946fa --- /dev/null +++ b/.wiki/en/Deployment Guide/CI CD.md @@ -0,0 +1,436 @@ +# CI/CD + + +**Files referenced in this document** +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [.changeset/config.json](file://.changeset/config.json) +- [.changeset/README.md](file://.changeset/README.md) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) +- [scripts/create-tag-n-release.mts](file://scripts/create-tag-n-release.mts) +- [eslint.config.mjs](file://eslint.config.mjs) +- [prettier.config.mjs](file://prettier.config.mjs) +- [.flake8](file://.flake8) +- [config/lint-config/eslint.mjs](file://config/lint-config/eslint.mjs) +- [.commitlintrc.js](file://.commitlintrc.js) +- [.lintstagedrc](file://.lintstagedrc) +- [.editorconfig](file://.editorconfig) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is intended for developers and operators who need to configure and maintain automated pipelines for ModelScope Studio. It systematically covers the following topics: + +- GitHub Actions workflows: configuration and execution logic for Lint and Publish +- Lint workflow integration: how ESLint, Prettier, Flake8, isort, yapf, and other tools are used in CI +- Publish workflow: version detection, build validation, PyPI publishing, tag and release creation +- Changesets usage: version updates, changelog generation, and release tag creation +- Custom workflows: how to extend and customize existing pipelines +- Troubleshooting and performance optimization recommendations + +## Project Structure + +The repository is a polyglot project: the frontend is built on Svelte/TypeScript, the backend is a Python package. Version and changelog management is unified through Changesets, and CI/CD is implemented with GitHub Actions. + +```mermaid +graph TB +subgraph "CI/CD Workflows" +LINT[".github/workflows/lint.yaml"] +PUBLISH[".github/workflows/publish.yaml"] +end +subgraph "Versioning & Changelog" +CHCFG[".changeset/config.json"] +CHREADM[".changeset/README.md"] +end +subgraph "Frontend & Scripts" +PKGJSON["package.json"] +ESLINTCFG["eslint.config.mjs"] +PRETTIERCFG["prettier.config.mjs"] +LINTSTAGED[".lintstagedrc"] +EDITOR[".editorconfig"] +SCRIPT_PUBLISH["scripts/publish-to-pypi.mts"] +SCRIPT_TAGREL["scripts/create-tag-n-release.mts"] +end +subgraph "Python Package" +PYPROJ["pyproject.toml"] +FLAKE8[".flake8"] +end +LINT --> PKGJSON +PUBLISH --> PKGJSON +PUBLISH --> SCRIPT_PUBLISH +PUBLISH --> SCRIPT_TAGREL +PKGJSON --> ESLINTCFG +PKGJSON --> PRETTIERCFG +PKGJSON --> LINTSTAGED +PKGJSON --> EDITOR +PKGJSON --> CHCFG +PKGJSON --> CHREADM +PKGJSON --> PYPROJ +PYPROJ --> FLAKE8 +``` + +Diagram sources + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/README.md:1-9](file://.changeset/README.md#L1-L9) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) +- [eslint.config.mjs:1-9](file://eslint.config.mjs#L1-L9) +- [prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26) +- [.lintstagedrc:1-7](file://.lintstagedrc#L1-L7) +- [.editorconfig:1-17](file://.editorconfig#L1-L17) +- [.flake8:1-16](file://.flake8#L1-L16) + +Section sources + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +## Core Components + +- **Lint Workflow**: Triggered on push and pull requests. Installs Python and Node dependencies, then runs the unified lint script. +- **Publish Workflow**: Triggered on pushes to main/next branches. Determines whether to execute version updates and publishing based on the commit message, and ultimately creates a Git tag and GitHub Release. +- **Changesets**: Centralized version and changelog management. Works with scripts to write version numbers and fix changelogs. +- **Publish Script**: Checks whether the target version already exists on PyPI, builds artifacts, uploads to PyPI, and sets a published output flag for downstream steps. +- **Tag & Release Script**: Aggregates changelogs from all packages, creates a Git tag, and creates a GitHub Release. + +Section sources + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [package.json:8-25](file://package.json#L8-L25) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) + +## Architecture Overview + +The diagram below shows the critical path and decision points from code commit to release. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant GH as "GitHub" +participant LINT as "Lint Workflow" +participant PUBLISH as "Publish Workflow" +participant PYPI as "PyPI" +participant TAGREL as "Tag & Release Script" +Dev->>GH : Push commit / open PR +GH->>LINT : Trigger Lint (push/pull_request) +LINT-->>GH : Lint result +Dev->>GH : Push to main/next +GH->>PUBLISH : Trigger Publish (push) +PUBLISH->>PUBLISH : Check if commit message is "update versions" +alt "update versions" commit +PUBLISH->>PYPI : Build and upload +PYPI-->>PUBLISH : Upload result +PUBLISH->>TAGREL : Create Tag and Release +TAGREL-->>GH : Release complete +else Not an "update versions" commit +PUBLISH-->>GH : Skip publish steps +end +``` + +Diagram sources + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +## Detailed Component Analysis + +### Lint Workflow Configuration and Execution + +- **Trigger conditions**: push and pull_request +- **Concurrency control**: Only one running instance is retained per workflow per branch +- **Step overview**: + - Check out code (full history) + - Install Python dependencies (flake8, isort, yapf) + - Install Node.js and pnpm + - Install Node dependencies + - Run the unified lint script (JS/TS linting and formatting run in parallel) + +```mermaid +flowchart TD +Start(["Start"]) --> Checkout["Check Out Code"] +Checkout --> PySetup["Set Up Python 3.9"] +PySetup --> PyDeps["Install Python Dependencies"] +PyDeps --> NodeSetup["Set Up Node.js 20"] +NodeSetup --> PNPM["Install pnpm"] +PNPM --> NPMInstall["Install Node Dependencies"] +NPMInstall --> RunLint["Run Unified Lint Script"] +RunLint --> End(["End"]) +``` + +Diagram sources + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) + +Section sources + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [package.json:18-22](file://package.json#L18-L22) +- [.lintstagedrc:1-7](file://.lintstagedrc#L1-L7) +- [.editorconfig:1-17](file://.editorconfig#L1-L17) +- [.flake8:1-16](file://.flake8#L1-L16) + +### Publish Workflow Configuration and Execution + +- **Trigger conditions**: Push to main or next branch +- **Concurrency control**: Independent group to avoid concurrent conflicts +- **Key steps**: + - **Conditional execution**: Subsequent steps run only when the commit message is "update versions" + - **Build and publish**: Invokes the publish script with the PyPI token + - **Tag and release**: If publishing succeeds, invokes the tag and release script with the GitHub token, repository name, and owner + +```mermaid +flowchart TD +PS(["Start"]) --> CheckCommit["Check if commit message is 'update versions'"] +CheckCommit --> |No| Skip["Skip publish steps"] +CheckCommit --> |Yes| Build["Install Python/Node dependencies"] +Build --> Publish["Run publish script to upload to PyPI"] +Publish --> Published{"Publish successful?"} +Published --> |No| End(["End"]) +Published --> |Yes| TagRel["Create Git Tag and publish to GitHub"] +TagRel --> End +``` + +Diagram sources + +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +Section sources + +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +### Changesets Version and Changelog Management + +- **Configuration highlights**: + - Uses a custom changelog generator with the repository URL specified + - Base branch is `main` + - Internal dependency update strategy is patch +- **Common commands**: + - Version update and changelog fix: executed by the root script + - CLI interactive version selection and change recording + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant CS as "Changesets CLI" +participant Root as "Root Script" +participant Changelog as "Changelog Generator" +Dev->>CS : Add/edit changeset +Dev->>Root : Run version update script +Root->>CS : Execute version update +CS-->>Root : Generate version numbers and changelogs +Root->>Changelog : Fix/aggregate changelogs +Changelog-->>Dev : Output changelog files +``` + +Diagram sources + +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [package.json](file://package.json#L24) + +Section sources + +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/README.md:1-9](file://.changeset/README.md#L1-L9) +- [package.json:8-25](file://package.json#L8-L25) + +### Publish Script: Version Detection, Build, and Upload + +- **Functionality overview**: + - Checks whether the target version already exists on PyPI; skips if it does + - Installs editable-mode dependencies and runs the build + - Verifies that the dist directory exists + - Uploads to PyPI with twine, skipping already-existing files + - Sets a published-success output flag for subsequent steps + +```mermaid +flowchart TD +S(["Start"]) --> Exists["Check if version already exists on PyPI"] +Exists --> |Exists| Warn["Skip and output notice"] --> End(["End"]) +Exists --> |Not exists| Install["Install editable dependencies"] +Install --> Build["Run build"] +Build --> Dist{"dist directory exists?"} +Dist --> |No| Fail["Throw build failure error"] --> End +Dist --> |Yes| Upload["Upload with twine"] +Upload --> SetOut["Set published-success output flag"] +SetOut --> End +``` + +Diagram sources + +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) + +Section sources + +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) + +### Tag & Release Script: Aggregating Changelogs, Creating Tag and Release + +- **Functionality overview**: + - Reads the root changelog and per-package changelogs, aggregated by version + - Configures Git user information + - Creates a tag with a `v` prefix and pushes it to the remote + - Calls the GitHub API to create a Release; the pre-release flag is determined based on the version number + +```mermaid +sequenceDiagram +participant Script as "Tag & Release Script" +participant FS as "File System" +participant Git as "Git" +participant GH as "GitHub API" +Script->>FS : Read root and per-package changelogs +Script->>Script : Parse change entries by version +Script->>Git : Configure user name and email +Script->>Git : Create tag and push +Script->>GH : Create Release (with pre-release flag) +GH-->>Script : Return result +``` + +Diagram sources + +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +Section sources + +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +### Lint Toolchain and Configuration + +- **ESLint**: Imports the unified lint configuration set from the root config +- **Prettier**: Unified formatting rules and plugins, supporting Svelte and package.json +- **Flake8**: Python static analysis, ignoring specific rules and directories +- **isort/yapf**: Python import sorting and formatting +- **Stylelint**: Style file checking (invoked via script) +- **Commit convention**: commitlint based on Conventional Commits + +Section sources + +- [eslint.config.mjs:1-9](file://eslint.config.mjs#L1-L9) +- [config/lint-config/eslint.mjs:1-11](file://config/lint-config/eslint.mjs#L1-L11) +- [prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26) +- [.lintstagedrc:1-7](file://.lintstagedrc#L1-L7) +- [.flake8:1-16](file://.flake8#L1-L16) +- [.commitlintrc.js:1-30](file://.commitlintrc.js#L1-L30) +- [.editorconfig:1-17](file://.editorconfig#L1-L17) + +## Dependency Analysis + +- **Workflow dependency on scripts**: The publish workflow directly invokes the publish and tag scripts +- **Script dependency on tools**: The publish script depends on twine and the build toolchain; the tag script depends on the GitHub API and Git +- **Language ecosystem dependencies**: The frontend uses pnpm for dependency management; Python uses hatchling for building and twine for uploading +- **Version and changelog**: Changesets and root scripts jointly drive version number and changelog generation + +```mermaid +graph LR +LINTWF[".github/workflows/lint.yaml"] --> PKG["package.json scripts"] +PUBWF[".github/workflows/publish.yaml"] --> PUBLISH["scripts/publish-to-pypi.mts"] +PUBWF --> TAGREL["scripts/create-tag-n-release.mts"] +PUBLISH --> TWINE["twine upload"] +PUBLISH --> BUILD["Build artifacts"] +TAGREL --> GHAPI["GitHub API"] +TAGREL --> GIT["Git tags"] +PKG --> ESL["ESLint/Prettier/Stylelint"] +PKG --> PY["Python deps (flake8/isort/yapf)"] +PY --> PYPROJ["pyproject.toml"] +``` + +Diagram sources + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) +- [package.json:8-25](file://package.json#L8-L25) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +Section sources + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +## Performance Considerations + +- **Caching and concurrency**: Make proper use of caching and concurrency control to avoid redundant installs and builds +- **Task splitting**: Separating Lint and build into independent steps facilitates parallelism and retries +- **Dependency minimization**: Install only the extra dependencies needed to reduce image size and wait time +- **Fail fast**: Exit early when a version already exists or a build fails to conserve resources + +## Troubleshooting Guide + +- **PyPI version already exists** + - Symptom: The publish script skips the upload and outputs a notice + - Resolution: Confirm whether the version number has been correctly updated, or clear the cache and retry +- **Missing build artifacts** + - Symptom: No `dist` directory generated after build, causing failure + - Resolution: Check whether the build script and dependency installation completed successfully +- **Upload failure (permissions / token)** + - Symptom: twine upload reports an error + - Resolution: Confirm that `PYPI_TOKEN` is configured and valid +- **Tag and Release failure** + - Symptom: GitHub API throws an exception or changelog is not found + - Resolution: Check whether changelog generation is working correctly and confirm the version number matches the tag +- **Lint failure** + - Symptom: ESLint / Prettier / Flake8 reports errors + - Resolution: Fix the code or adjust the rules according to the error messages; ensure local and CI use the same configuration + +Section sources + +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) +- [package.json:18-22](file://package.json#L18-L22) +- [.lintstagedrc:1-7](file://.lintstagedrc#L1-L7) +- [.flake8:1-16](file://.flake8#L1-L16) + +## Conclusion + +The CI/CD system in this repository is built around GitHub Actions, Changesets, and a set of Node/Python toolchains, implementing an end-to-end pipeline from code linting to version publishing. Through clear workflow separation, strict version and changelog management, and reusable publish and tag scripts, the team can deliver products efficiently and reliably. + +## Appendix + +### Custom Workflow Recommendations + +- **Adding lint rules**: Extend ESLint/Prettier rules in the root config and sync them to `.lintstagedrc` +- **Adding languages or tools**: Add scripts and dependencies in `package.json`, and add corresponding steps in the workflow +- **Publish strategy**: Adjust trigger branches and conditional checks as needed to ensure publishing only occurs on "update versions" commits +- **Security and secrets**: Strictly manage `PYPI_TOKEN` and `GITHUB_TOKEN`, restricting their scope and access + +### Reference File Index + +- Lint workflow: [lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- Publish workflow: [publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- Changesets config: [config.json:1-15](file://.changeset/config.json#L1-L15) +- Root scripts and toolchain: [package.json:8-25](file://package.json#L8-L25) +- Python build and publish: [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- Publish script: [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- Tag and release script: [create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) +- Lint configuration: [eslint.config.mjs:1-9](file://eslint.config.mjs#L1-L9), [prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26), [lint-staged config:1-7](file://.lintstagedrc#L1-L7), [flake8 config:1-16](file://.flake8#L1-L16) +- Commit convention: [commitlint config:1-30](file://.commitlintrc.js#L1-L30) +- Editor configuration: [EditorConfig:1-17](file://.editorconfig#L1-L17) diff --git a/.wiki/en/Deployment Guide/Deployment Guide.md b/.wiki/en/Deployment Guide/Deployment Guide.md new file mode 100644 index 00000000..cc1811de --- /dev/null +++ b/.wiki/en/Deployment Guide/Deployment Guide.md @@ -0,0 +1,333 @@ +# Deployment Guide + + +**Files Referenced in This Document** +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) +- [scripts/create-tag-n-release.mts](file://scripts/create-tag-n-release.mts) +- [frontend/package.json](file://frontend/package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [README.md](file://README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This guide is intended for operations personnel and developers, providing a systematic explanation of ModelScope Studio's build process, release strategy, and deployment practices, covering the following topics: + +- Frontend component build and packaging strategy +- Python package build and publishing to PyPI +- CI/CD pipeline configuration and usage +- Configuration methods for different deployment environments (local development, production, cloud platforms) +- Performance optimization and monitoring recommendations +- Common issue troubleshooting and solutions + +## Project Structure + +The project uses a multi-package workspace organization, with the root directory managing frontend sub-packages and configuration modules uniformly via pnpm workspaces. The backend Python package is in the `backend/modelscope_studio` directory and defines build and packaging rules via `pyproject.toml`. + +```mermaid +graph TB +Root["Repository Root"] --> Backend["Backend Python Package
backend/modelscope_studio"] +Root --> Frontend["Frontend Workspace
frontend/*"] +Root --> Config["Configuration Toolset
config/*"] +Root --> Scripts["Release Scripts
scripts/*"] +Root --> Workflows["CI/CD Pipelines
.github/workflows/*"] +Frontend --> Antd["Ant Design Component Library
frontend/antd/*"] +Frontend --> Antdx["Ant Design X Component Library
frontend/antdx/*"] +Frontend --> Pro["Pro Component Library
frontend/pro/*"] +Frontend --> Base["Base Component Library
frontend/base/*"] +``` + +Chart Sources + +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [frontend/package.json](file://frontend/package.json) +- [pyproject.toml](file://pyproject.toml) + +Section Sources + +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [frontend/package.json](file://frontend/package.json) +- [pyproject.toml](file://pyproject.toml) + +## Core Components + +- Build and Packaging + - Frontend: Based on Vite and custom plugins, implements React/Svelte mixed compilation and externalization strategies, outputting component assets usable by Gradio. + - Backend: Built using Hatchling, packaging templates and component assets into the Python package via toolchain. +- Release and Version Management + - Uses Changesets for version and changelog management; CI executes build, upload to PyPI, creation of Git Tag, and GitHub Release. +- Quality Assurance + - Lint pipeline runs on PRs and pushes to ensure consistent code style and static checks. + +Section Sources + +- [package.json](file://package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) +- [pyproject.toml](file://pyproject.toml) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) + +## Architecture Overview + +The diagram below shows the complete deployment path from local to cloud: Local development build → CI trigger → PyPI publishing → Tag and Release creation. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Local as "Local Build" +participant GH as "GitHub Actions" +participant PyPI as "PyPI" +participant Git as "Git Repository" +Dev->>Local : Execute build script +Local-->>Dev : Output dist/ frontend artifacts +Dev->>GH : Push branch / trigger pipeline +GH->>GH : Fetch code / install dependencies +GH->>GH : Build Python package and validate version +GH->>PyPI : Upload wheel and source package +PyPI-->>GH : Return publish result +GH->>Git : Create Tag and push +GH->>Git : Create GitHub Release +``` + +Chart Sources + +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) +- [scripts/create-tag-n-release.mts](file://scripts/create-tag-n-release.mts) + +## Detailed Component Analysis + +### Frontend Build and Packaging + +- Build Entry and Commands + - The build script in the root `package.json` calls the Gradio custom component CLI for building (using `--no-generate-docs` to disable automatic documentation generation for faster builds). + - Full command: `rimraf dist && gradio cc build --no-generate-docs` +- Vite Plugins and Aliases + - The custom Vite plugin is responsible for: + - Setting environment variables to production mode during the build phase + - Externalizing specified dependencies to reduce bundle size + - Transforming import/export statements via Babel AST to map modules to global objects, enabling on-demand loading in browser environments + - Alias mappings to utility and global component modules improve development experience and consistency. +- Externalization Strategy + - React, Ant Design, and their ecosystems are externalized to avoid duplicate bundling, reducing bundle size and improving cache hit rate. + +```mermaid +flowchart TD +Start(["Start Build"]) --> LoadCfg["Load Vite config and plugins"] +LoadCfg --> SetEnv["Set production environment variables"] +SetEnv --> Externalize["Configure externalized dependency list"] +Externalize --> Alias["Configure module aliases"] +Alias --> Transform["Babel AST transform imports/exports"] +Transform --> Bundle["Rollup bundle artifacts"] +Bundle --> End(["Done"]) +``` + +Chart Sources + +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) + +Section Sources + +- [package.json](file://package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) + +### Python Package Build and Release + +- Build System and Metadata + - Uses Hatchling as the build backend, declares dependencies and optional dependencies, defines classifiers and keywords. +- Asset Packaging + - A large number of component templates and static assets are included in the packaging scope via toolchain, ensuring they are directly available at runtime. +- Version and Metadata + - Root `pyproject.toml` stays consistent with the backend version file, ensuring unified release version numbers. + +```mermaid +flowchart TD +A["Read pyproject.toml metadata"] --> B["Install build dependencies"] +B --> C["Execute build command to generate dist/"] +C --> D{"Does dist/ exist?"} +D --> |No| E["Throw build failure error"] +D --> |Yes| F["Check if version already exists on PyPI"] +F --> |Exists| G["Skip publishing"] +F --> |Not Exists| H["Use Twine to upload to PyPI"] +H --> I["Mark publish as successful"] +``` + +Chart Sources + +- [pyproject.toml](file://pyproject.toml) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) + +Section Sources + +- [pyproject.toml](file://pyproject.toml) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) + +### CI/CD Pipeline + +- Publish Pipeline + - Trigger: Push to `main` or `next` branch + - Steps: Install Python and Node.js, install pnpm, install dependencies, build frontend and backend, upload to PyPI, create Tag and Release +- Lint Pipeline + - Trigger: Push and Pull Requests + - Steps: Install Python and Node.js, install dependencies, run Lint tasks + +```mermaid +sequenceDiagram +participant Push as "Push Event" +participant PubWF as "Publish Pipeline" +participant LintWF as "Lint Pipeline" +participant PyPI as "PyPI" +participant GH as "GitHub" +Push->>PubWF : Trigger publish +PubWF->>PubWF : Install dependencies / build +PubWF->>PyPI : Upload package +PubWF->>GH : Create Tag and Release +Push->>LintWF : Trigger Lint +LintWF->>LintWF : Run code style and static checks +``` + +Chart Sources + +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) + +Section Sources + +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) + +### Version and Changelog Management + +- Changesets + - Uses Changesets for version bumping and changelog generation, combined with scripts to automatically execute version updates and fixes in CI. +- Tags and Releases + - After a successful release, scripts generate unified Release content from the root and sub-package changelogs, create a Git Tag, and push to remote. + +Section Sources + +- [package.json](file://package.json) +- [scripts/create-tag-n-release.mts](file://scripts/create-tag-n-release.mts) + +## Dependency Analysis + +- Frontend Dependencies + - React and Svelte ecosystems, Ant Design and Ant Design X, Monaco Editor, Mermaid, etc., form the core capabilities of the component library. +- Build Tools + - Vite, @vitejs/plugin-react-swc, Babel, Rollup (driven by Vite) +- Python Dependencies + - Gradio as the runtime framework, Hatchling for building, Twine for uploading + +```mermaid +graph LR +FE["Frontend Build"] --> Vite["Vite"] +FE --> Babel["Babel"] +FE --> Rollup["Rollup"] +BE["Backend Build"] --> Hatch["Hatchling"] +BE --> Gradio["Gradio"] +Pub["Release"] --> Twine["Twine"] +Pub --> PyPI["PyPI"] +``` + +Chart Sources + +- [frontend/package.json](file://frontend/package.json) +- [pyproject.toml](file://pyproject.toml) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) + +Section Sources + +- [frontend/package.json](file://frontend/package.json) +- [pyproject.toml](file://pyproject.toml) + +## Performance Considerations + +- Frontend Bundle Optimization + - Externalization strategy: Externalizes large dependencies such as React and Ant Design to reduce bundle size and duplicate bundling. + - AST transformation: The plugin transforms imports/exports to global access at build time, avoiding redundant runtime logic. + - On-demand loading: Combined with Gradio's loading mechanism, component assets are only loaded when needed. +- Build Efficiency + - Disabling the documentation generation build option can significantly reduce frontend build time. + - Using pnpm workspaces to unify dependencies reduces disk usage and installation time. +- Python Package Size + - Only package the necessary templates and assets to avoid unnecessary files entering the distribution package. + +Section Sources + +- [frontend/plugin.js](file://frontend/plugin.js) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) + +## Troubleshooting Guide + +- Build Failure + - Symptom: `dist/` not generated or build errors + - Investigation: Confirm the frontend build script executed, verify Node.js and pnpm versions meet requirements, check dependency installation success + - Reference: Root `package.json` build scripts and frontend `defineConfig` configuration +- PyPI Upload Failure + - Symptom: Twine upload error or version already exists + - Investigation: Check whether `PYPI_TOKEN` is correctly configured, whether the version already exists on PyPI, and network connectivity + - Reference: Version check and upload logic in the publish script +- CI Pipeline Interruption + - Symptom: Lint or publish step fails + - Investigation: Check the corresponding workflow logs, confirm environment variables and permissions, verify trigger conditions + - Reference: `lint` and `publish` workflow configurations +- Documentation and Examples + - Reference: Root README installation and quick start instructions to ensure local development environment and dependency versions are consistent + +Section Sources + +- [package.json](file://package.json) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) +- [README.md](file://README.md) + +## Conclusion + +This guide provides an integrated deployment solution from local to cloud: optimizing bundle size via frontend Vite plugins and externalization strategies, achieving stable Python package publishing with Hatchling and Twine, and completing automated pipelines and version management with GitHub Actions. For production and cloud platform deployments, it is recommended to further optimize loading performance by combining externalization and caching strategies, and to continuously run Lint in CI to maintain quality. + +## Appendix + +### Configuration Methods for Different Deployment Environments + +- Local Development + - Install dependencies: use pnpm to install workspace dependencies + - Start development server: run the Gradio custom component development command + - Reference: Root README development instructions and `package.json` scripts +- Production Environment + - Build artifacts: execute the frontend build script to generate `dist/`, ensure externalized dependencies are available at runtime + - Python package: build with Hatchling, ensure templates and assets are packaged +- Cloud Platform Deployment + - Use CI to trigger the publish pipeline, automatically upload to PyPI and create Tag/Release + - Install the Python package on the target platform and start the application + +Section Sources + +- [README.md](file://README.md) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) diff --git a/.wiki/en/Deployment Guide/Environment Configuration.md b/.wiki/en/Deployment Guide/Environment Configuration.md new file mode 100644 index 00000000..0fb2becd --- /dev/null +++ b/.wiki/en/Deployment Guide/Environment Configuration.md @@ -0,0 +1,315 @@ +# Environment Configuration + + +**Files Referenced in This Document** +- [README.md](file://README.md) +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [docs/app.py](file://docs/app.py) +- [frontend/package.json](file://frontend/package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [backend/modelscope_studio/utils/dev/app_context.py](file://backend/modelscope_studio/utils/dev/app_context.py) +- [backend/modelscope_studio/utils/dev/process_links.py](file://backend/modelscope_studio/utils/dev/process_links.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is intended for operations personnel and developers, providing environment configuration and deployment best practices for ModelScope Studio, covering configuration essentials for local development, testing, and production environments, including environment variables, dependency management, containerization (Docker/Kubernetes), performance monitoring, log configuration, environment migration and upgrade strategies, as well as deployment differences and considerations across different platforms. + +## Project Structure + +The repository uses a multi-package workspace organization. The backend is published as a Python package, the frontend is built with Svelte + Vite, and the documentation site is started via Gradio CC. Key directories and responsibilities: + +- `backend/modelscope_studio`: Python backend components and utilities +- `frontend`: Frontend components and build configuration +- `docs`: Documentation site and example application +- `config`: Shared Lint and changelog configuration +- Root-level configuration: `pyproject.toml` (Python packaging), `package.json` (Node workspace scripts), `pnpm-workspace.yaml` (workspace definition) + +```mermaid +graph TB +A["Root Directory"] --> B["backend/modelscope_studio
Python Package and Components"] +A --> C["frontend
Svelte/Vite Frontend"] +A --> D["docs
Gradio CC Documentation Site"] +A --> E["config
Shared Configuration"] +A --> F["pyproject.toml
Python Packaging and Metadata"] +A --> G["package.json
Node Workspace Scripts"] +A --> H["pnpm-workspace.yaml
Workspace and Build-only Dependencies"] +``` + +**Chart Sources** + +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) + +**Section Sources** + +- [README.md](file://README.md) +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) + +## Core Components + +- Python Packaging and Distribution: Built using Hatchling, including a backend component template manifest and packaging targets +- Node Workspace: Unified scripts and dependency management, supporting parallel development across multiple sub-packages +- Documentation Site: `docs/app.py` based on Gradio CC, providing visual documentation for components and layout templates +- Frontend Build: Vite + React SWC plugin, combined with custom plugins and Svelte preprocessing + +**Section Sources** + +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [docs/app.py](file://docs/app.py) +- [frontend/package.json](file://frontend/package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) + +## Architecture Overview + +The diagram below shows the key path from development to runtime: local development starts `docs/app.py` via Gradio CC; the build phase is completed jointly by frontend Vite and backend packaging; at runtime, the Python backend and frontend static assets collaborate to serve the application. + +```mermaid +graph TB +Dev["Developer"] --> CC["Gradio CC Development Server
docs/app.py"] +CC --> FE["Frontend Build
Vite + Plugins"] +FE --> Dist["Static Asset Artifacts"] +CC --> Py["Python Backend Components
modelscope_studio"] +Py --> Serve["Service Startup and Page Rendering"] +Dist --> Serve +``` + +**Chart Sources** + +- [docs/app.py](file://docs/app.py) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/package.json](file://frontend/package.json) +- [pyproject.toml](file://pyproject.toml) + +## Detailed Component Analysis + +### Environment Variables and Runtime Parameters + +- The documentation site's default concurrency and thread count are set at the entry point and can be adjusted to fit the throughput and resource limits of different environments +- Development mode is triggered via environment variables to enable Gradio Watch Module for hot reloading and debugging + +Recommended environment variables and purposes (examples, not fixed values): + +- `GRADIO_WATCH_MODULE_NAME`: Used to enable development listening +- `PYTHONPATH` or workspace path: Ensures Python can import backend packages +- `NODE_ENV`: Controls frontend build mode (development/production) +- `PORT`/`APP_HOST`: Service listening address and port (if customization is needed) + +**Section Sources** + +- [docs/app.py](file://docs/app.py) +- [package.json](file://package.json) + +### Dependency Management Strategy + +- Python Dependencies + - Core dependency: Gradio version range constraints + - Packaging and distribution: Hatchling + hatch-requirements-txt + - Template manifest: The build phase includes a large number of frontend template directories to ensure complete artifacts +- Node.js Dependencies + - Workspace: pnpm workspace + build-only dependency declarations + - Scripts: Unified commands for building, developing, formatting, checking, etc. + - Frontend dependencies: React, Svelte, Ant Design, Monaco Editor, etc. +- Workspace Configuration + - `pnpm-workspace.yaml` defines `packages` and `onlyBuiltDependencies`, reducing unnecessary build overhead + +**Section Sources** + +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [frontend/package.json](file://frontend/package.json) + +### Containerized Deployment (Docker and Kubernetes) + +The following are general practice steps; specific images and orchestration need to be customized according to the actual environment: + +- Docker Build Process + - Base image: Select a base image containing Python and Node + - Install dependencies: Install system dependencies first, then Python and Node dependencies + - Build backend: Install the backend package with pip or in editable mode + - Build frontend: Execute the frontend build script to generate static assets + - Run: Start the Python service and serve static assets +- Kubernetes Deployment + - Use Deployments to manage Pod replicas + - Use Services to expose the service + - Use ConfigMap/Secret to manage environment variables and sensitive information + - Use PersistentVolume/PVC to store logs and temporary files (if needed) + - Health checks: Configure liveness/readiness probes + - Resource limits: Set CPU/memory requests and limits based on concurrency and thread configuration + +[This section provides general practice guidance and does not analyze specific files, so there are no "Section Sources"] + +### Performance Monitoring and Log Configuration + +- Performance Monitoring + - At the Python level: Record request latency, queue length, concurrency limits, and other metrics + - At the frontend level: Monitor first contentful paint time, resource load time, error rate + - At the container level: Collect CPU/memory/network metrics, combined with logs for correlation analysis +- Log Configuration + - Python: Use the standard logging module, output to stdout/stderr based on environment, combined with container log collection + - Frontend: Avoid outputting excessive debug logs in production; use conditional logging when necessary + - Documentation site: Note the impact of concurrency and thread configuration on resource usage + +[This section provides general practice guidance and does not analyze specific files, so there are no "Section Sources"] + +### Environment Migration and Upgrade + +- Python Upgrade + - Update Python version requirements and dependency version ranges to ensure compatibility + - Repackage and verify build artifact completeness +- Node Upgrade + - Update Node version and dependencies, run lint and type checks + - Rebuild frontend and verify static asset availability +- Documentation Site Upgrade + - Update Gradio CC version and related dependencies + - Verify rendering consistency of each component and layout template +- Migration Strategy + - Small steps: Gradually replace old components and templates + - Rollback plan: Keep the previous version's image and configuration to ensure fast rollback + - Data and configuration: Ensure backward compatibility of environment variables and configuration files + +[This section provides general practice guidance and does not analyze specific files, so there are no "Section Sources"] + +### Deployment Differences and Considerations Across Platforms + +- Local Development + - Use Gradio CC's development server with hot reloading enabled + - Pay attention to cross-platform path and permission issues +- Testing Environment + - Independent services and storage isolated from production + - Strictly control concurrency and thread count to simulate real load +- Production Environment + - Use stable versions and long-term support base images + - Configure health checks and auto-scaling + - Strict logging and monitoring strategies + +[This section provides general practice guidance and does not analyze specific files, so there are no "Section Sources"] + +## Dependency Analysis + +- Python Side + - Dependencies: Gradio version range constraints + - Packaging: Hatchling build, `artifacts` list contains a large number of frontend template directories +- Node Side + - Workspace: `packages` and `onlyBuiltDependencies` + - Scripts: Unified build, development, formatting, and check commands + - Frontend dependencies: React, Svelte, Ant Design, Monaco Editor, etc. + +```mermaid +graph LR +P["pyproject.toml
Python Dependencies and Packaging"] --> B["Backend Components
modelscope_studio"] +N["package.json
Node Scripts and Dependencies"] --> F["Frontend Build
Vite + Plugins"] +W["pnpm-workspace.yaml
Workspace and Build-only Dependencies"] --> N +F --> R["Static Asset Artifacts"] +B --> R +``` + +**Chart Sources** + +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) + +**Section Sources** + +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [frontend/package.json](file://frontend/package.json) + +## Performance Considerations + +- Concurrency and Threads + - The documentation site entry point sets default concurrency and maximum thread count; these should be tuned based on hardware and business load +- Build Optimization + - Use pnpm and `onlyBuiltDependencies` to reduce unnecessary dependency builds + - Set the frontend build target to `modules` for improved compatibility and loading efficiency +- Resources and Caching + - Place static assets on CDN or reverse proxy caching + - Control template and asset size to avoid redundant files in artifacts + +**Section Sources** + +- [docs/app.py](file://docs/app.py) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) + +## Troubleshooting Guide + +- Documentation Site Cannot Start or Page is Blank + - Check whether `GRADIO_WATCH_MODULE_NAME` is correctly set to enable development listening + - Confirm the backend package is correctly installed and can be imported +- Frontend Build Failure + - Check whether Node version and dependencies meet requirements + - Clear `node_modules` and build cache, then retry +- Link and Resource 404 + - Confirm static asset paths are consistent with service routes + - Check link transformation logic and resource cache path mapping +- Development Context Missing Warning + - Ensure the `Application` component is used at the top level to avoid empty runtime context + +```mermaid +flowchart TD +Start(["Start Troubleshooting"]) --> CheckEnv["Check environment variables and dependency versions"] +CheckEnv --> BuildFE["Execute frontend build and view errors"] +BuildFE --> FixFE["Fix frontend dependencies or build config"] +CheckEnv --> RunDocs["Start documentation site and observe behavior"] +RunDocs --> FixDocs["Fix runtime parameters and concurrency settings"] +FixFE --> Verify["Verify static asset availability"] +FixDocs --> Verify +Verify --> End(["End"]) +``` + +**Chart Sources** + +- [docs/app.py](file://docs/app.py) +- [package.json](file://package.json) +- [backend/modelscope_studio/utils/dev/process_links.py](file://backend/modelscope_studio/utils/dev/process_links.py) +- [backend/modelscope_studio/utils/dev/app_context.py](file://backend/modelscope_studio/utils/dev/app_context.py) + +**Section Sources** + +- [docs/app.py](file://docs/app.py) +- [backend/modelscope_studio/utils/dev/process_links.py](file://backend/modelscope_studio/utils/dev/process_links.py) +- [backend/modelscope_studio/utils/dev/app_context.py](file://backend/modelscope_studio/utils/dev/app_context.py) + +## Conclusion + +With clear environment variables and runtime parameters, standardized dependency management and workspace configuration, scalable containerization and monitoring strategies, and rigorous migration and upgrade processes, ModelScope Studio can run stably in different environments. It is recommended to prioritize controlled versions and a comprehensive observability system in production environments, and to continuously optimize build and runtime performance. + +## Appendix + +- Quick Start and Development + - Install backend and frontend dependencies and execute the build + - Use Gradio CC to start the documentation site for development and debugging +- Reference Commands + - Backend installation and build: See root-level README installation and development instructions + - Frontend installation and build: See scripts in `package.json` and dependencies in `frontend/package.json` + +**Section Sources** + +- [README.md](file://README.md) +- [package.json](file://package.json) +- [frontend/package.json](file://frontend/package.json) diff --git a/.wiki/en/Deployment Guide/Release Process.md b/.wiki/en/Deployment Guide/Release Process.md new file mode 100644 index 00000000..9aae0662 --- /dev/null +++ b/.wiki/en/Deployment Guide/Release Process.md @@ -0,0 +1,441 @@ +# Release Process + + +**Files Referenced in This Document** +- [publish.yaml](file://.github/workflows/publish.yaml) +- [lint.yaml](file://.github/workflows/lint.yaml) +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) +- [create-tag-n-release.mts](file://scripts/create-tag-n-release.mts) +- [.changeset/config.json](file://.changeset/config.json) +- [.changeset/pre.json](file://.changeset/pre.json) +- [version.py](file://backend/modelscope_studio/version.py) +- [CHANGELOG.md](file://CHANGELOG.md) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [index.ts](file://config/changelog/src/index.ts) +- [package.json](file://config/changelog/package.json) +- [frontend/package.json](file://frontend/package.json) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is intended for maintainers and senior developers who need to manage the release of the ModelScope Studio project. It systematically explains the complete process from local development to official PyPI release (including pre-releases and hotfixes), covering version management, changelog generation, automated pipelines, quality assurance, and rollback strategies. The content is based on existing release scripts, GitHub Actions workflows, and changeset configurations within the repository, ensuring it is actionable, traceable, and reproducible. + +## Project Structure + +ModelScope Studio uses a multi-package workspace (pnpm workspace) organization, with the root directory containing Python package metadata and frontend component source code. Key locations related to releases: + +- Root-level package metadata and build configuration: `pyproject.toml` +- Release scripts and workflows: `scripts/` and `.github/workflows/` +- Changeset and changelog generator: `.changeset/` and `config/changelog/` +- Version number sources: `backend/modelscope_studio/version.py` and each package's `package.json` +- Workspace definition: `pnpm-workspace.yaml` + +```mermaid +graph TB +A["Root Workspace
pnpm-workspace.yaml"] --> B["Python Package
pyproject.toml"] +A --> C["Frontend Package
frontend/package.json"] +A --> D["Changelog Generator
config/changelog/"] +A --> E["Release Scripts
scripts/"] +A --> F["GitHub Actions
.github/workflows/"] +B --> G["Version Source
backend/modelscope_studio/version.py"] +D --> H["Changeset Config
.changeset/config.json"] +D --> I[".changeset/pre.json"] +``` + +Chart Sources + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) + +Section Sources + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) + +## Core Components + +- Version and Metadata + - Python package version and metadata are provided by `pyproject.toml`; the Python module version is also maintained synchronously in `backend/modelscope_studio/version.py`. + - Frontend package and sub-package versions are declared in their respective `package.json` files. +- Changesets and Changelogs + - Uses Changesets to manage cross-package versions and change summaries, classifying changes and writing them to each package's `CHANGELOG.md` via a custom changelog generator. +- Automated Release Pipeline + - GitHub Actions triggers when a "version update" commit is detected on the main or next branch, executes build and release, and upon success, creates a tag and GitHub Release. +- Release Scripts + - `scripts/publish-to-pypi.mts` checks whether the version already exists, builds artifacts, and uploads to PyPI. + - `scripts/create-tag-n-release.mts` generates merged changelogs, creates a tag, and creates a Release. + +Section Sources + +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +## Architecture Overview + +The diagram below shows the overall flow from code commit to PyPI publishing and GitHub Release, including version checking, building, uploading, tagging, and releasing. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Repo as "Repository (main/next)" +participant GH as "GitHub Actions" +participant Script as "Release Script
publish-to-pypi.mts" +participant PyPI as "PyPI" +participant Tag as "Tag and Release
create-tag-n-release.mts" +Dev->>Repo : Push commit with "version update" +Repo-->>GH : Trigger publish workflow +GH->>Script : Execute build and release +Script->>PyPI : Check version and upload +PyPI-->>Script : Return publish result +Script-->>GH : Output published marker +GH->>Tag : If published, create tag and Release +Tag-->>Repo : Push tag and release notes +``` + +Chart Sources + +- [publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +Section Sources + +- [publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +## Detailed Component Analysis + +### Component 1: Version and Metadata Management + +- Python Package Version and Metadata + - `pyproject.toml` defines the package name, version, license, dependencies, and build targets, with clearly defined wheel and sdist packaging scope. + - `backend/modelscope_studio/version.py` serves as the Python module version entry point and must stay consistent with the `pyproject.toml` version. +- Frontend and Sub-package Versions + - Each package's `package.json` (such as `frontend/package.json`) declares an independent version, facilitating coordinated multi-package releases. +- Workspace and Multi-package + - `pnpm-workspace.yaml` explicitly includes root, `config/*`, `frontend`, and its sub-packages, ensuring release scripts can correctly resolve package metadata. + +```mermaid +flowchart TD +Start(["Start"]) --> ReadMeta["Read package metadata
pyproject.toml / package.json"] +ReadMeta --> CompareVer{"Version consistency check"} +CompareVer --> |Inconsistent| FixVer["Synchronize versions"] +CompareVer --> |Consistent| Next["Enter changeset flow"] +FixVer --> Next +Next --> End(["End"]) +``` + +Chart Sources + +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) + +Section Sources + +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) + +### Component 2: Changesets and Changelog Generation + +- Changesets Configuration + - `.changeset/config.json` specifies using a custom changelog generator and repository information, disables commit recording, and sets the base branch to `main`. + - `.changeset/pre.json` defines the pre-release mode and initial version mapping, supporting pre-releases with the `beta` tag. +- Custom Changelog Generator + - `index.ts` implements `getReleaseLine` and `getDependencyReleaseLine`, classifying changes by `feat`/`fix`/`chore`, extracting PR/Commit/User information, and writing to each package's `CHANGELOG.md`. +- Generation Flow + - The `version` script in `package.json` calls `changeset version` and fixes changelogs, then builds the changelog package. + +```mermaid +flowchart TD +CS["Changeset Summary"] --> Parse["Parse summary
PR/Commit/User/Type"] +Parse --> Classify{"Classify feat/fix/chore"} +Classify --> Write["Write to each package's CHANGELOG.md"] +Write --> Done["Done"] +``` + +Chart Sources + +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [package.json:1-55](file://package.json#L1-L55) +- [config/changelog/package.json:1-32](file://config/changelog/package.json#L1-L32) + +Section Sources + +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [package.json:1-55](file://package.json#L1-L55) +- [config/changelog/package.json:1-32](file://config/changelog/package.json#L1-L32) + +### Component 3: PyPI Release Script + +- Functional Responsibilities + - `publish-to-pypi.mts` checks whether the same version already exists on PyPI before releasing, to avoid duplicate uploads; then executes installation and build, and finally uploads via `twine`. +- Key Logic + - Uses `@manypkg/get-packages` to obtain workspace package metadata and read the root package version. + - Queries the PyPI JSON API to check whether the version exists; if it does, skips. + - Checks the existence of the `dist` directory after building before uploading. + - Sets the GitHub Actions output variable `published=true` for subsequent steps to use. + +```mermaid +flowchart TD +S(["Start"]) --> Check["Query PyPI for existing version"] +Check --> Exists{"Exists?"} +Exists --> |Yes| Skip["Skip publish and output marker"] +Exists --> |No| Build["Install and build"] +Build --> Dist{"dist exists?"} +Dist --> |No| Fail["Throw build failure error"] +Dist --> |Yes| Upload["twine upload"] +Upload --> SetOut["Set published=true"] +Skip --> End(["End"]) +SetOut --> End +Fail --> End +``` + +Chart Sources + +- [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) + +Section Sources + +- [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) + +### Component 4: Tag and Release Creation + +- Functional Responsibilities + - `create-tag-n-release.mts` aggregates change descriptions for the current version from the root and sub-package `CHANGELOG.md` files, creates a Git tag and pushes it, then calls the GitHub API to create a Release. +- Key Logic + - Parses `CHANGELOG.md`, extracts the entry for the corresponding version number, and concatenates it into the Release Body. + - Uses the GitHub Token to call `createRelease`; decides whether to mark as pre-release based on whether the version number contains a hyphen. + - Configures Git username and email to ensure tags are pushed to the remote. + +```mermaid +flowchart TD +R(["Start"]) --> ReadCL["Read root and sub-package CHANGELOG.md"] +ReadCL --> Merge["Aggregate into Release Body"] +Merge --> Tag["Create v
package.json, pyproject.toml"] --> Frontend["Frontend Workspace
frontend/*"] +Root --> Config["Config Packages
config/changelog"] +Root --> Scripts["Release Scripts
scripts/*"] +Frontend --> Antd["antd component package"] +Frontend --> Antdx["antdx component package"] +Frontend --> Base["base component package"] +Frontend --> Pro["pro component package"] +Root --> Backend["Backend Python Package
backend/modelscope_studio"] +``` + +**Diagram Sources** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +**Section Sources** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## Core Components + +- Frontend Vite build plugin: Handles React/Svelte preprocessing, global variable injection, and externalization strategy +- Python package build system: Based on Hatch, defining artifacts, wheel/sdist packaging scope, and optional dependencies +- Changesets and changelog: Changesets-driven version and log generation, supporting multi-package unified management +- Automated release pipeline: GitHub Actions triggers builds, PyPI releases, and GitHub Release creation + +**Section Sources** + +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [config/changelog/src/index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) + +## Architecture Overview + +The diagram below shows the overall process from local development to automated release: + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Root as "Root Package Scripts
package.json" +participant FE as "Frontend Build
Vite Plugin" +participant PY as "Python Build
Hatch" +participant TW as "Twine Release" +participant GH as "GitHub Actions" +participant Repo as "PyPI Repository" +Dev->>Root : Run build/version commands +Root->>FE : pnpm run build +FE-->>Root : Output dist/ frontend assets +Root->>PY : pnpm run build (backend) +PY-->>Root : Output wheel/sdist +Root->>TW : pnpm run ci:publish +TW->>Repo : Upload wheel/sdist +GH->>Root : Trigger release pipeline +Root->>GH : Create tags and Release +``` + +**Diagram Sources** + +- [package.json:8-25](file://package.json#L8-L25) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:22-55](file://scripts/publish-to-pypi.mts#L22-L55) + +## Detailed Component Analysis + +### Frontend Build and Bundling + +- Build entry and plugin chain + - Uses Vite plugin combination: React SWC and custom ModelScopeStudioVitePlugin + - Defines global variable mappings, externalizing common dependencies to host environment (e.g., `window.ms_globals.React`) + - Supports excluding certain externalized items on-demand, for inlining in specific scenarios +- Aliases and preprocessing + - Points to `utils/globals` directory via aliases to simplify import paths + - Disables Svelte preprocessing to avoid conflicts with existing solutions +- Production environment optimization + - Sets `NODE_ENV` to `production` during the build stage + - Performs AST transformation on exported modules, rewriting imports/exports to global object access to reduce bundle size + +```mermaid +flowchart TD +Start(["Start"]) --> DefineCfg["Load defineConfig options"] +DefineCfg --> UsePlugins["Enable React + ModelScopeStudioVitePlugin"] +UsePlugins --> ResolveAlias["@utils/@globals alias resolution"] +ResolveAlias --> Externalize{"Externalization enabled?"} +Externalize --> |Yes| RollupExt["Rollup externalize global mappings"] +Externalize --> |No| SkipExt["Skip externalization"] +RollupExt --> Transform["AST transformation: map imports/exports to globals"] +SkipExt --> Transform +Transform --> BuildOut["Output production build artifacts"] +BuildOut --> End(["End"]) +``` + +**Diagram Sources** + +- [frontend/defineConfig.js:8-18](file://frontend/defineConfig.js#L8-L18) +- [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) +- [frontend/plugin.js:77-165](file://frontend/plugin.js#L77-L165) + +**Section Sources** + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) + +### Python Package Build and Distribution + +- Build backend Python package + - Uses Hatchling as build backend, reading metadata and dependencies from `pyproject.toml` + - Specifies `artifacts` list to ensure templates and static assets are included in the wheel + - Target directories and exclusion rules for wheel/sdist are clearly defined to avoid redundant files in release packages +- Dependencies and compatibility + - Manages dependencies and README rendering via `hatch-requirements-txt` and `hatch-fancy-pypi-readme` + - Python version requirements and classifier declarations are clear, facilitating PyPI display and installer recognition +- Version consistency + - Root package and backend versions are kept in sync to avoid mismatches during release + +```mermaid +flowchart TD +A["Read pyproject.toml"] --> B["Hatchling Build"] +B --> C{"Target type?"} +C --> |wheel| D["Package as wheel
including artifacts"] +C --> |sdist| E["Package as sdist
including backend/modelscope_studio"] +D --> F["Verify artifact integrity"] +E --> F +F --> G["Upload to PyPI via Twine"] +``` + +**Diagram Sources** + +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) + +**Section Sources** + +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) + +### Version Management and Changelog + +- Changesets configuration + - Uses custom changelog generator, supporting PR/Commit/user link parsing + - Unified version baseline and pre-release tags (beta), facilitating preview and rollback +- Changelog generation + - Compiles configuration package via tsup, outputting both esm/cjs formats + - Changelog generator aggregates CHANGELOGs from each package and writes to a temporary state file, ultimately driven by the root package to generate unified release content +- Pre-release mode + - `pre.json` specifies pre-release tags and initial version, working with Changesets workflow for canary releases + +```mermaid +flowchart TD +CS["Changesets commit"] --> Gen["Run version script"] +Gen --> Changelog["Generate/update changelog"] +Changelog --> Pre["Pre-release tag (beta)"] +Pre --> Release["Trigger release pipeline"] +``` + +**Diagram Sources** + +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [config/changelog/src/index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [config/changelog/tsup.config.ts:1-21](file://config/changelog/tsup.config.ts#L1-L21) + +**Section Sources** + +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [config/changelog/src/index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [config/changelog/tsup.config.ts:1-21](file://config/changelog/tsup.config.ts#L1-L21) + +### Automated Release Pipeline + +- Trigger conditions + - Push to `main`/`next` branch with commit message "chore: update versions" +- Step breakdown + - Install Python and Node dependencies, prepare build environment + - Execute build: pip editable mode install, pnpm run build + - Check if `dist` exists to prevent continuing release after build failure + - Use Twine to upload all artifacts in `dist` to PyPI (with skip-existing) + - If release succeeds, call script to create Git tag and push, then create Release on GitHub with content from changelog + +```mermaid +sequenceDiagram +participant WF as "GitHub Actions" +participant Build as "Build Step" +participant Check as "Version Check" +participant Upload as "Twine Upload" +participant Tag as "Create Tag and Release" +WF->>Build : Install dependencies and build +Build-->>WF : Output dist/ +WF->>Check : Check if version already exists on PyPI +alt Already exists +Check-->>WF : Skip release +else Does not exist +WF->>Upload : Upload dist/* to PyPI +Upload-->>WF : Release complete +WF->>Tag : Create v
Set value/props/SLOTS/EVENTS/FrontendDir +Py->>Meta : Register event callbacks
Update _internal flags +Meta-->>FE : Frontend listens and binds events +FE-->>Py : User interaction triggers event +Py->>Py : preprocess(payload)
Normalize input +Py->>Py : postprocess(value)
Normalize output +Py-->>FE : Render result/state change +``` + +Diagram Sources + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) +- [backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) + +## Detailed Component Analysis + +### Component Class Inheritance Hierarchy and Responsibilities + +- `ModelScopeComponent`: General-purpose component, suitable for data-type components (e.g., text, input, select), supporting `value` and standard UI properties. +- `ModelScopeLayoutComponent`: Layout-type components (e.g., button, card, grid), emphasizing layout updates and context exit. +- `ModelScopeDataLayoutComponent`: Data-driven layout components (e.g., form, table), with `BlockContext` capability, suitable for complex interactions and state persistence. + +```mermaid +classDiagram +class ModelScopeComponent { ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class ModelScopeLayoutComponent { ++__exit__() +} +class ModelScopeDataLayoutComponent { ++__exit__() +} +ModelScopeLayoutComponent --|> ModelScopeComponent +ModelScopeDataLayoutComponent --|> ModelScopeComponent +ModelScopeDataLayoutComponent --|> BlockContext +``` + +Diagram Sources + +- [backend/modelscope_studio/utils/dev/component.py:54-169](file://backend/modelscope_studio/utils/dev/component.py#L54-L169) + +Section Sources + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +### Event Handling and Callback Mechanism + +- Event Definition: Declare events supported by the component via the `EVENTS` list, such as click, field change, submit completion, etc. +- Callback Logic: Event callbacks update the binding flags in `_internal`, notifying the frontend to bind events. +- Typical Usage: Click event of `AntdButton`; `fields_change`/`finish`/`values_change` of `AntdForm`, etc. + +```mermaid +sequenceDiagram +participant Btn as "AntdButton" +participant Form as "AntdForm" +participant FE as "Frontend" +Btn->>Btn : Define EVENTS["click"] +Btn->>Btn : Callback updates _internal.bind_click_event +FE-->>Btn : Listen for click event and execute callback +Form->>Form : Define EVENTS["fields_change","finish","finish_failed","values_change"] +Form->>Form : Callback updates _internal binding flags +FE-->>Form : Listen for form events and sync state +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) +- [backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) + +Section Sources + +- [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) +- [backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) + +### Property Definition and Validation Mechanism + +- Property Declaration: Components receive `value`, `additional_props`, and numerous UI-related parameters (e.g., size, shape, color, style) in `__init__`, saved as instance properties. +- Data Model: Some components provide custom data models (e.g., `AntdFormData`) to normalize complex data structures. +- Validation and Conversion: `preprocess`/`postprocess` explicitly define input/output shapes, preventing data inconsistencies between frontend and backend. + +```mermaid +flowchart TD +Start(["Enter Component"]) --> Init["Receive parameters and assign to instance properties"] +Init --> DataModel{"Data model defined?"} +DataModel --> |Yes| UseDM["Use data model to normalize input"] +DataModel --> |No| SkipDM["Skip data model"] +UseDM --> Pre["preprocess(payload) normalize input"] +SkipDM --> Pre +Pre --> Process["Business logic/state update"] +Process --> Post["postprocess(value) normalize output"] +Post --> End(["Return to frontend"]) +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antd/form/**init**.py:13-15](file://backend/modelscope_studio/components/antd/form/__init__.py#L13-L15) +- [backend/modelscope_studio/components/antd/form/**init**.py:120-126](file://backend/modelscope_studio/components/antd/form/__init__.py#L120-L126) + +Section Sources + +- [backend/modelscope_studio/components/antd/button/**init**.py:51-137](file://backend/modelscope_studio/components/antd/button/__init__.py#L51-L137) +- [backend/modelscope_studio/components/antd/form/**init**.py:13-15](file://backend/modelscope_studio/components/antd/form/__init__.py#L13-L15) +- [backend/modelscope_studio/components/antd/form/**init**.py:120-126](file://backend/modelscope_studio/components/antd/form/__init__.py#L120-L126) + +### Lifecycle Hooks and Render Control + +- Initialization: Sets base properties such as `visible`, `elem_id`, `elem_classes`, `elem_style`, `render`, `as_item`, and `_internal`. +- Context Exit: Layout-type components update `layout=True` in `__exit__` to ensure the frontend recalculates the layout. +- Rendering Strategy: `skip_api` controls whether to expose an API; `render` controls whether to render; `preserved_by_key` controls the data retention strategy (effective in data layout components). + +Section Sources + +- [backend/modelscope_studio/utils/dev/component.py:24-26](file://backend/modelscope_studio/utils/dev/component.py#L24-L26) +- [backend/modelscope_studio/utils/dev/component.py:125-127](file://backend/modelscope_studio/utils/dev/component.py#L125-L127) +- [backend/modelscope_studio/utils/dev/component.py:161-168](file://backend/modelscope_studio/utils/dev/component.py#L161-L168) + +### Integration with Frontend Svelte Components + +- Directory Mapping: Component classes point to the frontend Svelte component directory via `FRONTEND_DIR`, ensuring one-to-one correspondence between frontend and backend. +- Slots and Events: `SLOTS` defines slot names; `EVENTS` defines events; the frontend renders and binds accordingly. +- Data Conversion: `preprocess`/`postprocess` ensures consistent data shapes between Python and JS layers. + +Section Sources + +- [backend/modelscope_studio/components/antd/button/**init**.py:139-156](file://backend/modelscope_studio/components/antd/button/__init__.py#L139-L156) +- [backend/modelscope_studio/components/antd/form/**init**.py:114-132](file://backend/modelscope_studio/components/antd/form/__init__.py#L114-L132) +- [backend/modelscope_studio/components/base/text/**init**.py:39-56](file://backend/modelscope_studio/components/base/text/__init__.py#L39-L56) + +### Steps and Standards for Creating a New Component + +- Choose a Family and Directory + - Select the appropriate family from `antd`, `antdx`, `base`, or `pro`, and create a new component subdirectory under the corresponding directory. +- Write the Component Class + - Inherit from the appropriate base class (general / layout / data layout). + - Define `EVENTS`, `SLOTS`, and `FRONTEND_DIR`. + - Implement `preprocess`/`postprocess`/`example_payload`/`example_value`. + - Receive and store all external parameters in `__init__`. +- Register the Component + - Import and export the component class in the family-level `components.py`. + - If adding a new family, add the export to `components/__init__.py`. +- Reference Examples + - Text component (`base/text`): Minimal component example, demonstrating minimal properties and methods. + - Button component (`antd/button`): Layout-type component with events and slots. + - Form component (`antd/form`): Data layout component with a data model and multiple events. + +Section Sources + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) +- [backend/modelscope_studio/components/base/text/**init**.py:8-57](file://backend/modelscope_studio/components/base/text/__init__.py#L8-L57) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) + +## Dependency Analysis + +- Component Family Exports + - `antd/components.py` imports and exports numerous component classes, forming a complete ecosystem. + - `antdx/components.py` exports the extended component family. + - `pro/components.py` exports the professional component family. + - `base/__init__.py` exports the base component family. + - `components/__init__.py` aggregates the above family exports as a unified entry point. +- Component Class Dependencies + - All components depend on base classes and utility functions (e.g., `resolve_frontend_dir`) under `utils/dev`. +- Events and Context + - Events are defined via `gradio.events.EventListener`; callbacks update `_internal` flags, which the frontend uses to bind. + +```mermaid +graph LR +subgraph "Component Families" +ANTDA["antd/components.py"] +ANTDXA["antdx/components.py"] +PROA["pro/components.py"] +BASEA["base/__init__.py"] +end +subgraph "Aggregation" +ROOTI["components/__init__.py"] +end +ANTDA --> ROOTI +ANTDXA --> ROOTI +PROA --> ROOTI +BASEA --> ROOTI +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) + +Section Sources + +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) + +## Performance Considerations + +- Minimize Event Binding: Only enable event binding when necessary to avoid frequent `_internal` updates causing frontend re-renders. +- Lightweight Data Conversion: `preprocess`/`postprocess` should remain simple and efficient, avoiding deep copying and complex calculations. +- Render Control: Use `render` and `skip_api` appropriately to reduce unnecessary API exposure and rendering overhead. +- Layout Component Optimization: Layout components update `layout=True` in `__exit__`; avoid triggering this repeatedly in high-frequency events. + +## Troubleshooting Guide + +- Event Not Taking Effect + - Check that `EVENTS` is correctly declared and that callbacks update the corresponding `_internal` flags. + - Confirm that the frontend has bound events based on `_internal` flags. +- Frontend Cannot Find Component + - Check that `FRONTEND_DIR` points to the correct Svelte directory. + - Confirm that the component class is exported in `components.py` and aggregated in `components/__init__.py`. +- Data Inconsistency + - Check that `preprocess`/`postprocess` aligns with the data shapes on both frontend and backend. + - For complex data, confirm that a custom data model is used and correctly parsed/serialized. +- Rendering Anomaly + - Check that `skip_api` and `render` settings match expectations. + - For layout components, pay attention to the timing of layout updates in `__exit__`. + +Section Sources + +- [backend/modelscope_studio/utils/dev/component.py:15-26](file://backend/modelscope_studio/utils/dev/component.py#L15-L26) +- [backend/modelscope_studio/utils/dev/component.py:125-127](file://backend/modelscope_studio/utils/dev/component.py#L125-L127) +- [backend/modelscope_studio/components/antd/button/**init**.py:139-156](file://backend/modelscope_studio/components/antd/button/__init__.py#L139-L156) +- [backend/modelscope_studio/components/antd/form/**init**.py:114-132](file://backend/modelscope_studio/components/antd/form/__init__.py#L114-L132) + +## Conclusion + +Through a unified base class hierarchy, clear event and slot conventions, strict frontend-backend directory mapping, and data conversion standards, ModelScope Studio's backend component development achieves a highly cohesive, loosely coupled, and easily extensible architecture. By following the structural conventions and implementation steps in this document, you can quickly create high-quality components that integrate seamlessly with the frontend Svelte ecosystem. + +## Appendix + +- Quick Reference + - Component Base Classes: `ModelScopeComponent` / `ModelScopeLayoutComponent` / `ModelScopeDataLayoutComponent` + - Key Properties: `EVENTS`, `SLOTS`, `FRONTEND_DIR`, `skip_api`, `preprocess`/`postprocess`, `example_payload`/`example_value` + - Registration Path: Family-level `components.py` → `components/__init__.py` + - Example Components: `antd/button`, `antd/form`, `base/text` diff --git a/.wiki/en/Development Guide/Component Development/Component Development Best Practices.md b/.wiki/en/Development Guide/Component Development/Component Development Best Practices.md new file mode 100644 index 00000000..37bfbb9f --- /dev/null +++ b/.wiki/en/Development Guide/Component Development/Component Development Best Practices.md @@ -0,0 +1,407 @@ +# Component Development Best Practices + + +**Files Referenced in This Document** +- [frontend/package.json](file://frontend/package.json) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/base/text/text.tsx](file://frontend/base/text/text.tsx) +- [frontend/antd/layout/layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) +- [frontend/antd/grid/context.ts](file://frontend/antd/grid/context.ts) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/form/context.ts](file://frontend/antd/form/context.ts) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/utils/hooks/useMemoizedFn.ts](file://frontend/utils/hooks/useMemoizedFn.ts) +- [frontend/utils/createFunction.ts](file://frontend/utils/createFunction.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/antd/table/table.tsx](file://frontend/antd/table/table.tsx) +- [frontend/antd/modal/modal.tsx](file://frontend/antd/modal/modal.tsx) +- [eslint.config.mjs](file://eslint.config.mjs) +- [prettier.config.mjs](file://prettier.config.mjs) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This guide is intended for engineers developing components within the ModelScope Studio frontend ecosystem. It systematically summarizes design principles and coding conventions, covering naming conventions, file organization, code style, performance optimization, reusability design, error handling and edge cases, internationalization and accessibility, and cross-browser compatibility — with refactoring recommendations and best practices drawn from real component implementations in the repository. + +## Project Structure + +This project uses a multi-package workspace (pnpm workspace) structure, with the frontend centered on the Svelte 5 + React ecosystem, bridging the Ant Design component library through a preprocessing layer to form a unified component system. Components are layered by domain: modules such as `antd`, `antdx`, `base`, and `pro`, where each component typically consists of a Svelte entry file and a corresponding React wrapper, with utility functions and context for high cohesion and low coupling. + +```mermaid +graph TB +subgraph "Frontend Package" +Pkg["package.json
Dependency Declaration"] +end +subgraph "Component Layer" +AntD["antd/* Components"] +AntDX["antdx/* Components"] +Base["base/* Base Components"] +Pro["pro/* Pro Components"] +end +subgraph "Utilities and Context" +Utils["utils/* Utility Functions"] +Ctx["createItemsContext.tsx
Generic Items Context"] +end +Pkg --> AntD +Pkg --> AntDX +Pkg --> Base +Pkg --> Pro +AntD --> Utils +AntDX --> Utils +Base --> Utils +Pro --> Utils +Utils --> Ctx +``` + +Diagram Sources + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +Section Sources + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## Core Components + +This section focuses on key patterns and conventions for component development, including: + +- Unified entry and wrapping: The Svelte entry handles prop forwarding, lazy loading, and slot rendering; the React wrapper handles lifecycle and state management. +- Configurable internationalization and theming: Use `ConfigProvider` to manage language, theme algorithm, and container strategy. +- Highly cohesive context: `createItemsContext` abstracts "item collections" and "sub-item handlers", supporting complex component scenarios such as dynamic columns, row selection, and expand. +- Functional capabilities: `useFunction`, `useMemoizedFn`, and `createFunction` safely convert string or functional configurations into runtime functions. + +Section Sources + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/hooks/useMemoizedFn.ts:1-11](file://frontend/utils/hooks/useMemoizedFn.ts#L1-L11) +- [frontend/utils/createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +## Architecture Overview + +The diagram below shows the critical path from entry to rendering, as well as the relationships with utility functions and context. + +```mermaid +sequenceDiagram +participant Svelte as "Svelte Entry (Index.svelte)" +participant Preprocess as "Preprocess Bridge" +participant ReactComp as "React Wrapper (.tsx)" +participant Util as "Utility Functions (useFunction/createFunction)" +participant Ctx as "Context (createItemsContext)" +Svelte->>Preprocess : "importComponent lazy load" +Preprocess-->>Svelte : "Awaited component" +Svelte->>ReactComp : "processProps forward props/slots" +ReactComp->>Util : "useFunction/createFunction safe execution" +ReactComp->>Ctx : "withItemsContextProvider/ItemHandler" +ReactComp-->>Svelte : "Render final UI" +``` + +Diagram Sources + +- [frontend/antd/button/Index.svelte:10-73](file://frontend/antd/button/Index.svelte#L10-L73) +- [frontend/antd/form/form.tsx:15-76](file://frontend/antd/form/form.tsx#L15-L76) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/createFunction.ts:10-37](file://frontend/utils/createFunction.ts#L10-L37) +- [frontend/utils/createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) + +## Detailed Component Analysis + +### Component Naming and File Organization + +- Naming Conventions + - Component directories and file names use lowerCamelCase or kebab-case, e.g., `button`, `date-picker`, `config-provider`. + - Svelte entries are uniformly named `Index.svelte`; the corresponding component source file is named `componentName.tsx` or `componentName.svelte`. +- File Organization + - Each component contains: an entry file (`Index.svelte`), component implementation (`*.tsx`), styles (`*.less`), and configuration (`package.json`, `gradio.config.js`). + - Complex components are split into sub-modules (e.g., `column`, `row-selection`, `expandable` for `table`), aggregated via context. + +Section Sources + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/table/table.tsx:1-200](file://frontend/antd/table/table.tsx#L1-L200) + +### Prop Forwarding and Lazy Loading + +- Lazy Loading: Use `importComponent` for on-demand loading, preventing initial bundle bloat. +- Prop Forwarding: `processProps` filters internal fields and retains external-facing props such as visibility, style, class names, and IDs. +- Slot Rendering: `getSlots` retrieves default slots and renders custom nodes in conjunction with `ReactSlot`. + +```mermaid +flowchart TD +Start(["Enter Component"]) --> Load["Lazy load React component"] +Load --> Props["processProps filter/merge props"] +Props --> Slots["getSlots parse slots"] +Slots --> Visible{"visible is true?"} +Visible --> |Yes| Render["Render component with props/slots"] +Visible --> |No| Hide["Do not render"] +Render --> End(["Complete"]) +Hide --> End +``` + +Diagram Sources + +- [frontend/antd/button/Index.svelte:12-56](file://frontend/antd/button/Index.svelte#L12-L56) + +Section Sources + +- [frontend/antd/button/Index.svelte:12-74](file://frontend/antd/button/Index.svelte#L12-L74) + +### Form Component: State Synchronization and Action Dispatch + +- Action Dispatch: Triggers the corresponding behavior based on `formAction` (reset/submit/validate), then resets the action flag upon completion. +- Value Synchronization: Sets form values when `value` changes; resets fields when not provided. +- Slots and Callbacks: `requiredMark` and `feedbackIcons` prefer slots; otherwise fall back to functions or static values; `onValuesChange` syncs external state. + +```mermaid +sequenceDiagram +participant UI as "Caller" +participant Form as "Form Component" +participant AntD as "Antd Form" +UI->>Form : "Pass value / formAction" +Form->>AntD : "Initialize Form instance" +alt formAction = reset +Form->>AntD : "resetFields()" +else formAction = submit +Form->>AntD : "submit()" +else formAction = validate +Form->>AntD : "validateFields()" +end +Form->>UI : "onResetFormAction()" +UI->>Form : "value change" +Form->>AntD : "setFieldsValue(value)" +``` + +Diagram Sources + +- [frontend/antd/form/form.tsx:32-53](file://frontend/antd/form/form.tsx#L32-L53) +- [frontend/antd/form/form.tsx:15-76](file://frontend/antd/form/form.tsx#L15-L76) + +Section Sources + +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) + +### Layout Base Component: Dynamic Selector + +- The Base component dynamically selects Header/Footer/Content/Layout based on the `component` parameter and uniformly injects a class prefix for style isolation. + +Section Sources + +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +### Internationalization and Theming: ConfigProvider + +- Theme Algorithm: Supports dark and compact algorithm combinations, switching based on `themeMode`. +- Language Switching: Formats the `navigator` language as an available locale code and dynamically loads `antd` and `dayjs` localization resources. +- Container Strategy: `getPopupContainer`/`getTargetContainer` supports strings or functions; functions are safely executed via `useFunction`. +- Slot Injection: Supports converting slots like `renderEmpty` to React nodes. + +```mermaid +flowchart TD +Init["Initialize ConfigProvider"] --> Locale["Parse locale code"] +Locale --> LoadRes["Async load language resources"] +LoadRes --> ApplyTheme["Compute algorithm array"] +ApplyTheme --> Render["Render subtree"] +``` + +Diagram Sources + +- [frontend/antd/config-provider/config-provider.tsx:85-105](file://frontend/antd/config-provider/config-provider.tsx#L85-L105) +- [frontend/antd/config-provider/config-provider.tsx:127-143](file://frontend/antd/config-provider/config-provider.tsx#L127-L143) + +Section Sources + +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) + +### Context and Item Collections: createItemsContext + +- Purpose: Provides a collection and passing mechanism for "item collections" in complex components (e.g., tables, form item rules). +- Key Capabilities + - `withItemsContextProvider`: Wraps the subtree to establish context. + - `ItemHandler`: Writes child items (props/slots/children) to the context, supporting memoization and deduplication. + - `useItems`: Reads the current item collection and triggers the `onChange` callback. +- Use Cases: Table columns, expandable items, row selection, form item rules, etc. + +```mermaid +classDiagram +class ItemsContextProvider { ++allowedSlots ++onChange(items) ++setItem(slotKey, index, item) +} +class ItemHandler { ++itemIndex ++itemSlotKey ++itemProps(props, items) ++itemChildren(items) ++slots +} +class useItems { ++items ++initial ++setItem(...) +} +ItemsContextProvider --> useItems : "Provides" +ItemHandler --> ItemsContextProvider : "Write item" +useItems --> ItemsContextProvider : "Read item" +``` + +Diagram Sources + +- [frontend/utils/createItemsContext.tsx:108-170](file://frontend/utils/createItemsContext.tsx#L108-L170) +- [frontend/utils/createItemsContext.tsx:190-261](file://frontend/utils/createItemsContext.tsx#L190-L261) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) + +Section Sources + +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [frontend/antd/form/context.ts:1-10](file://frontend/antd/form/context.ts#L1-L10) + +### Table Component: Columns, Expand, Row Selection, and Function Configuration + +- Columns and Expand: Aggregates column and expand configurations via context, supporting default columns and built-in placeholders (`EXPAND_COLUMN`, `SELECTION_COLUMN`). +- Function Configuration: `getPopupContainer`, `rowKey`, `rowClassName`, `sticky`, `showSorterTooltip`, `summary`/`footer`, etc. all support strings or functions, executed safely via `createFunction`/`useFunction`. +- Slots: `loading`, `pagination`, `tooltip`, `summary`, etc. support parameterized slot rendering. + +Section Sources + +- [frontend/antd/table/table.tsx:41-200](file://frontend/antd/table/table.tsx#L41-L200) + +### Modal Component: Slots and Functional Configuration + +- Slot Priority: `okText`, `cancelText`, `footer`, `title`, `closeIcon`, `okButtonProps.icon`, `cancelButtonProps.icon`, `closable.closeIcon`, `modalRender`, etc. prefer slots. +- Function Fallback: When slots are unavailable, `useFunction` converts strings or functions into executable functions. +- Container Strategy: `getContainer` supports string selectors or functions. + +Section Sources + +- [frontend/antd/modal/modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) + +### Base Text Component: Minimal Implementation + +- Receives only `value` and renders it; inserts an empty placeholder element if empty, ensuring stable DOM structure. + +Section Sources + +- [frontend/base/text/text.tsx:1-11](file://frontend/base/text/text.tsx#L1-L11) + +## Dependency Analysis + +- Dependency Sources: `package.json` centrally declares dependencies related to Ant Design, React, Svelte, internationalization, and multimedia. +- Inter-Component Coupling: Coupling is reduced through the preprocessing bridge and utility functions; complex components are decoupled via context. +- External Integration: `ConfigProvider` works with `dayjs` for language switching; `StyleProvider` controls style hash priority. + +```mermaid +graph LR +AntD["antd"] --> Comp["Component Implementation (.tsx)"] +React["react + react-dom"] --> Comp +Svelte["svelte"] --> Entry["Entry (Index.svelte)"] +Entry --> Comp +Utils["Utility Functions"] --> Comp +Ctx["createItemsContext"] --> Comp +``` + +Diagram Sources + +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [frontend/antd/button/Index.svelte:6-10](file://frontend/antd/button/Index.svelte#L6-L10) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +Section Sources + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## Performance Considerations + +- Lazy Loading and On-Demand Rendering + - Use `importComponent` for on-demand loading, avoiding initial blocking from importing too many components at once. + - Svelte conditional rendering with the `visible` field reduces mounting of invalid nodes. +- Function and Object Stability + - `useFunction`/`useMemoizedFn`/`createFunction` convert string or functional configurations into stable functions, avoiding repeated closure creation. + - `useMemo`/`useMemoizedEqualValue` cache expensive calculations and equality comparisons in context. +- Slots and Hidden Rendering + - Complex components often render actual content in a hidden state, only exposing placeholders, to reduce initial layout jitter. +- Theming and Styles + - `StyleProvider` configures hash priority to prevent repaints caused by style conflicts. +- Events and Callbacks + - Use `useMemoizedFn` to cache references for high-frequency callbacks, reducing the probability of child component re-renders. + +Section Sources + +- [frontend/antd/button/Index.svelte:59-73](file://frontend/antd/button/Index.svelte#L59-L73) +- [frontend/antd/form/form.tsx:28-30](file://frontend/antd/form/form.tsx#L28-L30) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/hooks/useMemoizedFn.ts:3-10](file://frontend/utils/hooks/useMemoizedFn.ts#L3-L10) +- [frontend/utils/createFunction.ts:10-37](file://frontend/utils/createFunction.ts#L10-L37) +- [frontend/antd/config-provider/config-provider.tsx:110-110](file://frontend/antd/config-provider/config-provider.tsx#L110-L110) + +## Troubleshooting Guide + +- Slot Not Taking Effect + - Check that the slot key is correct (e.g., `footer`, `title`, `okText`); confirm that it is wrapped with `ReactSlot`. + - For slots requiring parameters, use `renderParamsSlot` for rendering. +- Function Configuration Anomaly + - If a string function is passed, ensure the format is valid; use `createFunction`/`useFunction` for safe execution. +- Theme or Language Not Taking Effect + - Confirm the `themeMode` and `locale` settings; check that language resource loading succeeded. +- Context Items Not Updating + - Ensure `ItemHandler`'s `itemIndex` and `itemSlotKey` are correct; check that `setItem` is being called. +- Performance Issues + - Check for unnecessary prop changes; use `useMemoizedFn` for callbacks; avoid creating new functions inside `render`. + +Section Sources + +- [frontend/antd/modal/modal.tsx:40-95](file://frontend/antd/modal/modal.tsx#L40-L95) +- [frontend/antd/config-provider/config-provider.tsx:96-105](file://frontend/antd/config-provider/config-provider.tsx#L96-L105) +- [frontend/utils/createFunction.ts:10-37](file://frontend/utils/createFunction.ts#L10-L37) +- [frontend/utils/createItemsContext.tsx:234-254](file://frontend/utils/createItemsContext.tsx#L234-L254) + +## Conclusion + +Based on existing component implementations in the repository, this guide summarizes the design principles and engineering practices for component development: using the Svelte entry + React wrapper bridging pattern for a unified ecosystem; achieving high cohesion and low coupling through context and utility functions; improving performance and extensibility through lazy loading, function stabilization, and the slot mechanism. Following these best practices will enhance component quality and maintainability while ensuring consistency. + +## Appendix + +### Design Principles and Coding Standards + +- Naming and Organization + - Component directories and file names use lowerCamelCase or kebab-case; entries are uniformly `Index.svelte`; implementations are `*.tsx`. + - Complex components are split into sub-modules and aggregated via context. +- Props and Slots + - Clearly distinguish between external and internal props; forward external props via `processProps`; slots take priority over static values. +- Functions and Callbacks + - All string functions are executed safely via `createFunction`/`useFunction`; high-frequency callbacks are cached with `useMemoizedFn`. +- Internationalization and Theming + - Use `ConfigProvider` to manage language and theme; load language resources on demand; container strategy supports both strings and functions. +- Styles and Theming + - Use `StyleProvider` to control style hash priority; inject unified prefix class names for different component types. +- Error Handling and Edge Cases + - Return `undefined` and degrade gracefully for unrecognized function strings; provide reasonable default values when slots are missing. +- Accessibility and Compatibility + - Maintain semantic tags and accessible attributes; avoid relying solely on color to convey information; test on mainstream browsers and mobile devices. + +Section Sources + +- [frontend/antd/button/Index.svelte:24-52](file://frontend/antd/button/Index.svelte#L24-L52) +- [frontend/antd/config-provider/config-provider.tsx:110-149](file://frontend/antd/config-provider/config-provider.tsx#L110-L149) +- [frontend/utils/createFunction.ts:10-37](file://frontend/utils/createFunction.ts#L10-L37) +- [eslint.config.mjs:1-9](file://eslint.config.mjs#L1-L9) +- [prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26) diff --git a/.wiki/en/Development Guide/Component Development/Component Development.md b/.wiki/en/Development Guide/Component Development/Component Development.md new file mode 100644 index 00000000..6aa46510 --- /dev/null +++ b/.wiki/en/Development Guide/Component Development/Component Development.md @@ -0,0 +1,366 @@ +# Component Development + + +**Files referenced in this document** +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/pro/__init__.py](file://backend/modelscope_studio/components/pro/__init__.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [frontend/svelte-preprocess-react/index.ts](file://frontend/svelte-preprocess-react/index.ts) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts](file://frontend/svelte-preprocess-react/sveltify.svelte.ts) +- [frontend/svelte-preprocess-react/react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/patchProps.tsx](file://frontend/utils/patchProps.tsx) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/form/Index.svelte](file://frontend/antd/form/Index.svelte) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This guide is intended for engineers and product teams developing components in ModelScope Studio. It covers backend Python component implementation, frontend Svelte component development, React component bridging and slot system usage, as well as component structure conventions, property definitions, event handling, testing, and documentation best practices. By analyzing the backend component base classes and frontend bridging mechanisms in parallel, this guide helps you quickly extend existing components or create entirely new component types. + +## Project Structure + +The ModelScope Studio component system consists of three layers: + +- Backend Python component layer: Uniformly inherits from Gradio's component metaclass, providing common lifecycle, events, and slot capabilities. +- Frontend Svelte layer: Each component loads its corresponding React implementation as a Svelte wrapper, responsible for prop passing, event bridging, and slot rendering. +- React bridging layer: Bridges Ant Design and other React components to be usable as Svelte components via `sveltify`, supporting slot and style passing. + +```mermaid +graph TB +subgraph "Backend Python" +PY_BASE["ModelScopeComponent
ModelScopeLayoutComponent
ModelScopeDataLayoutComponent"] +end +subgraph "Frontend Svelte" +SV_WRAPPER["Svelte Wrapper
Index.svelte"] +SV_SLOT["Slot Rendering Utility
renderSlot.tsx"] +end +subgraph "React Bridge" +REACT_SVELTIFY["sveltify Bridge
sveltify.svelte.ts"] +REACT_SLOT["ReactSlot Bridge
react-slot.tsx"] +PATCH_PROPS["Props Patch Utility
patchProps.tsx"] +end +PY_BASE --> SV_WRAPPER +SV_WRAPPER --> REACT_SVELTIFY +SV_WRAPPER --> SV_SLOT +SV_SLOT --> REACT_SLOT +REACT_SVELTIFY --> PATCH_PROPS +``` + +**Diagram Sources** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) + +**Section Sources** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) + +## Core Components + +- Backend component base classes + - ModelScopeComponent: For data components, supports common props like `visible`, `elem_id`, `elem_classes`, `elem_style`, `value`, `key`, `inputs`, `load_fn`, etc.; exposes API by default. + - ModelScopeLayoutComponent: For layout components, supports `as_item`, `visible`, `elem_id`, `elem_classes`, `elem_style`, `render`, etc.; skips API export by default. + - ModelScopeDataLayoutComponent: Data + layout hybrid component, has BlockContext capability and layout marker to avoid duplicate rendering. +- Frontend bridging and slots + - sveltify: Wraps React components as Svelte components, supporting slots parameter declaration and slot tree construction. + - ReactSlot: Clones and mounts Svelte slot content into React subtrees, supporting prop and event passing, and MutationObserver observation. + - renderSlot: Convenient entry point for context-wrapped rendering based on whether forced cloning or parameterized rendering is needed. + - patchProps/applyPatchToProps: Compatibility conversion of internal fields like `key`, ensuring stable React rendering. + +**Section Sources** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) + +## Architecture Overview + +The diagram below shows the call chain from backend component to frontend Svelte wrapper to React component, and how the slot system reuses Svelte slot content in React subtrees. + +```mermaid +sequenceDiagram +participant PY as "Backend Component
ModelScopeComponent" +participant SV as "Svelte Wrapper
Index.svelte" +participant BR as "Bridge
sveltify.svelte.ts" +participant RX as "React Component
button.tsx" +participant RS as "Slot Bridge
ReactSlot" +PY->>SV : Initialize and inject props/values +SV->>BR : importComponent loads React implementation +BR->>RX : Create Svelte node tree and mount +RX->>RS : Render slots using slots and ReactSlot +RS-->>RX : Clone and mount slot DOM (with events) +RX-->>SV : Event callback triggers updateProps +SV-->>PY : Update backend state (e.g., value, form_action) +``` + +**Diagram Sources** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) + +## Detailed Component Analysis + +### Backend Component Base Classes and Lifecycle + +- Inheritance relationships + - ModelScopeComponent: Base data component, supports `value`, `visible`, `elem_*`, `key`, `inputs`, `load_fn`, etc. + - ModelScopeLayoutComponent: Layout component, supports `as_item`, `visible`, `elem_*`, `render`. + - ModelScopeDataLayoutComponent: Combines data and layout characteristics, marks layout on enter/exit to avoid duplicate rendering. +- Key behaviors + - Automatically records parent component child node indexes for positioning and updates. + - Supports skipping API export (`skip_api`), used for layout components. + - Works with AppContext to ensure application context exists. + +```mermaid +classDiagram +class ModelScopeComponent { ++EVENTS ++skip_api ++__init__(...) +} +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__(...) +} +class ModelScopeDataLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__(...) +} +ModelScopeLayoutComponent --|> ModelScopeComponent +ModelScopeDataLayoutComponent --|> ModelScopeComponent +``` + +**Diagram Sources** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +**Section Sources** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +### Frontend Svelte Wrapper and Prop Handling + +- Typical flow + - Asynchronously load the corresponding React component via `importComponent`. + - Extract and transform props using `getProps`/`processProps`, mapping names (e.g., `fields_change` → `fieldsChange`). + - Retrieve the slot collection via `getSlots` and pass to the React component. + - Render with visibility control, passing `children` as the default slot. +- Event bridging + - For mutable value components (e.g., Form), listen to `onValueChange` and call `updateProps` to update backend state. + +```mermaid +flowchart TD +Start(["Enter Svelte Wrapper"]) --> Load["importComponent loads React component"] +Load --> Extract["getProps/processProps extract and transform props"] +Extract --> Slots["getSlots retrieves slot collection"] +Slots --> Visible{"visible is true?"} +Visible --> |Yes| Render["Render React component with slots/value/events"] +Visible --> |No| Skip["Skip rendering"] +Render --> Events["Bind event callbacks (e.g., onValueChange)"] +Events --> Update["updateProps updates backend state"] +Update --> End(["Complete"]) +Skip --> End +``` + +**Diagram Sources** + +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +**Section Sources** + +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +### React Component Bridging and Slot System + +- sveltify + - Accepts React component and optional slots declarations, returns a Sveltified component. + - Internally maintains shared root nodes and Portals, creating Bridge render trees on demand. + - Supports ignoring certain nodes for complex scenario optimization. +- ReactSlot + - Clones Svelte slots into React subtrees, preserving event listeners and child nodes. + - Supports force cloning (`forceClone`), parameterized rendering (`params`), and attribute observation (`observeAttributes`). + - Uses ContextPropsProvider and patchProps utilities to ensure internal fields like `key` are correctly passed. +- Slot rendering pipeline + - `renderSlot` decides whether to wrap with ContextPropsProvider based on options. + - `patchProps`/`applyPatchToProps` corrects the `key` field before and after bridging to avoid React warnings. + +```mermaid +sequenceDiagram +participant SV as "Svelte Component" +participant BR as "sveltify" +participant RD as "Bridge/ReactDOM" +participant RS as "ReactSlot" +participant RX as "Antd Component" +SV->>BR : sveltify(ReactComp, { slots }) +BR->>RD : Create shared root node and Portal +RD-->>BR : Initialization complete +BR-->>SV : Return renderable Sveltified component +SV->>RS : Pass slots and props +RS->>RS : Clone slot DOM (with events) +RS-->>RX : Render slot content +``` + +**Diagram Sources** + +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) + +**Section Sources** + +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) + +### Component Structure Conventions and Prop Definitions + +- Structure conventions + - Each component directory contains: `Index.svelte` (wrapper), corresponding React implementation (e.g., `button.tsx`), `package.json`, and `gradio.config.js`. + - Wrappers handle prop extraction, event bridging, and slot passing. +- Prop definitions + - Common props: `visible`, `elem_id`, `elem_classes`, `elem_style`, `as_item`, `_internal.layout`, etc. + - Business props: e.g., Form's `formAction`, `name`, Button's `target`, `loading.icon`, etc. + - Mapping rules: `processProps` supports name mapping (e.g., `fields_change` → `fieldsChange`). +- Event handling + - Data components write back to backend via `onValueChange`/`updateProps`. + - Behavior components trigger backend actions via native events like `onClick`/`onSubmit`. +- Slot system + - Named slots like `slots.icon`, `slots['loading.icon']` inject ReactSlot. + - Supports `children` default slot and parameterized slots (`params`). + +**Section Sources** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) + +### Extending Existing Components and Creating New Component Types + +- Extending existing components + - Backend: Based on `ModelScopeComponent`/`ModelScopeLayoutComponent`, add props and events, rewrite `__exit__`/`__enter__` as needed. + - Frontend: Extend `getProps`/`processProps` mappings in the Svelte wrapper, add event callbacks and slots. + - React: Use sveltify to add slot declarations, render slots with ReactSlot. +- Creating new component types + - Backend: Choose appropriate base class, define `EVENTS`/`SLOTS`, set `skip_api`. + - Frontend: Create new `Index.svelte`, import `importComponent` and `getSlots`, configure `processProps`. + - React: Implement sveltify wrapping, handle slots and styles, export default component. + +**Section Sources** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +## Dependency Analysis + +- Component classification entry points + - Backend `components/__init__.py` aggregates components from antd, antdx, base, and pro modules. + - `antd/__init__.py` lists numerous Ant Design component aliases for unified importing. + - `base/__init__.py` aggregates base layout and text components. + - `pro/__init__.py` aggregates professional components (e.g., Chatbot, Monaco Editor). +- Frontend bridging entry point + - `svelte-preprocess-react/index.ts` exposes sveltify and internal types for use in component wrappers. + +```mermaid +graph TB +A["backend/modelscope_studio/components/__init__.py"] --> B["antd/__init__.py"] +A --> C["antdx/__init__.py"] +A --> D["base/__init__.py"] +A --> E["pro/__init__.py"] +F["frontend/svelte-preprocess-react/index.ts"] --> G["sveltify.svelte.ts"] +F --> H["react-slot.tsx"] +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) + +**Section Sources** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) + +## Performance Considerations + +- Avoid duplicate rendering + - Use the `layout` marker of `ModelScopeDataLayoutComponent` to reduce duplicate BlockContext rendering. +- Slot cloning strategy + - ReactSlot supports force cloning (`clone`/`forceClone`) to maintain event and structure consistency during complex DOM changes. + - Uses MutationObserver to observe slot changes and redraw on demand, reducing full update costs. +- Prop passing optimization + - Only transform fields like `key` via `patchProps`/`applyPatchToProps` when necessary to reduce React diff overhead. +- Async loading + - Svelte wrappers use `importComponent` to asynchronously load React components to avoid first-screen blocking. + +## Troubleshooting Guide + +- Slots not working + - Check whether the Svelte wrapper correctly calls `getSlots` and passes them to the React component's slots. + - Confirm whether the ReactSlot's `slot` parameter points to the correct DOM node. +- Events not being passed back + - Confirm whether the component listens to `onValueChange` or other callbacks and calls `updateProps` to update backend state. + - For form components, check whether `formAction` has been cleared or reset. +- Style and class name abnormalities + - Check whether `elem_id`, `elem_classes`, `elem_style` are correctly passed to the React component. + - Confirm whether ReactSlot correctly applies `className` and inline styles. +- Key conflicts or warnings + - Use `patchProps`/`applyPatchToProps` to handle internal `key` fields to avoid React errors. + +**Section Sources** + +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) + +## Conclusion + +Through the coordination of backend component base classes and frontend bridging mechanisms, ModelScope Studio implements a complete component chain from Python to Svelte to React. By following this guide's structure conventions, prop definitions, and event handling practices, you can efficiently extend existing components or create entirely new component types, and use the slot system to achieve flexible content reuse and style passing. + +## Appendix + +- Component Development Checklist + - Backend: Choose appropriate base class, define EVENTS/SLOTS, set skip_api, rewrite lifecycle as needed. + - Frontend: Write Index.svelte, configure getProps/processProps and getSlots, handle event callbacks. + - React: Use sveltify wrapping, declare slots, render slots via ReactSlot, apply styles and props. + - Testing: Cover prop mapping, event passing, slot rendering, and error boundaries. + - Documentation: Write following each component README template under docs/components, provide minimal usable examples and parameter descriptions. diff --git a/.wiki/en/Development Guide/Component Development/Component Documentation Writing.md b/.wiki/en/Development Guide/Component Development/Component Documentation Writing.md new file mode 100644 index 00000000..3873098b --- /dev/null +++ b/.wiki/en/Development Guide/Component Development/Component Documentation Writing.md @@ -0,0 +1,345 @@ +# Component Documentation Writing + + +**Files Referenced in This Document** +- [Docs.py](file://docs/helper/Docs.py) +- [Site.py](file://docs/helper/Site.py) +- [app.py](file://docs/app.py) +- [README.md](file://docs/README.md) +- [FAQ.md](file://docs/FAQ.md) +- [parse_markdown.py](file://docs/helper/parse_markdown.py) +- [button/README.md](file://docs/components/antd/button/README.md) +- [button/app.py](file://docs/components/antd/button/app.py) +- [chatbot/README.md](file://docs/layout_templates/chatbot/README.md) +- [chatbot/app.py](file://docs/layout_templates/chatbot/app.py) +- [example.py](file://docs/demos/example.py) +- [basic.py (button example)](file://docs/components/antd/button/demos/basic.py) +- [basic.py (chatbot template example)](file://docs/layout_templates/chatbot/demos/basic.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This guide is intended for developers writing complete documentation for ModelScope Studio components, covering the following topics: + +- Writing conventions and metadata configuration for README.md +- Organization structure of the `demos` directory and naming conventions for example files +- Configuration methods for `app.py` and site navigation construction +- Features and usage of the documentation generation tools `Docs.py` and `Site.py` +- Layered conventions for example code: basic usage, advanced configuration, and FAQs +- How to organize component categories and navigation structures +- Template and example path references to help you get started quickly + +## Project Structure + +The documentation system consists of three parts: "component documentation," "layout templates," and "helper utilities," with a unified entry point `app.py` that builds site navigation and content rendering. + +```mermaid +graph TB +A["docs/app.py
Site Entry & Navigation"] --> B["docs/components/
Component Documentation Directory"] +A --> C["docs/layout_templates/
Layout Template Directory"] +A --> D["docs/helper/Docs.py
Documentation Rendering Tool"] +A --> E["docs/helper/Site.py
Site Layout & Navigation"] +D --> F["docs/helper/parse_markdown.py
Markdown Parser"] +B --> G["README.md
Component Description & Demo Placeholders"] +B --> H["app.py
Component Documentation Page Entry"] +B --> I["demos/*.py
Example Code Collection"] +C --> J["README.md
Template Description & Demo Placeholders"] +C --> K["app.py
Template Documentation Page Entry"] +C --> L["demos/*.py
Template Example Collection"] +``` + +Diagram Sources + +- [app.py:1-598](file://docs/app.py#L1-L598) +- [Docs.py:1-178](file://docs/helper/Docs.py#L1-L178) +- [Site.py:1-255](file://docs/helper/Site.py#L1-L255) +- [parse_markdown.py:1-84](file://docs/helper/parse_markdown.py#L1-L84) + +Section Sources + +- [app.py:1-598](file://docs/app.py#L1-L598) + +## Core Components + +- Docs Renderer: Responsible for parsing `
Svelte + React Wrapper"] +B["frontend/antdx/*
Svelte + React Wrapper"] +C["frontend/base/*
Base Components"] +D["frontend/pro/*
Pro Components"] +end +subgraph "Backend" +E["backend/modelscope_studio/
Python Package & Templates"] +end +subgraph "Testing & CI" +F[".github/workflows/lint.yaml
Code Linting"] +G[".github/workflows/publish.yaml
Publish Workflow"] +H[".changeset/*
Version & Changeset"] +end +A --> E +B --> E +C --> E +D --> E +F --> A +F --> B +F --> C +F --> D +G --> E +H --> G +``` + +**Diagram Sources** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) + +**Section Sources** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) + +## Core Components + +- Component Encapsulation Pattern: Frontend components typically use a Svelte template for prop and slot handling, bridging Ant Design components through a React wrapper layer to integrate with Gradio. +- Props and Slots: Components accept standard props and handle extended slots (such as icons and loading states) via `slots`, supporting dynamic values and visibility control. +- Test Entry Points: The repository provides simple Gradio-based test scripts that can serve as starting points for end-to-end tests. + +**Section Sources** + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [tests/test.py:1-17](file://tests/test.py#L1-L17) +- [tests/test1.py:1-15](file://tests/test1.py#L1-L15) + +## Architecture Overview + +The diagram below shows the overall flow from component to testing and release, as well as the role of Changesets in version management. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Repo as "Repository (.changeset)" +participant GH as "GitHub Actions" +participant PyPI as "PyPI" +Dev->>Repo : Commit changeset and version update +Repo-->>GH : Trigger publish workflow +GH->>GH : Install dependencies / Build / Publish +GH->>PyPI : Push package and create tag and release +PyPI-->>Dev : Publish completion notification +``` + +**Diagram Sources** + +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) + +**Section Sources** + +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [.changeset/README.md:1-9](file://.changeset/README.md#L1-L9) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) + +## Detailed Component Analysis + +### Component: Button (antd.button) + +This component demonstrates typical prop and slot handling patterns, including: + +- Prop Forwarding: Passes Ant Design Button props directly to the underlying component. +- Slot Support: Supports `icon` and `loading.icon` slots, allowing custom icons and loading states. +- Dynamic Values and Visibility: Determines render content based on `children` and `value`; `visible` controls display. + +```mermaid +classDiagram +class ButtonWrapper { ++props : All AntD Button props ++slots : icon, loading.icon ++value : Text value ++children : Child nodes ++render() : ReactElement +} +class AntDButton { ++...props ++icon ++loading +} +ButtonWrapper --> AntDButton : "Prop forwarding and slot rendering" +``` + +**Diagram Sources** + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) + +```mermaid +sequenceDiagram +participant Svelte as "Index.svelte" +participant Wrapper as "button.tsx" +participant AntD as "AntD Button" +Svelte->>Wrapper : Pass props and slots +Wrapper->>Wrapper : Parse slots and value +Wrapper->>AntD : Render Button and inject slots +AntD-->>Wrapper : Return React element +Wrapper-->>Svelte : Return final component +``` + +**Diagram Sources** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) + +**Section Sources** + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +### Testing Scenarios and Practical Guidance + +- Prop Validation: For the button component, verify that `icon` and `loading.icon` slots render correctly; the priority logic between `value` and `children`; the effect of `visible` on display. +- Event Triggering: In Gradio Blocks, bind a `click` callback to the button and verify input/output and callback trigger order. +- State Changes: Verify the effect of `loading` state switching, `disabled` state, `size`, and other props on rendering. +- End-to-End Testing: Start a local service using Gradio Interface/Blocks, then verify by clicking buttons and observing output and logs manually or via automation. + +```mermaid +flowchart TD +Start(["Start"]) --> Props["Prepare component props and slots"] +Props --> Render["Render component"] +Render --> Event["Simulate user event (e.g., click)"] +Event --> Verify["Assert results (props/events/state)"] +Verify --> Report["Generate test report"] +Report --> End(["End"]) +``` + +[This diagram is a conceptual flow and does not map directly to specific source files] + +**Section Sources** + +- [tests/test.py:1-17](file://tests/test.py#L1-L17) +- [tests/test1.py:1-15](file://tests/test1.py#L1-L15) + +## Dependency Analysis + +- Frontend Dependencies: Components depend on Ant Design and Svelte 5; `@svelte-preprocess-react` bridges React components to Svelte. +- Backend Packaging: Uses `hatchling` to build the Python package, containing numerous template files to ensure components are available in the Gradio environment. +- Versioning and Release: Changesets manages version numbers and change log; the publish workflow handles dependency installation, building, and publishing to PyPI. + +```mermaid +graph LR +A["frontend/package.json"] --> B["@svelte-preprocess-react"] +A --> C["antd/svelte"] +D["pyproject.toml"] --> E["hatchling build"] +F["package.json"] --> G["changesets/cli"] +H[".github/workflows/publish.yaml"] --> I["PyPI publish"] +G --> H +E --> I +``` + +**Diagram Sources** + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) +- [package.json:1-55](file://package.json#L1-L55) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +**Section Sources** + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) +- [package.json:1-55](file://package.json#L1-L55) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +## Performance Considerations + +- Component Rendering: Minimize unnecessary prop recalculation and slot parsing, avoiding heavy computations on the render path. +- Event Handling: When binding events in Gradio, ensure callback function idempotency and minimize side effects. +- Build and Release: The publish workflow already includes installation and build steps; consider caching dependencies locally to improve speed. + +[This section contains general recommendations; no source code references are required] + +## Troubleshooting Guide + +- Lint Workflow Failure: Check Python and Node dependency installation, and whether formatting and type checks pass. +- Publish Workflow Failure: Confirm correct configuration of PyPI credentials and GitHub Token; check version update and tag creation steps. +- Component Rendering Anomaly: Verify slot names and prop forwarding logic; check compatibility between the Svelte template and the React wrapper layer. + +**Section Sources** + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +## Conclusion + +Based on the existing repository structure and configuration, this guide provides recommendations for component testing and continuous integration. It is recommended to add unit and end-to-end testing steps on top of the existing Lint workflow, and to form a complete quality loop by combining Changesets with the publish workflow. + +## Appendix + +### Managing Versions and Releases with Changesets + +- Initialization and Configuration: The repository already includes Changesets configuration and documentation, ready to use. +- Common Commands: + - Version Update: Run the version update script to generate changesets and version numbers. + - Create Changeset: Add changeset files when needed to describe the scope and impact of changes. +- Collaboration with Publish Workflow: The publish workflow builds and publishes based on commits after version updates. + +**Section Sources** + +- [.changeset/README.md:1-9](file://.changeset/README.md#L1-L9) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [package.json:1-55](file://package.json#L1-L55) + +### Adding Test Steps in GitHub Actions + +- Current Workflows: + - Lint Workflow: Installs dependencies and performs code linting. + - Publish Workflow: Installs dependencies, builds, and publishes to PyPI. +- Recommended New Test Steps: + - Unit Tests: Add test scripts and run commands in the frontend component directories. + - Integration Tests: Add test scripts and run commands in the backend Python package. + - End-to-End Tests: Start a service using Gradio example scripts and perform interaction verification. +- Test Reports: After tests complete, upload reports or generate summary information. + +**Section Sources** + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [tests/test.py:1-17](file://tests/test.py#L1-L17) +- [tests/test1.py:1-15](file://tests/test1.py#L1-L15) + +### Key Points for Writing Component Test Cases and Test Data + +- Test Case Design: + - Normal Path: Verify normal rendering and interaction of props and slots. + - Edge Cases: Empty values, disabled state, loading state, extra-long text, etc. + - Error Scenarios: Invalid props, missing slots, etc. +- Test Data: + - Use a minimal dataset to cover key branches. + - For asynchronous scenarios (e.g., progress bars), use time slices and assertions. +- Assertion Strategy: + - Prop Assertions: Verify the final rendered DOM or React element props. + - Event Assertions: Verify callback trigger counts and parameters. + - State Assertions: Verify consistency between internal state changes and external behavior. + +**Section Sources** + +- [tests/test1.py:1-15](file://tests/test1.py#L1-L15) +- [frontend/fixtures.d.ts:1-50](file://frontend/fixtures.d.ts#L1-L50) diff --git a/.wiki/en/Development Guide/Component Development/Frontend Component Development.md b/.wiki/en/Development Guide/Component Development/Frontend Component Development.md new file mode 100644 index 00000000..c7e3cba8 --- /dev/null +++ b/.wiki/en/Development Guide/Component Development/Frontend Component Development.md @@ -0,0 +1,418 @@ +# Frontend Component Development + + +**Files Referenced in This Document** +- [frontend/package.json](file://frontend/package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/svelte-preprocess-react/index.ts](file://frontend/svelte-preprocess-react/index.ts) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts](file://frontend/svelte-preprocess-react/sveltify.svelte.ts) +- [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/patchProps.tsx](file://frontend/utils/patchProps.tsx) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/style.ts](file://frontend/utils/style.ts) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/base/text/Index.svelte](file://frontend/base/text/Index.svelte) +- [frontend/base/text/text.tsx](file://frontend/base/text/text.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This guide is intended for frontend developers and provides a systematic explanation of how to develop components under the `frontend/` directory using Svelte 5, and how to bridge existing React components as Svelte components via `svelte-preprocess-react`. Topics covered include component structure, lifecycle and state management, event handling, style processing, the slot system, property passing, inter-component communication, and data flow — with direct file path references and best practices. + +## Project Structure + +- The root directory contains Vite configuration and build entry points. The frontend project is organized in a modular fashion, layered by component type (antd, antdx, base, pro, etc.). +- Each concrete component typically consists of two parts: a Svelte layer `Index.svelte` (responsible for prop forwarding, visibility control, slot collection, and rendering) and a TSX layer component file (responsible for actual UI rendering and bridge logic). +- `svelte-preprocess-react` provides the `sveltify` utility to wrap React components as Svelte-compatible components, supporting slots, context, node tree management, and mount bridging. + +```mermaid +graph TB +subgraph "Frontend Project" +A["defineConfig.js
Vite Config"] +B["package.json
Dependencies & Scripts"] +end +subgraph "Component Layer" +C["antd/button/Index.svelte
Prop Forwarding/Visibility/Slots"] +D["antd/button/button.tsx
React Component Wrapper"] +E["base/text/Index.svelte
Base Text Component"] +F["base/text/text.tsx
React Component Wrapper"] +end +subgraph "Bridge Layer" +G["svelte-preprocess-react/index.ts
Export Entry"] +H["svelte-preprocess-react/sveltify.svelte.ts
sveltify Implementation"] +I["svelte-preprocess-react/internal/ReactWrapper.svelte
Svelte Wrapper"] +J["utils/renderSlot.tsx
Slot Render Utility"] +K["utils/patchProps.tsx
Prop Patch Utility"] +L["utils/createItemsContext.tsx
Items Context Utility"] +M["utils/style.ts
Style Conversion Utility"] +end +A --> C +A --> E +C --> D +E --> F +D --> H +C --> I +F --> H +H --> I +D --> J +F --> J +D --> K +F --> K +D --> L +F --> L +D --> M +F --> M +``` + +**Diagram Sources** + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/base/text/text.tsx:1-11](file://frontend/base/text/text.tsx#L1-L11) +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte:1-82](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte#L1-L82) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) + +**Section Sources** + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## Core Components + +- Svelte Component Layer (Index.svelte) + - Receives props from parent components, performs filtering and derived calculations, controls visibility, collects slots, and passes them to the TSX layer. + - Uses asynchronous loading to import TSX components, avoiding blocking initial render. +- TSX Component Layer (\*.tsx) + - Uses `sveltify` to wrap React components into Svelte-compatible components, supporting slot mapping, prop patching, context injection, and node tree management. + - Uses `ReactSlot` to render slot content from Svelte, supporting cloning and parameterized rendering. +- Bridge and Utilities + - `sveltify`: Establishes the bridge between Svelte and React, maintains shared root nodes and child node trees, and handles mounting and unmounting. + - `ReactWrapper`: Acts as a wrapper in Svelte, injects context, collects slots and props, and cleans up the node tree on destroy. + - `renderSlot`/`patchProps`/`createItemsContext`/`style`: Handle slot rendering, prop patching, items context, and style conversion respectively. + +**Section Sources** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/base/text/text.tsx:1-11](file://frontend/base/text/text.tsx#L1-L11) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte:1-82](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte#L1-L82) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) + +## Architecture Overview + +The diagram below illustrates the bridge flow from Svelte components to React components, along with the prop and slot propagation chain. + +```mermaid +sequenceDiagram +participant SvelteUI as "Svelte Component (Index.svelte)" +participant Wrapper as "ReactWrapper.svelte" +participant Sveltify as "sveltify.svelte.ts" +participant Bridge as "Bridge (React)" +participant ReactComp as "TSX Component (button.tsx/text.tsx)" +participant Slot as "ReactSlot" +SvelteUI->>Wrapper : "Call importComponent and pass props/children" +Wrapper->>Sveltify : "svelteInit initializes node tree" +Sveltify->>Bridge : "Create root node and render Bridge" +Bridge->>ReactComp : "Render React component" +ReactComp->>Slot : "Render slot content based on slots" +ReactComp-->>Bridge : "Return React element" +Bridge-->>Sveltify : "Update node tree" +Sveltify-->>Wrapper : "Initialization complete" +Wrapper-->>SvelteUI : "Render complete" +``` + +**Diagram Sources** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte:1-82](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte#L1-L82) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) + +## Detailed Component Analysis + +### Component Structure and Lifecycle + +- Svelte Layer (Index.svelte) + - Uses `$props`/`$derived` for prop derivation and visibility control; uses `importComponent` for asynchronous loading of TSX components to improve performance. + - Uses `getProps`/`processProps` to filter and additionally process props, ensuring only necessary props are passed. + - Uses `getSlots` to collect slots and pass them to the TSX layer. +- TSX Layer (\*.tsx) + - Uses `sveltify` to wrap React components, declares supported slot keys (e.g., `icon`, `loading.icon`), and maps slots via `ReactSlot` during rendering. + - Uses tools like `useTargets` to handle priority between `children` and `value`, ensuring rendering consistency. +- Lifecycle and State + - `ReactWrapper` injects context, collects slots and props during initialization; removes itself from the parent node and triggers re-render on destroy. + - `sveltify` internally maintains a shared root node and child node tree; node changes trigger rerender. + +```mermaid +flowchart TD +Start(["Enter Component"]) --> Props["Receive and derive props
$props/$derived"] +Props --> Visible{"visible is true?"} +Visible -- No --> Hide["Do not render"] +Visible -- Yes --> Import["importComponent async load TSX component"] +Import --> Slots["getSlots collect slots"] +Slots --> Render["Render TSX component with props and slots"] +Render --> End(["Complete"]) +Hide --> End +``` + +**Diagram Sources** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) + +**Section Sources** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte:1-82](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte#L1-L82) + +### Event Handling and Prop Passing + +- Prop Passing + - `processProps` filters and maps props, for example mapping `href_target` to `target`, while keeping `restProps` and additional props. + - Uses `patchProps`/`applyPatchToProps` to handle special props like `key` to avoid conflicts. +- Event Binding + - React event callbacks are bound directly in the TSX layer and forwarded via props through the Svelte layer; be careful to avoid duplicate binding or lost context. +- Slot Mapping + - Supported slot keys are declared in the TSX layer; `ReactSlot` renders the corresponding slot content, supporting `clone` and parameterized rendering. + +```mermaid +flowchart TD +A["Svelte Layer Props"] --> B["processProps Filter/Map"] +B --> C["patchProps Handle Special Props"] +C --> D["Forward to TSX Component"] +D --> E["React Event Binding"] +D --> F["Slot Key Declaration and Mapping"] +F --> G["ReactSlot Render Slot Content"] +``` + +**Diagram Sources** + +- [frontend/antd/button/Index.svelte:24-52](file://frontend/antd/button/Index.svelte#L24-L52) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/antd/button/button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) + +**Section Sources** + +- [frontend/antd/button/Index.svelte:24-52](file://frontend/antd/button/Index.svelte#L24-L52) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/antd/button/button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) + +### Style Processing and Unit Conversion + +- Style object to string: Converts camelCase to hyphenated form and automatically appends `px` units to numeric properties (except explicitly unitless properties). +- HTML inline style: Converts style objects into key-value pairs that can be used directly for inline styles. +- In the Svelte layer, `elem_style`/`elem_classes` can be used to forward styles and class names, which are then applied to the target React component in the TSX layer. + +```mermaid +flowchart TD +A["React.CSSProperties"] --> B["styleObject2String
Convert to string style"] +A --> C["styleObject2HtmlStyle
Convert to inline style object"] +B --> D["Apply to element in Svelte layer"] +C --> E["Apply to target component in TSX layer"] +``` + +**Diagram Sources** + +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) +- [frontend/antd/button/Index.svelte:62-63](file://frontend/antd/button/Index.svelte#L62-L63) + +**Section Sources** + +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) +- [frontend/antd/button/Index.svelte:62-63](file://frontend/antd/button/Index.svelte#L62-L63) + +### Slot System and Items Context + +- Slot Rendering + - `renderSlot` provides a unified slot rendering entry point, supporting `clone`, `forceClone`, and `params` parameterized rendering. + - `ReactSlot` receives slot DOM from Svelte and renders it as a React subtree. +- Items Context (ItemsContext) + - `createItemsContext` provides context for item collections, supporting item setting, change listening, and recursive child item construction. + - `ItemHandler` converts Svelte item descriptions (props, slots, children) into normalized structures and writes them into the context. + +```mermaid +sequenceDiagram +participant Svelte as "Svelte Component" +participant Utils as "renderSlot/patchProps" +participant ReactSlot as "ReactSlot" +participant Items as "createItemsContext" +Svelte->>Utils : "renderSlot(el, options)" +Utils->>ReactSlot : "Render slot content" +Svelte->>Items : "ItemHandler set item" +Items-->>Svelte : "onChange callback notification" +``` + +**Diagram Sources** + +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +**Section Sources** + +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +### Inter-Component Communication and Data Flow + +- Parent-Child Communication + - Parent components pass data and UI fragments to child components via props and slots; child components parse and render them in the TSX layer. +- Sibling/Cross-Layer Communication + - `createItemsContext` shares item collections across multiple levels, enabling data synchronization between sibling components. +- Event Propagation + - Callbacks are bound in the TSX layer and propagated upward to parent components via props; in the Svelte layer, event handlers forward the events. + +```mermaid +flowchart TD +Parent["Parent Component"] --> |props + slots| Child["Child Component (Svelte)"] +Child --> |importComponent| TSX["TSX Component"] +TSX --> |callbacks/events| Parent +Siblings["Sibling Components"] --> |ItemsContext| Shared["Shared Item Collection"] +Shared --> Siblings +``` + +**Diagram Sources** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +**Section Sources** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +## Dependency Analysis + +- Dependencies and Versions + - The frontend project uses Svelte 5 and React 19, along with the toolchain including `@vitejs/plugin-react-swc`, `less`, `typescript-json-schema`, and others. + - `svelte-preprocess-react` provides bridging capability, internally containing core modules such as Bridge, ReactWrapper, and ReactSlot. +- Key Dependency Relationships + - Svelte components depend on `@svelte-preprocess-react/component` and Svelte context utilities for prop and slot processing. + - TSX components depend on `sveltify` and `ReactSlot` for bridging and slot rendering. + - Utility modules (`renderSlot`, `patchProps`, `createItemsContext`, `style`) are used throughout prop, slot, and style processing. + +```mermaid +graph LR +Pkg["package.json Dependencies"] --> Svelte["Svelte 5"] +Pkg --> React["React 19"] +Pkg --> Tools["Vite/React-SWC/Less/TS"] +Comp["Svelte Component (Index.svelte)"] --> Bridge["@svelte-preprocess-react
sveltify/ReactWrapper"] +Comp --> Utils["renderSlot/patchProps/style"] +Comp --> Items["createItemsContext"] +TSX["TSX Component (button.tsx/text.tsx)"] --> Bridge +TSX --> Utils +TSX --> Items +``` + +**Diagram Sources** + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) + +**Section Sources** + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) + +## Performance Considerations + +- Asynchronous Component Loading + - Use `importComponent` for async loading of TSX components to reduce initial load burden; consider lazy-loading large components. +- Minimize Props and Slots + - `processProps` filters irrelevant props to avoid unnecessary re-renders; only pass necessary slot keys to reduce bridging overhead. +- Node Tree Management + - `sveltify` maintains a shared root node and child node tree; node changes trigger partial rerender. Avoid frequently creating/destroying nodes. +- Style Conversion Caching + - Cache the results of style object conversions (e.g., using `useMemoizedEqualValue`) to reduce repeated calculations. + +[This section contains general performance recommendations; no specific file references are required] + +## Troubleshooting Guide + +- Slot Not Displayed + - Check whether the corresponding slot key is declared in the TSX layer; confirm that the `el` in `renderSlot` exists and has not been force-cloned causing content loss. + - Reference path: [frontend/utils/renderSlot.tsx:13-28](file://frontend/utils/renderSlot.tsx#L13-L28) +- Prop Anomaly or Conflict + - Check the usage of `patchProps`/`applyPatchToProps`, ensuring special props like `key` are handled correctly. + - Reference path: [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- Component Not Rendering or Flickering + - Confirm the `visible` control logic and the timing of `importComponent` loading; check `ReactWrapper` initialization and destroy hooks. + - Reference paths: [frontend/antd/button/Index.svelte:59-73](file://frontend/antd/button/Index.svelte#L59-L73), [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte:60-66](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte#L60-L66) +- Items Context Not Updating + - Check the `setItem` call in `ItemHandler` and the `allowedSlots` configuration; confirm that the `onChange` callback is being triggered. + - Reference path: [frontend/utils/createItemsContext.tsx:124-156](file://frontend/utils/createItemsContext.tsx#L124-L156) +- Style Not Taking Effect + - Check the conversion results of `styleObject2String`/`styleObject2HtmlStyle`; confirm no missing units or typos. + - Reference path: [frontend/utils/style.ts:39-76](file://frontend/utils/style.ts#L39-L76) + +**Section Sources** + +- [frontend/utils/renderSlot.tsx:13-28](file://frontend/utils/renderSlot.tsx#L13-L28) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/antd/button/Index.svelte:59-73](file://frontend/antd/button/Index.svelte#L59-L73) +- [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte:60-66](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte#L60-L66) +- [frontend/utils/createItemsContext.tsx:124-156](file://frontend/utils/createItemsContext.tsx#L124-L156) +- [frontend/utils/style.ts:39-76](file://frontend/utils/style.ts#L39-L76) + +## Conclusion + +This guide systematically covers the component development approach in `frontend/` based on Svelte 5 and `svelte-preprocess-react`, including component structure, lifecycle, state management, event handling, styles and slots, prop passing, and inter-component communication. Through mechanisms such as async loading, prop filtering, slot mapping, and items context, you can maintain the simplicity of Svelte while efficiently reusing React ecosystem resources. It is recommended to follow the file organization and bridging patterns described in this guide when developing new components, to achieve better maintainability and performance. + +## Appendix + +- Steps for Creating a New Component (Recommended Workflow) + - Create a component directory under `frontend/` (e.g., `frontend/antd/my-component/`). + - Create `Index.svelte`: define props, visibility, slot collection, and `importComponent` async loading. + - Create `my-component.tsx`: use `sveltify` to wrap the React component, declare slot keys, and render `ReactSlot`. + - If styling is needed, use `style.ts` for conversion; for parameterized slots, use `renderSlot`/`patchProps`. + - If cross-layer data sharing is needed, use `createItemsContext` to provide context and `onChange` callbacks. +- Reference File Paths + - [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) + - [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) + - [frontend/base/text/Index.svelte](file://frontend/base/text/Index.svelte) + - [frontend/base/text/text.tsx](file://frontend/base/text/text.tsx) + - [frontend/svelte-preprocess-react/sveltify.svelte.ts](file://frontend/svelte-preprocess-react/sveltify.svelte.ts) + - [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte) + - [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) + - [frontend/utils/patchProps.tsx](file://frontend/utils/patchProps.tsx) + - [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) + - [frontend/utils/style.ts](file://frontend/utils/style.ts) diff --git a/.wiki/en/Development Guide/Contributing Guide.md b/.wiki/en/Development Guide/Contributing Guide.md new file mode 100644 index 00000000..4c3c304c --- /dev/null +++ b/.wiki/en/Development Guide/Contributing Guide.md @@ -0,0 +1,317 @@ +# Contributing Guide + + +**Files referenced in this document** +- [README.md](file://README.md) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [.commitlintrc.js](file://.commitlintrc.js) +- [.lintstagedrc](file://.lintstagedrc) +- [.editorconfig](file://.editorconfig) +- [.flake8](file://.flake8) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [eslint.config.mjs](file://eslint.config.mjs) +- [prettier.config.mjs](file://prettier.config.mjs) +- [config/lint-config/package.json](file://config/lint-config/package.json) +- [config/lint-config/eslint.mjs](file://config/lint-config/eslint.mjs) +- [config/lint-config/stylelint.js](file://config/lint-config/stylelint.js) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This guide is intended for contributors who wish to participate in the development and maintenance of ModelScope Studio. It covers the complete lifecycle from environment setup, code standards, commit conventions, Pull Request processes, bug reporting and feature suggestions, to governance and decision-making processes. The project uses multi-package workspaces (pnpm workspaces) to organize frontend components and backend Python packages, managing versions and changesets with Changesets, and automating Lint and releases with GitHub Actions. + +## Project Structure + +- The root directory contains the frontend component library, Python backend package, documentation site, scripts and configuration files. +- The frontend is based on Svelte 5, organized by Ant Design, Ant Design X, and Base component sub-packages; Pro-specific components also exist. +- The backend is a Python package using the Hatch build system, exporting numerous template resources for frontend runtime use. +- The workspace is uniformly managed through `pnpm-workspace.yaml`, including root, configuration, and various frontend sub-packages. + +```mermaid +graph TB +Root["Root Directory
package.json/pyproject.toml"] --> Frontend["Frontend Workspace
frontend/*"] +Root --> Backend["Backend Workspace
backend/modelscope_studio"] +Root --> Config["Config Workspace
config/*"] +Root --> Docs["Documentation Site
docs/*"] +Frontend --> Antd["antd sub-package"] +Frontend --> Antdx["antdx sub-package"] +Frontend --> Base["base sub-package"] +Frontend --> Pro["pro sub-package"] +Config --> LintCfg["lint-config sub-package"] +``` + +**Diagram Sources** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +**Section Sources** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +## Core Components + +- Multi-package workspace and build: Frontend uses Gradio CLI for builds; root scripts manage builds, formatting, type checking, style checking, and linting uniformly. +- Versioning and releases: Changesets handles version number advancement and changelog generation; GitHub Actions triggers the release process on main branch pushes. +- Commit conventions: Commitlint uses Conventional Commits types with constrained type enumeration and relaxed case/length restrictions. +- Local hooks: Husky as a Git hook tool, combined with lint-staged for quick Lint and formatting of staged files. +- Editor consistency: EditorConfig unifies indentation, line endings, and character sets; Prettier and ESLint/Stylelint handle formatting and rule validation respectively. + +**Section Sources** + +- [package.json:8-25](file://package.json#L8-L25) +- [.commitlintrc.js:1-30](file://.commitlintrc.js#L1-L30) +- [.lintstagedrc:1-7](file://.lintstagedrc#L1-L7) +- [.editorconfig:1-17](file://.editorconfig#L1-L17) +- [eslint.config.mjs:1-9](file://eslint.config.mjs#L1-L9) +- [prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26) + +## Architecture Overview + +The diagram below shows the key nodes of the contribution workflow: local development, commit conventions, CI Lint, versioning and release. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Git as "Git Hooks
lint-staged" +participant Lint as "Lint/Formatting" +participant CI as "GitHub Actions" +participant Cfg as "Changesets" +participant PyPI as "PyPI Release" +Dev->>Git : "Add files to staging area" +Git->>Lint : "Execute Lint/formatting on staged files" +Lint-->>Git : "Pass/fail" +Dev->>CI : "Push branch" +CI->>CI : "Run Lint tests" +Dev->>Cfg : "Create/update changeset" +Cfg-->>Dev : "Generate version and changelog" +CI->>PyPI : "Release when conditions are met" +``` + +**Diagram Sources** + +- [.lintstagedrc:1-7](file://.lintstagedrc#L1-L7) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [package.json:10-25](file://package.json#L10-L25) + +## Detailed Component Analysis + +### Code Standards and Toolchain + +- ESLint configuration: Root configuration aggregates base rules from lint-config, ensuring consistent JS/TS/Svelte rules across the frontend. +- Prettier configuration: Unifies indentation, quotes, trailing commas, line endings, etc.; specifies parser for Svelte files. +- Stylelint configuration: Base rules provided by lint-config, supporting LESS/CSS checking and fixing. +- EditorConfig: Unifies basic editor styles to avoid format drift caused by tool differences. +- Flake8: Python Lint rules and ignores, limiting max line length and ignoring specific rules. + +**Section Sources** + +- [eslint.config.mjs:1-9](file://eslint.config.mjs#L1-L9) +- [prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26) +- [config/lint-config/eslint.mjs](file://config/lint-config/eslint.mjs) +- [config/lint-config/stylelint.js](file://config/lint-config/stylelint.js) +- [.editorconfig:1-17](file://.editorconfig#L1-L17) +- [.flake8:1-16](file://.flake8#L1-L16) + +### Commit Conventions and Commitlint + +- Type enumeration: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. +- Relaxed policy: Case, empty scope, periods, and length restrictions are disabled or relaxed to lower commit barriers. +- Compatible with Conventional Commits: Facilitates downstream Changesets and automated release recognition. + +**Section Sources** + +- [.commitlintrc.js:1-30](file://.commitlintrc.js#L1-L30) + +### Local Hooks and lint-staged + +- Execute Lint and formatting grouped by file type: LESS/CSS, JS/TS/Svelte, Markdown/YAML/JSON/HTML, Python. +- Ensures minimum quality gate before each commit, reducing CI pressure. + +**Section Sources** + +- [.lintstagedrc:1-7](file://.lintstagedrc#L1-L7) + +### CI Workflow and Release + +- Lint testing: Installs Python dependencies (flake8/isort/yapf), Node dependencies (pnpm), runs `pnpm run lint`. +- Release process: On `main` or `next` branch push, installs build and release dependencies, executes version updates and release scripts, then creates tags and Releases after success. + +**Section Sources** + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +### Changesets and Version Management + +- Changesets handles version number advancement and changelog generation; root scripts provide commands like `version`, `fix-changelog`, etc. +- Before release, you can first build the changelog sub-package, then execute version updates and fix scripts. + +**Section Sources** + +- [package.json:10-25](file://package.json#L10-L25) + +### Getting Started for New Contributors + +- Clone repository and install dependencies: use pip for editable mode backend installation, pnpm for frontend installation and build. +- Start documentation site examples: use `gradio cc dev` to run `docs/app.py`. +- After modifying code, ensure local Lint and formatting pass; pre-commit is automatically handled by lint-staged. + +**Section Sources** + +- [README.md:80-101](file://README.md#L80-L101) +- [package.json:8-25](file://package.json#L8-L25) + +### Pull Request Process + +- Complete modifications and local verification (Lint/formatting/type checking/style checking) locally. +- Ensure lint-staged passes before committing; commit messages follow Conventional Commits types. +- Create PR and wait for CI Lint and necessary tests to pass; iterate modifications based on feedback. +- Maintainer reviews and merges, then the release process automatically handles versioning and release. + +**Section Sources** + +- [.lintstagedrc:1-7](file://.lintstagedrc#L1-L7) +- [.commitlintrc.js:1-30](file://.commitlintrc.js#L1-L30) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) + +### Bug Reports and Feature Requests + +- Before submitting an Issue, please confirm you have read the relevant documentation and FAQ. +- Provide clear reproduction steps, expected behavior, actual behavior, and environment information (Python/Node/browser versions). +- If involving frontend components, you can attach a minimal reproducible example or screenshot. + +**Section Sources** + +- [README.md:17-101](file://README.md#L17-L101) + +### Discussion and Collaboration + +- Prefer public discussions in Issues for traceability and archiving. +- For design or architecture level discussions, initiate topic posts in Discussion or Issues. + +**Section Sources** + +- [README.md:17-101](file://README.md#L17-L101) + +### Governance Structure and Decision-Making Process + +- Project maintainers are responsible for reviewing PRs, reviewing code quality and design rationality. +- Release permissions are controlled by maintainers, following Changesets and CI release processes. +- Community contributors participate in improvements through PRs; major changes are recommended to be discussed in Issues for consensus. + +**Section Sources** + +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [package.json:10-25](file://package.json#L10-L25) + +## Dependency Analysis + +- Toolchain dependencies: ESLint, Prettier, Stylelint, Husky, lint-staged, Changesets, Commitlint, etc. +- Frontend build: Gradio CLI, Svelte 5, TypeScript, Svelte check tool. +- Backend build: Hatch, Python dependency declarations and packaging configuration. +- Workspace: `pnpm-workspace.yaml` manages multiple packages uniformly, with only build dependencies explicitly listed. + +```mermaid +graph LR +Pkg["package.json"] --> ESL["ESLint Config"] +Pkg --> Prettier["Prettier Config"] +Pkg --> Husky["Husky Hooks"] +Pkg --> LintStaged["lint-staged"] +Pkg --> Changesets["Changesets"] +Pkg --> Commitlint["Commitlint"] +Pkg --> Gradio["Gradio CLI Build"] +Py["pyproject.toml"] --> Hatch["Hatch Build"] +WS["pnpm-workspace.yaml"] --> FE["frontend/*"] +WS --> CFG["config/*"] +WS --> BE["backend/*"] +``` + +**Diagram Sources** + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) + +**Section Sources** + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) + +## Performance Considerations + +- Local Lint and formatting: lint-staged only executes on staged files, shortening feedback cycles. +- CI parallel tasks: Lint tasks split JS/Python/Style/TS checks for parallel execution, improving overall efficiency. +- Type checking and style checking: Executed centrally in CI to avoid repeated local burden. + +**Section Sources** + +- [.lintstagedrc:1-7](file://.lintstagedrc#L1-L7) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) + +## Troubleshooting Guide + +- Commit rejected (Commitlint failure) + - Check whether commit message matches type enumeration; if temporarily relaxing is needed, adjust rules locally or use `--no-verify` to skip. + - Reference path: [.commitlintrc.js:1-30](file://.commitlintrc.js#L1-L30) +- Lint failure + - Run corresponding Lint commands by file type: `pnpm run lint:js`, `pnpm run lint:py`, `pnpm run lint:style`, `pnpm run lint:ts`. + - Reference path: [package.json:18-22](file://package.json#L18-L22) +- Formatting not taking effect + - Confirm Prettier plugins and Svelte parser configuration are correct; check whether `.editorconfig` is recognized by the editor. + - Reference path: [prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26), [.editorconfig:1-17](file://.editorconfig#L1-L17) +- CI Lint failure + - Check Python dependency installation and Node version; confirm pnpm installation and cache clearing. + - Reference path: [.github/workflows/lint.yaml:14-34](file://.github/workflows/lint.yaml#L14-L34) +- Release failure + - Confirm PyPI Token is valid; check version update and tag creation script output. + - Reference path: [.github/workflows/publish.yaml:59-74](file://.github/workflows/publish.yaml#L59-L74) + +**Section Sources** + +- [.commitlintrc.js:1-30](file://.commitlintrc.js#L1-L30) +- [package.json:18-22](file://package.json#L18-L22) +- [prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26) +- [.editorconfig:1-17](file://.editorconfig#L1-L17) +- [.github/workflows/lint.yaml:14-34](file://.github/workflows/lint.yaml#L14-L34) +- [.github/workflows/publish.yaml:59-74](file://.github/workflows/publish.yaml#L59-L74) + +## Conclusion + +Based on the project's existing configurations and workflows, this contributing guide provides a complete practical path from environment preparation, code and commit conventions, PR process to release and troubleshooting. New contributors are advised to prioritize completing local Lint and formatting validation on their first participation, and follow the Conventional Commits message conventions to ensure a smooth collaboration experience. + +## Appendix + +- Quick Command Reference + - Installation and build: See [README.md:80-101](file://README.md#L80-L101) + - Lint and formatting: See [package.json:18-22](file://package.json#L18-L22) + - Changesets: See [package.json:10-25](file://package.json#L10-L25) +- Configuration File Index + - ESLint: See [eslint.config.mjs:1-9](file://eslint.config.mjs#L1-L9) + - Prettier: See [prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26) + - Stylelint: See [config/lint-config/stylelint.js](file://config/lint-config/stylelint.js) + - Commitlint: See [.commitlintrc.js:1-30](file://.commitlintrc.js#L1-L30) + - EditorConfig: See [.editorconfig:1-17](file://.editorconfig#L1-L17) + - Flake8: See [.flake8:1-16](file://.flake8#L1-L16) + - Workspace: See [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) diff --git a/.wiki/en/Development Guide/Development Guide.md b/.wiki/en/Development Guide/Development Guide.md new file mode 100644 index 00000000..8c1d5dfe --- /dev/null +++ b/.wiki/en/Development Guide/Development Guide.md @@ -0,0 +1,325 @@ +# Development Guide + + +**Files referenced in this document** +- [README.md](file://README.md) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [frontend/package.json](file://frontend/package.json) +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [docs/app.py](file://docs/app.py) +- [docs/README.md](file://docs/README.md) +- [docs/helper/Docs.py](file://docs/helper/Docs.py) +- [docs/helper/Site.py](file://docs/helper/Site.py) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This guide is intended for engineers who wish to participate in the development and extension of ModelScope Studio (a third-party component library based on Gradio). It covers: development environment setup, dependency installation, starting the development server, build configuration, overall architecture and development workflow, standard component development process and best practices, documentation system usage and example conventions, testing and quality assurance, debugging tips and common issues, as well as contributing guidelines and code standards. + +## Project Structure + +The repository uses a multi-package workspace organization, consisting of the following main parts: + +- Backend Python package: Provides component classes and packaging configuration, responsible for component export and distribution on the Python side. +- Frontend Svelte/React ecosystem: Built with Vite, providing frontend implementations and bundling for components. +- Documentation site: A Gradio-based documentation system that dynamically loads documentation and examples for each component. +- Tools and scripts: Changeset version management, release scripts, encoding checks, etc. + +```mermaid +graph TB +subgraph "Backend" +PY["Python Package
backend/modelscope_studio"] +PY_INIT["__init__.py"] +PY_VER["version.py"] +PY_CFG["pyproject.toml"] +end +subgraph "Frontend" +FE_PKG["frontend/package.json"] +FE_CFG["frontend/defineConfig.js"] +FE_PLG["frontend/plugin.js"] +FE_BTN["frontend/antd/button/Index.svelte"] +end +subgraph "Documentation" +DOCS_APP["docs/app.py"] +DOCS_README["docs/README.md"] +DOCS_HELPER["docs/helper/Docs.py"] +DOCS_SITE["docs/helper/Site.py"] +end +PY --> DOCS_APP +FE_PKG --> DOCS_APP +FE_CFG --> FE_PLG +FE_BTN --> DOCS_APP +DOCS_APP --> DOCS_HELPER +DOCS_APP --> DOCS_SITE +DOCS_APP --> DOCS_README +``` + +**Diagram Sources** + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [docs/README.md:1-75](file://docs/README.md#L1-L75) +- [docs/helper/Docs.py:1-178](file://docs/helper/Docs.py#L1-L178) +- [docs/helper/Site.py:1-255](file://docs/helper/Site.py#L1-L255) + +**Section Sources** + +- [README.md:80-101](file://README.md#L80-L101) +- [package.json:8-25](file://package.json#L8-L25) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## Core Components + +- Backend component exports: The backend exposes components from various sub-modules through a unified export entry, enabling on-demand import and use. +- Frontend component bridging: The frontend wraps Ant Design/React components as Svelte components, using plugins for global variable mapping and externalization. +- Documentation system: The documentation site generates docs and examples by dynamically loading `app.py` from each component directory, supporting language switching and theme style injection. + +**Section Sources** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [docs/app.py:19-91](file://docs/app.py#L19-L91) + +## Architecture Overview + +The diagram below shows the critical path from development to runtime: the developer runs a command locally to start the documentation site, the site reads component documentation and examples, frontend components are built and externalized through the Vite plugin, and are finally rendered in the browser. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant CLI as "Script Commands" +participant Docs as "Documentation Site docs/app.py" +participant Helper as "Docs/Site Helpers" +participant FE as "Frontend Component Build" +participant Browser as "Browser" +Dev->>CLI : Run development command +CLI-->>Docs : Start docs/app.py +Docs->>Helper : Initialize Docs/Site +Helper-->>Docs : Inject menus/docs/examples +Docs->>FE : Render component pages +FE->>FE : Vite plugin processing and bundling +FE-->>Browser : Output static assets +Browser-->>Dev : Display interactive docs and examples +``` + +**Diagram Sources** + +- [package.json:15](file://package.json#L15) +- [docs/app.py:577-595](file://docs/app.py#L577-L595) +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) +- [docs/helper/Site.py:9-255](file://docs/helper/Site.py#L9-L255) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:41-168](file://frontend/plugin.js#L41-L168) + +## Detailed Component Analysis + +### Documentation System and Site Rendering + +- Dynamic loading: The site scans directories by component type, dynamically loads each component's `app.py`, and extracts the `docs` dictionary. +- Menus and tabs: The `Site` class organizes top-level tabs and sidebar menus, supporting horizontal menu and nested menu interaction. +- CSS injection: To avoid style loss in multi-Blocks scenarios, CSS from all examples is merged and injected into the root Blocks. + +```mermaid +flowchart TD +Start(["Start docs/app.py"]) --> LoadDocs["Scan component directories and load app.py"] +LoadDocs --> BuildSite["Initialize Site and build menus/tabs"] +BuildSite --> Render["Render Blocks pages"] +Render --> InjectCSS["Merge and inject example CSS"] +InjectCSS --> End(["Rendering complete"]) +``` + +**Diagram Sources** + +- [docs/app.py:19-91](file://docs/app.py#L19-L91) +- [docs/helper/Site.py:41-255](file://docs/helper/Site.py#L41-L255) +- [docs/helper/Docs.py:163-178](file://docs/helper/Docs.py#L163-L178) + +**Section Sources** + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [docs/helper/Site.py:1-255](file://docs/helper/Site.py#L1-L255) +- [docs/helper/Docs.py:1-178](file://docs/helper/Docs.py#L1-L178) + +### Frontend Build and Component Bridging + +- Vite plugin: Externalizes specific modules by mapping imports to global objects on `window`, reducing bundle size and improving load performance. +- Svelte components: Wraps React/AntD components via `importComponent`, handling props, slots, and visibility control uniformly. + +```mermaid +flowchart TD +Entry(["Index.svelte"]) --> GetProps["Parse component props and additional attributes"] +GetProps --> ProcessProps["Filter internal fields and generate final props"] +ProcessProps --> Slots["Retrieve slot contents"] +Slots --> Render["Asynchronously render target component"] +Render --> End(["Output to page"]) +``` + +**Diagram Sources** + +- [frontend/antd/button/Index.svelte:10-74](file://frontend/antd/button/Index.svelte#L10-L74) +- [frontend/plugin.js:41-168](file://frontend/plugin.js#L41-L168) + +**Section Sources** + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +### Backend Component Exports and Versioning + +- Unified exports: Backend components are centrally exported via `__init__.py` from all sub-modules, enabling users to import on-demand. +- Version management: Version numbers are maintained centrally in `version.py`, ensuring consistency between frontend and backend. + +**Section Sources** + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) + +## Dependency Analysis + +- Python dependencies: The backend is built with hatchling and declares version range constraints on Gradio; frontend dependencies include Ant Design, React, Svelte, and other ecosystem libraries. +- Documentation and scripts: `package.json` defines scripts for development, building, formatting, validation, and release; `pyproject.toml` configures build artifacts and metadata. + +```mermaid +graph LR +PJS["package.json scripts"] --> DOCS["docs/app.py"] +PJS --> FEPLG["frontend/plugin.js"] +PYTOML["pyproject.toml"] --> BACK["backend/modelscope_studio"] +FEPKG["frontend/package.json"] --> FEPLG +DOCS --> FEPLG +DOCS --> BACK +``` + +**Diagram Sources** + +- [package.json:8-25](file://package.json#L8-L25) +- [pyproject.toml:25-43](file://pyproject.toml#L25-L43) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +**Section Sources** + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## Performance Considerations + +- Externalization and aliases: The Vite plugin externalizes commonly used libraries, reducing repeated bundling and improving initial load speed. +- On-demand rendering: The component bridging layer only renders when `visible` is true, avoiding unnecessary nodes. +- CSS merging: The documentation site merges and injects example CSS to avoid style loss and repaint/flicker in multi-Blocks scenarios. + +[This section contains general recommendations and does not involve specific file analysis] + +## Troubleshooting Guide + +- Documentation site not displaying or style abnormalities + - Confirm whether `ssr_mode=False` is set in Hugging Face Space. + - Check whether the documentation site is correctly merging and injecting CSS. +- Component not working or throwing errors + - Check whether the component has been correctly exported and aggregated in `__init__.py`. + - Confirm that the frontend component's props and slots are passed according to convention. +- Build failure or externalization errors + - Check whether the Vite plugin's `external excludes` configuration covers the modules that need to be externalized. +- Development server startup failure + - Use the command provided in the documentation to start development mode, confirm port and hot-reload configuration. + +**Section Sources** + +- [README.md:32-33](file://README.md#L32-L33) +- [docs/helper/Site.py:60-73](file://docs/helper/Site.py#L60-L73) +- [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) + +## Conclusion + +This guide provides a complete path from environment setup to component development, documentation system usage, build and deployment, debugging and troubleshooting. During development, it is recommended to follow the unified component development workflow and naming conventions, make full use of the documentation system and script tools, and ensure consistency and maintainability between frontend and backend. + +[This section is a summary and does not involve specific file analysis] + +## Appendix + +### Development Environment Setup and Commands + +- Clone the repository and install backend and frontend dependencies +- Use the development command provided in the documentation to start the local documentation site + +**Section Sources** + +- [README.md:82-101](file://README.md#L82-L101) +- [package.json:15](file://package.json#L15) + +### Standard Component Development Process and Best Practices + +- Create or complete `app.py` and example files in the corresponding component directory, ensuring the documentation system can load them. +- Keep frontend components with minimal necessary prop passing, avoiding redundant logic. +- Use the unified slot and style injection mechanism to ensure consistent appearance and behavior. + +**Section Sources** + +- [docs/app.py:19-91](file://docs/app.py#L19-L91) +- [frontend/antd/button/Index.svelte:10-74](file://frontend/antd/button/Index.svelte#L10-L74) + +### Documentation System Usage and Example Writing Conventions + +- Use the Docs helper to parse Markdown and render examples, supporting collapsing, titles, and position control. +- Show example code and rendered results side by side for easier comparison and debugging. + +**Section Sources** + +- [docs/helper/Docs.py:82-178](file://docs/helper/Docs.py#L82-L178) + +### Testing Strategy and Quality Assurance + +- Use scripts for formatting, style checking, and type checking to ensure code consistency. +- Verify component behavior in different environments through the documentation site. + +**Section Sources** + +- [package.json:18-22](file://package.json#L18-L22) + +### Debugging Tips + +- Use Gradio's event and update mechanisms to observe menu switching and tab interactions. +- Check component rendering and prop passing in the browser console. + +**Section Sources** + +- [docs/helper/Site.py:203-255](file://docs/helper/Site.py#L203-L255) + +### Contributing Guidelines and Code Standards + +- Follow the project's established scripts and toolchain; ensure formatting and validation pass before committing. +- Version changes and release workflows are automated through Changesets and scripts. + +**Section Sources** + +- [package.json:10-25](file://package.json#L10-L25) diff --git a/.wiki/en/Development Guide/Development Workflow.md b/.wiki/en/Development Guide/Development Workflow.md new file mode 100644 index 00000000..7ccb67a3 --- /dev/null +++ b/.wiki/en/Development Guide/Development Workflow.md @@ -0,0 +1,302 @@ +# Development Workflow + + +**Files referenced in this document** +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [pyproject.toml](file://pyproject.toml) +- [README.md](file://README.md) +- [docs/app.py](file://docs/app.py) +- [frontend/package.json](file://frontend/package.json) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) +- [scripts/create-tag-n-release.mts](file://scripts/create-tag-n-release.mts) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This guide is intended for developers and maintainers of ModelScope Studio, systematically explaining the project's overall architecture, development patterns, and release process. The project uses a Monorepo structure, with the frontend based on Svelte and the Gradio component ecosystem, while the backend provides Python package encapsulation and template generation. The documentation site dynamically loads component examples and documentation through Python. This document covers the complete workflow from requirements analysis to component release, including Git workflow, branch management, code review, local development and hot reload, CI/CD, and automated releases. + +## Project Structure + +- The top level uses pnpm workspace to manage multiple packages, including the root project, frontend packages, base and professional component packages, and shared lint configuration packages. +- The backend is provided as a Python package offering component templates and packaging rules, with build artifacts for PyPI release. +- The documentation site is located in the `docs` directory, dynamically scanning component directories and rendering example pages through Python, supporting local development and hot reload. +- Frontend components are built with Svelte + TypeScript, working with the Gradio ecosystem for demonstration and integration. + +```mermaid +graph TB +Root["Root Workspace
package.json / pnpm-workspace.yaml"] --> Frontend["Frontend Package
frontend/package.json"] +Root --> Backend["Backend Package
pyproject.toml"] +Root --> Lint["Shared Lint Config
config/lint-config/package.json"] +Docs["Documentation Site
docs/app.py"] --> Backend +Docs --> Frontend +Frontend --> Gradio["@gradio/* ecosystem"] +Backend --> PyPI["PyPI Release"] +``` + +**Diagram Sources** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +**Section Sources** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## Core Components + +- Documentation site and routing: `docs/app.py` is responsible for dynamically loading `app.py` examples and documentation for each component, organizing multiple tabs and menu items, and enabling hot reload during local development. +- Frontend component ecosystem: The `frontend` directory organizes components by categories such as `antd`, `antdx`, `base`, `pro`, with each component containing Svelte implementation and Gradio configuration. +- Backend Python package: `pyproject.toml` defines build targets and artifact manifests, packaging a large number of template files into the wheel for PyPI use. +- Shared Lint configuration: `config/lint-config` provides unified ESLint and Stylelint rules and parsers, ensuring cross-package consistency. +- CI/CD scripts: The `scripts` directory contains PyPI release and GitHub Release creation scripts, working with GitHub Actions for automated releases. + +**Section Sources** + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [config/lint-config/package.json:1-48](file://config/lint-config/package.json#L1-L48) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +## Architecture Overview + +ModelScope Studio's development and release revolves around "documentation-driven component development": frontend components are implemented in Svelte, the backend Python package handles templates and packaging, and the documentation site serves as the unified entry point aggregating all component examples; CI/CD triggers builds and releases on the main branch, ensuring version consistency and traceability. + +```mermaid +graph TB +Dev["Developer"] --> LocalDev["Local Development
gradio cc dev docs/app.py"] +LocalDev --> Docs["Documentation Site
docs/app.py"] +Docs --> Antd["Antd Components
frontend/antd/*"] +Docs --> Antdx["Antdx Components
frontend/antdx/*"] +Docs --> Base["Base Components
frontend/base/*"] +Docs --> Pro["Pro Components
frontend/pro/*"] +Antd --> Backend["Backend Template Packaging
pyproject.toml"] +Antdx --> Backend +Base --> Backend +Pro --> Backend +Backend --> PyPI["PyPI Release"] +PyPI --> Users["User Installation and Usage"] +``` + +**Diagram Sources** + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [package.json:8-25](file://package.json#L8-L25) + +**Section Sources** + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [package.json:8-25](file://package.json#L8-L25) + +## Detailed Component Analysis + +### Documentation Site and Component Discovery Mechanism + +The documentation site scans subdirectories under `docs/components` and `docs/layout_templates`, dynamically imports each component's `app.py`, and extracts its `docs` field to form a unified site structure. This mechanism allows new components to be added without modifying site routing; simply provide `app.py` and examples in the corresponding directory. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Docs as "docs/app.py" +participant FS as "File System" +participant Comp as "Component app.py" +Dev->>Docs : Start gradio cc dev +Docs->>FS : Scan components/* and layout_templates/* +FS-->>Docs : Return component directory list +Docs->>Comp : importlib.spec_from_file_location() +Comp-->>Docs : Export docs dictionary +Docs-->>Dev : Render site and examples +``` + +**Diagram Sources** + +- [docs/app.py:19-61](file://docs/app.py#L19-L61) + +**Section Sources** + +- [docs/app.py:19-61](file://docs/app.py#L19-L61) + +### Frontend Component Development and Build + +- Components are written in Svelte + TypeScript, each with its own `package.json` and Gradio configuration for independent development and demonstration. +- The top-level `package.json` provides unified build and development scripts, invoking the Gradio CLI to build and start the documentation site. +- Frontend packages depend on `@gradio/*` ecosystem and core libraries such as `antd` and `svelte`, ensuring compatibility with the Gradio component ecosystem. + +**Section Sources** + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [package.json:8-25](file://package.json#L8-L25) + +### Backend Template Packaging and Release + +- `pyproject.toml` defines packaging rules for a large number of template files; build artifacts include backend component templates, ensuring they can be used directly on the Python side after installation. +- The release process uses scripts to check if the version already exists; if not, it executes the build and uses `twine` to upload to PyPI. + +```mermaid +flowchart TD +Start(["Start"]) --> Check["Check if version already exists on PyPI"] +Check --> Exists{"Already exists?"} +Exists --> |Yes| Skip["Skip release"] +Exists --> |No| Build["pip install -e . && pnpm run build"] +Build --> Dist{"dist exists?"} +Dist --> |No| Fail["Throw build failure error"] +Dist --> |Yes| Upload["twine upload dist/*"] +Upload --> Done(["End"]) +Skip --> Done +Fail --> Done +``` + +**Diagram Sources** + +- [scripts/publish-to-pypi.mts:14-55](file://scripts/publish-to-pypi.mts#L14-L55) +- [pyproject.toml:45-245](file://pyproject.toml#L45-L245) + +**Section Sources** + +- [scripts/publish-to-pypi.mts:14-55](file://scripts/publish-to-pypi.mts#L14-L55) +- [pyproject.toml:45-245](file://pyproject.toml#L45-L245) + +### CI/CD Process and Automated Release + +- Lint workflow: Automatically executes on push and pull_request, installing Python and Node dependencies, running the unified lint script to ensure code style consistency. +- Release workflow: Triggers on push to `main`/`next` branches, but requires the commit message to be "chore: update versions"; only commits meeting this condition will execute the PyPI release script; after successful release, a Git Tag is created and a GitHub Release is created with content from the changelog. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant GH as "GitHub Actions" +participant Lint as "Lint Job" +participant Pub as "Publish Job" +participant PyPI as "PyPI" +participant GHRel as "GitHub Releases" +Dev->>GH : Push code (main/next) +GH->>Lint : Trigger lint.yaml +Lint-->>GH : Lint pass/fail +GH->>Pub : Trigger publish.yaml +Pub->>PyPI : Upload package +PyPI-->>Pub : Success/failure +Pub->>GHRel : Create Tag and Release +GHRel-->>Dev : New version accessible +``` + +**Diagram Sources** + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:32-42](file://scripts/publish-to-pypi.mts#L32-L42) +- [scripts/create-tag-n-release.mts:88-115](file://scripts/create-tag-n-release.mts#L88-L115) + +**Section Sources** + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:32-42](file://scripts/publish-to-pypi.mts#L32-L42) +- [scripts/create-tag-n-release.mts:88-115](file://scripts/create-tag-n-release.mts#L88-L115) + +## Dependency Analysis + +- Package management: The root `package.json` and `pnpm-workspace.yaml` define workspace scope and script commands, with `frontend` and `config/lint-config` as independent packages. +- Language and toolchain: Python side is built with hatchling, Node side manages dependencies and scripts with pnpm; ESLint and Stylelint are provided by the shared lint configuration package. +- Component ecosystem: Frontend depends on `@gradio/*` and `antd/svelte`, documentation site imports component examples through Python, achieving a "documentation as example" development experience. + +```mermaid +graph LR +Root["Root Project"] --> WS["pnpm-workspace.yaml"] +Root --> Scripts["package.json scripts"] +WS --> FE["frontend/*"] +WS --> CFG["config/lint-config"] +FE --> Gradio["@gradio/*"] +FE --> Antd["antd/svelte"] +CFG --> ESLint["ESLint/Stylelint Rules"] +``` + +**Diagram Sources** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:8-25](file://package.json#L8-L25) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [config/lint-config/package.json:8-42](file://config/lint-config/package.json#L8-L42) + +**Section Sources** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:8-25](file://package.json#L8-L25) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [config/lint-config/package.json:8-42](file://config/lint-config/package.json#L8-L42) + +## Performance Considerations + +- Dynamic imports in the documentation site are only enabled in development mode; production builds can optimize startup time by disabling watch or adjusting concurrency parameters. +- Frontend components are built on-demand, avoiding unnecessary full compilation; during local development, it's recommended to focus only on the current component directory to reduce unnecessary file watching. +- Check if the version exists on PyPI before releasing to avoid repeated uploads and network waste. + +## Troubleshooting Guide + +- Documentation site not hot-reloading + - Confirm that the environment variable `GRADIO_WATCH_MODULE_NAME` is set correctly and `docs/app.py` is running in dev mode. + - Reference path: [docs/app.py:10](file://docs/app.py#L10) +- Build failure or dist does not exist + - Check whether root project and frontend package dependencies are fully installed; confirm that build scripts execute successfully. + - Reference path: [scripts/publish-to-pypi.mts:22-30](file://scripts/publish-to-pypi.mts#L22-L30) +- PyPI duplicate release skipped + - If the version already exists on PyPI, the script will skip the upload; confirm whether the version number needs to be changed or clear the cache. + - Reference path: [scripts/publish-to-pypi.mts:44-51](file://scripts/publish-to-pypi.mts#L44-L51) +- GitHub Release creation failure + - Check `GITHUB_TOKEN` permissions and repository visibility; confirm that CHANGELOG content can be parsed. + - Reference path: [scripts/create-tag-n-release.mts:88-115](file://scripts/create-tag-n-release.mts#L88-L115) + +**Section Sources** + +- [docs/app.py:10](file://docs/app.py#L10) +- [scripts/publish-to-pypi.mts:22-30](file://scripts/publish-to-pypi.mts#L22-L30) +- [scripts/publish-to-pypi.mts:44-51](file://scripts/publish-to-pypi.mts#L44-L51) +- [scripts/create-tag-n-release.mts:88-115](file://scripts/create-tag-n-release.mts#L88-L115) + +## Conclusion + +ModelScope Studio adopts a "documentation-driven + Monorepo + CI/CD automation" development model. The frontend is centered on Svelte and Gradio ecosystem, while the backend packages templates through a Python package and releases to PyPI. Through unified lint configuration and workflows, the team can collaborate efficiently while maintaining quality and consistency. When adding new components, it's recommended to follow existing directory structure and naming conventions to ensure smooth documentation site and release processes. + +## Appendix + +### Local Development and Hot Reload + +- Install dependencies and build + - Reference path: [README.md:82-94](file://README.md#L82-L94) +- Start documentation site (with hot reload) + - Reference path: [package.json:15](file://package.json#L15) +- Version information + - Reference path: [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) + +**Section Sources** + +- [README.md:82-94](file://README.md#L82-L94) +- [package.json:15](file://package.json#L15) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) diff --git a/.wiki/en/Development Guide/Documentation System.md b/.wiki/en/Development Guide/Documentation System.md new file mode 100644 index 00000000..58e137a9 --- /dev/null +++ b/.wiki/en/Development Guide/Documentation System.md @@ -0,0 +1,382 @@ +# Documentation System + + +**Files referenced in this document** +- [docs/app.py](file://docs/app.py) +- [docs/helper/Docs.py](file://docs/helper/Docs.py) +- [docs/helper/Site.py](file://docs/helper/Site.py) +- [docs/helper/parse_markdown.py](file://docs/helper/parse_markdown.py) +- [docs/helper/env.py](file://docs/helper/env.py) +- [docs/components/antd/button/README.md](file://docs/components/antd/button/README.md) +- [docs/components/antd/button/app.py](file://docs/components/antd/button/app.py) +- [docs/layout_templates/chatbot/README.md](file://docs/layout_templates/chatbot/README.md) +- [docs/layout_templates/chatbot/app.py](file://docs/layout_templates/chatbot/app.py) +- [docs/demos/example.py](file://docs/demos/example.py) +- [docs/requirements.txt](file://docs/requirements.txt) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [README.md](file://README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This guide is intended for maintainers and contributors, systematically explaining the architecture and usage of the ModelScope Studio documentation system. It covers the following topics: + +- Overall architecture and build process of the documentation site +- Component documentation generation mechanism (Markdown parsing, example rendering) +- Example management and demo module loading +- Multi-language support and environment variable handling +- Usage of Docs and Site utility classes +- Documentation update workflow and release strategy + +## Project Structure + +The documentation system is located in the `docs` directory, organized by "component/template classification + helper tools": + +- `docs/app.py`: Site entry and routing, menu, tab layout, site assembly +- `docs/helper/`: Documentation parsing and site rendering utilities + - `Docs.py`: Document reading, Markdown parsing, example module loading and rendering + - `Site.py`: Overall site layout, menu interaction, responsive sidebar and content area + - `parse_markdown.py`: Custom Markdown parser supporting demo/file tags + - `env.py`: Environment variable switches (whether in ModelScope Studio environment) +- `docs/components/antd/button/...`: Documentation and standalone example pages for each component +- `docs/layout_templates/chatbot/...`: Layout template example pages +- `docs/demos/example.py`: Example demo script template +- `docs/requirements.txt`: Dependencies required to run the documentation site +- `.github/workflows/publish.yaml`, `lint.yaml`: CI release and code checks +- `package.json`, `pyproject.toml`: Frontend and backend build scripts and packaging configuration +- `README.md`: Project overview and development guidelines + +```mermaid +graph TB +A["docs/app.py
Site Entry and Assembly"] --> B["docs/helper/Site.py
Site Layout and Menu Interaction"] +A --> C["docs/helper/Docs.py
Document Reading and Example Rendering"] +C --> D["docs/helper/parse_markdown.py
Markdown Parser"] +C --> E["docs/helper/env.py
Environment Variable Switches"] +A --> F["docs/components/*/README.md
Component Documentation"] +A --> G["docs/layout_templates/*/README.md
Layout Template Documentation"] +C --> H["docs/demos/*.py
Example Modules"] +``` + +**Diagram Sources** + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [docs/helper/Site.py:1-255](file://docs/helper/Site.py#L1-L255) +- [docs/helper/Docs.py:1-178](file://docs/helper/Docs.py#L1-L178) +- [docs/helper/parse_markdown.py:1-84](file://docs/helper/parse_markdown.py#L1-L84) +- [docs/helper/env.py:1-4](file://docs/helper/env.py#L1-L4) + +**Section Sources** + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-L4) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +## Core Components + +- Docs utility class + - Function: Scans Markdown files and `demos` subdirectory in the same directory; selects Chinese/English documentation based on environment variables; parses Markdown and renders examples; collects example module styles; renders uniformly as Gradio Blocks pages. + - Key points: Supports demo tags (name, position, collapsible, fixed, title) and demo-prefix/demo-suffix injection; supports file tags for inlining external file content. +- Site utility class + - Function: Assembles top-level tabs and sidebar menus; renders corresponding documentation in content area; handles menu switch events; dynamically controls sidebar size and visibility; merges CSS from all example modules. +- Markdown parser + - Function: Lightweight parser based on HTMLParser, recognizing demo/file tags, outputting structured node sequences (text/example) for Docs rendering. +- Environment variable handling + - Function: Controls whether in Studio environment via `MODELSCOPE_ENVIRONMENT`, determining document naming and filtering rules. + +**Section Sources** + +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) +- [docs/helper/Site.py:9-255](file://docs/helper/Site.py#L9-L255) +- [docs/helper/parse_markdown.py:12-84](file://docs/helper/parse_markdown.py#L12-L84) +- [docs/helper/env.py:1-4](file://docs/helper/env.py#L1-L4) + +## Architecture Overview + +The documentation system uses `docs/app.py` as the entry point, with Site responsible for overall layout and menu interaction, and Docs responsible for rendering individual component or template documentation. The Markdown parser converts demo/file tags in documentation into executable rendering instructions, and example modules are dynamically imported by Docs and rendered in the page. + +```mermaid +sequenceDiagram +participant U as "User" +participant APP as "docs/app.py" +participant SITE as "Site.render()" +participant DOCS as "Docs.render()" +participant MD as "parse_markdown.py" +participant DEMO as "Example Module(.py)" +U->>APP : Access documentation site +APP->>SITE : Assemble Tabs/menus/layout +SITE->>DOCS : Render current component/template documentation +DOCS->>MD : Parse demo/file tags in Markdown +MD-->>DOCS : Return structured nodes +DOCS->>DEMO : Dynamically import and call demo.render() +DEMO-->>DOCS : Return render result +DOCS-->>SITE : Return Blocks page +SITE-->>U : Display complete documentation page +``` + +**Diagram Sources** + +- [docs/app.py:577-590](file://docs/app.py#L577-L590) +- [docs/helper/Site.py:41-254](file://docs/helper/Site.py#L41-L254) +- [docs/helper/Docs.py:171-178](file://docs/helper/Docs.py#L171-L178) +- [docs/helper/parse_markdown.py:80-84](file://docs/helper/parse_markdown.py#L80-L84) + +## Detailed Component Analysis + +### Docs Utility Class (Document Rendering) + +- Initialization and file discovery + - Scans `.md` files in the same directory, filtering Chinese/English versions by environment variable; automatically discovers and dynamically imports `.py` example modules in the `demos` subdirectory. +- Markdown parsing + - Uses `parse_markdown` to convert documentation into a node sequence, supporting three node types: text, demo, file. +- Example rendering + - Supports demo tag attributes: name, position, collapsible, fixed, title; supports demo-prefix/demo-suffix for injecting prefix/suffix code; supports file tag for inlining external file content. +- CSS merging + - Iterates through example modules, collecting `css` fields and injecting into the page, solving style loss issues in multi-Blocks scenarios. + +```mermaid +classDiagram +class Docs { ++__init__(file_path) +-_get_filename(filename) +-_remove_formatter(markdown_text) +-_list_demos(dir_path, prefix) +-_get_demo_modules() +-_read_file(relative_path) +-_render_demo(demo_name, prefix, suffix, position, collapsible, fixed, title) +-_render_markdown(markdown_file) ++get_css() ++render(module_name) +} +``` + +**Diagram Sources** + +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) + +**Section Sources** + +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) +- [docs/helper/parse_markdown.py:12-84](file://docs/helper/parse_markdown.py#L12-L84) + +### Site Utility Class (Site Layout) + +- Tabs and menus + - Defines multiple Tabs (Overview, Base Components, Advanced Components, Antd Components, Antdx Components), each Tab can contain inline menus and content areas. +- Event interaction + - Top-level menus and sidebar menus interact; clicking menu items synchronously updates `active_key` and visible content; applies with default sidebar size based on screen width on mount. +- Responsive layout + - Uses Splitter and Layout for adaptive sidebar and content area; hides sidebar on small screen devices and provides inline menus. +- CSS injection + - Merges CSS from all example modules to ensure example styles take effect. + +```mermaid +classDiagram +class Site { ++__init__(tabs, docs, default_active_tab, logo) +-_render_docs(items, tab) ++render() +} +``` + +**Diagram Sources** + +- [docs/helper/Site.py:9-255](file://docs/helper/Site.py#L9-L255) + +**Section Sources** + +- [docs/helper/Site.py:9-255](file://docs/helper/Site.py#L9-L255) + +### Markdown Parser (demo/file tags) + +- Supported tags + - demo: Contains attributes like name, position, collapsible, fixed, title; used to identify example modules to render. + - demo-prefix/demo-suffix: Used to inject additional code snippets before/after demo. + - file: Inline reads file content from specified path and inserts at current position. +- Parsing flow + - Based on HTMLParser, outputs non-allowed tags as-is; constructs corresponding nodes when demo/file tags are encountered; maintains tag stack for correct closing. + +```mermaid +flowchart TD +Start(["Start Parsing"]) --> Feed["Feed content segment by segment"] +Feed --> Tag{"Encounter tag?"} +Tag --> |No| AppendText["Append to current text node"] +Tag --> |Yes| Allowed{"Is allowed tag?"} +Allowed --> |No| OutputRaw["Output tag text as-is"] +Allowed --> |Yes| HandleDemo["Handle demo tag
name/position/collapsible/fixed/title"] +Allowed --> |Yes| HandleFile["Handle file tag
read external file content"] +HandleDemo --> Next["Continue parsing"] +HandleFile --> Next +OutputRaw --> Next +AppendText --> Next +Next --> End(["Return node sequence"]) +``` + +**Diagram Sources** + +- [docs/helper/parse_markdown.py:12-84](file://docs/helper/parse_markdown.py#L12-L84) + +**Section Sources** + +- [docs/helper/parse_markdown.py:12-84](file://docs/helper/parse_markdown.py#L12-L84) + +### Environment Variables and Multi-language Support + +- Environment variables + - When `MODELSCOPE_ENVIRONMENT=studio`, Chinese documentation and specific filtering logic are enabled; otherwise only English documentation is shown. +- Document naming and filtering + - Chinese documentation files end with `-zh_CN.md`; English documentation has no suffix; Docs filters available documentation files based on environment variables during initialization. + +**Section Sources** + +- [docs/helper/env.py:1-4](file://docs/helper/env.py#L1-L4) +- [docs/helper/Docs.py:17-31](file://docs/helper/Docs.py#L17-L31) + +### Component Documentation and Example Management + +- Component documentation + - Each component directory contains `README.md` and `app.py`; README.md uses demo tags to reference example modules; `app.py` renders the component's documentation page via Docs. +- Example modules + - `.py` files are placed in the `demos` directory; Docs dynamically imports and calls their `demo.render()` method for rendering; you can define `css` strings in example modules to inject styles. +- Layout templates + - Reusable page layout examples are provided under the `layout_templates` directory, also rendered via `app.py` and Docs. + +```mermaid +sequenceDiagram +participant DOC as "Component README.md" +participant DOCS as "Docs" +participant DEMO as "Example Module(.py)" +DOC->>DOCS : Parse demo tags +DOCS->>DEMO : Dynamically import and execute demo.render() +DEMO-->>DOCS : Return render result +DOCS-->>DOC : Render to page +``` + +**Diagram Sources** + +- [docs/components/antd/button/README.md:1-8](file://docs/components/antd/button/README.md#L1-L8) +- [docs/components/antd/button/app.py:1-7](file://docs/components/antd/button/app.py#L1-L7) +- [docs/helper/Docs.py:82-161](file://docs/helper/Docs.py#L82-L161) + +**Section Sources** + +- [docs/components/antd/button/README.md:1-8](file://docs/components/antd/button/README.md#L1-L8) +- [docs/components/antd/button/app.py:1-7](file://docs/components/antd/button/app.py#L1-L7) +- [docs/layout_templates/chatbot/README.md:1-20](file://docs/layout_templates/chatbot/README.md#L1-L20) +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +## Dependency Analysis + +- Runtime dependencies + - `docs/requirements.txt` specifies gradio and modelscope_studio versions, ensuring documentation site compatibility with the component library. +- Build and scripts + - `package.json` provides dev/build/publish scripts; `pyproject.toml` defines backend packaging and artifact manifest. +- CI workflows + - `publish.yaml`: Installs dependencies, builds, and publishes to PyPI on branch push, creates tags and releases. + - `lint.yaml`: Executes code style and formatting checks. + +```mermaid +graph LR +R["docs/requirements.txt"] --> APP["docs/app.py"] +PJ["package.json"] --> APP +PY["pyproject.toml"] --> APP +WF1[".github/workflows/publish.yaml"] --> APP +WF2[".github/workflows/lint.yaml"] --> APP +``` + +**Diagram Sources** + +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-L4) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) + +**Section Sources** + +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-L4) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) + +## Performance Considerations + +- CSS injection in multi-Blocks scenarios + - Site merges CSS from all example modules to avoid style loss caused by repeated injection in multiple Blocks. +- Example module lazy loading + - Docs only dynamically imports example modules when needed, reducing memory footprint at startup. +- Responsive layout optimization + - Sidebar size dynamically adjusts based on screen width, improving mobile experience. + +**Section Sources** + +- [docs/helper/Site.py:55-73](file://docs/helper/Site.py#L55-L73) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) +- [docs/helper/Site.py:241-249](file://docs/helper/Site.py#L241-L249) + +## Troubleshooting Guide + +- Documentation not showing Chinese or English incorrectly + - Check whether `MODELSCOPE_ENVIRONMENT` is set to `studio` or not set; confirm README file naming follows `-zh_CN.md` convention. +- Examples not rendering or throwing errors + - Confirm that corresponding `.py` files exist in the `demos` directory and contain `demo.render()`; check if example modules can be dynamically imported. +- Page style abnormalities + - Confirm that example modules have defined `css` strings; Site will merge these styles; if still abnormal, check if multiple Blocks cause styles not being injected. +- Startup failure or port occupied + - Use the dev script in `package.json` to start; ensure port is not occupied; if necessary, set `ssr_mode=false` in launch parameters. + +**Section Sources** + +- [docs/helper/env.py:1-4](file://docs/helper/env.py#L1-L4) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) +- [docs/helper/Site.py:55-73](file://docs/helper/Site.py#L55-L73) +- [README.md:32-32](file://README.md#L32-L32) +- [package.json:15-15](file://package.json#L15-L15) + +## Conclusion + +The ModelScope Studio documentation system, through the Docs and Site utility classes combined with a custom Markdown parser and example module dynamic loading mechanism, achieves unified rendering and multi-language support for component documentation and layout templates. With clear directory structure and CI workflow, maintainers can efficiently extend documentation content, add examples, and publish updates. + +## Appendix + +### Usage and Maintenance Guide (Operation Steps) + +- Write component documentation + - Add `README.md` under `docs/components/
package.json / pnpm-workspace.yaml"] --> Frontend["Frontend Workspace
frontend/*"] +Root --> Config["Config Workspace
config/*"] +Root --> Backend["Backend Python Package
backend/modelscope_studio"] +Docs["Documentation Examples
docs/app.py"] --> Backend +Docs --> Frontend +``` + +**Diagram Sources** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +**Section Sources** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [README.md:80-101](file://README.md#L80-L101) + +## Core Components + +- Root-level scripts and toolchain: Commands for build, development, formatting, validation, etc. are defined via `package.json`. +- pnpm workspace: Unified management of frontend sub-packages and configuration packages, ensuring dependency version consistency and incremental builds. +- Python build and packaging: Uses hatchling as the build backend, supporting source distribution and wheel distribution. +- Documentation site: Based on Gradio's `docs/app.py`, provides component demonstrations and navigation. +- Frontend project: Vite + Svelte 5, with custom plugins and type configurations. + +**Section Sources** + +- [package.json:8-25](file://package.json#L8-L25) +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/app.py:577-595](file://docs/app.py#L577-L595) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## Architecture Overview + +The diagram below shows the overall process from cloning the repository to starting the documentation site during development: + +```mermaid +flowchart TD +A["Clone Repository"] --> B["Install Backend Dependencies
pip install -e '.'"] +B --> C["Install pnpm
npm install pnpm -g"] +C --> D["Install Frontend Dependencies
pnpm install"] +D --> E["Build Project
pnpm build"] +E --> F["Start Development Server
gradio cc dev docs/app.py"] +F --> G["Access Documentation Site in Browser"] +``` + +**Diagram Sources** + +- [README.md:82-101](file://README.md#L82-L101) +- [package.json:8-16](file://package.json#L8-L16) +- [docs/app.py:592-595](file://docs/app.py#L592-L595) + +## Detailed Component Analysis + +### System Requirements and Prerequisites + +- Python + - Minimum version for local development: Python 3.8+ + - CI/CD release environment: Python 3.12 (specified by `.github/workflows/publish.yaml`) + - Recommended to use virtual environment for dependency isolation +- Node.js + - Minimum version: Node.js 18.0+, recommended 20+ or newer + - Uses pnpm as package manager; recommend installing pnpm globally +- Operating System + - Linux/macOS/Windows all supported, be aware of path separator and permission differences +- Optional: Docker (for twine upload in the release process) + +**Section Sources** + +- [pyproject.toml:15](file://pyproject.toml#L15) +- [README.md:82-101](file://README.md#L82-L101) + +### Clone and Initialize + +- Clone the repository locally +- Execute backend editable install in the root directory to make the Python environment recognize `backend/modelscope_studio` +- Install pnpm globally +- Execute `pnpm install` in the root directory to install all workspace dependencies +- Execute `pnpm build` to complete frontend build + +**Section Sources** + +- [README.md:82-101](file://README.md#L82-L101) +- [package.json:8-16](file://package.json#L8-L16) + +### Backend Dependency Installation (Python) + +- Use editable install to integrate `backend/modelscope_studio` into the current Python environment +- Python version must meet the minimum requirements in `pyproject.toml` +- For release process, refer to the twine upload steps in the release script + +**Section Sources** + +- [pyproject.toml:15](file://pyproject.toml#L15) +- [scripts/publish-to-pypi.mts:22-42](file://scripts/publish-to-pypi.mts#L22-L42) + +### Frontend Dependency Installation and Build + +- pnpm workspace contains multiple frontend sub-packages and configuration packages; unified installation avoids version conflicts +- Frontend project uses Vite and Svelte 5; `defineConfig.js` provides plugin and preprocessing configuration +- `tsconfig.json` and `svelte-tsconfig.json` provide type checking and path alias configuration + +**Section Sources** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) +- [tsconfig.json:1-33](file://tsconfig.json#L1-L33) +- [svelte-tsconfig.json:1-4](file://svelte-tsconfig.json#L1-L4) + +### Development Server Startup and Verification + +- Use `gradio cc dev docs/app.py` to start the documentation site +- The documentation site will automatically scan example applications under `docs/components` and `docs/layout_templates` +- Access the default address (output by Gradio) to view component demonstrations and navigation + +**Section Sources** + +- [README.md:96-101](file://README.md#L96-L101) +- [docs/app.py:10,19-61,577-595](file://docs/app.py#L10,L19-L61,L577-L595) + +### Release and Packaging (Optional) + +- The release script first executes `pip install -e '.'` and `pnpm run build`, then checks if `dist` exists +- If the version does not exist on PyPI, it calls `twine` to upload `dist/*` artifacts + +**Section Sources** + +- [scripts/publish-to-pypi.mts:14-55](file://scripts/publish-to-pypi.mts#L14-L55) + +## Dependency Analysis + +- Root-level dependencies + - Build and scripts: gradio cc, rimraf, tsx, husky, etc. + - Types and validation: typescript, svelte-check, eslint, stylelint, prettier +- Frontend dependencies + - UI frameworks: antd, @ant-design/x, @ant-design/icons + - React/Svelte: react, react-dom, svelte 5 + - Editors and visualization: monaco-editor, @monaco-editor/react, mermaid, katex +- Python dependencies + - Core: gradio (version range constraint) + - Build: hatchling, hatch-requirements-txt, hatch-fancy-pypi-readme + - Optional: openai (used in documentation examples) + +```mermaid +graph LR +RootPkg["Root package.json"] --> Scripts["Build and Scripts"] +RootPkg --> Linters["Types and Validation"] +FrontPkg["frontend/package.json"] --> UI["UI Frameworks"] +FrontPkg --> Runtime["React/Svelte Runtime"] +FrontPkg --> Editor["Editors and Visualization"] +PyProj["pyproject.toml"] --> Gradio["gradio dependency"] +PyProj --> Build["Build Backend"] +DocsReq["docs/requirements.txt"] --> OpenAI["openai example dependency"] +``` + +**Diagram Sources** + +- [package.json:26-52](file://package.json#L26-L52) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [pyproject.toml:2,42-43](file://pyproject.toml#L2,L42-L43) +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-L4) + +**Section Sources** + +- [package.json:26-52](file://package.json#L26-L52) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [pyproject.toml:2,42-43](file://pyproject.toml#L2,L42-L43) +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-L4) + +## Performance Considerations + +- Use pnpm workspace for unified dependency versions, reducing repeated installations and memory footprint +- Frontend build targets ESNext, leveraging modern browser features for improved runtime efficiency +- Documentation site loads component examples on-demand, avoiding loading all resources at once +- In large projects, it's recommended to enable TypeScript's `noEmit` and `svelte-check` to catch type issues early + +## Troubleshooting Guide + +- Backend dependency installation failed + - Confirm Python version meets >=3.8 + - Use virtual environment to avoid global pollution + - Reference the `pip install -e '.'` process in the release script for troubleshooting +- pnpm installation failed or dependencies incompatible + - Clear cache and retry: delete `node_modules` and `pnpm-lock.yaml`, then reinstall + - Confirm pnpm version matches workspace configuration +- Build failed + - Check whether `pnpm build` has been executed + - Confirm that the `dist` directory was generated +- Development server inaccessible + - Confirm `gradio cc dev docs/app.py` has been executed + - Check firewall and port occupation + - If using Hugging Face Space, set `ssr_mode=False` as indicated in README + +**Section Sources** + +- [pyproject.toml:15](file://pyproject.toml#L15) +- [scripts/publish-to-pypi.mts:22-30](file://scripts/publish-to-pypi.mts#L22-L30) +- [README.md:32,96-101](file://README.md#L32,L96-L101) + +## Conclusion + +By following the steps above, you can successfully set up the ModelScope Studio development environment locally, complete backend and frontend dependency installation, build, and documentation site startup. If you encounter issues, you can troubleshoot item by item according to the troubleshooting section of this guide. It's recommended to clear cache and use a virtual environment before making changes to ensure consistency and reproducibility. + +## Appendix + +### Common Commands Quick Reference + +- Clone and Initialize + - `pip install -e '.'` + - `npm install pnpm -g` + - `pnpm install` + - `pnpm build` +- Start Development Server + - `gradio cc dev docs/app.py` +- Format and Validate + - `pnpm run lint` + - `pnpm run format` +- Version and Release (CI) + - `pnpm run version` + - `pnpm run ci:version` + - `pnpm run ci:publish` + +**Section Sources** + +- [README.md:82-101](file://README.md#L82-L101) +- [package.json:8-25](file://package.json#L8-L25) diff --git a/.wiki/en/Development Guide/Testing and Debugging.md b/.wiki/en/Development Guide/Testing and Debugging.md new file mode 100644 index 00000000..996d958d --- /dev/null +++ b/.wiki/en/Development Guide/Testing and Debugging.md @@ -0,0 +1,311 @@ +# Testing and Debugging + + +**Files referenced in this document** +- [package.json](file://package.json) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [pyproject.toml](file://pyproject.toml) +- [tests/test.py](file://tests/test.py) +- [tests/test1.py](file://tests/test1.py) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx) +- [backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py) +- [backend/modelscope_studio/components/pro/monaco_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py) +- [docs/components/pro/web_sandbox/demos/error_handling.py](file://docs/components/pro/web_sandbox/demos/error_handling.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This guide is intended for developers and maintainers of ModelScope Studio, systematically introducing the project's testing and debugging strategies. It covers unit testing, integration testing, and end-to-end test writing and execution methods; debugging techniques, common tool usage, common problem diagnosis and resolution paths, as well as performance testing and optimization recommendations. The documentation is based on existing scripts, workflows, and examples in the repository to ensure operability and traceability. + +## Project Structure + +ModelScope Studio is a third-party component library based on Gradio, with a separated frontend and backend: the frontend builds components using Svelte (TypeScript), while the backend bridges frontend templates with the Gradio runtime through Python components. Testing and quality assurance mainly rely on the following resources: + +- Scripts and workflows: Automated checks and releases through scripts in `package.json` and GitHub Actions workflows. +- Examples and demos: The `tests` directory contains basic functional demo scripts, while `demos` under `docs` provides more complex interactive scenarios and error handling examples. +- Component implementations: Backend components define interfaces such as `preprocess`/`postprocess`, `example_payload`/`example_value` for testing and verification. + +```mermaid +graph TB +A["package.json
Scripts and Dependencies"] --> B[".github/workflows/lint.yaml
Code Style Check"] +A --> C[".github/workflows/publish.yaml
Build and Release"] +D["tests/test.py
Basic Interaction Example"] --> E["Gradio Application Runtime"] +F["tests/test1.py
Progress and Queue Example"] --> E +G["docs/components/pro/web_sandbox/demos/error_handling.py
Error Handling Demo"] --> E +H["pyproject.toml
Python Package and Build Config"] --> I["Backend Component Implementation
Backend Component Classes"] +J["frontend/.../alert.error-boundary.tsx
Frontend Error Boundary"] --> K["Component Bridging and Rendering"] +I --> K +``` + +**Diagram Sources** + +- [package.json:1-55](file://package.json#L1-L55) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [tests/test.py:1-17](file://tests/test.py#L1-L17) +- [tests/test1.py:1-15](file://tests/test1.py#L1-L15) +- [docs/components/pro/web_sandbox/demos/error_handling.py:1-28](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L28) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +**Section Sources** + +- [package.json:1-55](file://package.json#L1-L55) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +## Core Components + +- Test scripts and demos + - `tests/test.py`: Demonstrates combined usage of Application and ConfigProvider, as well as simple interactions with button click events and input/output. + - `tests/test1.py`: Demonstrates usage of progress bars and queues in Gradio interfaces. +- Error handling and boundaries + - Frontend error boundary: `frontend/antd/alert/error-boundary/alert.error-boundary.tsx` bridges Ant Design's ErrorBoundary to the Svelte component system via `sveltify`. + - Backend error boundary: `backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py` defines an error boundary component with slots support, `skip_api=True` indicates it doesn't directly expose API. +- Integration point examples + - `docs/components/pro/web_sandbox/demos/error_handling.py`: Demonstrates WebSandbox behavior under render errors, compilation errors, and custom compilation error rendering, suitable for end-to-end testing and regression validation. + +**Section Sources** + +- [tests/test.py:1-17](file://tests/test.py#L1-L17) +- [tests/test1.py:1-15](file://tests/test1.py#L1-L15) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:20-72](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L20-L72) +- [docs/components/pro/web_sandbox/demos/error_handling.py:1-28](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L28) + +## Architecture Overview + +The diagram below shows the critical path from test scripts to component rendering and error handling, reflecting testing perspectives at unit level (component interfaces), integration level (frontend-backend bridging), and end-to-end (application runtime). + +```mermaid +sequenceDiagram +participant T as "Test Script
tests/test.py" +participant G as "Gradio Application Runtime" +participant MS as "Backend Component
Application/ConfigProvider" +participant FE as "Frontend Component
ErrorBoundary" +participant RB as "Error Boundary Component
Backend Definition" +T->>G : "Start Blocks and register events" +G->>MS : "Initialize context and components" +MS-->>G : "Render component tree" +G->>FE : "Mount frontend components" +FE-->>G : "Capture and display errors" +MS->>RB : "Backend error boundary configuration" +RB-->>G : "Skip API calls (skip_api=True)" +``` + +**Diagram Sources** + +- [tests/test.py:10-17](file://tests/test.py#L10-L17) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:55-72](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L55-L72) + +## Detailed Component Analysis + +### Unit Testing: Component Interfaces and Data Flow + +- Objectives + - Verify that backend component `preprocess`/`postprocess`, `example_payload`/`example_value` behave as expected. + - Verify that frontend components behave stably in error boundary scenarios. +- Suggested test cases + - For backend components: construct input payload, assert `preprocess` output; construct backend value, assert `postprocess` output; call `example_payload`/`example_value` to get sample data. + - For frontend error boundaries: simulate exception throwing, assert whether the error boundary correctly captures and renders the description. +- Reference implementation locations + - Backend component interface definitions and examples: [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:87-106](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L87-L106) + - Frontend error boundary implementation: [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +```mermaid +flowchart TD +Start(["Start: Prepare test cases"]) --> Prep["Construct input payload or sample data"] +Prep --> Pre["Call preprocess to verify input transformation"] +Pre --> Post["Call postprocess to verify output transformation"] +Post --> Example["Call example_payload/example_value to get samples"] +Example --> FEError["Frontend error boundary: simulate exception and assert rendering"] +FEError --> End(["End: Record results and report"]) +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:87-106](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L87-L106) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +**Section Sources** + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:87-106](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L87-L106) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +### Integration Testing: Frontend-Backend Bridging and Context + +- Objectives + - Verify that the bridging between Python components and frontend templates is correct, and that context (such as Application, ConfigProvider) is effective. +- Suggested test cases + - In test scripts, combine Application and ConfigProvider, trigger component interactions, assert rendering results and state changes. + - Use progress and queue interfaces to verify scheduling and feedback of async tasks. +- Reference implementation locations + - Basic interaction examples: [tests/test.py:10-17](file://tests/test.py#L10-L17) + - Progress and queue examples: [tests/test1.py:6-14](file://tests/test1.py#L6-L14) + +```mermaid +sequenceDiagram +participant U as "Test Case" +participant P as "Python Component
Application/ConfigProvider" +participant R as "Gradio Runtime" +participant F as "Frontend Template Rendering" +U->>P : "Create component instances and context" +P->>R : "Register components and events" +R->>F : "Dispatch rendering instructions" +F-->>R : "Return render results" +R-->>U : "Assert results and state" +``` + +**Diagram Sources** + +- [tests/test.py:10-17](file://tests/test.py#L10-L17) +- [tests/test1.py:6-14](file://tests/test1.py#L6-L14) + +**Section Sources** + +- [tests/test.py:10-17](file://tests/test.py#L10-L17) +- [tests/test1.py:6-14](file://tests/test1.py#L6-L14) + +### End-to-End Testing: Error Handling and Regression Validation + +- Objectives + - Verify WebSandbox stability and recoverability under render errors, compilation errors, and custom compilation error rendering. +- Suggested test cases + - Simulate render error: click button to trigger exception, assert error message appears. + - Simulate compilation error: pass empty template or invalid content, assert compilation error rendering slot is activated. + - Custom compilation error rendering: via slot parameter mapping, assert title and subtitle are correctly displayed. +- Reference implementation locations + - Error handling demo: [docs/components/pro/web_sandbox/demos/error_handling.py:1-28](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L28) + +```mermaid +sequenceDiagram +participant E as "User Interaction" +participant WS as "WebSandbox Component" +participant ER as "Error Boundary/Compilation Error Rendering Slot" +E->>WS : "Trigger render/compile" +WS-->>ER : "Capture exception or compile failure" +ER-->>E : "Display error information and title" +``` + +**Diagram Sources** + +- [docs/components/pro/web_sandbox/demos/error_handling.py:1-28](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L28) + +**Section Sources** + +- [docs/components/pro/web_sandbox/demos/error_handling.py:1-28](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L28) + +## Dependency Analysis + +- Quality and build pipeline + - Lint workflow: Installs Python and Node dependencies, executes unified lint script, covering JS/TS, style, and Python conventions. + - Release workflow: Executes build and release when conditions are met, and creates tags and release notes. +- Package and build configuration + - Python packages are built with hatchling, artifacts list includes numerous component template directories, ensuring packaging completeness. +- Testing and debugging tools + - Gradio provides queue and progress capabilities, suitable for verifying async task scheduling and progress callback performance in test scripts. + - Frontend error boundary components use `sveltify` and ReactSlot to implement slot rendering, facilitating injection of custom error views in tests. + +```mermaid +graph TB +A["lint.yaml
Lint Workflow"] --> B["package.json
lint script"] +C["publish.yaml
Release Workflow"] --> D["package.json
ci:publish script"] +E["pyproject.toml
Build and Packaging Config"] --> F["Backend Component Template Packaging"] +G["tests/test1.py
Progress and Queue"] --> H["Gradio Runtime"] +I["frontend/.../alert.error-boundary.tsx
Error Boundary"] --> J["Component Rendering and Testing"] +``` + +**Diagram Sources** + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [package.json:18-24](file://package.json#L18-L24) +- [pyproject.toml:45-245](file://pyproject.toml#L45-L245) +- [tests/test1.py:6-14](file://tests/test1.py#L6-L14) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +**Section Sources** + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [package.json:18-24](file://package.json#L18-L24) +- [pyproject.toml:45-245](file://pyproject.toml#L45-L245) + +## Performance Considerations + +- Async and queue + - Using Gradio's `queue()` and `Progress` interfaces, you can verify the performance of task scheduling and progress callbacks in test scripts. + - Reference: [tests/test1.py:6-14](file://tests/test1.py#L6-L14) +- Frontend rendering and error boundaries + - Error boundary components should minimize additional rendering overhead to ensure quick degradation and minimal UI display in exception situations. + - Reference: [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- Packaging and templates + - The Python package's artifacts list includes numerous component templates; it's recommended to load only necessary templates during local development to reduce build time. + - Reference: [pyproject.toml:45-245](file://pyproject.toml#L45-L245) + +[This section provides general guidance and does not require specific file analysis] + +## Troubleshooting Guide + +- Common issues and diagnosis + - Render errors: Use the demo in `docs/components/pro/web_sandbox/demos/error_handling.py` to confirm whether the error boundary correctly captures and renders. + - Compilation errors: When templates are empty or have syntax errors, check whether the compilation error rendering slot is activated. + - Slot parameter mapping: If custom error views are not taking effect, check whether parameter mapping is correctly passed to the slot. +- Debugging steps + - Start test scripts, observe console output and page interactions. + - Add logging or minimal rendering to frontend error boundary components to confirm exception paths. + - Use Gradio's queue and progress interfaces to verify response time and stability of async tasks. +- Reference implementation locations + - Error handling demo: [docs/components/pro/web_sandbox/demos/error_handling.py:1-28](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L28) + - Frontend error boundary: [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +**Section Sources** + +- [docs/components/pro/web_sandbox/demos/error_handling.py:1-28](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L28) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +## Conclusion + +Based on the repository's existing scripts, workflows, and examples, this guide provides testing strategies and debugging methods covering unit, integration, and end-to-end testing. During daily development, it's recommended to: + +- Write unit tests centered on component interfaces and data flow; +- Write integration tests centered on context and event-driven interactions; +- Write end-to-end tests centered on error handling and interaction regression; +- Use Gradio's queue and progress capabilities for performance validation; +- Use GitHub Actions workflows to ensure code quality and release consistency. + +[This section is a summary and does not require specific file analysis] + +## Appendix + +- Run test suite + - Local execution: Refer to scripts in `package.json`, install dependencies first, then run the corresponding test scripts. + - Reference: [package.json:8-24](file://package.json#L8-L24) +- Quality checks and release + - Lint workflow: [lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) + - Release workflow: [publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- Component packaging and templates + - Python package build configuration: [pyproject.toml:45-245](file://pyproject.toml#L45-L245) + +**Section Sources** + +- [package.json:8-24](file://package.json#L8-L24) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [pyproject.toml:45-245](file://pyproject.toml#L45-L245) diff --git a/.wiki/en/Pro Components/Chatbot/Basic Usage.md b/.wiki/en/Pro Components/Chatbot/Basic Usage.md new file mode 100644 index 00000000..03d5c02a --- /dev/null +++ b/.wiki/en/Pro Components/Chatbot/Basic Usage.md @@ -0,0 +1,388 @@ +# Basic Usage + + +**Files Referenced in This Document** +- [frontend/pro/chatbot/Index.svelte](file://frontend/pro/chatbot/Index.svelte) +- [frontend/pro/chatbot/chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) +- [frontend/pro/chatbot/type.ts](file://frontend/pro/chatbot/type.ts) +- [frontend/pro/chatbot/utils.ts](file://frontend/pro/chatbot/utils.ts) +- [frontend/pro/chatbot/message.tsx](file://frontend/pro/chatbot/message.tsx) +- [frontend/pro/chatbot/chatbot-footer.tsx](file://frontend/pro/chatbot/chatbot-footer.tsx) +- [frontend/pro/chatbot/chatbot-header.tsx](file://frontend/pro/chatbot/chatbot-header.tsx) +- [frontend/pro/chatbot/messages/text.tsx](file://frontend/pro/chatbot/messages/text.tsx) +- [frontend/pro/chatbot/messages/file.tsx](file://frontend/pro/chatbot/messages/file.tsx) +- [frontend/pro/chatbot/messages/suggestion.tsx](file://frontend/pro/chatbot/messages/suggestion.tsx) +- [frontend/pro/chatbot/messages/tool.tsx](file://frontend/pro/chatbot/messages/tool.tsx) +- [docs/layout_templates/chatbot/README-zh_CN.md](file://docs/layout_templates/chatbot/README-zh_CN.md) +- [docs/layout_templates/chatbot/app.py](file://docs/layout_templates/chatbot/app.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This chapter is aimed at beginners and introduces the basic concepts and core capabilities of the Chatbot component to help you quickly get started and build your first chatbot application. The Chatbot component provides message display, user interaction, welcome guidance, scroll behavior control, Markdown rendering, attachment display, suggestion prompts, and tool state expand/collapse functionality. Through a unified message data model and configurable role styles, you can flexibly customize the appearance and interaction of user and bot messages. + +## Project Structure + +The Chatbot component is located in the frontend Pro block, using Svelte as the bridge layer, with React components as the core implementation internally. It uses Ant Design X's Bubble.List to host message rendering and interaction. Message content supports multiple types: text, tool state (collapsible), file, and suggestion prompts; the bottom action area supports copy, like/dislike, retry, edit, and delete actions; the top title supports Markdown rendering; the welcome area supports guide text and suggestion prompts. + +```mermaid +graph TB +A["Index.svelte
Bridge layer"] --> B["chatbot.tsx
Main container and logic"] +B --> C["message.tsx
Message dispatcher"] +C --> C1["messages/text.tsx
Text rendering"] +C --> C2["messages/tool.tsx
Tool state collapse"] +C --> C3["messages/file.tsx
File card"] +C --> C4["messages/suggestion.tsx
Suggestion prompts"] +B --> D["chatbot-header.tsx
Title rendering"] +B --> E["chatbot-footer.tsx
Action area"] +B --> F["utils.ts
Utility functions"] +B --> G["type.ts
Type definitions"] +``` + +Diagram sources + +- [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [frontend/pro/chatbot/chatbot-header.tsx:1-23](file://frontend/pro/chatbot/chatbot-header.tsx#L1-L23) +- [frontend/pro/chatbot/chatbot-footer.tsx:1-363](file://frontend/pro/chatbot/chatbot-footer.tsx#L1-L363) +- [frontend/pro/chatbot/utils.ts:1-157](file://frontend/pro/chatbot/utils.ts#L1-L157) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/messages/text.tsx:1-19](file://frontend/pro/chatbot/messages/text.tsx#L1-L19) +- [frontend/pro/chatbot/messages/tool.tsx:1-46](file://frontend/pro/chatbot/messages/tool.tsx#L1-L46) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/pro/chatbot/messages/suggestion.tsx:1-37](file://frontend/pro/chatbot/messages/suggestion.tsx#L1-L37) + +Section sources + +- [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) + +## Core Components + +- Main container Chatbot: Responsible for message list rendering, scroll control, welcome area, Markdown configuration, user/bot role configuration, and event callbacks (copy, edit, delete, like/dislike, retry, suggestion selection, welcome prompt selection). +- Message dispatcher Message: Dispatches to corresponding sub-components for rendering based on message content type (text/tool/file/suggestion). +- Top title ChatbotHeader: Supports Markdown rendering in titles. +- Bottom action area ChatbotFooter: Uniformly handles copy, like/dislike, retry, edit, delete, and other actions, supporting disable and confirmation dialogs. +- Utility functions utils: Provides avatar resolution, message content normalization, copy text extraction, and suggestion content traversal. +- Type definitions type: Defines message body, role configuration, Markdown configuration, file/suggestion/tool content configuration, and event data structures. +- Sub-message components: Text, tool state (collapsible), file card, suggestion prompts. + +Section sources + +- [frontend/pro/chatbot/chatbot.tsx:51-475](file://frontend/pro/chatbot/chatbot.tsx#L51-L475) +- [frontend/pro/chatbot/message.tsx:25-184](file://frontend/pro/chatbot/message.tsx#L25-L184) +- [frontend/pro/chatbot/chatbot-header.tsx:6-23](file://frontend/pro/chatbot/chatbot-header.tsx#L6-L23) +- [frontend/pro/chatbot/chatbot-footer.tsx:34-363](file://frontend/pro/chatbot/chatbot-footer.tsx#L34-L363) +- [frontend/pro/chatbot/utils.ts:19-157](file://frontend/pro/chatbot/utils.ts#L19-L157) +- [frontend/pro/chatbot/type.ts:27-197](file://frontend/pro/chatbot/type.ts#L27-L197) + +## Architecture Overview + +The diagram below shows the overall flow from the bridge layer to the React main container, then to message rendering and interaction: + +```mermaid +sequenceDiagram +participant UI as "Index.svelte
Bridge layer" +participant CB as "Chatbot
Main container" +participant MSG as "Message
Dispatcher" +participant HDR as "ChatbotHeader
Title" +participant FTR as "ChatbotFooter
Action area" +participant UTIL as "utils.ts
Utility functions" +UI->>CB : Pass props.value, config, callbacks +CB->>UTIL : Resolve avatar/copy text/content normalization +CB->>HDR : Render title (Markdown supported) +CB->>MSG : Render message content (text/tool/file/suggestion) +MSG-->>FTR : Trigger actions (copy/like/retry/edit/delete) +FTR-->>CB : Callback events (onCopy/onLike/onRetry/onEdit/onDelete) +CB-->>UI : onValueChange updates message array +``` + +Diagram sources + +- [frontend/pro/chatbot/Index.svelte:64-89](file://frontend/pro/chatbot/Index.svelte#L64-L89) +- [frontend/pro/chatbot/chatbot.tsx:107-472](file://frontend/pro/chatbot/chatbot.tsx#L107-L472) +- [frontend/pro/chatbot/message.tsx:39-184](file://frontend/pro/chatbot/message.tsx#L39-L184) +- [frontend/pro/chatbot/chatbot-header.tsx:11-22](file://frontend/pro/chatbot/chatbot-header.tsx#L11-L22) +- [frontend/pro/chatbot/chatbot-footer.tsx:255-362](file://frontend/pro/chatbot/chatbot-footer.tsx#L255-L362) +- [frontend/pro/chatbot/utils.ts:46-140](file://frontend/pro/chatbot/utils.ts#L46-L140) + +## Detailed Component Analysis + +### Main Container Chatbot (Properties and Behavior) + +- Key Properties + - Size and layout: height, minHeight, maxHeight + - Scroll behavior: autoScroll, showScrollToBottomButton, scrollToBottomButtonOffset + - Role configuration: userConfig, botConfig (including avatar, styles, class names, actions, disabled actions, etc.) + - Content configuration: markdownConfig (whether to render Markdown, root path, theme mode, etc.) + - Welcome configuration: welcomeConfig (welcome text, icon, suggestion prompts, etc.) + - Data and callbacks: value (message array), onValueChange, onChange, onCopy, onEdit, onDelete, onLike, onRetry, onSuggestionSelect, onWelcomePromptSelect +- Behavior Characteristics + - Auto-scroll to bottom and "scroll to bottom" button + - Welcome area placeholder and guidance + - Interactions: copy, like/dislike, retry, edit, delete + - Markdown rendering and theme adaptation + - Message indexing and last message marking + +```mermaid +classDiagram +class Chatbot { ++props : rootUrl, apiPrefix, themeMode ++props : role, autoScroll, showScrollToBottomButton, scrollToBottomButtonOffset ++props : height, minHeight, maxHeight ++props : userConfig, botConfig, markdownConfig, welcomeConfig ++props : value, onValueChange, onChange ++props : onCopy, onEdit, onDelete, onLike, onRetry ++props : onSuggestionSelect, onWelcomePromptSelect +} +class Message { ++props : index, isEditing, isLastMessage, markdownConfig, message ++props : rootUrl, apiPrefix, onEdit, onSuggestionSelect +} +class ChatbotFooter { ++props : isEditing, index, editValues, message ++props : actions, disabledActions, extra ++props : onCopy, onEdit, onDelete, onRetry, onLike +} +class ChatbotHeader { ++props : markdownConfig, title +} +Chatbot --> Message : "Render messages" +Chatbot --> ChatbotFooter : "Render bottom actions" +Chatbot --> ChatbotHeader : "Render title" +``` + +Diagram sources + +- [frontend/pro/chatbot/chatbot.tsx:51-107](file://frontend/pro/chatbot/chatbot.tsx#L51-L107) +- [frontend/pro/chatbot/message.tsx:25-49](file://frontend/pro/chatbot/message.tsx#L25-L49) +- [frontend/pro/chatbot/chatbot-footer.tsx:34-51](file://frontend/pro/chatbot/chatbot-footer.tsx#L34-L51) +- [frontend/pro/chatbot/chatbot-header.tsx:6-14](file://frontend/pro/chatbot/chatbot-header.tsx#L6-L14) + +Section sources + +- [frontend/pro/chatbot/chatbot.tsx:51-475](file://frontend/pro/chatbot/chatbot.tsx#L51-L475) + +### Message Content Types and Rendering + +- Text messages: Supports Markdown toggle and Markdown parameter pass-through +- Tool messages: Supports title and status (in-progress/complete), defaults to collapse incomplete items +- File messages: Supports image/video/audio preview cards, auto-resolves accessible links +- Suggestion messages: Supports multi-level prompts, automatically disabled when not the last message + +```mermaid +flowchart TD +Start(["Enter Message rendering"]) --> Normalize["Normalize message content"] +Normalize --> IsEditing{"In edit mode?"} +IsEditing --> |Yes| RenderEdit["Render edit input"] +IsEditing --> |No| TypeSwitch{"Content type check"} +TypeSwitch --> |text| RenderText["Render text (Markdown supported)"] +TypeSwitch --> |tool| RenderTool["Render tool state (collapsible)"] +TypeSwitch --> |file| RenderFile["Render file card"] +TypeSwitch --> |suggestion| RenderSuggest["Render suggestion prompt (can be disabled)"] +RenderText --> End(["Done"]) +RenderTool --> End +RenderFile --> End +RenderSuggest --> End +RenderEdit --> End +``` + +Diagram sources + +- [frontend/pro/chatbot/message.tsx:52-175](file://frontend/pro/chatbot/message.tsx#L52-L175) +- [frontend/pro/chatbot/messages/text.tsx:11-18](file://frontend/pro/chatbot/messages/text.tsx#L11-L18) +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) +- [frontend/pro/chatbot/messages/file.tsx:44-118](file://frontend/pro/chatbot/messages/file.tsx#L44-L118) +- [frontend/pro/chatbot/messages/suggestion.tsx:16-36](file://frontend/pro/chatbot/messages/suggestion.tsx#L16-L36) + +Section sources + +- [frontend/pro/chatbot/message.tsx:25-184](file://frontend/pro/chatbot/message.tsx#L25-L184) +- [frontend/pro/chatbot/messages/text.tsx:1-19](file://frontend/pro/chatbot/messages/text.tsx#L1-L19) +- [frontend/pro/chatbot/messages/tool.tsx:1-46](file://frontend/pro/chatbot/messages/tool.tsx#L1-L46) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/pro/chatbot/messages/suggestion.tsx:1-37](file://frontend/pro/chatbot/messages/suggestion.tsx#L1-L37) + +### Welcome Area and Suggestion Prompts + +- Welcome area: Displayed when there are no messages, supports custom styles, avatar, guide text, and suggestion prompts +- Suggestion prompts: Click enabled only for the last message; automatically disabled for other messages to prevent accidental triggers + +Section sources + +- [frontend/pro/chatbot/chatbot.tsx:306-328](file://frontend/pro/chatbot/chatbot.tsx#L306-L328) +- [frontend/pro/chatbot/messages/suggestion.tsx:16-36](file://frontend/pro/chatbot/messages/suggestion.tsx#L16-L36) + +### Action Area Interaction (Copy/Like/Retry/Edit/Delete) + +- Copy: Extracts copyable text based on content type, supports JSON-serializing file links +- Like/Dislike: Updates feedback status in message meta, supports cancellation +- Retry: Triggers the external onRetry callback +- Edit: Enters edit mode, supports sequential editing of multiple content segments, writes back after confirmation +- Delete: Removes the corresponding message + +```mermaid +sequenceDiagram +participant U as "User" +participant F as "ChatbotFooter" +participant C as "Chatbot" +participant M as "Message" +U->>F : Click "copy/like/retry/edit/delete" +alt Copy +F->>C : onCopy({index, value}) +else Like/Dislike +F->>C : onLike({index, value, liked}) +C->>C : Update message meta.feedback +else Retry +F->>C : onRetry({index, value}) +else Edit +F->>C : Enter edit mode +U->>M : Modify input +M-->>F : onEdit(index, value) +F->>C : onEdit({index, value, previous_value}) +C->>C : onValueChange replaces content +else Delete +F->>C : onDelete({index, value}) +C->>C : onValueChange removes message +end +``` + +Diagram sources + +- [frontend/pro/chatbot/chatbot-footer.tsx:102-362](file://frontend/pro/chatbot/chatbot-footer.tsx#L102-L362) +- [frontend/pro/chatbot/chatbot.tsx:195-245](file://frontend/pro/chatbot/chatbot.tsx#L195-L245) +- [frontend/pro/chatbot/utils.ts:74-103](file://frontend/pro/chatbot/utils.ts#L74-L103) + +Section sources + +- [frontend/pro/chatbot/chatbot-footer.tsx:34-363](file://frontend/pro/chatbot/chatbot-footer.tsx#L34-L363) +- [frontend/pro/chatbot/chatbot.tsx:172-245](file://frontend/pro/chatbot/chatbot.tsx#L172-L245) +- [frontend/pro/chatbot/utils.ts:74-140](file://frontend/pro/chatbot/utils.ts#L74-L140) + +## Dependency Analysis + +- Bridge layer: Index.svelte uses importComponent to dynamically import React components and passes props, slots, and shared context (rootUrl, apiPrefix, theme). +- Main container: chatbot.tsx depends on Ant Design X's Bubble.List and Antd components, combined with utils and type for rendering and interaction. +- Message sub-components: Each depends on Markdown rendering and Antd components; file messages depend on upload utilities to resolve accessible links. +- Type system: Uniformly defines message body, role configuration, content configuration, and event data to ensure cross-component consistency. + +```mermaid +graph LR +IDX["Index.svelte"] --> CB["chatbot.tsx"] +CB --> MSG["message.tsx"] +MSG --> TXT["messages/text.tsx"] +MSG --> TOOL["messages/tool.tsx"] +MSG --> FIL["messages/file.tsx"] +MSG --> SUG["messages/suggestion.tsx"] +CB --> HDR["chatbot-header.tsx"] +CB --> FTR["chatbot-footer.tsx"] +CB --> UTL["utils.ts"] +CB --> TYP["type.ts"] +``` + +Diagram sources + +- [frontend/pro/chatbot/Index.svelte:12-87](file://frontend/pro/chatbot/Index.svelte#L12-L87) +- [frontend/pro/chatbot/chatbot.tsx:1-49](file://frontend/pro/chatbot/chatbot.tsx#L1-L49) +- [frontend/pro/chatbot/message.tsx:1-25](file://frontend/pro/chatbot/message.tsx#L1-L25) + +Section sources + +- [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) + +## Performance Considerations + +- Message list optimization: Uses useMemo and shallow comparison to reduce re-renders; triggers onChange only when value changes. +- Scroll control: useScroll provides smooth scrolling and button show/hide to avoid frequent DOM calculations. +- Content normalization: normalizeMessageContent uniformly wraps strings/arrays/objects to reduce branching complexity. +- Markdown rendering: Renders on demand, supports disabling Markdown to reduce overhead. +- File links: Lazy resolution and caching strategy to avoid repeated computation of accessible URLs. + +Section sources + +- [frontend/pro/chatbot/chatbot.tsx:117-183](file://frontend/pro/chatbot/chatbot.tsx#L117-L183) +- [frontend/pro/chatbot/utils.ts:46-72](file://frontend/pro/chatbot/utils.ts#L46-L72) + +## Troubleshooting Guide + +- Messages not displaying or blank + - Check whether value is empty; if empty, the welcome area placeholder will be displayed + - Confirm message content type and options configuration are correct +- Copy not working + - Check whether the content is copyable (some types are not copyable by default) + - Confirm rootUrl and apiPrefix are correct to generate accessible links +- File cannot open + - Confirm the file URL or path has been correctly resolved to an accessible address +- Scroll abnormal + - Adjust autoScroll and scrollToBottomButtonOffset parameters + - Ensure the container height is set reasonably (height/minHeight/maxHeight) +- Action buttons not working + - Check actions and disabled_actions configuration + - Confirm callback functions (onCopy/onLike/onRetry/onEdit/onDelete) are bound + +Section sources + +- [frontend/pro/chatbot/chatbot.tsx:433-468](file://frontend/pro/chatbot/chatbot.tsx#L433-L468) +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) +- [frontend/pro/chatbot/messages/file.tsx:18-42](file://frontend/pro/chatbot/messages/file.tsx#L18-L42) + +## Conclusion + +The Chatbot component provides complete chat message rendering and interaction capabilities through a clear type system and modular design. With a unified configuration and callback mechanism, you can quickly build a chat interface with welcome guidance, message editing, file and suggestion prompts, and Markdown rendering. It is recommended to start with the minimal working demo and progressively extend role styles and interaction actions for a better user experience. + +## Appendix + +### Getting Started Example (Step-by-step) + +- Create a minimal chat interface + - Prepare an empty message array as the initial value + - Set the container height and scroll behavior + - Bind onValueChange to receive message changes + - Optional: Configure userConfig/botConfig to control avatar and styles +- Add the first message + - Add a user message to the message array (role=user) + - When the bot replies, insert an assistant message (role=assistant) +- Start the application + - Run the application using the startup method in the documentation template + +Section sources + +- [docs/layout_templates/chatbot/README-zh_CN.md:1-20](file://docs/layout_templates/chatbot/README-zh_CN.md#L1-L20) +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) + +### Common Properties and Parameter Descriptions + +- Size and scroll + - height/minHeight/maxHeight: Container size control + - autoScroll: Whether to auto-scroll to the bottom + - showScrollToBottomButton/scrollToBottomButtonOffset: Bottom button show/hide and offset +- Role configuration + - userConfig/botConfig: Avatar, styles, class names, actions, disabled actions, extra header/footer content +- Content configuration + - markdownConfig: Whether to render Markdown, root path, theme mode, etc. + - welcomeConfig: Welcome text, icon, suggestion prompts, etc. +- Event callbacks + - onValueChange: Message array changes + - onCopy/onEdit/onDelete/onLike/onRetry: Corresponding action callbacks + - onSuggestionSelect/onWelcomePromptSelect: Suggestion and welcome prompt selection callbacks + +Section sources + +- [frontend/pro/chatbot/chatbot.tsx:51-107](file://frontend/pro/chatbot/chatbot.tsx#L51-L107) +- [frontend/pro/chatbot/type.ts:86-119](file://frontend/pro/chatbot/type.ts#L86-L119) +- [frontend/pro/chatbot/type.ts:27-41](file://frontend/pro/chatbot/type.ts#L27-L41) diff --git a/.wiki/en/Pro Components/Chatbot/Chatbot.md b/.wiki/en/Pro Components/Chatbot/Chatbot.md new file mode 100644 index 00000000..6a439415 --- /dev/null +++ b/.wiki/en/Pro Components/Chatbot/Chatbot.md @@ -0,0 +1,348 @@ +# Chatbot + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) +- [frontend/pro/chatbot/chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) +- [frontend/pro/chatbot/type.ts](file://frontend/pro/chatbot/type.ts) +- [frontend/pro/chatbot/message.tsx](file://frontend/pro/chatbot/message.tsx) +- [frontend/pro/chatbot/utils.ts](file://frontend/pro/chatbot/utils.ts) +- [frontend/pro/chatbot/hooks/useScroll.ts](file://frontend/pro/chatbot/hooks/useScroll.ts) +- [docs/layout_templates/chatbot/README.md](file://docs/layout_templates/chatbot/README.md) +- [docs/layout_templates/chatbot/app.py](file://docs/layout_templates/chatbot/app.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is aimed at developers who need to build intelligent chat applications on the model platform. It systematically describes the design and implementation of the Chatbot component, covering the following core capabilities: + +- Message processing: Supports multiple content types including text, tool, file, and suggestion; supports message states (such as pending) and feedback markers. +- Multimodal support: Unified message content normalization and rendering, supporting file upload, preview, and download link generation. +- Thinking chain display: Presents reasoning and decision-making processes through tool messages and suggestion prompts combined with Markdown rendering. +- Tool invocation: Message content can embed tool execution results, supporting state management and title annotation. +- Configuration system: Provides welcome page, Markdown rendering, user and bot message style, and behavior configuration. + +The document also provides complete usage examples, internal architecture and message flow mechanism descriptions, performance optimization recommendations, and solutions to common issues. + +## Project Structure + +The Chatbot component consists of a backend Python data class and frontend React/Svelte dual implementations, adopting a layered design of "data class definition + frontend rendering": + +- Backend: Defines message data models, pre/post-processing logic, and static resource service encapsulation. +- Frontend: Renders messages using @ant-design/x's Bubble list, dispatches to specific message components by content type, and provides interactions such as scroll, edit, copy, like/dislike, and retry. + +```mermaid +graph TB +subgraph "Backend" +PY_INIT["Python data classes and components
backend/modelscope_studio/components/pro/chatbot/__init__.py"] +end +subgraph "Frontend" +TS_CHATBOT["React component Chatbot
frontend/pro/chatbot/chatbot.tsx"] +TS_TYPE["Type definitions and configuration interfaces
frontend/pro/chatbot/type.ts"] +TS_MESSAGE["Message content dispatcher
frontend/pro/chatbot/message.tsx"] +TS_UTILS["Message content normalization and update utilities
frontend/pro/chatbot/utils.ts"] +TS_SCROLL["Scroll control hook
frontend/pro/chatbot/hooks/useScroll.ts"] +end +PY_INIT --> TS_CHATBOT +TS_TYPE --> TS_CHATBOT +TS_CHATBOT --> TS_MESSAGE +TS_MESSAGE --> TS_UTILS +TS_CHATBOT --> TS_SCROLL +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [frontend/pro/chatbot/chatbot.tsx:51-475](file://frontend/pro/chatbot/chatbot.tsx#L51-L475) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/message.tsx:25-184](file://frontend/pro/chatbot/message.tsx#L25-L184) +- [frontend/pro/chatbot/utils.ts:46-103](file://frontend/pro/chatbot/utils.ts#L46-L103) +- [frontend/pro/chatbot/hooks/useScroll.ts](file://frontend/pro/chatbot/hooks/useScroll.ts) + +**Section sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:1-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L1-L495) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [frontend/pro/chatbot/utils.ts:46-103](file://frontend/pro/chatbot/utils.ts#L46-L103) +- [frontend/pro/chatbot/hooks/useScroll.ts](file://frontend/pro/chatbot/hooks/useScroll.ts) + +## Core Components + +- Backend Component: ModelScopeProChatbot + - Defines message data models and configuration items, responsible for message content preprocessing, postprocessing, and static resource path conversion. + - Provides event binding (change, copy, edit, delete, like, retry, suggestion_select, welcome_prompt_select). +- Frontend Component: Chatbot (React) + - Maps message arrays to @ant-design/x's Bubble list, rendering by role and content type. + - Supports interactions including auto-scroll, scroll-to-bottom button, edit, copy, like/dislike, delete, retry, suggestion selection, and welcome prompt selection. +- Types and Configuration: type.ts + - Defines interfaces for welcome page, Markdown, user/bot configuration, message body, action objects, content types, and options. +- Message Dispatcher: message.tsx + - Normalizes message content and dispatches to text, tool, file, and suggestion message components by type. +- Utility Functions: utils.ts + - Normalizes message content, batch updates content values, supports mixed string/array/object structures. +- Scroll Control: useScroll.ts + - Controls list scroll and "scroll to bottom" button display threshold logic. + +**Section sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L284) +- [frontend/pro/chatbot/chatbot.tsx:51-475](file://frontend/pro/chatbot/chatbot.tsx#L51-L475) +- [frontend/pro/chatbot/type.ts:27-197](file://frontend/pro/chatbot/type.ts#L27-L197) +- [frontend/pro/chatbot/message.tsx:25-184](file://frontend/pro/chatbot/message.tsx#L25-L184) +- [frontend/pro/chatbot/utils.ts:46-103](file://frontend/pro/chatbot/utils.ts#L46-L103) +- [frontend/pro/chatbot/hooks/useScroll.ts](file://frontend/pro/chatbot/hooks/useScroll.ts) + +## Architecture Overview + +The diagram below shows the overall flow from backend data classes to frontend rendering, as well as the event callback propagation path. + +```mermaid +sequenceDiagram +participant Backend as "Backend Component
ModelScopeProChatbot" +participant Frontend as "Frontend Component
Chatbot" +participant Message as "Message Dispatcher
Message" +participant Utils as "Utility Functions
utils.ts" +Backend->>Frontend : "value : ChatbotMessages" +Frontend->>Frontend : "Parse config and message array" +Frontend->>Message : "Render messages one by one" +Message->>Utils : "Normalize message content" +Utils-->>Message : "Standardized content array" +Message-->>Frontend : "Return corresponding content component" +Frontend-->>Backend : "Event callbacks: copy/edit/delete/like/retry/suggestion/welcome" +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:418-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L418-L495) +- [frontend/pro/chatbot/chatbot.tsx:176-472](file://frontend/pro/chatbot/chatbot.tsx#L176-L472) +- [frontend/pro/chatbot/message.tsx:52-184](file://frontend/pro/chatbot/message.tsx#L52-L184) +- [frontend/pro/chatbot/utils.ts:46-103](file://frontend/pro/chatbot/utils.ts#L46-L103) + +## Detailed Component Analysis + +### Backend Component: ModelScopeProChatbot + +- Data Model + - ChatbotDataMessage: Defines fields for message role, key, status, content, actions, meta information, etc. + - ChatbotDataMessages: Root message container. + - Configuration classes: ChatbotWelcomeConfig, ChatbotMarkdownConfig, ChatbotUserConfig, ChatbotBotConfig, ChatbotActionConfig, etc. +- Preprocessing and Postprocessing + - preprocess: Preprocesses file paths and other content in messages for frontend rendering. + - postprocess: Converts file content to FileData, processes avatar and static resource paths. +- Event Binding + - EVENTS: Binds change, copy, edit, delete, like, retry, suggestion_select, welcome_prompt_select, and other events. +- Frontend Directory + - FRONTEND_DIR: Points to the frontend pro/chatbot directory to ensure correct component loading. + +```mermaid +classDiagram +class ModelScopeProChatbot { ++EVENTS ++FRONTEND_DIR ++data_model ++preprocess(payload) ++postprocess(value) +} +class ChatbotDataMessage { ++role ++status ++content ++actions ++meta +} +class ChatbotDataMessages { ++root : ChatbotDataMessage[] +} +class ChatbotWelcomeConfig +class ChatbotMarkdownConfig +class ChatbotUserConfig +class ChatbotBotConfig +class ChatbotActionConfig +ModelScopeProChatbot --> ChatbotDataMessages : "Uses" +ChatbotDataMessages --> ChatbotDataMessage : "Contains" +ModelScopeProChatbot --> ChatbotWelcomeConfig : "Config" +ModelScopeProChatbot --> ChatbotMarkdownConfig : "Config" +ModelScopeProChatbot --> ChatbotUserConfig : "Config" +ModelScopeProChatbot --> ChatbotBotConfig : "Config" +ChatbotUserConfig --> ChatbotActionConfig : "Actions" +ChatbotBotConfig --> ChatbotActionConfig : "Actions" +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L284) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) + +**Section sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L284) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) + +### Frontend Component: Chatbot (React) + +- Role and Rendering + - Uses withRoleItemsContextProvider to provide rendering strategies for different roles (user, bot, system, divider, welcome page). + - Skips system and divider by default, retaining chatbot-internal-welcome, user, and assistant. +- Content Rendering + - Dispatches to text, tool, file, and suggestion components based on message content type. + - Supports edit mode (text/tool only); triggers onValueChange update after editing. +- Interaction Events + - Copy, like/dislike, delete, retry, suggestion selection, welcome prompt selection, and other events are passed to the backend via callbacks. +- Scroll Control + - useScroll controls auto-scroll and the display threshold for the "scroll to bottom" button. + +```mermaid +flowchart TD +Start(["Enter Chatbot rendering"]) --> ResolveConfig["Parse config and message array"] +ResolveConfig --> RoleMap{"Role matching"} +RoleMap --> |chatbot-internal-welcome| RenderWelcome["Render welcome page"] +RoleMap --> |user/assistant| RenderBubble["Render bubble message"] +RenderBubble --> ContentDispatch["Message content dispatch"] +ContentDispatch --> TypeText["Text type"] +ContentDispatch --> TypeTool["Tool type"] +ContentDispatch --> TypeFile["File type"] +ContentDispatch --> TypeSuggestion["Suggestion type"] +RenderWelcome --> End(["Done"]) +TypeText --> End +TypeTool --> End +TypeFile --> End +TypeSuggestion --> End +``` + +**Diagram sources** + +- [frontend/pro/chatbot/chatbot.tsx:107-472](file://frontend/pro/chatbot/chatbot.tsx#L107-L472) +- [frontend/pro/chatbot/message.tsx:52-184](file://frontend/pro/chatbot/message.tsx#L52-L184) + +**Section sources** + +- [frontend/pro/chatbot/chatbot.tsx:51-475](file://frontend/pro/chatbot/chatbot.tsx#L51-L475) +- [frontend/pro/chatbot/message.tsx:25-184](file://frontend/pro/chatbot/message.tsx#L25-L184) + +### Types and Configuration: type.ts + +- Welcome page config ChatbotWelcomeConfig: Supports icon, title, description, extra info, and prompt collections. +- Markdown config ChatbotMarkdownConfig: Controls whether to render, line breaks, LaTeX delimiters, HTML sanitization, etc. +- User/bot config ChatbotUserConfig/ChatbotBotConfig: Action list, disabled actions, avatar, variant, shape, placement, loading state, etc. +- Action object ChatbotActionConfig: Supports Tooltip and Popconfirm. +- Message content types: text, tool, file, suggestion; each type has corresponding option configurations. +- Event data structures: CopyData, EditData, DeleteData, LikeData, RetryData, SuggestionData, WelcomePromptData. + +**Section sources** + +- [frontend/pro/chatbot/type.ts:27-197](file://frontend/pro/chatbot/type.ts#L27-L197) + +### Message Content Normalization and Update: utils.ts + +- normalizeMessageContent: Unifies strings, arrays, and objects into content object arrays for rendering. +- updateContent: Performs batch updates on edited values, supporting mixed string and object structures. + +**Section sources** + +- [frontend/pro/chatbot/utils.ts:46-103](file://frontend/pro/chatbot/utils.ts#L46-L103) + +### Scroll Control: useScroll.ts + +- Controls list scroll to bottom and button display threshold to improve user experience. + +**Section sources** + +- [frontend/pro/chatbot/hooks/useScroll.ts](file://frontend/pro/chatbot/hooks/useScroll.ts) + +## Dependency Analysis + +- Component Export + - The backend exports ProChatbot via components/pro/components.py for direct use by upper-level applications. +- Documentation Templates + - layout_templates/chatbot provides application templates and example entry points for quick demonstration and integration. + +```mermaid +graph LR +BackendInit["Backend initialization
backend/modelscope_studio/components/pro/chatbot/__init__.py"] --> Export["Export component
backend/modelscope_studio/components/pro/components.py"] +Export --> App["Application template entry
docs/layout_templates/chatbot/app.py"] +App --> Demo["Demo page
docs/layout_templates/chatbot/README.md"] +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:386-388](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L386-L388) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) +- [docs/layout_templates/chatbot/README.md:1-20](file://docs/layout_templates/chatbot/README.md#L1-L20) + +**Section sources** + +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [docs/layout_templates/chatbot/README.md:1-20](file://docs/layout_templates/chatbot/README.md#L1-L20) +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) + +## Performance Considerations + +- Message Rendering Optimization + - Uses useMemo to cache configuration parsing and message array conversion to reduce unnecessary re-renders. + - Enables the edit input only for the last message or when in edit state, avoiding full rendering. +- File Processing + - Converts file paths to FileData on the backend; the frontend renders on demand to avoid duplicate requests. +- Scroll Control + - Controls "scroll to bottom" button display via threshold to reduce overhead from frequent scrolling. +- Event Callbacks + - Wraps callbacks with useMemoizedFn to reduce the number of event handler reconstructions. + +## Troubleshooting Guide + +- Messages not displaying or rendering abnormal + - Check whether message content conforms to the ChatbotDataMessage structure, especially the type and options of content. + - Confirm whether the backend postprocess has correctly handled file paths and avatar resources. +- Files cannot be previewed or downloaded + - Confirm the file path is a local file or HTTP address; the backend generates FileData based on the path type. +- Edit function not working + - Confirm the message content type is text or tool, and the editable field is not disabled. +- Scroll button not appearing + - Check autoScroll and scroll_to_bottom_button_offset configuration; confirm the message count and height settings are reasonable. +- Events not triggering + - Confirm the frontend has bound the corresponding event callbacks and the backend EVENTS includes the corresponding event listener. + +**Section sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:418-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L418-L495) +- [frontend/pro/chatbot/chatbot.tsx:176-472](file://frontend/pro/chatbot/chatbot.tsx#L176-L472) +- [frontend/pro/chatbot/message.tsx:37-184](file://frontend/pro/chatbot/message.tsx#L37-L184) + +## Conclusion + +The Chatbot component achieves multimodal message processing, thinking chain display, and tool invocation integration through a clear data model and frontend/backend collaboration. Its configuration system is flexible, its event callbacks are comprehensive, and it is suitable for building high-quality intelligent chat applications in complex conversational scenarios. It is recommended to configure the welcome page, Markdown rendering, and message actions according to business requirements for the best user experience. + +## Appendix + +### Usage Examples and Best Practices + +- Basic Chat + - Initialize ModelScopeProChatbot with an initial message array and basic configuration. + - Listen to events such as change, copy, edit, delete, like, and retry to implement business logic. +- Multimodal Input + - Use the file type of ChatbotDataMessageContent to carry attachment lists; the backend automatically converts them to FileData. + - The frontend previews based on image/video/audioProps in options. +- Tool Integration + - Use the tool type to carry tool execution results; annotate execution status with options.title and status. +- Thinking Chain Display + - Use the suggestion type to provide input suggestions; combine with Markdown rendering to enhance readability. +- Configuration Key Points + - Welcome page: Set icon, title, description, prompts, etc. + - Markdown: Control line breaks, LaTeX delimiters, HTML sanitization, and tag allowlist. + - User/bot: Customize actions, avatar, variant, and placement to improve UI consistency. diff --git a/.wiki/en/Pro Components/Chatbot/Configuration Options.md b/.wiki/en/Pro Components/Chatbot/Configuration Options.md new file mode 100644 index 00000000..4be04b1a --- /dev/null +++ b/.wiki/en/Pro Components/Chatbot/Configuration Options.md @@ -0,0 +1,364 @@ +# Configuration Options + + +**Files Referenced in This Document** +- [frontend/pro/chatbot/type.ts](file://frontend/pro/chatbot/type.ts) +- [frontend/pro/chatbot/chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) +- [frontend/pro/chatbot/message.tsx](file://frontend/pro/chatbot/message.tsx) +- [frontend/pro/chatbot/messages/text.tsx](file://frontend/pro/chatbot/messages/text.tsx) +- [frontend/pro/chatbot/messages/tool.tsx](file://frontend/pro/chatbot/messages/tool.tsx) +- [frontend/pro/chatbot/messages/welcome.tsx](file://frontend/pro/chatbot/messages/welcome.tsx) +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) +- [docs/layout_templates/chatbot/demos/basic.py](file://docs/layout_templates/chatbot/demos/basic.py) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py](file://docs/layout_templates/chatbot/demos/fine_grained_control.py) +- [docs/layout_templates/chatbot/README-zh_CN.md](file://docs/layout_templates/chatbot/README-zh_CN.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This chapter is aimed at developers and product personnel using the Chatbot component, systematically covering frontend and backend configuration options, including `welcome_config`, `markdown_config`, `user_config`, and `bot_config`. It explains the purpose, allowed values, and default behavior of each configuration option, provides configuration examples and typical use cases, explains the relationships and priority between configurations, and offers advanced tips and performance optimization recommendations. + +## Project Structure + +The Chatbot component is composed of a frontend Svelte/React implementation and backend Gradio data class definitions: + +- **Frontend**: Type definitions, rendering logic, message sub-components, welcome message component, etc. +- **Backend**: Data model, event binding, static resource handling, pre/post-processing logic + +```mermaid +graph TB +subgraph "Frontend" +T["type.ts
Types & Config Interfaces"] +C["chatbot.tsx
Main Component & Parsing Logic"] +M["message.tsx
Message Rendering Dispatcher"] +MT["messages/text.tsx
Text Messages"] +MU["messages/tool.tsx
Tool Messages"] +MW["messages/welcome.tsx
Welcome Messages"] +end +subgraph "Backend" +PY["__init__.py
Data Classes & Component Implementation"] +end +T --> C +C --> M +M --> MT +M --> MU +C --> MW +PY --> C +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [frontend/pro/chatbot/messages/text.tsx:1-19](file://frontend/pro/chatbot/messages/text.tsx#L1-L19) +- [frontend/pro/chatbot/messages/tool.tsx:1-46](file://frontend/pro/chatbot/messages/tool.tsx#L1-L46) +- [frontend/pro/chatbot/messages/welcome.tsx:1-55](file://frontend/pro/chatbot/messages/welcome.tsx#L1-L55) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:1-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L1-L495) + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:1-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L1-L495) + +## Core Components + +- **Types and config interfaces**: Define the structure and optional fields of `welcome_config`, `markdown_config`, `user_config`, `bot_config`, and message content objects +- **Main component**: Responsible for merging defaults, parsing configurations, injecting theme and root path, and rendering the message list and welcome area +- **Message rendering**: Dispatches to text, tool, file, suggestion, and other sub-components based on content type +- **Welcome message**: Renders the welcome text and prompt word cards + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:27-158](file://frontend/pro/chatbot/type.ts#L27-L158) +- [frontend/pro/chatbot/chatbot.tsx:51-472](file://frontend/pro/chatbot/chatbot.tsx#L51-L472) +- [frontend/pro/chatbot/message.tsx:25-184](file://frontend/pro/chatbot/message.tsx#L25-L184) +- [frontend/pro/chatbot/messages/welcome.tsx:11-54](file://frontend/pro/chatbot/messages/welcome.tsx#L11-L54) + +## Architecture Overview + +The diagram below illustrates the Chatbot configuration parsing and rendering flow, showing key nodes and dependencies from props to final rendering. + +```mermaid +sequenceDiagram +participant U as "Caller" +participant C as "Chatbot Main Component" +participant R as "Role Resolver" +participant W as "Welcome Message" +participant MSG as "Message Rendering" +participant MD as "Markdown Rendering" +U->>C : Pass welcome_config / markdown_config / user_config / bot_config +C->>C : Parse and merge defaults +C->>R : Inject role mapping and post-processing +R-->>C : Return role-based Bubble.List +C->>W : Render welcome area with prompts +C->>MSG : Render message list +MSG->>MD : Text/tool messages render Markdown as needed +MSG-->>C : Sub-component output +W-->>C : Welcome area output +C-->>U : Complete UI output +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/chatbot.tsx:76-472](file://frontend/pro/chatbot/chatbot.tsx#L76-L472) +- [frontend/pro/chatbot/messages/welcome.tsx:18-54](file://frontend/pro/chatbot/messages/welcome.tsx#L18-L54) +- [frontend/pro/chatbot/message.tsx:39-184](file://frontend/pro/chatbot/message.tsx#L39-L184) +- [frontend/pro/chatbot/messages/text.tsx:11-18](file://frontend/pro/chatbot/messages/text.tsx#L11-L18) +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) + +## Detailed Component Analysis + +### Welcome Configuration (`welcome_config`) + +- **Purpose**: Controls the appearance, text, and prompt word cards of the welcome area +- **Key fields**: + - `variant`: Appearance variant, supports `borderless`, `filled` + - `icon`: Icon, can be a string, path, or file data + - `title`: Title + - `description`: Description + - `extra`: Additional content + - `elem_style` / `elem_classes` / `styles` / `class_names`: Styles and class names + - `prompts`: Collection of prompt word cards (see "Prompt Configuration" below) +- **Default behavior**: + - If not provided, the main component uses `borderless` as the default variant +- **Relationship with prompts**: + - The `prompts` field can nest prompt word card configurations to guide users to quickly get started + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:34-41](file://frontend/pro/chatbot/type.ts#L34-L41) +- [frontend/pro/chatbot/chatbot.tsx:108-115](file://frontend/pro/chatbot/chatbot.tsx#L108-L115) +- [frontend/pro/chatbot/messages/welcome.tsx:24-51](file://frontend/pro/chatbot/messages/welcome.tsx#L24-L51) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:38-50](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L38-L50) + +### Prompt Configuration (`prompts` in `welcome_config`) + +- **Purpose**: Displays a set of prompt word cards in the welcome area to help users quickly start a conversation +- **Key fields**: + - `title`: Title of the prompt area + - `vertical` / `wrap`: Layout direction and wrapping + - `styles` / `class_names` / `elem_style` / `elem_classes`: Styles and class names + - `items`: Array of prompt entries (each entry contains `label`, `description`, `children`, etc.) + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:27-32](file://frontend/pro/chatbot/type.ts#L27-L32) +- [frontend/pro/chatbot/messages/welcome.tsx:41-51](file://frontend/pro/chatbot/messages/welcome.tsx#L41-L51) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:26-36](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L26-L36) + +### Markdown Configuration (`markdown_config`) + +- **Purpose**: Uniformly controls the Markdown rendering behavior in text and tool messages +- **Key fields**: + - `renderMarkdown`: Whether to enable Markdown rendering (frontend) + - `render_markdown`: Whether to enable Markdown rendering (backend) + - `latex_delimiters`: LaTeX delimiter configuration + - `sanitize_html`: Whether to sanitize HTML + - `line_breaks`: Whether to preserve line breaks + - `rtl`: Whether to render right-to-left + - `allow_tags`: Allowed tags or boolean switch +- **Default behavior**: + - Frontend enables `renderMarkdown` by default and sets the line break strategy + - Backend enables rendering, HTML sanitization, line breaks, and multiple LaTeX delimiter groups by default + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:54-56](file://frontend/pro/chatbot/type.ts#L54-L56) +- [frontend/pro/chatbot/message.tsx:87-95](file://frontend/pro/chatbot/message.tsx#L87-L95) +- [frontend/pro/chatbot/messages/tool.tsx:14-18](file://frontend/pro/chatbot/messages/tool.tsx#L14-L18) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:52-106](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L52-L106) + +### User Configuration (`user_config`) + +- **Purpose**: Controls the appearance, avatar, action buttons, and styles of user message bubbles +- **Key fields**: + - `actions`: Action button list, supports `copy`, `edit`, `delete`; or objects with `tooltip`/`popconfirm` + - `disabled_actions`: Set of disabled actions + - `header` / `footer`: Header and footer text + - `avatar`: Avatar, can be a string, file data, or avatar property object + - `variant` / `shape` / `placement`: Appearance, shape, and position + - `loading` / `typing`: Loading and typing effects + - `elem_style` / `elem_classes` / `styles` / `class_names`: Styles and class names +- **Default behavior**: + - Only the `copy` action is enabled by default (backend default) + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:86-97](file://frontend/pro/chatbot/type.ts#L86-L97) +- [frontend/pro/chatbot/chatbot.tsx:246-432](file://frontend/pro/chatbot/chatbot.tsx#L246-L432) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:117-151](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L117-L151) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:123-131](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L123-L131) + +### Bot Configuration (`bot_config`) + +- **Purpose**: Controls the appearance, avatar, action buttons, and styles of bot message bubbles +- **Key fields**: + - `actions`: Action button list, supports `copy`, `like`, `dislike`, `retry`, `edit`, `delete`; or objects with `tooltip`/`popconfirm` + - `disabled_actions`: Set of disabled actions + - `header` / `footer`: Header and footer text + - `avatar`: Avatar + - `variant` / `shape` / `placement`: Appearance, shape, and position + - `loading` / `typing`: Loading and typing effects + - `elem_style` / `elem_classes` / `styles` / `class_names`: Styles and class names +- **Default behavior**: + - The `copy` action is enabled by default (backend default) + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:108-119](file://frontend/pro/chatbot/type.ts#L108-L119) +- [frontend/pro/chatbot/chatbot.tsx:246-432](file://frontend/pro/chatbot/chatbot.tsx#L246-L432) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:153-180](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L153-L180) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:162-170](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L162-L170) + +### Message Content and Rendering (Message Types and Options) + +- **Content types**: + - `text`: Plain text or Markdown text + - `tool`: Tool message, collapsible display with title and content + - `file`: File list, supports image/video/audio properties + - `suggestion`: Suggestion list, supports disabled state and click callbacks +- **Content options**: + - Text/tool: Inherits Markdown configuration; tool messages support `title` and `status` (`pending`/`done`) + - File: Inherits Flex layout configuration, supports `imageProps`/`videoProps`/`audioProps` + - Suggestion: Inherits prompt configuration +- **Edit and copyable**: + - Editing can be controlled via `content.options.editable` + - Copying can be controlled via `content.options.copyable` + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:43-68](file://frontend/pro/chatbot/type.ts#L43-L68) +- [frontend/pro/chatbot/type.ts:121-135](file://frontend/pro/chatbot/type.ts#L121-L135) +- [frontend/pro/chatbot/message.tsx:52-174](file://frontend/pro/chatbot/message.tsx#L52-L174) +- [frontend/pro/chatbot/messages/text.tsx:11-18](file://frontend/pro/chatbot/messages/text.tsx#L11-L18) +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) + +### Configuration Priority and Merge Rules + +- **Main component parsing order**: + - `welcome_config`: Uses `borderless` as the default variant; other fields are overridden by what is passed in + - `markdown_config`: Frontend enables line breaks and rendering by default; backend enables rendering and sanitization by default + - `user_config` / `bot_config`: Overridden by what is passed in; defaults to empty object if not provided + - Message-level configuration: `message.options` merges with global `markdown_config`; `message.options` takes priority +- **Avatar and static resources**: + - The backend wraps `avatar` and `welcome.icon` as static resources to ensure accessibility +- **Role and styles**: + - The main component applies different styles and class names based on role (`user`/`assistant`/`chatbot-internal-welcome`) + +**Section Sources** + +- [frontend/pro/chatbot/chatbot.tsx:108-136](file://frontend/pro/chatbot/chatbot.tsx#L108-L136) +- [frontend/pro/chatbot/chatbot.tsx:246-432](file://frontend/pro/chatbot/chatbot.tsx#L246-L432) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:363-380](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L363-L380) + +### Configuration Examples and Use Cases + +- **Basic example**: + - Use `welcome_config` to set title, description, and prompt word cards + - Use `user_config`/`bot_config` to configure action buttons and avatars + - Reference: [basic.py:516-564](file://docs/layout_templates/chatbot/demos/basic.py#L516-L564) +- **Fine-grained control example**: + - Custom role rendering, message state, and feedback buttons + - Reference: [fine_grained_control.py:575-800](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L575-L800) +- **Use cases**: + - Instant assistant: Enable copy, like/dislike, retry, delete actions + - Multi-turn conversation: Combine session list with message state management + - Multimedia input: Combine file upload with file message rendering + +**Section Sources** + +- [docs/layout_templates/chatbot/demos/basic.py:516-564](file://docs/layout_templates/chatbot/demos/basic.py#L516-L564) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py:575-800](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L575-L800) +- [docs/layout_templates/chatbot/README-zh_CN.md:1-20](file://docs/layout_templates/chatbot/README-zh_CN.md#L1-L20) + +## Dependency Analysis + +- **Component coupling**: + - The main component depends on type definitions and message sub-components; message sub-components depend on Markdown rendering + - Welcome messages depend on the prompt component and file URL handling +- **External dependencies**: + - Ant Design X (Welcome, Prompts, Bubble.List) + - Ant Design (Avatar, Button, Collapse, Flex, etc.) + - Global Markdown component and file upload utilities + +```mermaid +graph LR +Chatbot["chatbot.tsx"] --> Types["type.ts"] +Chatbot --> Msg["message.tsx"] +Msg --> Text["messages/text.tsx"] +Msg --> Tool["messages/tool.tsx"] +Chatbot --> Welcome["messages/welcome.tsx"] +Chatbot --> ADX["Ant Design X Components"] +Chatbot --> AD["Ant Design Components"] +Chatbot --> GlobalMD["Global Markdown Component"] +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/chatbot.tsx:26-47](file://frontend/pro/chatbot/chatbot.tsx#L26-L47) +- [frontend/pro/chatbot/message.tsx:10-23](file://frontend/pro/chatbot/message.tsx#L10-L23) +- [frontend/pro/chatbot/messages/text.tsx:2-4](file://frontend/pro/chatbot/messages/text.tsx#L2-L4) +- [frontend/pro/chatbot/messages/tool.tsx:3-4](file://frontend/pro/chatbot/messages/tool.tsx#L3-L4) +- [frontend/pro/chatbot/messages/welcome.tsx:3-6](file://frontend/pro/chatbot/messages/welcome.tsx#L3-L6) + +## Performance Considerations + +- **Rendering optimization**: + - Use `elem_style` / `styles` and `class_names` judiciously to avoid excessive reflows + - Tool messages use collapse to reduce initial rendering overhead +- **Resource handling**: + - Avatars and welcome icons are served via the static resource service to avoid repeated transfers +- **Interaction throttling**: + - Debounce/throttle frequently triggered events (e.g., scroll, edit) (implemented at the parent application level) +- **Memory and state**: + - For long conversations, consider limiting the number of messages or adopting pagination/lazy loading strategies + +## Troubleshooting Guide + +- **Welcome icon not displayed**: + - Check whether `welcome_config.icon` is a valid path or file data; confirm that the static resource service is enabled +- **Markdown rendering issues**: + - Frontend: check the `renderMarkdown` switch; Backend: check `render_markdown` and `sanitize_html` +- **Action buttons not working**: + - Confirm that `actions` and `disabled_actions` are correctly configured; use `tooltip`/`popconfirm` dialogs as needed +- **File message cannot be previewed**: + - Check file path and MIME type; confirm that the post-processing stage has converted to `FileData` + +**Section Sources** + +- [frontend/pro/chatbot/messages/welcome.tsx:32-38](file://frontend/pro/chatbot/messages/welcome.tsx#L32-L38) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:363-380](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L363-L380) +- [frontend/pro/chatbot/messages/tool.tsx:14-18](file://frontend/pro/chatbot/messages/tool.tsx#L14-L18) + +## Conclusion + +With systematic configuration options and clear priority rules, the Chatbot component can flexibly adapt to various business scenarios. In real-world projects, it is recommended to: + +- Clearly define the boundaries of responsibility for each configuration option to avoid redundant overrides +- Centralize Markdown and style configurations globally, with local fine-tuning +- Apply collapse/lazy loading strategies for multimedia and long text content +- Use fine-grained control examples as a basis for secondary encapsulation in complex interaction scenarios + +## Appendix + +- **Quick Reference Table**: + - `welcome_config`: `variant` / `icon` / `title` / `description` / `extra` / `prompt` + - `markdown_config`: `renderMarkdown` / `render_markdown` / `latex_delimiters` / `sanitize_html` / `line_breaks` / `rtl` / `allow_tags` + - `user_config`: `actions` / `disabled_actions` / `header` / `footer` / `avatar` / `variant` / `shape` / `placement` / `loading` / `typing` / `elem_style` / `elem_classes` / `styles` / `class_names` + - `bot_config`: `actions` / `disabled_actions` / `header` / `footer` / `avatar` / `variant` / `shape` / `placement` / `loading` / `typing` / `elem_style` / `elem_classes` / `styles` / `class_names` + - Message content: `text` / `tool` / `file` / `suggestion`, each supporting `options` and `copyable`/`editable` diff --git a/.wiki/en/Pro Components/Chatbot/Data Model.md b/.wiki/en/Pro Components/Chatbot/Data Model.md new file mode 100644 index 00000000..0385788c --- /dev/null +++ b/.wiki/en/Pro Components/Chatbot/Data Model.md @@ -0,0 +1,441 @@ +# Data Model + + +**Files Referenced in This Document** +- [frontend/pro/chatbot/type.ts](file://frontend/pro/chatbot/type.ts) +- [frontend/pro/chatbot/utils.ts](file://frontend/pro/chatbot/utils.ts) +- [frontend/pro/chatbot/message.tsx](file://frontend/pro/chatbot/message.tsx) +- [frontend/pro/chatbot/messages/text.tsx](file://frontend/pro/chatbot/messages/text.tsx) +- [frontend/pro/chatbot/messages/tool.tsx](file://frontend/pro/chatbot/messages/tool.tsx) +- [frontend/pro/chatbot/messages/file.tsx](file://frontend/pro/chatbot/messages/file.tsx) +- [frontend/pro/chatbot/messages/suggestion.tsx](file://frontend/pro/chatbot/messages/suggestion.tsx) +- [docs/components/pro/chatbot/README.md](file://docs/components/pro/chatbot/README.md) +- [docs/components/pro/chatbot/demos/message_config.py](file://docs/components/pro/chatbot/demos/message_config.py) +- [docs/components/pro/chatbot/demos/chatbot_config.py](file://docs/components/pro/chatbot/demos/chatbot_config.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This chapter focuses on the data model of the Chatbot component, systematically covering message and content data structures, field definitions, rendering behavior, serialization/deserialization paths, and validation and error handling strategies. The key types covered include: + +- `ChatbotMessage`: A single message +- `ChatbotMessages`: An array of messages +- `ChatbotMessageContentObject`: A message content object +- The structure and configuration of four content types: text, tool, file, and suggestion +- The mapping relationship between the frontend rendering pipeline and the backend Python model + +## Project Structure + +Code related to the data model is primarily distributed across the frontend Pro Chatbot component and documentation examples: + +- Type definitions and configuration: `frontend/pro/chatbot/type.ts` +- Message content normalization and copy logic: `frontend/pro/chatbot/utils.ts` +- Single message rendering entry point: `frontend/pro/chatbot/message.tsx` +- Content sub-components: `text.tsx`, `tool.tsx`, `file.tsx`, `suggestion.tsx` +- Documentation and examples (Python backend model): `docs/components/pro/chatbot/README.md`, `demos/*.py` + +```mermaid +graph TB +subgraph "Frontend Types & Rendering" +T["type.ts
Type Definitions"] +U["utils.ts
Content Normalization/Copy/Traversal"] +M["message.tsx
Message Rendering Entry"] +MT["messages/text.tsx"] +MU["messages/tool.tsx"] +MF["messages/file.tsx"] +MS["messages/suggestion.tsx"] +end +subgraph "Documentation & Examples" +D1["README.md
Python Type Definitions"] +E1["demos/message_config.py"] +E2["demos/chatbot_config.py"] +end +T --> M +U --> M +M --> MT +M --> MU +M --> MF +M --> MS +D1 --> E1 +D1 --> E2 +E1 --> M +E2 --> M +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/utils.ts:1-157](file://frontend/pro/chatbot/utils.ts#L1-L157) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [frontend/pro/chatbot/messages/text.tsx:1-19](file://frontend/pro/chatbot/messages/text.tsx#L1-L19) +- [frontend/pro/chatbot/messages/tool.tsx:1-46](file://frontend/pro/chatbot/messages/tool.tsx#L1-L46) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/pro/chatbot/messages/suggestion.tsx:1-37](file://frontend/pro/chatbot/messages/suggestion.tsx#L1-L37) +- [docs/components/pro/chatbot/README.md:80-354](file://docs/components/pro/chatbot/README.md#L80-L354) +- [docs/components/pro/chatbot/demos/message_config.py:1-65](file://docs/components/pro/chatbot/demos/message_config.py#L1-L65) +- [docs/components/pro/chatbot/demos/chatbot_config.py:1-123](file://docs/components/pro/chatbot/demos/chatbot_config.py#L1-L123) + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/utils.ts:1-157](file://frontend/pro/chatbot/utils.ts#L1-L157) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [docs/components/pro/chatbot/README.md:80-354](file://docs/components/pro/chatbot/README.md#L80-L354) + +## Core Components + +This section provides a detailed breakdown of the key types in the data model, including field semantics, allowed values, default behaviors, and usage notes. + +- **ChatbotMessage** (single message) + - Key fields: + - `role`: user, assistant, system, divider, or internal welcome identifier + - `content`: string, content object, or array of content objects; supports multi-segment content composition + - `status`: pending/done; when pending, the action area (action buttons and footer info) is not rendered + - `meta.feedback`: like/dislike feedback state + - `divider_props`, `key`, header/footer/avatar symbol keys: used for rendering and identification + - Usage: + - Construct message lists via `ChatbotDataMessage` on the backend and pass them to the frontend Chatbot component + - Frontend `message.tsx` normalizes `content` to an array of content objects and dispatches to the corresponding sub-component + +- **ChatbotMessages** (message array) + - Type alias: `ChatbotMessage[]` + - Purpose: Carries the complete conversation history as the component's `value` prop + +- **ChatbotMessageContentObject** (message content object) + - Key fields: + - `type`: one of `text`, `tool`, `file`, `suggestion` + - `content`: the actual value for the corresponding type + - `options`: type-specific configuration + - `copyable`, `editable`: whether copying/editing is allowed (only applies to text/tool) + +- **Text content** (`text`) + - Value type: string + - Configuration: Inherits Markdown rendering capabilities (whether to render, tag whitelist, line breaks, RTL, etc.) + - Behavior: Supports copying and editing (when `editable` is true and in an editable context) + +- **Tool content** (`tool`) + - Value type: string + - Configuration: Title, status (`pending`/`done`), Markdown rendering + - Behavior: Determines collapse/expand based on status; supports copying and editing + +- **File content** (`file`) + - Value type: string or array of attachment objects + - Configuration: Flex layout parameters (vertical/wrap/justify/align/gap), as well as image/video/audio card properties + - Behavior: Parses strings or attachments into previewable file cards with link opening support + +- **Suggestion content** (`suggestion`) + - Value type: array of prompt items (Ant Design X Prompts) + - Configuration: Title, vertical layout, wrap, styles, and class names + - Behavior: Renders as a clickable prompt list; interaction is disabled for non-last messages + +- **User/bot configuration** (`ChatbotUserConfig`, `ChatbotBotConfig`) + - Actions: copy, edit, delete (user); copy, like, dislike, retry, edit, delete (bot) + - Header/footer/avatar: supports customization + - Styles: `elem_style`, `elem_classes`, `styles`, `class_names` + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:121-160](file://frontend/pro/chatbot/type.ts#L121-L160) +- [frontend/pro/chatbot/type.ts:137-158](file://frontend/pro/chatbot/type.ts#L137-L158) +- [docs/components/pro/chatbot/README.md:297-352](file://docs/components/pro/chatbot/README.md#L297-L352) + +## Architecture Overview + +The diagram below illustrates the end-to-end flow from "message content" to "concrete rendering", covering frontend type definitions, content normalization, sub-component rendering, and backend model mapping. + +```mermaid +sequenceDiagram +participant Backend as "Backend
ChatbotDataMessage" +participant Frontend as "Frontend
Chatbot" +participant Utils as "Utilities
normalizeMessageContent" +participant Message as "Message Rendering
message.tsx" +participant Text as "Text Component
text.tsx" +participant Tool as "Tool Component
tool.tsx" +participant File as "File Component
file.tsx" +participant Suggest as "Suggestion Component
suggestion.tsx" +Backend->>Frontend : Pass ChatbotDataMessages +Frontend->>Utils : Normalize content +Utils-->>Frontend : Return array of content objects +Frontend->>Message : Render each message +Message->>Text : type="text" +Message->>Tool : type="tool" +Message->>File : type="file" +Message->>Suggest : type="suggestion" +Text-->>Message : Text render result +Tool-->>Message : Collapsed/expanded tool content +File-->>Message : File card rendering +Suggest-->>Message : Prompt list rendering +Message-->>Frontend : Complete message rendering +``` + +**Diagram Sources** + +- [docs/components/pro/chatbot/README.md:321-352](file://docs/components/pro/chatbot/README.md#L321-L352) +- [frontend/pro/chatbot/utils.ts:46-72](file://frontend/pro/chatbot/utils.ts#L46-L72) +- [frontend/pro/chatbot/message.tsx:52-175](file://frontend/pro/chatbot/message.tsx#L52-L175) +- [frontend/pro/chatbot/messages/text.tsx:11-18](file://frontend/pro/chatbot/messages/text.tsx#L11-L18) +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) +- [frontend/pro/chatbot/messages/file.tsx:44-118](file://frontend/pro/chatbot/messages/file.tsx#L44-L118) +- [frontend/pro/chatbot/messages/suggestion.tsx:16-36](file://frontend/pro/chatbot/messages/suggestion.tsx#L16-L36) + +## Detailed Component Analysis + +### Type System and Relationships + +```mermaid +classDiagram +class ChatbotMessage { ++role ++content ++status ++meta ++divider_props ++key +} +class ChatbotMessageContentObject { ++type ++content ++options ++copyable ++editable +} +class ChatbotTextContentConfig +class ChatbotToolContentConfig { ++status ++title +} +class ChatbotFileContentConfig { ++vertical ++wrap ++justify ++align ++gap ++imageProps ++videoProps ++audioProps +} +class ChatbotSuggestionContentConfig +ChatbotMessage --> ChatbotMessageContentObject : "contains" +ChatbotMessageContentObject --> ChatbotTextContentConfig : "options" +ChatbotMessageContentObject --> ChatbotToolContentConfig : "options" +ChatbotMessageContentObject --> ChatbotFileContentConfig : "options" +ChatbotMessageContentObject --> ChatbotSuggestionContentConfig : "options" +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/type.ts:121-160](file://frontend/pro/chatbot/type.ts#L121-L160) +- [frontend/pro/chatbot/type.ts:54-68](file://frontend/pro/chatbot/type.ts#L54-L68) + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:121-160](file://frontend/pro/chatbot/type.ts#L121-L160) + +### Content Normalization and Copy + +- **Normalization rules**: + - String: converted to a single-element content object (`type=text`) + - Array: each item is checked; strings are converted to `text` objects, otherwise the original object is kept + - Other objects: wrapped as a single-element array +- **Copy rules**: + - If content is not copyable (`copyable=false`), returns an empty string + - String: returned directly + - File: serialized as a JSON list of accessible URLs + - Other: serialized as a JSON string +- **Edit update**: + - Supports batch updating content objects or strings by index + +```mermaid +flowchart TD +Start(["Start"]) --> CheckType["Determine content type"] +CheckType --> |String| ToSingle["Wrap as type=text object"] +CheckType --> |Array| MapItems["Map each item: string -> text object"] +CheckType --> |Object| WrapOne["Wrap as single-element array"] +CheckType --> |Other| Empty["Return empty array"] +ToSingle --> End(["End"]) +MapItems --> End +WrapOne --> End +Empty --> End +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/utils.ts:46-72](file://frontend/pro/chatbot/utils.ts#L46-L72) + +**Section Sources** + +- [frontend/pro/chatbot/utils.ts:46-103](file://frontend/pro/chatbot/utils.ts#L46-L103) + +### Text Content Rendering + +- Configuration: whether to render Markdown, LaTeX delimiters, HTML sanitization, line breaks, RTL, allowed tags +- Behavior: displays directly or delegates to the Markdown component based on configuration + +**Section Sources** + +- [frontend/pro/chatbot/messages/text.tsx:11-18](file://frontend/pro/chatbot/messages/text.tsx#L11-L18) +- [docs/components/pro/chatbot/README.md:120-174](file://docs/components/pro/chatbot/README.md#L120-L174) + +### Tool Content Rendering + +- Configuration: title, status (`pending`/`done` controls collapse), Markdown rendering +- Behavior: initializes collapse state based on status; supports click to toggle + +**Section Sources** + +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) +- [docs/components/pro/chatbot/README.md:254-261](file://docs/components/pro/chatbot/README.md#L254-L261) + +### File Content Rendering + +- Value parsing: strings or attachment objects are uniformly parsed to the fields required by the file card (uid/name/url/type/size) +- Configuration: Flex layout and image/video/audio card properties +- Behavior: renders file cards with preview links + +**Section Sources** + +- [frontend/pro/chatbot/messages/file.tsx:18-42](file://frontend/pro/chatbot/messages/file.tsx#L18-L42) +- [frontend/pro/chatbot/messages/file.tsx:44-118](file://frontend/pro/chatbot/messages/file.tsx#L44-L118) +- [docs/components/pro/chatbot/README.md:264-281](file://docs/components/pro/chatbot/README.md#L264-L281) + +### Suggestion Content Rendering + +- Value type: array of prompt items (supports nested `children`) +- Configuration: title, vertical/wrap, styles, and class names +- Behavior: renders as a clickable prompt list; disables interaction for non-last messages + +**Section Sources** + +- [frontend/pro/chatbot/messages/suggestion.tsx:16-36](file://frontend/pro/chatbot/messages/suggestion.tsx#L16-L36) +- [docs/components/pro/chatbot/README.md:284-291](file://docs/components/pro/chatbot/README.md#L284-L291) + +### Serialization and Deserialization Examples + +- **Backend to frontend**: + - Backend constructs message lists using `ChatbotDataMessage`/`ChatbotDataMessages` + - Frontend `message.tsx` receives and calls `normalizeMessageContent` to normalize + - Sub-components are dispatched to render based on `type` +- **Frontend to backend**: + - Copy: `getCopyText` serializes content to a string or JSON + - Edit: `updateContent` updates content objects or strings by index +- **Example references**: + - Basic message configuration and action buttons: [docs/components/pro/chatbot/demos/message_config.py:10-61](file://docs/components/pro/chatbot/demos/message_config.py#L10-L61) + - Welcome prompt and retry: [docs/components/pro/chatbot/demos/chatbot_config.py:43-119](file://docs/components/pro/chatbot/demos/chatbot_config.py#L43-L119) + +**Section Sources** + +- [docs/components/pro/chatbot/demos/message_config.py:10-61](file://docs/components/pro/chatbot/demos/message_config.py#L10-L61) +- [docs/components/pro/chatbot/demos/chatbot_config.py:43-119](file://docs/components/pro/chatbot/demos/chatbot_config.py#L43-L119) +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) +- [frontend/pro/chatbot/utils.ts:74-103](file://frontend/pro/chatbot/utils.ts#L74-L103) + +### Data Validation and Error Handling + +- Role enum validation: `role` must be one of the supported enum values +- Content type validation: `type` must be one of `text`/`tool`/`file`/`suggestion` +- Editability: only enters edit mode when `editable` is true and the type is `text`/`tool` +- Status affects rendering: action area is not rendered when `status=pending` +- Suggestion disabling: interaction is automatically disabled for non-last messages +- Copy protection: copy returns an empty string when `copyable=false` + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:137-158](file://frontend/pro/chatbot/type.ts#L137-L158) +- [frontend/pro/chatbot/type.ts:121-135](file://frontend/pro/chatbot/type.ts#L121-L135) +- [frontend/pro/chatbot/message.tsx:52-175](file://frontend/pro/chatbot/message.tsx#L52-L175) +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) + +## Dependency Analysis + +- **Type dependencies**: + - `ChatbotMessage` depends on `ChatbotMessageContentObject` and configuration types (user/bot) + - Content objects depend on their respective configuration types (text/tool/file/suggestion) +- **Rendering dependencies**: + - `message.tsx` depends on each sub-component (text/tool/file/suggestion) + - `utils.ts` provides content normalization, copy, and traversal capabilities to `message.tsx` +- **Backend mapping**: + - `ChatbotDataMessage`/`ChatbotDataMessages` in `README.md` documentation correspond one-to-one with frontend types + +```mermaid +graph LR +A["ChatbotMessage"] --> B["ChatbotMessageContentObject"] +B --> C["ChatbotTextContentConfig"] +B --> D["ChatbotToolContentConfig"] +B --> E["ChatbotFileContentConfig"] +B --> F["ChatbotSuggestionContentConfig"] +G["message.tsx"] --> B +G --> C +G --> D +G --> E +G --> F +H["utils.ts"] --> G +I["README.md
ChatbotDataMessage"] --> A +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/type.ts:121-160](file://frontend/pro/chatbot/type.ts#L121-L160) +- [frontend/pro/chatbot/message.tsx:52-175](file://frontend/pro/chatbot/message.tsx#L52-L175) +- [frontend/pro/chatbot/utils.ts:46-72](file://frontend/pro/chatbot/utils.ts#L46-L72) +- [docs/components/pro/chatbot/README.md:321-352](file://docs/components/pro/chatbot/README.md#L321-L352) + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:121-160](file://frontend/pro/chatbot/type.ts#L121-L160) +- [frontend/pro/chatbot/message.tsx:52-175](file://frontend/pro/chatbot/message.tsx#L52-L175) +- [frontend/pro/chatbot/utils.ts:46-72](file://frontend/pro/chatbot/utils.ts#L46-L72) +- [docs/components/pro/chatbot/README.md:321-352](file://docs/components/pro/chatbot/README.md#L321-L352) + +## Performance Considerations + +- **Content normalization**: Avoid repeated checks and conversions; construct standardized structures upstream (backend) whenever possible +- **Rendering optimization**: It is recommended to enable virtual scrolling for long lists; apply lazy loading and size constraints for file cards +- **Copy and edit**: Avoid unnecessary re-renders during batch updates; prefer immutable update strategies +- **Markdown rendering**: Configure allowed tags and sanitization policies appropriately to reduce DOM injection risks + +## Troubleshooting Guide + +- **Symptom**: Action buttons not displayed for messages + - Possible cause: `status=pending` + - Fix: Set `status` to `done` or remove the pending state +- **Symptom**: Suggestion items cannot be clicked + - Possible cause: Not the last message + - Fix: Ensure the message is the last one, or disable suggestion items before rendering +- **Symptom**: Copy returns empty + - Possible cause: `copyable=false` or content is not copyable + - Fix: Enable `copyable` or adjust the content type +- **Symptom**: Tool content not collapsed + - Possible cause: `status` not set to `done` + - Fix: Set `status` to `done` to initially collapse + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:137-158](file://frontend/pro/chatbot/type.ts#L137-L158) +- [frontend/pro/chatbot/messages/tool.tsx:13-18](file://frontend/pro/chatbot/messages/tool.tsx#L13-L18) +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) + +## Conclusion + +This document systematically covers the data model of the Chatbot component, clarifying message and content object fields, rendering behavior, and configuration methods, and providing front-to-backend mapping, serialization/deserialization paths, and troubleshooting for common issues. Following the structure and constraints in this document allows you to extend more content types and interaction capabilities while maintaining consistency. + +## Appendix + +- **Example References** + - Basic messages and action buttons: [docs/components/pro/chatbot/demos/message_config.py:10-61](file://docs/components/pro/chatbot/demos/message_config.py#L10-L61) + - Welcome prompt and retry: [docs/components/pro/chatbot/demos/chatbot_config.py:43-119](file://docs/components/pro/chatbot/demos/chatbot_config.py#L43-L119) +- **Type Definition References** + - Python types such as `ChatbotDataMessage`/`ChatbotDataMessages`: [docs/components/pro/chatbot/README.md:297-352](file://docs/components/pro/chatbot/README.md#L297-L352) + - Frontend type definitions: [frontend/pro/chatbot/type.ts:121-160](file://frontend/pro/chatbot/type.ts#L121-L160) diff --git a/.wiki/en/Pro Components/Chatbot/Integration Examples.md b/.wiki/en/Pro Components/Chatbot/Integration Examples.md new file mode 100644 index 00000000..bba2ac88 --- /dev/null +++ b/.wiki/en/Pro Components/Chatbot/Integration Examples.md @@ -0,0 +1,349 @@ +# Integration Examples + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [frontend/pro/chatbot/Index.svelte](file://frontend/pro/chatbot/Index.svelte) +- [frontend/pro/chatbot/package.json](file://frontend/pro/chatbot/package.json) +- [docs/layout_templates/chatbot/README.md](file://docs/layout_templates/chatbot/README.md) +- [docs/layout_templates/chatbot/app.py](file://docs/layout_templates/chatbot/app.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is aimed at developers who need to integrate the Chatbot component into real-world projects, providing complete integration examples and best practices from the backend Python component to the frontend Svelte wrapper layer. Topics covered include: integration methods with Gradio applications, message data models and event binding, connection approaches with external AI services, data interaction strategies with databases, and implementation methods for various typical use cases (customer service bots, Q&A systems, content creation assistants). Deployment guidance, common problem solutions, and performance optimization recommendations are also provided. + +## Project Structure + +The Chatbot component consists of a backend Python component and a frontend Svelte wrapper: + +- **Backend**: A Gradio-based custom component responsible for the message data model, pre/post-processing, static resource hosting, and event binding +- **Frontend**: A Svelte wrapper layer responsible for mapping Gradio properties to the internal chat component and enabling on-demand rendering via async loading + +```mermaid +graph TB +subgraph "Backend" +PY_INIT["Python Component Definition
backend/modelscope_studio/components/pro/chatbot/__init__.py"] +PY_PRO["Export Entry
backend/modelscope_studio/components/pro/components.py"] +end +subgraph "Frontend" +FE_INDEX["Svelte Wrapper Entry
frontend/pro/chatbot/Index.svelte"] +FE_PKG["Package Export Config
frontend/pro/chatbot/package.json"] +end +PY_INIT --> PY_PRO +PY_PRO --> FE_INDEX +FE_INDEX --> FE_PKG +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) +- [frontend/pro/chatbot/package.json:1-15](file://frontend/pro/chatbot/package.json#L1-L15) + +**Section Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) +- [frontend/pro/chatbot/package.json:1-15](file://frontend/pro/chatbot/package.json#L1-L15) + +## Core Components + +- **Message data model and configuration class family**: + - Multiple content type options: text, tool, file, suggestion, etc. + - User/bot message styles, avatars, action buttons, meta information, etc. +- **Main component**: + - Supports height control, auto-scroll, welcome page, Markdown rendering, user/bot configuration + - Event binding: change, copy, edit, delete, like, retry, suggestion_select, welcome_prompt_select +- **Pre-processing and post-processing**: + - Converts message content passed in from the frontend to a format recognized by the backend; converts file paths to Gradio `FileData` and injects MIME types + - Handles avatar and static resource paths + +**Section Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L284) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) + +## Architecture Overview + +The diagram below illustrates the call chain and data flow from the Gradio application to the Chatbot component: + +```mermaid +sequenceDiagram +participant App as "Gradio Application" +participant Py as "Python Component
ModelScopeProChatbot" +participant FE as "Svelte Wrapper
Index.svelte" +participant UI as "Chat Interface" +App->>Py : Initialize component and pass value/config +Py->>FE : Inject properties and event callbacks +FE->>UI : Async load and render Chatbot +UI-->>FE : User interaction events: copy/edit/delete/like/retry/suggestion_select +FE-->>Py : Trigger corresponding event callbacks +Py-->>App : Return processed message list +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-314](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L314) +- [frontend/pro/chatbot/Index.svelte:67-89](file://frontend/pro/chatbot/Index.svelte#L67-L89) + +## Detailed Component Analysis + +### Data Model and Message Structure + +- **Content types**: + - Text, tool (with title and status), file (supports multiple files, auto-injects FileData), suggestion (Prompts) +- **Message object**: + - Role (`user`/`assistant`/`system`/`divider`), key, status (`pending`/`done`), content, actions, meta information +- **Markdown and rendering**: + - Configurable Markdown rendering, LaTeX delimiters, HTML sanitization, line breaks, RTL, allowed tags +- **File display layout**: + - Flex layout parameters (vertical/wrap/justify/align/gap), with separately configurable image/video/audio properties +- **Action buttons**: + - User and bot action sets can be independently configured, supporting Tooltip and confirmation popups + +```mermaid +classDiagram +class ChatbotMarkdownConfig { ++bool render_markdown ++list latex_delimiters ++bool sanitize_html ++bool line_breaks ++bool rtl ++allow_tags +} +class ChatbotActionConfig { ++action ++tooltip ++popconfirm +} +class ChatbotUserConfig { ++actions ++disabled_actions ++avatar ++placement ++typing +} +class ChatbotBotConfig { ++actions ++disabled_actions ++placement +} +class ChatbotDataTextContentOptions +class ChatbotDataToolContentOptions { ++title ++status +} +class ChatbotDataFileContentOptions { ++vertical ++wrap ++justify ++align ++gap +} +class ChatbotDataSuggestionContentOptions +class ChatbotDataSuggestionContentItem +class ChatbotDataMeta { ++feedback +} +class ChatbotDataMessageContent { ++type ++copyable ++editable ++content ++options +} +class ChatbotDataMessage { ++role ++key ++status ++content ++meta +} +ChatbotDataMessage --> ChatbotDataMessageContent : "contains" +ChatbotDataMessageContent --> ChatbotDataTextContentOptions : "optional" +ChatbotDataMessageContent --> ChatbotDataToolContentOptions : "optional" +ChatbotDataMessageContent --> ChatbotDataFileContentOptions : "optional" +ChatbotDataMessageContent --> ChatbotDataSuggestionContentOptions : "optional" +ChatbotDataMessage --> ChatbotDataMeta : "optional" +ChatbotUserConfig <|-- ChatbotBotConfig : "inherits" +ChatbotMarkdownConfig <|-- ChatbotDataTextContentOptions : "inherits" +ChatbotPromptsConfig <|-- ChatbotDataSuggestionContentOptions : "inherits" +ChatbotPromptConfig <|-- ChatbotDataSuggestionContentItem : "inherits" +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L284) + +**Section Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L284) + +### Event Binding and Interaction Flow + +- **Event list**: + - `change`, `copy`, `edit`, `delete`, `like`, `retry`, `suggestion_select`, `welcome_prompt_select` +- **Binding mechanism**: + - Corresponding callbacks are bound at initialization via Gradio event listeners; upon triggering, they update the internal state and return it to the application + +```mermaid +sequenceDiagram +participant UI as "Chat Interface" +participant FE as "Svelte Wrapper" +participant Py as "Python Component" +participant App as "Gradio Application" +UI->>FE : User clicks "Copy/Edit/Delete/Like/Retry" +FE->>Py : Trigger corresponding event (copy/edit/delete/like/retry) +Py-->>App : Callback returns processed message list +App->>Py : May trigger suggestion_select or welcome_prompt_select +Py-->>App : Updated messages and state +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:289-314](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L289-L314) + +**Section Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:289-314](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L289-L314) + +### Pre-Processing and Post-Processing Logic + +- **Pre-processing**: + - Extracts `FileData` paths from file-type content as strings for cross-layer transfer +- **Post-processing**: + - Converts file paths to Gradio `FileData`, auto-infers MIME type and size, supports HTTP/local paths + - Avatar and static resource paths are uniformly processed via `serve_static_file` + +```mermaid +flowchart TD +Start(["Enter preprocess/postprocess"]) --> CheckType{"Input type?"} +CheckType --> |String/Dict| Convert["Convert to standard structure"] +CheckType --> |List/Tuple| MapList["Recursively convert each element"] +Convert --> DonePre["Return normalized message list"] +MapList --> DonePre +DonePre --> PostProcess["Post-processing: convert files to FileData
handle avatar paths"] +PostProcess --> End(["Done"]) +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:400-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L400-L495) + +**Section Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:400-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L400-L495) + +### Integration with Gradio Applications + +- **Export and import**: + - Components are uniformly exposed via the export entry on the backend; the frontend is parsed by Gradio in Svelte wrapper form +- **Property passing**: + - The Svelte wrapper layer passes Gradio shared properties (`root`, `api_prefix`, `theme`) through to the component +- **Example templates**: + - Application templates and demo pages are provided, showcasing multi-conversation management, history operations, interrupt notifications, input suggestions, and file upload features + +**Section Sources** + +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [frontend/pro/chatbot/Index.svelte:14-89](file://frontend/pro/chatbot/Index.svelte#L14-L89) +- [docs/layout_templates/chatbot/README.md:1-20](file://docs/layout_templates/chatbot/README.md#L1-L20) +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) + +## Dependency Analysis + +- **Component coupling**: + - The backend component and frontend wrapper are decoupled via the Gradio protocol; the frontend is only responsible for property mapping and async loading +- **External dependencies**: + - Uses Gradio's data classes and event system; file processing depends on Gradio Client utilities +- **Package export**: + - The frontend package exports the entry point in a Gradio-compatible manner, ensuring it can be used directly in the Gradio ecosystem + +```mermaid +graph LR +PY["Python Component"] --> |events/data| GR["Gradio Protocol"] +GR --> |properties/events| FE["Svelte Wrapper"] +FE --> |rendering| UI["Chat Interface"] +PY --> |file handling| GC["Gradio Client Utilities"] +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [frontend/pro/chatbot/package.json:4-13](file://frontend/pro/chatbot/package.json#L4-L13) + +**Section Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [frontend/pro/chatbot/package.json:4-13](file://frontend/pro/chatbot/package.json#L4-L13) + +## Performance Considerations + +- **Rendering optimization**: + - Use async component loading to avoid blocking the initial render + - Control the number of messages and file sizes; use pagination or lazy loading when necessary +- **Event handling**: + - Throttle or debounce high-frequency events (such as copy/edit) +- **File handling**: + - Prefer using HTTP links to reduce local read overhead; local files auto-calculate size and MIME type +- **Theme and styles**: + - Unified rendering via Gradio shared theme properties reduces redundant computations + +## Troubleshooting Guide + +- **Unable to display file content**: + - Check whether the file path is correct and whether the HTTP link is accessible; confirm that the post-processing stage has converted to `FileData` +- **Avatar not displayed**: + - Confirm that the avatar path has been converted via the static resource handling function +- **Events not triggered**: + - Confirm that event names are spelled consistently and have been bound at initialization +- **Message status is abnormal**: + - `pending` status does not render the action area; check the status setting logic + +**Section Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:390-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L390-L495) + +## Conclusion + +The Chatbot component, with its clear data model, comprehensive event system, and decoupled frontend-backend design, can efficiently support various chat scenarios. Combined with Gradio application templates and the Svelte wrapper layer, developers can quickly build intelligent chat interfaces with multi-turn conversation, history management, file upload, and feedback capabilities, and then extend and optimize from there. + +## Appendix + +### Scenario-Specific Integration Notes + +- **Customer service bot**: + - Use the welcome page and prompts to guide users; enable "retry" and "edit" actions to improve error correction efficiency +- **Q&A system**: + - Use "suggestion select" and "welcome prompt select" to quickly generate questions; enable LaTeX rendering for formula support +- **Content creation assistant**: + - Support multiple file type uploads and display; use "like/feedback" to collect user preferences + +### Deployment and Running + +- **Running example application templates**: + - Use the entry script provided by the documentation template to start queues and services +- **Package export and installation**: + - The frontend package is exported in a Gradio-compatible manner and can be referenced directly in a Gradio environment + +**Section Sources** + +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) +- [frontend/pro/chatbot/package.json:4-13](file://frontend/pro/chatbot/package.json#L4-L13) diff --git a/.wiki/en/Pro Components/Chatbot/Message Processing.md b/.wiki/en/Pro Components/Chatbot/Message Processing.md new file mode 100644 index 00000000..05e9e80f --- /dev/null +++ b/.wiki/en/Pro Components/Chatbot/Message Processing.md @@ -0,0 +1,397 @@ +# Message Processing + + +**Files Referenced in This Document** +- [frontend/pro/chatbot/chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) +- [frontend/pro/chatbot/message.tsx](file://frontend/pro/chatbot/message.tsx) +- [frontend/pro/chatbot/utils.ts](file://frontend/pro/chatbot/utils.ts) +- [frontend/pro/chatbot/type.ts](file://frontend/pro/chatbot/type.ts) +- [frontend/pro/chatbot/chatbot-footer.tsx](file://frontend/pro/chatbot/chatbot-footer.tsx) +- [frontend/pro/chatbot/chatbot-header.tsx](file://frontend/pro/chatbot/chatbot-header.tsx) +- [frontend/pro/chatbot/messages/text.tsx](file://frontend/pro/chatbot/messages/text.tsx) +- [frontend/pro/chatbot/messages/tool.tsx](file://frontend/pro/chatbot/messages/tool.tsx) +- [frontend/pro/chatbot/messages/file.tsx](file://frontend/pro/chatbot/messages/file.tsx) +- [frontend/pro/chatbot/messages/suggestion.tsx](file://frontend/pro/chatbot/messages/suggestion.tsx) +- [frontend/pro/chatbot/messages/welcome.tsx](file://frontend/pro/chatbot/messages/welcome.tsx) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) + +## Introduction + +This chapter covers the message processing capabilities of the Chatbot component, systematically explaining the pre-processing and post-processing mechanisms for messages, content transformation and formatting, event binding and handling (copy, edit, delete, like/dislike, retry, etc.), message state management (pending, done) and real-time update strategies, and provides extensible customization methods and callback usage recommendations. The document is organized in a progressive manner, suitable both for quick onboarding and for in-depth understanding of implementation details. + +## Project Structure + +Message processing code is concentrated in the frontend `pro/chatbot` directory, using a layered design of "container component + message sub-components + utility functions + type definitions": + +- **Container component**: Responsible for message list rendering, event bridging, state management, and scroll control +- **Message sub-components**: Render text, tool output, file attachments, suggestion prompts, and other types +- **Utility functions**: Message content normalization, copy text extraction, edit content update, avatar property parsing, etc. +- **Type definitions**: Unified message structure, action data, configuration items, and callback parameters + +```mermaid +graph TB +Chatbot["Chatbot Container Component
chatbot.tsx"] --> Header["ChatbotHeader
chatbot-header.tsx"] +Chatbot --> Footer["ChatbotFooter
chatbot-footer.tsx"] +Chatbot --> Message["Message Renderer
message.tsx"] +Message --> TextMsg["Text Message
messages/text.tsx"] +Message --> ToolMsg["Tool Message
messages/tool.tsx"] +Message --> FileMsg["File Message
messages/file.tsx"] +Message --> SuggestionMsg["Suggestion Prompt
messages/suggestion.tsx"] +Chatbot --> Utils["Utility Functions
utils.ts"] +Chatbot --> Types["Type Definitions
type.ts"] +Chatbot --> Welcome["Welcome Message
messages/welcome.tsx"] +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [frontend/pro/chatbot/utils.ts:1-157](file://frontend/pro/chatbot/utils.ts#L1-L157) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/chatbot-footer.tsx:1-363](file://frontend/pro/chatbot/chatbot-footer.tsx#L1-L363) +- [frontend/pro/chatbot/chatbot-header.tsx:1-23](file://frontend/pro/chatbot/chatbot-header.tsx#L1-L23) +- [frontend/pro/chatbot/messages/text.tsx:1-19](file://frontend/pro/chatbot/messages/text.tsx#L1-L19) +- [frontend/pro/chatbot/messages/tool.tsx:1-46](file://frontend/pro/chatbot/messages/tool.tsx#L1-L46) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/pro/chatbot/messages/suggestion.tsx:1-37](file://frontend/pro/chatbot/messages/suggestion.tsx#L1-L37) +- [frontend/pro/chatbot/messages/welcome.tsx:1-55](file://frontend/pro/chatbot/messages/welcome.tsx#L1-L55) + +**Section Sources** + +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [frontend/pro/chatbot/utils.ts:1-157](file://frontend/pro/chatbot/utils.ts#L1-L157) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) + +## Core Components + +- **Chatbot container component**: Responsible for message list rendering, scroll control, event bridging (copy, edit, delete, like/dislike, retry, suggestion selection, welcome prompt selection), and message state changes (e.g., feedback marking) +- **Message renderer**: Differentiates rendering based on message content type (text, tool, file, suggestion); supports inline editing of editable content in edit mode +- **Message sub-components**: Handle text Markdown rendering, tool output collapsible panels, file attachment cards, and suggestion prompt lists respectively +- **Utility functions**: Message content normalization, copy text extraction, edit content update, avatar property parsing, suggestion content traversal +- **Type definitions**: Unified message structure, action data, configuration items, and callback parameters to ensure compile-time constraints and IDE hints + +**Section Sources** + +- [frontend/pro/chatbot/chatbot.tsx:51-472](file://frontend/pro/chatbot/chatbot.tsx#L51-L472) +- [frontend/pro/chatbot/message.tsx:25-183](file://frontend/pro/chatbot/message.tsx#L25-L183) +- [frontend/pro/chatbot/utils.ts:46-157](file://frontend/pro/chatbot/utils.ts#L46-L157) +- [frontend/pro/chatbot/type.ts:121-197](file://frontend/pro/chatbot/type.ts#L121-L197) + +## Architecture Overview + +The overall message processing flow is as follows: + +- The input message array is parsed by the container component into Bubble list items, with injected index, header/footer info, avatar properties, and "is last message" markers +- Each message is dispatched by the Message renderer to the corresponding sub-component based on type in the default post-processing stage +- Users trigger copy, edit, delete, like/dislike, and retry events through the bottom action area; the container component passes events and indexes to the parent application via callbacks +- The edit flow uses a two-stage interaction of "edit mode → confirm/cancel"; upon confirmation, the corresponding message content is replaced via an immutable update +- State management records feedback state via the message object's `meta` field, supporting `pending`/`done` states to drive collapsible panels in tool messages + +```mermaid +sequenceDiagram +participant U as "User" +participant CB as "Chatbot Container
chatbot.tsx" +participant MSG as "Message Renderer
message.tsx" +participant FOOT as "Bottom Action Area
chatbot-footer.tsx" +participant UTIL as "Utility Functions
utils.ts" +U->>CB : "Pass message array value" +CB->>CB : "Parse and inject metadata
index/avatar/last message" +CB->>MSG : "Render each message content" +U->>FOOT : "Click copy/edit/delete/like/retry" +FOOT->>CB : "Callback onCopy/onEdit/onDelete/onLike/onRetry" +CB->>UTIL : "On copy: extract plain text/links" +CB->>CB : "On edit: enter edit mode
collect input values" +U->>FOOT : "Confirm edit" +FOOT->>CB : "onEditConfirm({index, value, previous_value})" +CB->>CB : "Immutable update to replace message content" +CB-->>U : "UI refreshes in real time" +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/chatbot.tsx:137-245](file://frontend/pro/chatbot/chatbot.tsx#L137-L245) +- [frontend/pro/chatbot/message.tsx:52-175](file://frontend/pro/chatbot/message.tsx#L52-L175) +- [frontend/pro/chatbot/chatbot-footer.tsx:255-362](file://frontend/pro/chatbot/chatbot-footer.tsx#L255-L362) +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) + +## Detailed Component Analysis + +### Message Pre-Processing and Post-Processing Mechanisms + +- **Pre-processing**: + - Parse the input message array, inject index, header/footer info, avatar properties, "is last message" marker, and generate a unique key for each message + - Merge user/bot configurations, unify styles, class names, element classes, etc. + - Normalize the markdown configuration, inject root path and theme mode +- **Post-processing**: + - Default post-processing stage: render header/body/footer based on role, inject avatar, title, and content renderer + - Content renderer: selects text, tool, file, or suggestion component based on message type + - Edit mode: when a message is in edit mode, editable types (text, tool) display a text area, with input values temporarily stored in `editValues` + +```mermaid +flowchart TD +Start(["Start"]) --> Pre1["Parse input value
Inject index/avatar/last message marker"] +Pre1 --> Pre2["Merge user/bot configurations"] +Pre2 --> Pre3["Normalize markdown configuration"] +Pre3 --> Post1["Default post-processing: role mapping
Inject header/body/footer"] +Post1 --> Render["Content renderer: select sub-component by type"] +Render --> EditCheck{"In edit mode?"} +EditCheck --> |Yes| Edit["Show text area
collect input values"] +EditCheck --> |No| Done(["Done"]) +Edit --> Done +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/chatbot.tsx:137-165](file://frontend/pro/chatbot/chatbot.tsx#L137-L165) +- [frontend/pro/chatbot/chatbot.tsx:246-422](file://frontend/pro/chatbot/chatbot.tsx#L246-L422) +- [frontend/pro/chatbot/message.tsx:52-81](file://frontend/pro/chatbot/message.tsx#L52-L81) + +**Section Sources** + +- [frontend/pro/chatbot/chatbot.tsx:137-165](file://frontend/pro/chatbot/chatbot.tsx#L137-L165) +- [frontend/pro/chatbot/chatbot.tsx:246-422](file://frontend/pro/chatbot/chatbot.tsx#L246-L422) +- [frontend/pro/chatbot/message.tsx:52-81](file://frontend/pro/chatbot/message.tsx#L52-L81) + +### Message Content Transformation, Validation, and Formatting + +- **Normalization**: Uniformly wraps string, array, or object-form content as an array of objects, ensuring consistent downstream rendering +- **Copy text extraction**: Extracts copyable text based on content type and `copyable` flag; file types return a JSON representation of accessible link URLs +- **Edit content update**: Generates a new content structure based on the current content shape (string/array/object) and edit mapping +- **Suggestion content traversal**: Recursively traverses nested suggestions to uniformly set disabled state and other properties + +```mermaid +flowchart TD +In(["Input content"]) --> N1{"String?"} +N1 --> |Yes| N2["Wrap as single-element array
type=text"] +N1 --> |No| N3{"Array?"} +N3 --> |Yes| N4["Map each item: string -> wrap
object -> keep as-is"] +N3 --> |No| N5{"Object?"} +N5 --> |Yes| N6["Wrap as single-element array"] +N5 --> |No| N7["Return empty array"] +N2 --> Out(["Output object array"]) +N4 --> Out +N6 --> Out +N7 --> Out +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/utils.ts:46-72](file://frontend/pro/chatbot/utils.ts#L46-L72) + +**Section Sources** + +- [frontend/pro/chatbot/utils.ts:46-157](file://frontend/pro/chatbot/utils.ts#L46-L157) + +### Message Event Binding and Handling (copy/edit/delete/like/retry) + +- **Copy** (`copy`): + - Triggered by the copy button in the bottom action area; internally calls the copy text extraction function and ultimately triggers the `onCopy` callback +- **Edit** (`edit`): + - After entering edit mode, input values are temporarily stored in `editValues`; upon confirmation, the corresponding message content is replaced via an immutable update and the `onEdit` callback is triggered +- **Delete** (`delete`): + - Triggered by an immutable update that deletes the message item at the corresponding index, and triggers the `onDelete` callback +- **Like/Dislike** (`like`/`dislike`): + - Updates the message's `meta.feedback` field, supports toggling; triggers the `onLike` callback simultaneously +- **Retry** (`retry`): + - Triggers the `onRetry` callback, leaving it to the parent to decide how to handle it + +```mermaid +sequenceDiagram +participant U as "User" +participant FOOT as "Bottom Action Area
chatbot-footer.tsx" +participant CB as "Chatbot Container
chatbot.tsx" +participant UTIL as "Utility Functions
utils.ts" +U->>FOOT : "Click copy/edit/delete/like/retry" +alt Copy +FOOT->>UTIL : "getCopyText(content, root, apiPrefix)" +UTIL-->>FOOT : "Return copyable text" +FOOT->>CB : "onCopy({index, value: text})" +else Edit +FOOT->>CB : "onEdit(index)" +CB->>CB : "setEditIndex(index)" +U->>CB : "Input field changes" +CB->>CB : "setEditValues(collect input)" +U->>FOOT : "Click confirm" +FOOT->>CB : "onEditConfirm({index, value, previous_value})" +CB->>CB : "Immutable update to replace content" +else Delete +FOOT->>CB : "onDelete({index, value})" +CB->>CB : "Immutable delete of that message" +else Like/Dislike +FOOT->>CB : "onLike({index, value, liked})" +CB->>CB : "Update meta.feedback and trigger callback" +else Retry +FOOT->>CB : "onRetry({index, value})" +end +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/chatbot-footer.tsx:53-100](file://frontend/pro/chatbot/chatbot-footer.tsx#L53-L100) +- [frontend/pro/chatbot/chatbot-footer.tsx:255-362](file://frontend/pro/chatbot/chatbot-footer.tsx#L255-L362) +- [frontend/pro/chatbot/chatbot.tsx:195-245](file://frontend/pro/chatbot/chatbot.tsx#L195-L245) +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) + +**Section Sources** + +- [frontend/pro/chatbot/chatbot-footer.tsx:53-100](file://frontend/pro/chatbot/chatbot-footer.tsx#L53-L100) +- [frontend/pro/chatbot/chatbot-footer.tsx:255-362](file://frontend/pro/chatbot/chatbot-footer.tsx#L255-L362) +- [frontend/pro/chatbot/chatbot.tsx:195-245](file://frontend/pro/chatbot/chatbot.tsx#L195-L245) +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) + +### Message State Management (pending, done) and Real-Time Updates + +- **Status field**: Message objects support a `status` field to identify "pending" or "done" states +- **Tool message state linkage**: The tool message component controls the collapsible panel's initial expanded state based on `status` +- **Feedback state**: The message object's `meta.feedback` records user feedback (like/dislike/null), used for UI coloring and state toggling +- **Immutable updates**: Edit confirmation, deletion, and like/dislike all modify the message array via an immutable update strategy, ensuring effective React diff and re-rendering + +```mermaid +stateDiagram-v2 +[*] --> Pending : "status='pending'" +Pending --> Done : "status='done'" +Done --> Pending : "status='pending'" +Done --> FeedbackLike : "User liked" +Done --> FeedbackDislike : "User disliked" +FeedbackLike --> Done : "Like again/cancel" +FeedbackDislike --> Done : "Dislike again/cancel" +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/type.ts:154-157](file://frontend/pro/chatbot/type.ts#L154-L157) +- [frontend/pro/chatbot/messages/tool.tsx:14-18](file://frontend/pro/chatbot/messages/tool.tsx#L14-L18) +- [frontend/pro/chatbot/chatbot.tsx:222-237](file://frontend/pro/chatbot/chatbot.tsx#L222-L237) + +**Section Sources** + +- [frontend/pro/chatbot/type.ts:154-157](file://frontend/pro/chatbot/type.ts#L154-L157) +- [frontend/pro/chatbot/messages/tool.tsx:14-18](file://frontend/pro/chatbot/messages/tool.tsx#L14-L18) +- [frontend/pro/chatbot/chatbot.tsx:222-237](file://frontend/pro/chatbot/chatbot.tsx#L222-L237) + +### Custom Extensions and Callback Usage + +- **Custom rendering**: + - Inject styles, class names, element classes, header/footer content, and avatars via Chatbot's `userConfig`/`botConfig` + - Control Markdown rendering behavior and theme mode via `markdownConfig` +- **Custom actions**: + - `actions`/`disabled_actions` supports enabling/disabling and secondary confirmation for copy, edit, delete, like/dislike, and retry actions + - Actions can include Tooltip and Popconfirm prompts +- **Callback extensions**: + - `onCopy`/`onEdit`/`onDelete`/`onLike`/`onRetry`/`onSuggestionSelect`/`onWelcomePromptSelect` and other callbacks for business integration + - `onValueChange` for receiving the latest value after message array changes, for persistence or further processing + +**Section Sources** + +- [frontend/pro/chatbot/chatbot.tsx:66-107](file://frontend/pro/chatbot/chatbot.tsx#L66-L107) +- [frontend/pro/chatbot/chatbot.tsx:379-400](file://frontend/pro/chatbot/chatbot.tsx#L379-L400) +- [frontend/pro/chatbot/type.ts:79-119](file://frontend/pro/chatbot/type.ts#L79-L119) + +### Message Sub-Components and Rendering Logic + +- **Text messages**: Support Markdown rendering or direct text display +- **Tool messages**: Support Markdown rendering for title and content; state-driven collapsible panel +- **File messages**: Support image/video/audio cards; automatically resolves accessible links +- **Suggestion prompts**: Support multi-level nesting with unified disabled state and click callbacks +- **Welcome messages**: Integrate welcome text and prompt word lists; support icon URL resolution + +**Section Sources** + +- [frontend/pro/chatbot/messages/text.tsx:11-18](file://frontend/pro/chatbot/messages/text.tsx#L11-L18) +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) +- [frontend/pro/chatbot/messages/file.tsx:44-118](file://frontend/pro/chatbot/messages/file.tsx#L44-L118) +- [frontend/pro/chatbot/messages/suggestion.tsx:16-36](file://frontend/pro/chatbot/messages/suggestion.tsx#L16-L36) +- [frontend/pro/chatbot/messages/welcome.tsx:18-54](file://frontend/pro/chatbot/messages/welcome.tsx#L18-L54) + +## Dependency Analysis + +- **Component coupling**: + - Chatbot has strong dependencies on Message, ChatbotHeader, ChatbotFooter, utility functions, and type definitions + - Message has conditional rendering dependencies on each message sub-component + - ChatbotFooter directly calls copy text extraction and content update functions from utility functions +- **External dependencies**: + - Uses Ant Design component library and `@ant-design/x`'s Bubble/List/Prompts/Welcome and other components + - Uses `immer` for immutable updates + - Uses `lodash-es`'s `isEqual`/`omit` and other utility functions + +```mermaid +graph LR +Chatbot["chatbot.tsx"] --> Message["message.tsx"] +Chatbot --> Footer["chatbot-footer.tsx"] +Chatbot --> Header["chatbot-header.tsx"] +Chatbot --> Utils["utils.ts"] +Chatbot --> Types["type.ts"] +Message --> Text["messages/text.tsx"] +Message --> Tool["messages/tool.tsx"] +Message --> File["messages/file.tsx"] +Message --> Suggestion["messages/suggestion.tsx"] +Footer --> Utils +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/chatbot.tsx:20-47](file://frontend/pro/chatbot/chatbot.tsx#L20-L47) +- [frontend/pro/chatbot/message.tsx:6-23](file://frontend/pro/chatbot/message.tsx#L6-L23) +- [frontend/pro/chatbot/chatbot-footer.tsx:32-31](file://frontend/pro/chatbot/chatbot-footer.tsx#L32-L31) + +**Section Sources** + +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [frontend/pro/chatbot/chatbot-footer.tsx:1-363](file://frontend/pro/chatbot/chatbot-footer.tsx#L1-L363) +- [frontend/pro/chatbot/utils.ts:1-157](file://frontend/pro/chatbot/utils.ts#L1-L157) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) + +## Performance Considerations + +- **Immutable updates**: Reduce unnecessary re-renders via immutable update strategy to improve list update efficiency +- **Event memoization**: Wrap callbacks with `useMemoizedFn` to reduce sub-component re-renders caused by reference changes +- **Conditional rendering**: Only render the bottom action area and edit mode UI when needed, avoiding unnecessary DOM structure +- **State minimization**: Edit mode only saves the necessary `editValues` mapping, avoiding redundant state +- **Scroll control**: Use `useScroll` hooks to control scroll button display and scroll behavior, avoiding frequent scroll calculations + +**Section Sources** + +- [frontend/pro/chatbot/chatbot.tsx:172-183](file://frontend/pro/chatbot/chatbot.tsx#L172-L183) +- [frontend/pro/chatbot/chatbot.tsx:433-438](file://frontend/pro/chatbot/chatbot.tsx#L433-L438) +- [frontend/pro/chatbot/chatbot-footer.tsx:273-301](file://frontend/pro/chatbot/chatbot-footer.tsx#L273-L301) + +## Troubleshooting Guide + +- **Copy result is empty**: + - Check whether the content is marked as not copyable (`copyable=false`) or if the content shape doesn't support extraction + - Confirm that `rootUrl` and `apiPrefix` are correct and that file link resolution is available +- **Edit confirmation has no effect**: + - Confirm that the current message is in edit mode (`isEditing`) and that `editIndex` matches the current index + - Check whether `editValues` contains the input value for the corresponding index +- **Like/dislike state is abnormal**: + - Check whether `meta.feedback` is being correctly updated and whether the UI coloring depends on this field +- **Tool message not collapsed as expected**: + - Confirm whether `status` is `'pending'` or `'done'`; the initial collapse state of the panel is determined by this status +- **Welcome prompt click has no response**: + - Check whether the `onWelcomePromptSelect` callback is correctly passed and whether the `items` in Prompts are correctly parsed + +**Section Sources** + +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) +- [frontend/pro/chatbot/chatbot-footer.tsx:291-298](file://frontend/pro/chatbot/chatbot-footer.tsx#L291-L298) +- [frontend/pro/chatbot/chatbot.tsx:222-237](file://frontend/pro/chatbot/chatbot.tsx#L222-L237) +- [frontend/pro/chatbot/messages/tool.tsx:14-18](file://frontend/pro/chatbot/messages/tool.tsx#L14-L18) +- [frontend/pro/chatbot/messages/welcome.tsx:46-51](file://frontend/pro/chatbot/messages/welcome.tsx#L46-L51) + +## Conclusion + +Through a clear pre-processing/post-processing pipeline, comprehensive event bridging, and an immutable update strategy, this component achieves efficient rendering and interaction of multiple message types. With rich configuration and callback extension points, developers can flexibly customize the UI and business logic without disrupting the overall structure. Combined with performance optimization and troubleshooting advice, this further enhances user experience and development efficiency. diff --git a/.wiki/en/Pro Components/Chatbot/Multimodal Support.md b/.wiki/en/Pro Components/Chatbot/Multimodal Support.md new file mode 100644 index 00000000..11972e11 --- /dev/null +++ b/.wiki/en/Pro Components/Chatbot/Multimodal Support.md @@ -0,0 +1,397 @@ +# Multimodal Support + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) +- [backend/modelscope_studio/components/pro/multimodal_input/__init__.py](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py) +- [frontend/pro/chatbot/index.svelte](file://frontend/pro/chatbot/index.svelte) +- [frontend/pro/multimodal-input/index.svelte](file://frontend/pro/multimodal-input/index.svelte) +- [frontend/pro/chatbot/type.ts](file://frontend/pro/chatbot/type.ts) +- [frontend/pro/chatbot/messages/file.tsx](file://frontend/pro/chatbot/messages/file.tsx) +- [frontend/antdx/attachments/attachments.tsx](file://frontend/antdx/attachments/attachments.tsx) +- [frontend/utils/upload.ts](file://frontend/utils/upload.ts) +- [docs/layout_templates/chatbot/demos/basic.py](file://docs/layout_templates/chatbot/demos/basic.py) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py](file://docs/layout_templates/chatbot/demos/fine_grained_control.py) +- [docs/components/pro/chatbot/demos/multimodal.py](file://docs/components/pro/chatbot/demos/multimodal.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This chapter focuses on the multimodal support capabilities of the Chatbot component. It systematically describes the processing mechanisms for multimedia content such as images, videos, audio, and files, covering message structure definitions, frontend/backend data flow, upload/download/preview processes, and security and performance optimization strategies. Readers can use this to build conversational applications with multimodal input/output capabilities in the Gradio/ModelScope ecosystem. + +## Project Structure + +Multimodal support is accomplished collaboratively by three parts: "backend component + frontend rendering + utility functions": + +- Backend components are responsible for the message data model, preprocessing/postprocessing logic, static resource services, and event binding +- Frontend components handle chat bubble rendering, attachment panels, file card display, and interaction +- Utility functions handle file URL resolution and fetchable URL generation + +```mermaid +graph TB +subgraph "Backend" +BC["Chatbot component
Message model and pre/post-processing"] +MI["MultimodalInput component
Multimodal input and upload"] +end +subgraph "Frontend" +CI["chatbot/index.svelte
Chat container"] +CT["chatbot/type.ts
Message type definitions"] +CF["messages/file.tsx
File message rendering"] +AI["attachments/attachments.tsx
Attachment panel"] +UF["utils/upload.ts
URL resolution utility"] +end +subgraph "Documentation Examples" +DB["basic.py
Basic multimodal history formatting"] +DF["fine_grained_control.py
Fine-grained control example"] +DM["multimodal.py
Multimodal submit and streaming response"] +end +BC --> CI +MI --> CI +CI --> CT +CI --> CF +CI --> AI +CF --> UF +MI --> AI +DB --> BC +DF --> BC +DM --> BC +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) +- [frontend/pro/chatbot/index.svelte:1-90](file://frontend/pro/chatbot/index.svelte#L1-L90) +- [frontend/pro/multimodal-input/index.svelte:1-99](file://frontend/pro/multimodal-input/index.svelte#L1-L99) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/utils/upload.ts:1-45](file://frontend/utils/upload.ts#L1-L45) +- [docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py:100-133](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L100-L133) +- [docs/components/pro/chatbot/demos/multimodal.py:82-118](file://docs/components/pro/chatbot/demos/multimodal.py#L82-L118) + +**Section sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) +- [frontend/pro/chatbot/index.svelte:1-90](file://frontend/pro/chatbot/index.svelte#L1-L90) +- [frontend/pro/multimodal-input/index.svelte:1-99](file://frontend/pro/multimodal-input/index.svelte#L1-L99) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/utils/upload.ts:1-45](file://frontend/utils/upload.ts#L1-L45) +- [docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py:100-133](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L100-L133) +- [docs/components/pro/chatbot/demos/multimodal.py:82-118](file://docs/components/pro/chatbot/demos/multimodal.py#L82-L118) + +## Core Components + +- Chatbot component (backend): Defines message structure, supports four content types: text/tool/file/suggestion; provides preprocessing and postprocessing hooks to uniformly handle file paths/URLs, MIME types, and static resource services. +- MultimodalInput component (backend): Encapsulates multimodal input, supporting text and file lists; provides upload pre/post-processing, cached downloads, HTTP link resolution, and local file mapping. +- Frontend renderer (chatbot): Renders text, tool, file, or suggestion based on message type; file messages are displayed via file card components with image/video/audio support, along with preview and download links. +- Attachment panel (attachments): Provides drag-and-drop/paste/select upload, maximum count limit, placeholder, icon rendering, and preview configuration. +- Utility functions (upload): Converts relative paths to fetchable URLs, compatible with http/https protocols and backend API prefixes. + +**Section sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:229-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L229-L284) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:76-137](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L76-L137) +- [frontend/pro/chatbot/type.ts:43-135](file://frontend/pro/chatbot/type.ts#L43-L135) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/utils/upload.ts:12-44](file://frontend/utils/upload.ts#L12-L44) + +## Architecture Overview + +The diagram below shows the full chain from user input to message rendering: the frontend MultimodalInput uploads text and files to the backend; the backend component performs preprocessing/postprocessing; and the result is passed to the frontend Chatbot renderer as a unified message structure. + +```mermaid +sequenceDiagram +participant U as "User" +participant MUI as "MultimodalInput (Frontend)" +participant MI as "MultimodalInput (Backend)" +participant CB as "Chatbot (Backend)" +participant FE as "Chatbot (Frontend Renderer)" +U->>MUI : Input text + select/paste/drag files +MUI->>MI : Submit change value {text, files} +MI->>MI : Preprocess/download/map files +MI-->>CB : Unified message structure (with file path/URL/MIME) +CB-->>FE : Render messages (text/file/tool/suggestion) +FE-->>U : Display chat bubbles and file cards +``` + +**Diagram sources** + +- [frontend/pro/multimodal-input/index.svelte:68-75](file://frontend/pro/multimodal-input/index.svelte#L68-L75) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:418-488](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L418-L488) +- [frontend/pro/chatbot/index.svelte:67-89](file://frontend/pro/chatbot/index.svelte#L67-L89) + +## Detailed Component Analysis + +### Message Structure and Content Types + +- Supported content types: text, tool, file, suggestion +- File content supports string paths, FileData objects, attachment objects, and extended properties (such as type) +- Text content supports Markdown rendering, LaTeX delimiters, HTML sanitization, and tag allowlists +- Tool content supports title and status (pending/done) +- Suggestion content uses prompt group configuration, supporting vertical/wrapping layout and styles + +```mermaid +classDiagram +class ChatbotDataMessageContent { ++type ++content ++options ++copyable ++editable +} +class ChatbotDataFileContentOptions { ++vertical ++wrap ++justify ++align ++gap ++imageProps ++videoProps ++audioProps +} +class ChatbotDataToolContentOptions { ++title ++status +} +class ChatbotMarkdownConfig { ++render_markdown ++latex_delimiters ++sanitize_html ++allow_tags +} +class ChatbotDataMessage { ++role ++content ++status ++meta +} +ChatbotDataMessageContent --> ChatbotDataFileContentOptions : "File options" +ChatbotDataMessageContent --> ChatbotDataToolContentOptions : "Tool options" +ChatbotDataMessageContent --> ChatbotMarkdownConfig : "Text options" +ChatbotDataMessage --> ChatbotDataMessageContent : "Contains" +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:229-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L229-L284) +- [frontend/pro/chatbot/type.ts:54-135](file://frontend/pro/chatbot/type.ts#L54-L135) + +**Section sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:229-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L229-L284) +- [frontend/pro/chatbot/type.ts:43-135](file://frontend/pro/chatbot/type.ts#L43-L135) + +### File Message Rendering and Preview + +- File messages are displayed via file card components, supporting image thumbnails, video/audio players, file size, and name +- Preview buttons use fetchable URLs to open new windows, ensuring cross-origin security +- Image/video/audio dimensions and styles can be injected via options + +```mermaid +flowchart TD +Start(["Enter file message rendering"]) --> Resolve["Resolve file items
string/object -> unified object"] +Resolve --> BuildCard["Build file card
name/size/type/src"] +BuildCard --> Preview["Generate preview button
href=fetchable URL"] +Preview --> Style["Inject styles and dimensions
imageProps/videoProps/audioProps"] +Style --> End(["Rendering complete"]) +``` + +**Diagram sources** + +- [frontend/pro/chatbot/messages/file.tsx:18-118](file://frontend/pro/chatbot/messages/file.tsx#L18-L118) +- [frontend/utils/upload.ts:12-44](file://frontend/utils/upload.ts#L12-L44) + +**Section sources** + +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/utils/upload.ts:1-45](file://frontend/utils/upload.ts#L1-L45) + +### Attachment Panel and Upload Flow + +- Supports drag-and-drop, paste, and select upload; configurable maximum count, placeholder, icon, and preview behavior +- Automatically deduplicates during upload; uses temporary state and merge strategies; supports single file overwrite and multiple file append +- Provides download, preview, and remove event callbacks for easy business logic integration + +```mermaid +sequenceDiagram +participant U as "User" +participant AT as "Attachments (Attachment Panel)" +participant CL as "Client Upload" +participant ST as "Storage/Cache" +U->>AT : Select/drag/paste file +AT->>CL : Trigger upload (filter incomplete files) +CL->>ST : Save file +ST-->>CL : Return FileData list +CL-->>AT : Update file list (merge/overwrite) +AT-->>U : Display upload progress and result +``` + +**Diagram sources** + +- [frontend/antdx/attachments/attachments.tsx:275-354](file://frontend/antdx/attachments/attachments.tsx#L275-L354) +- [frontend/pro/multimodal-input/multimodal-input.tsx:181-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L181-L246) + +**Section sources** + +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/pro/multimodal-input/multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) + +### History Message Formatting and Multimodal Submission + +- History messages need to be organized by role and content type; user messages can contain text and file arrays +- File items can be paths or FileData; the backend uniformly converts them to fetchable URLs or local paths +- Examples demonstrate converting images to base64 and combining files with text as multimodal messages + +```mermaid +flowchart TD +A["Read history records"] --> B{"Role is user?"} +B -- Yes --> C["Assemble content array
[{type:text},{type:image_url}]"] +B -- No --> D["Copy assistant message directly"] +C --> E["Append current assistant placeholder message"] +D --> E +E --> F["Submit to LLM / streaming response"] +``` + +**Diagram sources** + +- [docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py:100-133](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L100-L133) +- [docs/components/pro/chatbot/demos/multimodal.py:82-118](file://docs/components/pro/chatbot/demos/multimodal.py#L82-L118) + +**Section sources** + +- [docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py:100-133](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L100-L133) +- [docs/components/pro/chatbot/demos/multimodal.py:82-118](file://docs/components/pro/chatbot/demos/multimodal.py#L82-L118) + +### Frontend/Backend Data Flow and Event Binding + +- The Chatbot component exposes event listeners for change/copy/edit/delete/like/retry/suggestion_select/welcome_prompt_select, etc. +- The MultimodalInput component exposes events for change/submit/cancel/keyDown/keyPress/focus/blur/upload/paste/paste_file/drop/download/preview/remove, etc. +- The frontend container passes the Gradio shared context (rootUrl, apiPrefix) to rendering components for file URL resolution and download + +**Section sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-314](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L314) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-135](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L135) +- [frontend/pro/chatbot/index.svelte:76-84](file://frontend/pro/chatbot/index.svelte#L76-L84) +- [frontend/pro/multimodal-input/index.svelte:80-93](file://frontend/pro/multimodal-input/index.svelte#L80-L93) + +## Dependency Analysis + +- The backend Chatbot component depends on Gradio data classes and the event system, responsible for message structuring and static resource services +- The backend MultimodalInput component depends on Gradio FileData and cached download utilities, responsible for file upload and local mapping +- The frontend Chatbot renderer depends on Ant Design X and Ant Design component ecosystems, responsible for message rendering and interaction +- The attachment panel and file card components reuse Ant Design X's Attachments and FileCard for a consistent upload experience +- Utility functions uniformly handle file URL generation to ensure cross-origin accessibility + +```mermaid +graph LR +MI["MultimodalInput (Backend)"] --> GR["Gradio FileData/Utils"] +BC["Chatbot (Backend)"] --> GR +MUI["MultimodalInput (Frontend)"] --> AX["@ant-design/x"] +MUI --> AD["Ant Design"] +CB["Chatbot (Frontend)"] --> AX +CB --> AD +CB --> UF["upload.ts"] +MUI --> AT["Attachments (Frontend)"] +AT --> AX +``` + +**Diagram sources** + +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:1-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L1-L495) +- [frontend/pro/multimodal-input/multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/utils/upload.ts:1-45](file://frontend/utils/upload.ts#L1-L45) + +**Section sources** + +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:1-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L1-L495) +- [frontend/pro/multimodal-input/multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/utils/upload.ts:1-45](file://frontend/utils/upload.ts#L1-L45) + +## Performance Considerations + +- File upload + - Uses Gradio cache directory and download utilities to avoid repeated network requests + - Limits maximum file count; enables single file overwrite mode to reduce memory usage +- Render optimization + - File cards are set to fixed size and border radius to avoid layout jitter + - Image thumbnails and media controls are loaded on demand to reduce initial render pressure +- Streaming response + - The backend marks assistant messages as loading/pending; the frontend only renders completed parts to improve perceived speed +- Resource service + - A unified fetchable URL generation strategy reduces cross-origin and permission issues + +## Troubleshooting Guide + +- File cannot be previewed + - Check whether the file is an http/https link or is fetchable through the backend API + - Confirm root path and API prefix configuration are correct + - Reference: [frontend/utils/upload.ts:12-44](file://frontend/utils/upload.ts#L12-L44) +- Upload fails or gets stuck + - Check upload disabled state (disabled/loading/readOnly/uploading) + - Check maximum count limit and beforeUpload callback return value + - Reference: [frontend/antdx/attachments/attachments.tsx:168-354](file://frontend/antdx/attachments/attachments.tsx#L168-L354) +- History message format error + - User messages must contain type and content arrays; file items should be paths or FileData + - Reference: [docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- Events not triggering + - Confirm the frontend container has bound the corresponding events (e.g., suggestionSelect, welcomePromptSelect) + - Reference: [frontend/pro/chatbot/index.svelte:58-61](file://frontend/pro/chatbot/index.svelte#L58-L61) + +**Section sources** + +- [frontend/utils/upload.ts:12-44](file://frontend/utils/upload.ts#L12-L44) +- [frontend/antdx/attachments/attachments.tsx:168-354](file://frontend/antdx/attachments/attachments.tsx#L168-L354) +- [docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- [frontend/pro/chatbot/index.svelte:58-61](file://frontend/pro/chatbot/index.svelte#L58-L61) + +## Conclusion + +This multimodal support solution is centered on a standardized message structure. By combining backend component data processing with frontend component rendering capabilities, it achieves unified input, upload, storage, and display of images, videos, audio, and files. Through configurable attachment panels and file cards, developers can flexibly extend and customize the form of multimodal chatbots without sacrificing user experience. + +## Appendix + +- Multimodal message sending example + - Combine text and file arrays into a user message, submit to the backend, and await streaming response + - Reference: [docs/components/pro/chatbot/demos/multimodal.py:82-118](file://docs/components/pro/chatbot/demos/multimodal.py#L82-L118) +- History message formatting + - User messages contain text and image arrays; images can be converted to base64 or kept as paths + - Reference: [docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- Fine-grained control + - Customize file item fields (such as text/files) and assemble messages on demand + - Reference: [docs/layout_templates/chatbot/demos/fine_grained_control.py:100-133](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L100-L133) + +**Section sources** + +- [docs/components/pro/chatbot/demos/multimodal.py:82-118](file://docs/components/pro/chatbot/demos/multimodal.py#L82-L118) +- [docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py:100-133](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L100-L133) diff --git a/.wiki/en/Pro Components/Chatbot/Thinking Process Display.md b/.wiki/en/Pro Components/Chatbot/Thinking Process Display.md new file mode 100644 index 00000000..729a90f3 --- /dev/null +++ b/.wiki/en/Pro Components/Chatbot/Thinking Process Display.md @@ -0,0 +1,329 @@ +# Thinking Process Display + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/antdx/thought_chain/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py) +- [backend/modelscope_studio/components/antdx/think/__init__.py](file://backend/modelscope_studio/components/antdx/think/__init__.py) +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) +- [frontend/antdx/thought-chain/Index.svelte](file://frontend/antdx/thought-chain/Index.svelte) +- [frontend/antdx/thought-chain/thought-chain.tsx](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [frontend/antdx/thought-chain/thought-chain-item/Index.svelte](file://frontend/antdx/thought-chain/thought-chain-item/Index.svelte) +- [frontend/pro/chatbot/chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) +- [frontend/pro/chatbot/message.tsx](file://frontend/pro/chatbot/message.tsx) +- [frontend/pro/chatbot/messages/tool.tsx](file://frontend/pro/chatbot/messages/tool.tsx) +- [frontend/pro/chatbot/type.ts](file://frontend/pro/chatbot/type.ts) +- [docs/components/antdx/thought_chain/README-zh_CN.md](file://docs/components/antdx/thought_chain/README-zh_CN.md) +- [docs/components/antdx/thought_chain/demos/basic.py](file://docs/components/antdx/thought_chain/demos/basic.py) +- [docs/components/pro/chatbot/demos/thinking.py](file://docs/components/pro/chatbot/demos/thinking.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Component Details](#component-details) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document provides a systematic explanation of the "Thinking Process Display" capability within the Chatbot component. It aims to help developers correctly configure and present AI reasoning processes, including intermediate reasoning results, tool call chains, state transitions, and timing control for final responses. The document covers the following key points: + +- How to insert "thinking" messages (type `tool`) into Chatbot and visualize them using ThoughtChain/Think components +- Configuration options, state management, and nested usage of Thought Chain +- Timing control and interaction design for thinking processes vs. final responses +- Visualization approaches and debugging/optimization recommendations + +## Project Structure + +This feature involves collaboration between backend Python components and the frontend Svelte/React layer: + +- **Backend**: Provides component classes such as ThoughtChain, ThoughtChainItem, and Think, responsible for property forwarding and frontend resource resolution +- **Frontend**: The Svelte wrapper bridges Ant Design X's ThoughtChain/Item into consumable components; the Chatbot message renderer selects ToolMessage or other message types based on content type + +```mermaid +graph TB +subgraph "Backend" +BT["AntdXThoughtChain
AntdXThoughtChainItem
AntdXThink"] +end +subgraph "Frontend" +FS["frontend/antdx/thought-chain/*
Svelte Wrapper Layer"] +FC["frontend/pro/chatbot/*
Chatbot & Message Rendering"] +end +BT --> FS +FS --> FC +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:51-80](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L51-L80) +- [backend/modelscope_studio/components/antdx/think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [frontend/antdx/thought-chain/Index.svelte:1-62](file://frontend/antdx/thought-chain/Index.svelte#L1-L62) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/message.tsx:1-133](file://frontend/pro/chatbot/message.tsx#L1-L133) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [frontend/antdx/thought-chain/Index.svelte:1-62](file://frontend/antdx/thought-chain/Index.svelte#L1-L62) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) + +## Core Components + +- **ThoughtChain** (backend class): Container for multiple ThoughtChainItems, supporting expand/collapse, line styles, root class names, and other configurations +- **ThoughtChainItem** (backend class): A single thinking node, supporting title, description, status, collapsible, extra action area, content area, and footer area +- **Think** (backend class): Used within Chatbot to display intermediate reasoning or tool call UI fragments in a "thinking" style +- **Chatbot** (backend class): Message container supporting multiple content types (text/tool/file/suggestion), defining the message data model and pre/post-processing logic +- **Frontend Wrapper Layer**: Svelte bridges Ant Design X's ThoughtChain/Item components as consumable components, while passing slots and props +- **ToolMessage**: Renders `tool` type messages, supporting collapse/expand and Markdown rendering + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:51-80](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L51-L80) +- [backend/modelscope_studio/components/antdx/think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [frontend/pro/chatbot/messages/tool.tsx:1-46](file://frontend/pro/chatbot/messages/tool.tsx#L1-L46) + +## Architecture Overview + +The diagram below illustrates the overall flow from backend components to frontend rendering, as well as the insertion and display path for "thinking" messages in Chatbot. + +```mermaid +sequenceDiagram +participant Py as "Backend Components
AntdXThoughtChain/Item
AntdXThink" +participant FE as "Frontend Wrapper Layer
Svelte + TSX" +participant CB as "Chatbot
Message Rendering" +participant TM as "ToolMessage
Collapse/Expand" +Py->>FE : "Parse and forward properties and slots" +FE->>FE : "Dynamically import Ant Design X components" +FE->>CB : "Inject as child component into Chatbot" +CB->>TM : "Render ToolMessage when content.type='tool'" +TM-->>CB : "Control collapse state based on options.status" +CB-->>Py : "Final value processed by backend pre/post hooks" +``` + +**Diagram Sources** + +- [frontend/antdx/thought-chain/Index.svelte:1-62](file://frontend/antdx/thought-chain/Index.svelte#L1-L62) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/message.tsx:1-133](file://frontend/pro/chatbot/message.tsx#L1-L133) +- [frontend/pro/chatbot/messages/tool.tsx:1-46](file://frontend/pro/chatbot/messages/tool.tsx#L1-L46) + +## Component Details + +### ThoughtChain and ThoughtChainItem Configuration and Usage + +- **ThoughtChain** supports: + - `expanded_keys` / `default_expanded_keys`: Controls initially expanded items + - `line`: Connection line style (solid/dashed/dotted) + - `items`: Explicitly pass a list of nodes + - Root-level styles/class names: `styles` / `class_names` / `root_class_name` + - Events: `expand` (callback for expanded key changes) +- **ThoughtChainItem** supports: + - `title` / `description` / `status` / `prefixCls` / `icon` / `key` / `collapsible` + - Slots: `extra` / `content` / `footer` + - Inject complex content via `slots` (e.g., buttons, icons, paragraphs) + +```mermaid +classDiagram +class AntdXThoughtChain { ++expanded_keys ++default_expanded_keys ++line ++items ++styles ++class_names ++root_class_name ++EVENTS ++SLOTS +} +class AntdXThoughtChainItem { ++title ++description ++status ++key ++collapsible ++icon ++extra ++content ++footer ++blink ++SLOTS +} +AntdXThoughtChain --> AntdXThoughtChainItem : "contains multiple nodes" +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:30-67](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L30-L67) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:51-60](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L51-L60) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:51-80](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L51-L80) +- [docs/components/antdx/thought_chain/README-zh_CN.md:1-10](file://docs/components/antdx/thought_chain/README-zh_CN.md#L1-L10) +- [docs/components/antdx/thought_chain/demos/basic.py:1-77](file://docs/components/antdx/thought_chain/demos/basic.py#L1-L77) + +### Using the Think Component in Chatbot + +- Think provides a UI fragment for "thinking" segments, supporting `loading`, default expansion, blink effects, and more +- In Chatbot, the "thinking" process can be displayed by appending an entry with type `tool` to the message content array +- The example demonstrates how, during a streaming response, a `tool` message titled "Thinking..." is first inserted, then its content is updated in real time; when the first final response fragment arrives, the "thinking" title is updated to "End of Thought (elapsed time)" and marked as done + +```mermaid +sequenceDiagram +participant Demo as "Example Logic
thinking.py" +participant Chatbot as "Chatbot" +participant OpenAI as "OpenAI Streaming Response" +Demo->>Chatbot : "Append a type='tool' thinking message" +OpenAI-->>Demo : "delta.reasoning_content" +Demo->>Chatbot : "Incrementally update thinking message content" +OpenAI-->>Demo : "delta.content (final response fragment)" +Demo->>Chatbot : "Update thinking message title and status to done" +Demo->>Chatbot : "Append final text reply message" +``` + +**Diagram Sources** + +- [docs/components/pro/chatbot/demos/thinking.py:82-118](file://docs/components/pro/chatbot/demos/thinking.py#L82-L118) +- [frontend/pro/chatbot/messages/tool.tsx:13-18](file://frontend/pro/chatbot/messages/tool.tsx#L13-L18) + +**Section Sources** + +- [backend/modelscope_studio/components/antdx/think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [docs/components/pro/chatbot/demos/thinking.py:82-118](file://docs/components/pro/chatbot/demos/thinking.py#L82-L118) +- [frontend/pro/chatbot/messages/tool.tsx:13-18](file://frontend/pro/chatbot/messages/tool.tsx#L13-L18) + +### Chatbot Message Types and ToolMessage Rendering + +- Chatbot-supported message types: `text`, `tool`, `file`, `suggestion` +- `tool` type messages are rendered by ToolMessage, which supports: + - `options.title`: Title (Markdown rendering depends on `renderMarkdown`) + - `options.status`: `'pending'` / `'done'` determines whether to collapse + - Content area supports Markdown rendering or plain text +- The Chatbot message renderer dispatches to the corresponding component based on `content.type` + +```mermaid +flowchart TD +Start(["Enter Message Rendering"]) --> CheckType{"content.type"} +CheckType --> |text| RenderText["Render TextMessage"] +CheckType --> |tool| RenderTool["Render ToolMessage
Collapse/Expand based on options.status"] +CheckType --> |file| RenderFile["Render FileMessage"] +CheckType --> |suggestion| RenderSuggestion["Render SuggestionMessage"] +RenderTool --> End(["Done"]) +RenderText --> End +RenderFile --> End +RenderSuggestion --> End +``` + +**Diagram Sources** + +- [frontend/pro/chatbot/message.tsx:39-133](file://frontend/pro/chatbot/message.tsx#L39-L133) +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) +- [frontend/pro/chatbot/type.ts:121-135](file://frontend/pro/chatbot/type.ts#L121-L135) + +**Section Sources** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [frontend/pro/chatbot/message.tsx:39-133](file://frontend/pro/chatbot/message.tsx#L39-L133) +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) +- [frontend/pro/chatbot/type.ts:54-66](file://frontend/pro/chatbot/type.ts#L54-L66) + +### Thought Chain Configuration and Usage + +- In Chatbot, if you need to display reasoning and tool calls step-by-step in a "thought chain" style, use the ThoughtChain/Item components +- Combine multiple ThoughtChainItems into a chain through the backend component class's `slots` mechanism +- Supports placing `extra` / `content` / `footer` slots within each node for richer interaction and information density + +**Section Sources** + +- [docs/components/antdx/thought_chain/README-zh_CN.md:1-10](file://docs/components/antdx/thought_chain/README-zh_CN.md#L1-L10) +- [docs/components/antdx/thought_chain/demos/basic.py:24-77](file://docs/components/antdx/thought_chain/demos/basic.py#L24-L77) +- [frontend/antdx/thought-chain/Index.svelte:1-62](file://frontend/antdx/thought-chain/Index.svelte#L1-L62) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) + +## Dependency Analysis + +- Backend component classes are only responsible for property forwarding and frontend directory resolution; they do not participate directly in business logic +- The frontend Svelte wrapper layer is responsible for bridging Ant Design X's ThoughtChain/Item components as consumable components and handling slots and props +- Chatbot dispatches to specific message components (TextMessage/ToolMessage/FileMessage/SuggestionMessage) based on message type + +```mermaid +graph LR +PyTC["Backend ThoughtChain/Item"] --> Wrap["Svelte Wrapper Layer"] +PyThink["Backend Think"] --> Wrap +Wrap --> ADX["Ant Design X Component Library"] +ADX --> CB["Chatbot"] +CB --> Msg["Message Renderer"] +Msg --> Tool["ToolMessage"] +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:68-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L68-L86) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:61-80](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L61-L80) +- [backend/modelscope_studio/components/antdx/think/**init**.py:61-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L61-L79) +- [frontend/antdx/thought-chain/Index.svelte:10-62](file://frontend/antdx/thought-chain/Index.svelte#L10-L62) +- [frontend/antdx/thought-chain/thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [frontend/pro/chatbot/chatbot.tsx:450-472](file://frontend/pro/chatbot/chatbot.tsx#L450-L472) + +**Section Sources** + +- [frontend/antdx/thought-chain/Index.svelte:1-62](file://frontend/antdx/thought-chain/Index.svelte#L1-L62) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) + +## Performance Considerations + +- **Streaming update strategy**: Use incremental updates in Chatbot to avoid frequently re-rendering the entire message list +- **ToolMessage collapse control**: Use `options.status` to initially determine collapse state, reducing unnecessary renders +- **Judicious use of slots**: Only inject necessary content into ThoughtChain/Item nodes to avoid overly deep nesting +- **Backend pre/post processing**: Pre-process static assets such as file paths and avatars to reduce frontend rendering cost + +[This section provides general guidance and requires no specific file references] + +## Troubleshooting Guide + +- **Thinking message not displayed** + - Check whether the message type is `tool` and whether `content` contains valid content + - Confirm whether `options.status` has been set to `done`, causing automatic collapse +- **Thinking title not updated** + - Confirm that when the first `delta.content` is received, the thinking message's `options.title` and `options.status` have been updated +- **ThoughtChain/Item not taking effect** + - Confirm that the backend component class's `slots` are correctly passed and that the frontend wrapper layer has correctly resolved the `slots` +- **Performance issues** + - Reduce the amount of data updated per round; merge multiple incremental updates + - Pay attention to text size when enabling Markdown rendering for long content + +**Section Sources** + +- [docs/components/pro/chatbot/demos/thinking.py:82-118](file://docs/components/pro/chatbot/demos/thinking.py#L82-L118) +- [frontend/pro/chatbot/messages/tool.tsx:13-18](file://frontend/pro/chatbot/messages/tool.tsx#L13-L18) + +## Conclusion + +By using ThoughtChain/Item and Think components in combination with Chatbot's message type system, you can clearly display AI reasoning processes and tool call chains. Properly configuring states and slots, combined with a streaming update strategy, both enhances user experience and ensures good performance. In real-world projects, it is recommended to prioritize using `tool` type messages to carry "thinking" content, and to promptly update the status and title when the final response arrives, forming a complete "think → execute → feedback" loop. + +[This section is a summary and requires no specific file references] + +## Appendix + +- **Example References** + - ThoughtChain basic example: [docs/components/antdx/thought_chain/demos/basic.py:1-77](file://docs/components/antdx/thought_chain/demos/basic.py#L1-L77) + - Chatbot thinking process example: [docs/components/pro/chatbot/demos/thinking.py:1-218](file://docs/components/pro/chatbot/demos/thinking.py#L1-L218) +- **Component Documentation** + - ThoughtChain docs: [docs/components/antdx/thought_chain/README-zh_CN.md:1-10](file://docs/components/antdx/thought_chain/README-zh_CN.md#L1-L10) + +[This section is supplementary material and requires no specific file references] diff --git a/.wiki/en/Pro Components/MonacoEditor/Advanced Features.md b/.wiki/en/Pro Components/MonacoEditor/Advanced Features.md new file mode 100644 index 00000000..949e4b44 --- /dev/null +++ b/.wiki/en/Pro Components/MonacoEditor/Advanced Features.md @@ -0,0 +1,305 @@ +# Advanced Features + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/pro/monaco_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py) +- [frontend/pro/monaco-editor/monaco-editor.tsx](file://frontend/pro/monaco-editor/monaco-editor.tsx) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx) +- [frontend/pro/monaco-editor/loader.ts](file://frontend/pro/monaco-editor/loader.ts) +- [frontend/pro/monaco-editor/useValueChange.ts](file://frontend/pro/monaco-editor/useValueChange.ts) +- [frontend/pro/monaco-editor/monaco-editor.less](file://frontend/pro/monaco-editor/monaco-editor.less) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This "Advanced Features" document focuses on the advanced usage and extensibility of MonacoEditor in ModelScope Studio, covering the following topics: + +- **JavaScript customization**: How to inject custom logic before and after mounting (e.g., language services, theme switching, event binding) +- **Service overrides**: Replacing or enhancing Monaco's internal services via the `override_services` parameter +- **Loader configuration**: Choosing and configuring between local loading and CDN loading modes +- **Editor extensions**: Custom language support, plugin development, and theme customization +- **Complex scenario integration**: Deep integration examples with the Gradio ecosystem (Blocks, ConfigProvider, Application) +- **Underlying implementation and performance optimization**: Event binding, value synchronization strategies, Web Worker and resource path management + +## Project Structure + +The MonacoEditor implementation uses a layered design of "backend component + frontend Svelte/React wrapper": + +- The backend component handles parameter forwarding, event binding, loader configuration, and service override configuration +- The frontend component wraps `@monaco-editor/react` to provide a unified React/Svelte interface, with built-in loader initialization, value change throttling, and theme adaptation + +```mermaid +graph TB +subgraph "Backend" +PY["Python Backend Component
ModelScopeProMonacoEditor"] +end +subgraph "Frontend" +FE["Svelte/React Wrapper
MonacoEditor / MonacoDiffEditor"] +LDR["Loader Initialization
loader.ts"] +VAL["Value Change Throttle Hook
useValueChange.ts"] +CSS["Style Class Names
monaco-editor.less"] +end +subgraph "External Dependencies" +ME["@monaco-editor/react"] +MR["monaco-editor Web Workers"] +end +PY --> FE +FE --> ME +FE --> VAL +FE --> LDR +LDR --> MR +FE --> CSS +``` + +Diagram Source + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L161) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) + +Section Source + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L161) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) + +## Core Components + +- **Backend Component**: `ModelScopeProMonacoEditor` + - Supported events: `mount`, `change`, `validate` + - Supported slots: `loading` + - Supported loader configuration: `LOADER` (default: `local` mode) + - Key parameters: `language`, `options`, `read_only`, `height`, `before_mount`, `after_mount`, `override_services`, `line` +- **Frontend Components**: `MonacoEditor` (single editor), `MonacoDiffEditor` (diff editor) + - Provide `themeMode`, `height`, `readOnly`, `onValueChange`, `loading` slot, etc. + - Built-in loader initialization, value change throttling, and theme mapping (`dark` ↔ `vs-dark`) + +Section Source + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L161) + +## Architecture Overview + +The diagram below shows the overall call chain from the Python backend to the frontend wrapper components, then to the Monaco editor and Web Workers. + +```mermaid +sequenceDiagram +participant Py as "Backend Component
ModelScopeProMonacoEditor" +participant FE as "Frontend Component
MonacoEditor/MonacoDiffEditor" +participant L as "Loader
loader.ts" +participant MR as "@monaco-editor/react" +participant M as "Monaco Editor Instance" +participant W as "Web Workers" +Py->>FE : Pass parameters: options, language, read_only, height, before_mount, after_mount, override_services, line +FE->>L : Initialize loader (local/CDN) +L-->>FE : Done configuring Monaco, Worker mapping, resource paths +FE->>MR : Render Editor/DiffEditor +MR->>M : Create editor instance +M->>W : Register Web Workers (JSON/CSS/HTML/TS/general) +FE->>FE : Bind events (onChange/onMount/onValidate) +FE-->>Py : Trigger mount/change/validate event callbacks +``` + +Diagram Source + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:21-38](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L21-L38) +- [frontend/pro/monaco-editor/monaco-editor.tsx:38-91](file://frontend/pro/monaco-editor/monaco-editor.tsx#L38-L91) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:67-98](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L67-L98) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +## Detailed Component Analysis + +### Backend Component: ModelScopeProMonacoEditor + +- **Event system** + - `mount`: Triggered when the editor mounts; used to execute `before_mount`/`after_mount` callbacks + - `change`: Triggered when editor content changes; can be used for real-time validation or saving + - `validate`: Triggered after marker (error/warning) updates complete +- **Slots and loader** + - `loading` slot: Allows customizing the loading state UI + - `LOADER`: Supports both `local` and `CDN` modes; defaults to `local` +- **Key parameters** + - `language`: Language identifier that drives syntax highlighting and language services + - `options`: Configuration object passed to Monaco + - `read_only`: Read-only mode + - `height`: Container height + - `before_mount`/`after_mount`: Hooks executed before/after mounting + - `override_services`: Service override dictionary + - `line`: Navigate to the specified line (diff editor) + +Section Source + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) + +### Frontend Component: MonacoEditor (Single Editor) + +- **Theme and sizing** + - `themeMode` mapping: `dark` → `vs-dark`; `light` → `light` + - `height` controls container height +- **Value changes and events** + - Uses `useValueChange` for input throttling (~100ms) to avoid high-frequency callbacks + - `onChange` → `setValue` → `onValueChange`, ensuring consistency with the Gradio data flow +- **Loading state** + - Default loading state is `Spin`; can be replaced via the `loading` slot +- **Web Workers and loader** + - Initialized by `loader.ts`, returning the corresponding Worker by language type + +Section Source + +- [frontend/pro/monaco-editor/monaco-editor.tsx:21-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L21-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:4-44](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L44) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) + +### Frontend Component: MonacoDiffEditor (Diff Editor) + +- **Features** + - Supports `modified`/`original` dual-view comparison + - `onValidate`: Listens for marker changes and returns `markers` + - `line`: Automatically scrolls to the specified line +- **Lifecycle and events** + - `onMount`: Registers content change and marker change listeners; releases `IDisposable` on cleanup + - `onChange`: Syncs the modified value upstream +- **Loading state and theme** + - Same loading state and theme mapping as the single editor + +Section Source + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:35-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L35-L161) + +### Loader and Service Overrides + +- **Loader initialization** + - `initLocalLoader`: Dynamically imports `monaco-editor` and various Workers, sets `MonacoEnvironment.getWorker` + - `initCDNLoader`: Specifies the resource path via `loader.config(paths.vs = cdn)` +- **Service overrides** + - The backend passes the service dictionary to the frontend wrapper component via `override_services` + - The frontend can access the `monaco` instance in `before_mount` to replace or extend services (e.g., replacing language services, registering custom contribution points) + +Section Source + +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:54-84](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L54-L84) + +### Value Change Throttling and Data Flow + +```mermaid +flowchart TD +Start(["Start"]) --> Typing["Typing detected?"] +Typing --> |Yes| Debounce["Start timer (~100ms)"] +Debounce --> SetTyping["Mark as typing"] +SetTyping --> Wait["Wait for timer to end"] +Wait --> ClearTyping["Stop typing, clear timer"] +ClearTyping --> Sync["Sync display value and upstream callback"] +Typing --> |No| Sync +Sync --> End(["End"]) +``` + +Diagram Source + +- [frontend/pro/monaco-editor/useValueChange.ts:14-32](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L32) + +## Dependency Analysis + +- **Component coupling** + - The backend component is tightly coupled to the frontend wrapper component through parameter forwarding; event callbacks are decoupled via the Gradio event system + - The frontend component's coupling with Monaco is decoupled through `@monaco-editor/react` and `loader.ts` +- **External dependencies** + - `@monaco-editor/react`: Editor rendering and lifecycle management + - `monaco-editor` Web Workers: Language services and syntax parsing + - Ant Design `Spin`: Loading state UI +- **Build and packaging** + - `defineConfig.js` provides Vite plugins and preprocessing configuration to ensure proper Svelte/React wrapper builds + +```mermaid +graph LR +PY["Backend Component"] --> FE["Frontend Wrapper Component"] +FE --> REACT["@monaco-editor/react"] +FE --> WORKER["monaco-editor Web Workers"] +FE --> ANT["Ant Design Spin"] +FE --> CFG["defineConfig.js"] +``` + +Diagram Source + +- [frontend/defineConfig.js:8-18](file://frontend/defineConfig.js#L8-L18) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-11](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L11) + +Section Source + +- [frontend/defineConfig.js:8-18](file://frontend/defineConfig.js#L8-L18) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## Performance Considerations + +- **Input throttling** + - `useValueChange` reduces `onChange` frequency with an ~100ms timer, lessening the burden on upstream callbacks and re-renders +- **Worker dispatch** + - Returns the precise Worker by language type, avoiding unnecessary multi-threading overhead +- **Resource paths** + - In CDN mode, `loader.config(paths.vs = cdn)` reduces local bundle size and initial load time +- **Theme switching** + - `themeMode` switching only affects the theme mapping without rebuilding the editor instance, minimizing jitter + +Section Source + +- [frontend/pro/monaco-editor/useValueChange.ts:14-24](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L24) +- [frontend/pro/monaco-editor/loader.ts:53-69](file://frontend/pro/monaco-editor/loader.ts#L53-L69) + +## Troubleshooting Guide + +- **Loading failure or blank screen** + - Check whether the `LOADER` configuration is correct (local/CDN) and confirm that the CDN path is reachable + - If using CDN, ensure cross-origin and caching policies are correctly configured +- **Language service issues** + - Confirm that `language` matches the actual code + - For custom language services, use `before_mount` to inject Monaco service replacement logic +- **Events not firing** + - Confirm that the relevant event binding is enabled (`bind_mount_event`/`bind_change_event`/`bind_validate_event`) + - Check that the Gradio event system is functioning correctly (queue and launch) +- **Diff editor line navigation not working** + - Confirm that the `line` parameter is a valid number and that it is set only after `onMount` completes + +Section Source + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:21-38](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L21-L38) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:109-113](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L109-L113) + +## Conclusion + +The advanced features of MonacoEditor in ModelScope Studio revolve around "parameter forwarding + frontend wrapper + loader initialization + event system", ensuring seamless integration with the Gradio ecosystem while providing flexible extension points (language services, theming, loading strategies). Through throttling and precise Worker dispatch, it balances interaction smoothness and runtime efficiency. + +## Appendix + +### Integration Examples with the Gradio Ecosystem + +- **Blocks and ConfigProvider**: Use the component within a Blocks context for unified global configuration +- **Application**: Provides application-level context for easier event and state management +- **Example reference**: Demonstrates basic usage and `options` configuration (e.g., disabling minimap, hiding line numbers) + +Section Source + +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:6-34](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L6-L34) diff --git a/.wiki/en/Pro Components/MonacoEditor/Basic Usage.md b/.wiki/en/Pro Components/MonacoEditor/Basic Usage.md new file mode 100644 index 00000000..581b41c0 --- /dev/null +++ b/.wiki/en/Pro Components/MonacoEditor/Basic Usage.md @@ -0,0 +1,379 @@ +# Component Overview + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/pro/monaco_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py) +- [frontend/pro/monaco-editor/Index.svelte](file://frontend/pro/monaco-editor/Index.svelte) +- [frontend/pro/monaco-editor/monaco-editor.tsx](file://frontend/pro/monaco-editor/monaco-editor.tsx) +- [frontend/pro/monaco-editor/loader.ts](file://frontend/pro/monaco-editor/loader.ts) +- [frontend/pro/monaco-editor/useValueChange.ts](file://frontend/pro/monaco-editor/useValueChange.ts) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte](file://frontend/pro/monaco-editor/diff-editor/Index.svelte) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx) +- [docs/components/pro/monaco_editor/README.md](file://docs/components/pro/monaco_editor/README.md) +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +MonacoEditor is a professional code editor component based on Gradio, integrating Microsoft's Monaco editor at its core. It provides syntax highlighting, IntelliSense, error markers, theme adaptation, and supports diff comparison editing (Diff Editor). This component is widely used in machine learning and AI applications for: + +- Writing and validating model training scripts and configuration files +- Prompt engineering and prompt template editing +- Code/text mixed editing in multimodal input scenarios +- Online code review and comparison display + +Component features include: + +- Syntax highlighting and language mode switching +- IntelliSense and autocomplete +- Error markers and validation events +- Theme adaptation (light/dark themes) +- Diff comparison editing (side-by-side comparison) +- Pluggable loading strategy (local bundling or CDN) + +## Project Structure + +The MonacoEditor component is composed of a backend Python component definition and a frontend Svelte/React implementation, with documentation and examples in the `docs` directory. + +```mermaid +graph TB +subgraph "Backend" +PY["Python Backend Component
backend/modelscope_studio/components/pro/monaco_editor/__init__.py"] +end +subgraph "Frontend" +IDX["Svelte Entry
frontend/pro/monaco-editor/Index.svelte"] +CORE["React Wrapper Component
frontend/pro/monaco-editor/monaco-editor.tsx"] +DIFF_IDX["Svelte Entry (Diff)
frontend/pro/monaco-editor/diff-editor/Index.svelte"] +DIFF_CORE["React Diff Wrapper Component
frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx"] +LOADER["Loader
frontend/pro/monaco-editor/loader.ts"] +VALUEHOOK["Value Change Hook
frontend/pro/monaco-editor/useValueChange.ts"] +end +subgraph "Docs and Examples" +DOC["Component Docs
docs/components/pro/monaco_editor/README.md"] +DEMO["Example Script
docs/components/pro/monaco_editor/demos/monaco_editor_options.py"] +end +PY --> IDX +PY --> DIFF_IDX +IDX --> CORE +DIFF_IDX --> DIFF_CORE +CORE --> LOADER +DIFF_CORE --> LOADER +CORE --> VALUEHOOK +DIFF_CORE --> VALUEHOOK +DOC --> DEMO +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [frontend/pro/monaco-editor/Index.svelte:1-101](file://frontend/pro/monaco-editor/Index.svelte#L1-L101) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L95) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:1-103](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L1-L103) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L161) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [docs/components/pro/monaco_editor/README.md:1-89](file://docs/components/pro/monaco_editor/README.md#L1-L89) +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:1-34](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L1-L34) + +**Section Sources** + +- [docs/components/pro/monaco_editor/README.md:1-89](file://docs/components/pro/monaco_editor/README.md#L1-L89) + +## Core Components + +- **Python backend component**: Responsible for declaring component properties, event bindings, default loading strategy, and frontend directory resolution. +- **Frontend wrapper components**: + - Standard editor: Bridges the Monaco Editor React component as a Svelte component, handling value changes, themes, loading state, and event forwarding. + - Diff editor: Extends the standard editor with left/right source comparison, line positioning, and validation events. +- **Loader**: Supports both local bundling and CDN loading modes; initializes the Monaco environment and Web Workers on demand. +- **Value change hook**: Optimizes the input experience by delaying change callbacks to avoid frequent re-renders. + +**Section Sources** + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L161) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/useValueChange.ts:4-43](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L43) + +## Architecture Overview + +The runtime control flow of MonacoEditor is as follows: + +```mermaid +sequenceDiagram +participant User as "User" +participant Svelte as "Svelte Entry
Index.svelte" +participant Loader as "Loader
loader.ts" +participant ReactComp as "React Wrapper Component
monaco-editor.tsx / diff-editor.tsx" +participant Monaco as "Monaco Editor" +User->>Svelte : Render component with props +Svelte->>Loader : Initialize loading strategy (local/cdn) +Loader-->>Svelte : Return Monaco environment and resources +Svelte->>ReactComp : Pass props (value, options, events, etc.) +ReactComp->>Monaco : Create editor instance (onMount) +User->>Monaco : Type / modify content +Monaco-->>ReactComp : Trigger onChange/onValidate +ReactComp-->>Svelte : Call onValueChange to return value +Svelte-->>User : Update component state +``` + +**Diagram Sources** + +- [frontend/pro/monaco-editor/Index.svelte:64-90](file://frontend/pro/monaco-editor/Index.svelte#L64-L90) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/monaco-editor.tsx:38-91](file://frontend/pro/monaco-editor/monaco-editor.tsx#L38-L91) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:67-107](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L67-L107) + +## Detailed Component Analysis + +### Standard Editor Component (MonacoEditor) + +- **Responsibilities** + - Maps Gradio properties to the Monaco React component + - Handles read-only, height, theme, loading state, and event forwarding + - Uses the value change hook to optimize the input experience +- **Key points** + - Passes Monaco configuration via `options`; merges `readOnly` with `options` + - Theme is automatically selected as light/dark based on the Gradio shared theme + - Supports custom loading slots or default loading indicators +- **Applicable scenarios** + - Code/configuration file editing + - Text content input with real-time validation + +```mermaid +classDiagram +class MonacoEditor { ++height ++value ++options ++readOnly ++themeMode ++onValueChange() ++beforeMount() ++afterMount() +} +class Loader { ++initLocalLoader() ++initCDNLoader(cdn) +} +class ValueHook { ++useValueChange() +} +MonacoEditor --> Loader : "Initialize Monaco environment" +MonacoEditor --> ValueHook : "Optimize input callbacks" +``` + +**Diagram Sources** + +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/useValueChange.ts:4-43](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L43) + +**Section Sources** + +- [frontend/pro/monaco-editor/monaco-editor.tsx:21-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L21-L95) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/useValueChange.ts:4-43](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L43) + +### Diff Editor Component (MonacoEditor.DiffEditor) + +- **Responsibilities** + - Compares "original" and "modified" content + - Provides line positioning, validation events, and model change listeners +- **Key points** + - Subscribes to model change and marker change events in `onMount` + - Supports independently setting `original_language` and `modified_language` + - Supports `line` parameter to scroll to a specified line +- **Applicable scenarios** + - Code reviews, change comparisons, configuration diff display + +```mermaid +sequenceDiagram +participant Svelte as "Svelte Entry (Diff)" +participant ReactDiff as "React Diff Wrapper Component" +participant Monaco as "Monaco Diff Editor" +Svelte->>ReactDiff : Pass props (original/value/options, etc.) +ReactDiff->>Monaco : onMount subscribes to model changes and marker changes +Monaco-->>ReactDiff : Model change event (onChange) +Monaco-->>ReactDiff : Marker change event (onValidate) +ReactDiff-->>Svelte : Trigger onValueChange/onValidate +``` + +**Diagram Sources** + +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:66-91](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L66-L91) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:35-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L35-L161) + +**Section Sources** + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:35-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L35-L161) + +### Loader and Resource Initialization + +- **Functionality** + - Local loading: Dynamically imports Monaco and various language Workers + - CDN loading: Points to CDN resources via path configuration + - Unified initialization: Ensures the Monaco environment is available before rendering the editor +- **Notes** + - Local loading introduces a larger bundle size; CDN is recommended for production + - CDN path can be customized for intranet deployment + +```mermaid +flowchart TD +Start(["Start"]) --> Mode{"Loading Mode?"} +Mode --> |local| Local["initLocalLoader()
Dynamically import Monaco and Workers"] +Mode --> |cdn| CDN["initCDNLoader(cdn)
Configure vs path"] +Local --> Ready["Initialization complete"] +CDN --> Ready +Ready --> Render["Render editor"] +``` + +**Diagram Sources** + +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +**Section Sources** + +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +### Value Change and Input Optimization + +- **Mechanism** + - `useValueChange` delays triggering callbacks during input to reduce frequent updates + - Coordinates typing state and timers to ensure the final value and callback timing are consistent +- **Effect** + - Improves smoothness for large document input and real-time preview + +**Section Sources** + +- [frontend/pro/monaco-editor/useValueChange.ts:4-43](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L43) + +## Dependency Analysis + +- **Component coupling** + - The backend component is only responsible for declarations and frontend directory resolution; logic decoupling is clean + - The frontend bridges React components via Svelte with single-responsibility +- **External dependencies** + - `@monaco-editor/react`: Core editor capabilities + - antd Spin: Loading state display + - `lodash-es/isNumber`: Type and nullability helpers +- **Circular dependencies** + - No direct circular dependencies found; the loader and components are decoupled through function calls + +```mermaid +graph LR +PY["Backend Component"] --> IDX["Svelte Entry"] +IDX --> CORE["MonacoEditor Wrapper"] +IDX --> DIFF_IDX["Svelte Entry (Diff)"] +DIFF_IDX --> DIFF_CORE["MonacoDiffEditor Wrapper"] +CORE --> MONACO["@monaco-editor/react"] +DIFF_CORE --> MONACO +CORE --> ANT["antd Spin"] +DIFF_CORE --> ANT +CORE --> Lodash["lodash-es/isNumber"] +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-10](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L10) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-13](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L13) + +**Section Sources** + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-10](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L10) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-13](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L13) + +## Performance Considerations + +- **Loading strategy** + - CDN is recommended for production to reduce initial bundle size + - Local loading is suitable for development/debugging or offline environments +- **Input optimization** + - `useValueChange` delays callbacks to reduce the rendering impact of high-frequency input +- **Theme and styles** + - Light/dark theme switching is handled internally by Monaco; be careful to avoid duplicate style overrides +- **Diff editor** + - Large document comparisons may create memory pressure; consider splitting or limiting line count + +[This section contains general guidelines with no specific file sources] + +## Troubleshooting Guide + +- **Editor not displayed or blank** + - Check whether the loader initialization is complete (local/cdn) + - Confirm `_loader` configuration and network reachability +- **Language highlighting/IntelliSense not working** + - Confirm `language` and `options` are correctly set + - If using custom `before_mount`/`after_mount`, check whether they affect the Monaco instance +- **Validation event not triggered** + - Validation events are only triggered for languages with rich IntelliSense support +- **Line positioning not working** + - Confirm `line` is a number and within a valid range +- **Loading state not displayed** + - If a custom loading slot is used, ensure the slot content can be rendered + +**Section Sources** + +- [docs/components/pro/monaco_editor/README.md:66-89](file://docs/components/pro/monaco_editor/README.md#L66-L89) +- [frontend/pro/monaco-editor/monaco-editor.tsx:71-82](file://frontend/pro/monaco-editor/monaco-editor.tsx#L71-L82) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:141-152](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L141-L152) + +## Conclusion + +The MonacoEditor component uses Gradio as its entry point, combined with a Svelte-React bridging approach, to deliver a stable and extensible code editing experience. Its core advantages are: + +- Seamless integration with Monaco's powerful language services and ecosystem +- Clear separation of front/backend responsibilities and configurable loading strategies +- Differentiated capabilities for AI/ML scenarios (Diff Editor, validation events, theme adaptation) + +For beginners, it is recommended to start with basic usage, progressively master language settings, option configuration, and event binding, and then explore advanced customization and loading strategy optimization. + +[This section is a summary with no specific file sources] + +## Appendix + +### Basic Usage Example and Configuration Key Points + +- The example script demonstrates how to pass `value`, `language`, `height`, and `options` (e.g., disabling minimap and line numbers) +- The documentation provides API tables and event descriptions for easy reference + +**Section Sources** + +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:6-30](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L6-L30) +- [docs/components/pro/monaco_editor/README.md:31-89](file://docs/components/pro/monaco_editor/README.md#L31-L89) + +### Component API Overview (Key Fields) + +- **Common properties** + - `value`: Initial editor value + - `language`: Language mode + - `options`: Monaco constructor options + - `read_only`: Read-only toggle + - `height`: Component height + - `before_mount`/`after_mount`: JS strings executed before/after mounting +- **Events** + - `mount`: Editor mount completed + - `change`: Content changed + - `validate`: Validation triggered with error markers present +- **Slots** + - `loading`: Custom loading state + +**Section Sources** + +- [docs/components/pro/monaco_editor/README.md:31-89](file://docs/components/pro/monaco_editor/README.md#L31-L89) diff --git a/.wiki/en/Pro Components/MonacoEditor/Configuration Options.md b/.wiki/en/Pro Components/MonacoEditor/Configuration Options.md new file mode 100644 index 00000000..263705c1 --- /dev/null +++ b/.wiki/en/Pro Components/MonacoEditor/Configuration Options.md @@ -0,0 +1,406 @@ +# Configuration Options + + +**Files Referenced in This Document** +- [frontend/pro/monaco-editor/monaco-editor.tsx](file://frontend/pro/monaco-editor/monaco-editor.tsx) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx) +- [frontend/pro/monaco-editor/loader.ts](file://frontend/pro/monaco-editor/loader.ts) +- [frontend/pro/monaco-editor/useValueChange.ts](file://frontend/pro/monaco-editor/useValueChange.ts) +- [frontend/pro/monaco-editor/Index.svelte](file://frontend/pro/monaco-editor/Index.svelte) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte](file://frontend/pro/monaco-editor/diff-editor/Index.svelte) +- [backend/modelscope_studio/components/pro/monaco_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py) +- [docs/components/pro/monaco_editor/README.md](file://docs/components/pro/monaco_editor/README.md) +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Configuration Reference and Examples](#appendix-configuration-reference-and-examples) + +## Introduction + +This document is a complete configuration options reference for MonacoEditor in the current repository, covering key aspects such as editor appearance, behavior, functionality, language and theme, loading and performance. Combined with the frontend and Python backend integration approach, it provides directly applicable configuration recommendations, best practices, and common compatibility considerations. + +## Project Structure + +The configuration and usage of MonacoEditor spans the following layers: + +- **Documentation layer**: Provides component API descriptions and example entry points +- **Frontend layer**: Svelte wrapper, React component, loader, and event bridging +- **Backend layer**: Gradio component wrapper exposing properties, events, and slots + +```mermaid +graph TB +subgraph "Documentation Layer" +D1["docs/components/pro/monaco_editor/README.md"] +D2["docs/components/pro/monaco_editor/demos/monaco_editor_options.py"] +end +subgraph "Frontend Layer" +F1["frontend/pro/monaco-editor/Index.svelte"] +F2["frontend/pro/monaco-editor/diff-editor/Index.svelte"] +F3["frontend/pro/monaco-editor/monaco-editor.tsx"] +F4["frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx"] +F5["frontend/pro/monaco-editor/loader.ts"] +F6["frontend/pro/monaco-editor/useValueChange.ts"] +end +subgraph "Backend Layer" +B1["backend/modelscope_studio/components/pro/monaco_editor/__init__.py"] +B2["backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py"] +end +D1 --> F1 +D1 --> F2 +D2 --> F1 +F1 --> F3 +F2 --> F4 +F3 --> F5 +F4 --> F5 +F3 --> F6 +F4 --> F6 +F1 --> B1 +F2 --> B2 +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/Index.svelte:1-101](file://frontend/pro/monaco-editor/Index.svelte#L1-L101) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:1-103](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L1-L103) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L161) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:1-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L1-L107) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:1-106](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L1-L106) + +Section Sources + +- [docs/components/pro/monaco_editor/README.md:1-89](file://docs/components/pro/monaco_editor/README.md#L1-L89) +- [frontend/pro/monaco-editor/Index.svelte:1-101](file://frontend/pro/monaco-editor/Index.svelte#L1-L101) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:1-103](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L1-L103) + +## Core Components + +- **MonacoEditor (Standard Editor)** + - Maps Gradio properties to Monaco constructor parameters, handling loading state, read-only, theme mode, value changes, and mount callbacks + - Supports passing Monaco constructor options via `options`; supports injecting JS strings via `before_mount`/`after_mount` +- **MonacoDiffEditor (Diff Editor)** + - Displays left/right content comparison, supports separate language settings for original and modified content, line positioning, and validation marker listening + - Supports `options` and read-only configuration; supports the `line` parameter to scroll to a specified line after mounting +- **Loader (local/CDN)** + - Initializes the Monaco environment and Web Workers; selects local bundling or CDN path on demand +- **Value change throttling** + - Uses a timer to avoid frequent upper-level callback triggers, improving input experience and performance + +Section Sources + +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L161) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) + +## Architecture Overview + +The call chain for MonacoEditor in this project is as follows: + +```mermaid +sequenceDiagram +participant Py as "Python Component
ModelScopeProMonacoEditor" +participant FE as "Svelte Wrapper
Index.svelte" +participant R as "React Component
monaco-editor.tsx" +participant M as "Monaco Instance" +participant L as "Loader
loader.ts" +Py->>FE : Pass properties (value/language/options/height/...) +FE->>L : Initialize local/CDN loader +FE->>R : Render Editor with injected props +R->>M : Create editor instance (merge options and readOnly) +R-->>FE : Mount callbacks (beforeMount/afterMount) +R-->>Py : Value change callback (change event) +``` + +Diagram Sources + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:46-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L46-L107) +- [frontend/pro/monaco-editor/Index.svelte:64-90](file://frontend/pro/monaco-editor/Index.svelte#L64-L90) +- [frontend/pro/monaco-editor/monaco-editor.tsx:56-88](file://frontend/pro/monaco-editor/monaco-editor.tsx#L56-L88) +- [frontend/pro/monaco-editor/loader.ts:27-78](file://frontend/pro/monaco-editor/loader.ts#L27-L78) + +## Detailed Component Analysis + +### Standard Editor (MonacoEditor) Configuration Key Points + +- **Property mapping and defaults** + - `value`, `language`, `line`, `read_only`, `loading`, `options`, `overrideServices`, `height`, `before_mount`, `after_mount` + - Theme mode is determined by `themeMode`; dark mode maps to `vs-dark`, otherwise `light` +- **Behavioral characteristics** + - `options` and `readOnly` are merged and passed to the underlying constructor + - The `onChange` callback synchronously updates the displayed value to avoid frequent upstream notifications + - Loading state supports custom slots or the default spinner +- **Events and slots** + - Events: `mount`, `change`, `validate` (only triggered in languages with rich IntelliSense) + - Slots: `loading` + +```mermaid +flowchart TD +Start(["Enter Editor Render"]) --> MergeOpts["Merge options and readOnly"] +MergeOpts --> ThemeMap["Map theme based on themeMode"] +ThemeMap --> Loading["Render loading slot or default"] +Loading --> MountHooks["Execute beforeMount/afterMount"] +MountHooks --> ListenChange["Listen for value changes and throttle reporting"] +ListenChange --> End(["Done"]) +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/monaco-editor.tsx:64-88](file://frontend/pro/monaco-editor/monaco-editor.tsx#L64-L88) +- [frontend/pro/monaco-editor/useValueChange.ts:14-32](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L32) + +Section Sources + +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [docs/components/pro/monaco_editor/README.md:35-74](file://docs/components/pro/monaco_editor/README.md#L35-L74) + +### Diff Editor (MonacoDiffEditor) Configuration Key Points + +- **Property mapping and defaults** + - `value` (right side), `original` (left side), `language`, `original_language`, `modified_language`, `line`, `read_only`, `loading`, `options`, `overrideServices`, `height`, `before_mount`, `after_mount` +- **Behavioral characteristics** + - Read-only and `options` are merged and passed to the underlying constructor + - After mounting, scrolls to the line specified by the `line` parameter + - Listens for model marker changes and triggers the `validate` event + - The `onChange` callback synchronously updates the right-side editor value +- **Events and slots** + - Events: `mount`, `change`, `validate` + - Slots: `loading` + +```mermaid +sequenceDiagram +participant FE as "DiffEditor Wrapper" +participant R as "DiffEditor Component" +participant E as "Right-side Editor" +participant M as "Monaco Marker System" +FE->>R : Render DiffEditor (merge options and readOnly) +R->>E : Get right-side editor instance +R->>E : If line provided, scroll to that line +R->>E : Listen for content changes, sync value +R->>M : Listen for marker changes, trigger validate +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:67-98](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L67-L98) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:127-153](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L127-L153) + +Section Sources + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L161) +- [docs/components/pro/monaco_editor/README.md:48-74](file://docs/components/pro/monaco_editor/README.md#L48-L74) + +### Loader and Theme + +- **Loader** + - Local loading: Dynamically imports Monaco and various language workers; sets `MonacoEnvironment.getWorker` + - CDN loading: Configures the `vs` path via monaco-loader +- **Theme** + - Maps dark mode to `vs-dark` via `themeMode`, otherwise `light`; uniformly handled by the underlying Editor + +```mermaid +flowchart TD +Init(["Initialize Loader"]) --> Mode{"Mode?"} +Mode --> |local| Local["Dynamically import monaco and workers
Set MonacoEnvironment"] +Mode --> |cdn| CDN["Configure monaco-loader vs path"] +Local --> Done(["Done"]) +CDN --> Done +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/loader.ts:27-78](file://frontend/pro/monaco-editor/loader.ts#L27-L78) +- [frontend/pro/monaco-editor/loader.ts:80-94](file://frontend/pro/monaco-editor/loader.ts#L80-L94) +- [frontend/pro/monaco-editor/monaco-editor.tsx:87-88](file://frontend/pro/monaco-editor/monaco-editor.tsx#L87-L88) + +Section Sources + +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) + +### Value Change Throttle Mechanism + +- **Goal**: Reduce callback storms caused by high-frequency input +- **Mechanism**: Starts a timer on input; if no new input occurs within 100ms, commits one change +- **Effect**: Reduces upper-level processing pressure and improves interaction smoothness + +```mermaid +flowchart TD +In(["New value received"]) --> SetTyping["Mark as typing"] +SetTyping --> Timer["Start 100ms timer"] +Timer --> NewInput{"New input during timer?"} +NewInput --> |Yes| Reset["Reset timer"] --> Timer +NewInput --> |No| Commit["Commit change and clear state"] +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/useValueChange.ts:14-24](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L24) +- [frontend/pro/monaco-editor/useValueChange.ts:26-32](file://frontend/pro/monaco-editor/useValueChange.ts#L26-L32) + +Section Sources + +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) + +## Dependency Analysis + +- **Component coupling** + - The Svelte wrapper is responsible for property forwarding and loader initialization + - The React component is responsible for specific editor instantiation and event binding + - The loader and Workers are decoupled from the editor logic +- **External dependencies** + - `@monaco-editor/react` provides Editor/DiffEditor + - `monaco-editor` and language workers + - Gradio component bridging (Python layer) + +```mermaid +graph LR +Svelte["Svelte Wrapper"] --> ReactComp["React Component"] +ReactComp --> Monaco["@monaco-editor/react"] +ReactComp --> Loader["Loader"] +Loader --> MonacoLib["monaco-editor"] +Loader --> Workers["Language Workers"] +Svelte --> Gradio["Gradio Component (Python)"] +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/Index.svelte:10-12](file://frontend/pro/monaco-editor/Index.svelte#L10-L12) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-2](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L2) +- [frontend/pro/monaco-editor/loader.ts:33-51](file://frontend/pro/monaco-editor/loader.ts#L33-L51) + +Section Sources + +- [frontend/pro/monaco-editor/Index.svelte:1-101](file://frontend/pro/monaco-editor/Index.svelte#L1-L101) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L95) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) + +## Performance Considerations + +- **Loading strategy** + - Prefer local loading to reduce the impact of network jitter on initial load; for offline or intranet deployments, fix the version and pre-warm + - In CDN mode, ensure paths are stable to avoid repeated downloads +- **Language and Workers** + - Load only the workers needed for the required languages to reduce memory usage + - If custom languages are needed, introduce additional workers carefully +- **Input performance** + - Use the built-in throttle mechanism to avoid upper-level redraws caused by high-frequency changes +- **View and layout** + - Set `height` reasonably to avoid unnecessary reflows from oversized containers + - Disable unnecessary features (e.g., `minimap`, `lineNumbers`) to reduce rendering cost + +Section Sources + +- [frontend/pro/monaco-editor/loader.ts:53-69](file://frontend/pro/monaco-editor/loader.ts#L53-L69) +- [frontend/pro/monaco-editor/useValueChange.ts:14-24](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L24) +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:24-29](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L24-L29) + +## Troubleshooting Guide + +- **Editor not loading or blank** + - Check the `_loader` configuration (mode/local/cdn_url); confirm that loader initialization succeeded + - Confirm that `before_mount`/`after_mount` do not block the main thread +- **Language highlighting missing** + - Confirm `language` is set correctly; if using a custom language, check whether the corresponding worker is loaded +- **Read-only not working** + - Confirm there is no conflict between how `read_only` is passed and `options` (the latter overrides the former); it is recommended to control this consistently via `read_only` +- **Line scroll not working** + - For DiffEditor, the `line` parameter takes effect after mounting; confirm `line` is a number and is set after mount completes +- **Event not triggered** + - The `validate` event is only triggered in languages with rich IntelliSense; confirm the language and validation rules are enabled + +Section Sources + +- [frontend/pro/monaco-editor/loader.ts:27-78](file://frontend/pro/monaco-editor/loader.ts#L27-L78) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:110-113](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L110-L113) +- [docs/components/pro/monaco_editor/README.md:74-74](file://docs/components/pro/monaco_editor/README.md#L74-L74) + +## Conclusion + +The MonacoEditor wrapper in this repository provides clear property mapping, event bridging, and loader abstraction, preserving Monaco's powerful capabilities while lowering the barrier to use in the Gradio ecosystem. By properly configuring `options`, choosing the appropriate loading mode and language workers, and utilizing the built-in throttle mechanism, you can achieve good performance while maintaining a smooth user experience. + +## Appendix: Configuration Reference and Examples + +### Property Overview (Standard Editor) + +- `value`: Initial editor value +- `language`: Editor language +- `line`: Scroll vertically to the specified line +- `read_only`: Whether read-only +- `loading`: Loading prompt text or slot +- `options`: Monaco constructor options (passes through `IStandaloneEditorConstructionOptions`) +- `overrideServices`: Service overrides (passes through `IEditorOverrideServices`) +- `height`: Component height (number = px, string = CSS unit) +- `before_mount`: JS function string executed before loading (can access `monaco`) +- `after_mount`: JS function string executed after loading (can access `editor` and `monaco`) + +Section Sources + +- [docs/components/pro/monaco_editor/README.md:35-47](file://docs/components/pro/monaco_editor/README.md#L35-L47) +- [frontend/pro/monaco-editor/monaco-editor.tsx:35-70](file://frontend/pro/monaco-editor/monaco-editor.tsx#L35-L70) + +### Property Overview (Diff Editor) + +- `value`: Modified source (right side) +- `original`: Original source (left side) +- `language`: Editor language +- `original_language`: Separate language for the original source +- `modified_language`: Separate language for the modified source +- `line`: Scroll vertically to the specified line +- `read_only`: Whether read-only +- `loading`: Loading prompt text or slot +- `options`: Monaco constructor options (passes through `IStandaloneEditorConstructionOptions`) +- `overrideServices`: Service overrides (passes through `IEditorOverrideServices`) +- `height`: Component height (number = px, string = CSS unit) +- `before_mount`: JS function string executed before loading (can access `monaco`) +- `after_mount`: JS function string executed after loading (can access `editor` and `monaco`) + +Section Sources + +- [docs/components/pro/monaco_editor/README.md:48-65](file://docs/components/pro/monaco_editor/README.md#L48-L65) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:49-153](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L49-L153) + +### Events and Slots + +- **Events** + - `mount`: Editor mount completed + - `change`: Editor value changed + - `validate`: Triggered when validation markers are present (only certain languages) +- **Slots** + - `loading`: Custom loading state + +Section Sources + +- [docs/components/pro/monaco_editor/README.md:66-89](file://docs/components/pro/monaco_editor/README.md#L66-L89) + +### Configuration Examples and Best Practices + +- **Basic example (with options)** + - Reference: docs/components/pro/monaco_editor/demos/monaco_editor_options.py + - Recommendation: Disable `minimap` and line numbers in `options` for better performance +- **Language and theme** + - Language: Set via `language`; for different languages on each side of the diff editor, set `original_language` and `modified_language` separately + - Theme: Automatically mapped to `vs-dark`/`light` via `themeMode` +- **Loading mode** + - Local: Suitable for controlled environments and offline scenarios + - CDN: Suitable for quick deployment and multi-version management + +Section Sources + +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:1-34](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L1-L34) +- [frontend/pro/monaco-editor/monaco-editor.tsx:87-88](file://frontend/pro/monaco-editor/monaco-editor.tsx#L87-L88) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:43-44](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L43-L44) diff --git a/.wiki/en/Pro Components/MonacoEditor/Diff Editor.md b/.wiki/en/Pro Components/MonacoEditor/Diff Editor.md new file mode 100644 index 00000000..87b74fc2 --- /dev/null +++ b/.wiki/en/Pro Components/MonacoEditor/Diff Editor.md @@ -0,0 +1,383 @@ +# Diff Editor + + +**Files Referenced in This Document** +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte](file://frontend/pro/monaco-editor/diff-editor/Index.svelte) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py) +- [docs/components/pro/monaco_editor/README.md](file://docs/components/pro/monaco_editor/README.md) +- [docs/components/pro/monaco_editor/README-zh_CN.md](file://docs/components/pro/monaco_editor/README-zh_CN.md) +- [docs/components/pro/monaco_editor/demos/diff_editor.py](file://docs/components/pro/monaco_editor/demos/diff_editor.py) +- [frontend/pro/monaco-editor/loader.ts](file://frontend/pro/monaco-editor/loader.ts) +- [frontend/pro/monaco-editor/useValueChange.ts](file://frontend/pro/monaco-editor/useValueChange.ts) +- [frontend/pro/monaco-editor/monaco-editor.less](file://frontend/pro/monaco-editor/monaco-editor.less) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document focuses on the Diff Editor capability of MonacoEditor. It systematically explains how to use the diff editor for side-by-side comparison, diff highlighting, and synchronized scrolling within the ModelScope Studio Pro component system. It covers configuration options, event binding, loading modes (local/CDN), and usage recommendations for version control and code review scenarios. It also provides technical analysis of internal implementation mechanisms such as value change throttling, validation marker listening, theming, and loading states, helping readers customize and optimize behavior in complex scenarios. + +## Project Structure + +The diff editor is composed of three coordinated parts: a frontend Svelte component bridge, a React wrapper layer, and a backend Gradio component: + +- The frontend Svelte layer handles prop forwarding, loader initialization, and slot rendering; +- The React wrapper layer handles integration with `@monaco-editor/react` DiffEditor, event binding, value change throttling, and validation marker listening; +- The backend Python component manages the Gradio lifecycle, event declarations, and frontend resource directory mapping. + +```mermaid +graph TB +subgraph "Backend" +PY["Python Component
ModelScopeProMonacoEditorDiffEditor"] +end +subgraph "Frontend" +IDX["Svelte Entry
Index.svelte"] +WRAP["React Wrapper
monaco-editor.diff-editor.tsx"] +LDR["Loader
loader.ts"] +VAL["Value Change Throttle Hook
useValueChange.ts"] +STY["Styles
monaco-editor.less"] +end +PY --> IDX +IDX --> LDR +IDX --> WRAP +WRAP --> VAL +WRAP --> STY +``` + +**Diagram Source** + +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:1-103](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L1-L103) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-160](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L160) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) + +**Section Source** + +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:1-103](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L1-L103) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-160](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L160) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:1-106](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L1-L106) + +## Core Components + +- **Frontend Diff Editor Wrapper**: Handles integration with `@monaco-editor/react` DiffEditor, processes value changes, validation markers, theme switching, loading state, and mount callbacks. +- **Svelte Entry Component**: Handles loader initialization (local or CDN), prop forwarding, slot rendering, and visibility control. +- **Backend Gradio Component**: Declares events (`mount`/`change`/`validate`), exposes properties and default values, and maps the frontend resource directory. +- **Loader**: Uniformly initializes the Monaco environment and Web Workers, supporting both local bundling and CDN path configuration. +- **Value Change Throttle Hook**: Reduces callback frequency during high-frequency input, improving interaction smoothness. +- **Styles**: Provides full-size loading container dimensions and theme class name conventions. + +**Section Source** + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-33](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L33) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:1-103](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L1-L103) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:10-31](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L10-L31) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) + +## Architecture Overview + +The diff editor call chain is as follows: + +- The backend component instantiates and declares events; +- The frontend Svelte entry initializes the loader based on the `_loader` configuration; +- The React wrapper mounts the DiffEditor and registers content change and validation marker listeners; +- User interactions trigger value changes, which are throttled before being passed upstream; +- The theme switches with the Gradio shared theme, and the loading state supports customizable slots. + +```mermaid +sequenceDiagram +participant Py as "Backend Component" +participant S as "Svelte Entry" +participant L as "Loader" +participant R as "React Wrapper" +participant M as "@monaco-editor/react DiffEditor" +Py->>S : Initialize and pass props/events +S->>L : Select local or CDN based on _loader mode +L-->>S : Monaco environment and Worker injection complete +S->>R : Forward props and render +R->>M : onMount registers content change and validation listeners +M-->>R : Trigger onChange/onValidate +R-->>S : onValueChange returns throttled value +S-->>Py : Update value and trigger events +``` + +**Diagram Source** + +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:14-31](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L14-L31) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:66-91](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L66-L91) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:67-98](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L67-L98) + +## Detailed Component Analysis + +### React Wrapper (Diff Editor) + +This component is the core implementation of the diff editor. Its responsibilities include: + +- Receiving and merging `options` and read-only state; +- Listening to content changes on the modified editor side, triggering `onValueChange` and `onChange`; +- Listening to validation marker changes, triggering `onValidate`; +- Supporting line number-based positioning and scrolling; +- Automatically switching themes with the Gradio theme; +- Providing a pluggable `loading` slot. + +```mermaid +classDiagram +class MonacoDiffEditor { ++height ++className ++style ++themeMode ++slots ++beforeMount ++afterMount ++children ++onMount ++onChange ++onValueChange ++onValidate ++value ++modified ++options ++readOnly ++line ++handleEditorMount(editor, monaco) ++useEffect(clean up Disposable) ++useEffect(scroll to line) +} +``` + +**Diagram Source** + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-33](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L33) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:67-98](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L67-L98) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:109-113](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L109-L113) + +**Section Source** + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-160](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L160) + +### Svelte Entry (Loading and Prop Forwarding) + +- Decides between local loading and CDN based on `_loader.mode`; +- Forwards the Gradio shared theme to the React wrapper to enable theme synchronization; +- Renders `children` as a React Slot, supporting the `loading` slot; +- Writes back the value from `onValueChange` to the component state via `updateProps`. + +```mermaid +flowchart TD +Start(["Enter Svelte Entry"]) --> CheckMode{"Check _loader.mode"} +CheckMode --> |local| InitLocal["initLocalLoader()"] +CheckMode --> |cdn| InitCDN["initCDNLoader(cdn_url)"] +CheckMode --> |not set| Skip["Skip initialization"] +InitLocal --> Render["Render React Wrapper"] +InitCDN --> Render +Skip --> Render +Render --> Theme["Forward themeMode"] +Theme --> Slots["Forward children/slots"] +Slots --> Done(["Done"]) +``` + +**Diagram Source** + +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:66-91](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L66-L91) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +**Section Source** + +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:1-103](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L1-L103) + +### Backend Component (Gradio) + +- Declares events: `mount`, `change`, `validate`; +- Supports slots: `loading`; +- Exposes properties: `original`, `language`, `original_language`, `modified_language`, `line`, `read_only`, `options`, `override_services`, `height`, `before_mount`, `after_mount`, etc.; +- Maps the frontend resource directory to `pro/monaco-editor/diff-editor`. + +```mermaid +classDiagram +class ModelScopeProMonacoEditorDiffEditor { ++EVENTS ++SLOTS ++original ++line ++loading ++override_services ++options ++read_only ++before_mount ++after_mount ++language ++original_language ++modified_language ++height ++FRONTEND_DIR ++api_info() ++preprocess() ++postprocess() +} +``` + +**Diagram Source** + +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:14-31](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L14-L31) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:36-82](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L36-L82) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:84-86](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L84-L86) + +**Section Source** + +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:1-106](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L1-L106) + +### Loader (Local/CDN) + +- **Local loading**: Dynamically imports `monaco-editor` and various language Workers, then injects `MonacoEnvironment`; +- **CDN loading**: Points to a CDN via path configuration; +- Unified initialization entry point to avoid duplicate loading. + +```mermaid +flowchart TD +A["Call initLocalLoader()/initCDNLoader()"] --> B{"Already initialized?"} +B --> |No| C["Wait for initialization to complete"] +B --> |Yes| D["Local: inject MonacoEnvironment and Worker"] +B --> |Yes| E["CDN: configure vs path"] +D --> F["Done"] +E --> F +``` + +**Diagram Source** + +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +**Section Source** + +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) + +### Value Change Throttle Hook + +- Delays triggering `onValueChange` during high-frequency input to reduce upstream update frequency; +- Controls the display value and callback timing via a timer and `typing` state. + +```mermaid +flowchart TD +Start(["Receive new value"]) --> SetTyping["Set typing=true"] +SetTyping --> ClearTimer["Clear old timer"] +ClearTimer --> StartTimer["Start 100ms timer"] +StartTimer --> Callback["Trigger onValueChange"] +Callback --> ResetTyping["Timer ends, typing=false"] +ResetTyping --> UpdateDisplay["Update display value outside typing period"] +``` + +**Diagram Source** + +- [frontend/pro/monaco-editor/useValueChange.ts:14-32](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L32) + +**Section Source** + +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) + +## Dependency Analysis + +- The React wrapper depends on `@monaco-editor/react` DiffEditor and `monaco-editor` types; +- Uses `useValueChange` for throttling; +- The Svelte entry depends on the loader and `ReactSlot`; +- The backend component depends on the Gradio event system and frontend resource directory mapping. + +```mermaid +graph LR +PY["Backend Component"] --> IDX["Svelte Entry"] +IDX --> LDR["Loader"] +IDX --> WRAP["React Wrapper"] +WRAP --> VAL["useValueChange"] +WRAP --> MONACO["@monaco-editor/react DiffEditor"] +WRAP --> STY["monaco-editor.less"] +``` + +**Diagram Source** + +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:84-86](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L84-L86) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:12-14](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L12-L14) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-17](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L17) +- [frontend/pro/monaco-editor/useValueChange.ts:1-2](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L2) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) + +**Section Source** + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-17](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L17) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:12-14](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L12-L14) + +## Performance Considerations + +- **Input throttling**: `useValueChange` reduces callback frequency during high-frequency input, preventing excessive upstream propagation and re-renders. +- **Disposable management**: Releases editor and marker listener subscriptions on unmount to prevent memory leaks. +- **Theme switching**: Switches `vs-dark`/`light` on demand, avoiding unnecessary redraws. +- **Loading strategy**: Prefer local loading to reduce network latency; in CDN mode, ensure correct paths and cache hit rates. +- **Large document optimization**: It is recommended to configure options such as `minimap`, `lineNumbers`, and `scrollBeyondLastLine` appropriately to reduce rendering overhead. + +[This section is general guidance and does not directly analyze specific files] + +## Troubleshooting Guide + +- **Editor not displaying or showing blank** + - Check whether the `_loader` configuration is correct and confirm that local loading or CDN path is available; + - Confirm that the Gradio theme is properly forwarded to `themeMode`. +- **Value not propagating or events not firing** + - Confirm that `onValueChange` is correctly bound; + - Check whether `onChange`/`onValidate` are registered; + - Confirm that the `before_mount`/`after_mount` string functions are valid. +- **Validation markers not appearing** + - Only triggered for languages with rich IntelliSense support (TypeScript, JavaScript, CSS, LESS, SCSS, JSON, HTML); + - Confirm that the `monaco.editor.onDidChangeMarkers` subscription is active. +- **Line number navigation not working** + - Confirm that `line` is passed as a numeric value; + - Confirm that `revealLine` is called only after the editor is ready. + +**Section Source** + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:67-98](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L67-L98) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:109-113](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L109-L113) +- [docs/components/pro/monaco_editor/README.md:66-74](file://docs/components/pro/monaco_editor/README.md#L66-L74) + +## Conclusion + +The diff editor in ModelScope Studio achieves a stable and extensible side-by-side comparison and diff highlighting experience through a layered design of "backend events + frontend bridging + React wrapper + loader". Combined with value change throttling, validation marker listening, and theme synchronization, it works efficiently in version control and code review scenarios. In production environments, it is recommended to combine large-document optimizations with appropriate loading strategies, and to continuously manage event and subscription lifecycles. + +[This section is a summary and does not directly analyze specific files] + +## Appendix + +### Usage Examples and Scenarios + +- **Basic diff editor example**: Demonstrates comparison between `original` and `value`, read-only toggling, and `change` event binding. +- **Version control scenario**: The left side shows the baseline version, the right side shows current modifications, combined with the `validate` event to highlight error locations. +- **Code review scenario**: Enable read-only mode to allow only viewing diffs and comments, with `before_mount`/`after_mount` for extending advanced capabilities. + +**Section Source** + +- [docs/components/pro/monaco_editor/demos/diff_editor.py:1-44](file://docs/components/pro/monaco_editor/demos/diff_editor.py#L1-L44) + +### Property and Event Reference + +- **Properties (DiffEditor)**: `value`, `original`, `language`, `original_language`, `modified_language`, `line`, `read_only`, `loading`, `options`, `override_services`, `height`, `before_mount`, `after_mount`. +- **Events**: `mount`, `change`, `validate`. +- **Slots**: `loading`. + +**Section Source** + +- [docs/components/pro/monaco_editor/README.md:48-64](file://docs/components/pro/monaco_editor/README.md#L48-L64) +- [docs/components/pro/monaco_editor/README-zh_CN.md:48-64](file://docs/components/pro/monaco_editor/README-zh_CN.md#L48-L64) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:14-31](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L14-L31) diff --git a/.wiki/en/Pro Components/MonacoEditor/Getting Started.md b/.wiki/en/Pro Components/MonacoEditor/Getting Started.md new file mode 100644 index 00000000..3e5c92e5 --- /dev/null +++ b/.wiki/en/Pro Components/MonacoEditor/Getting Started.md @@ -0,0 +1,331 @@ +# Getting Started + + +**Files Referenced in This Document** +- [frontend/pro/monaco-editor/Index.svelte](file://frontend/pro/monaco-editor/Index.svelte) +- [frontend/pro/monaco-editor/monaco-editor.tsx](file://frontend/pro/monaco-editor/monaco-editor.tsx) +- [frontend/pro/monaco-editor/loader.ts](file://frontend/pro/monaco-editor/loader.ts) +- [frontend/pro/monaco-editor/useValueChange.ts](file://frontend/pro/monaco-editor/useValueChange.ts) +- [backend/modelscope_studio/components/pro/monaco_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py) +- [docs/components/pro/monaco_editor/README.md](file://docs/components/pro/monaco_editor/README.md) +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py) +- [frontend/package.json](file://frontend/package.json) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This chapter is intended for beginners and introduces how to quickly get started with MonacoEditor in the ModelScope Studio Pro component system. Topics covered: + +- The simplest usage examples: basic text editing, language settings, height configuration +- Common parameter descriptions: how to use `language`, `height`, and `options` +- Editor initialization flow and basic configuration items +- Directly referenceable example paths and runtime behavior descriptions + +## Project Structure + +MonacoEditor is integrated on the frontend using a Svelte + React wrapper approach, and exposed to Python on the backend as a Gradio component. Key directories and files: + +- Frontend component entry: frontend/pro/monaco-editor/Index.svelte +- React wrapper: frontend/pro/monaco-editor/monaco-editor.tsx +- Loader: frontend/pro/monaco-editor/loader.ts +- Value change handling: frontend/pro/monaco-editor/useValueChange.ts +- Backend component definition: backend/modelscope_studio/components/pro/monaco_editor/**init**.py +- Documentation and examples: docs/components/pro/monaco_editor/README.md, demos/monaco_editor_options.py +- Dependency declarations: frontend/package.json + +```mermaid +graph TB +subgraph "Backend" +PyComp["Python Component
ModelScopeProMonacoEditor"] +end +subgraph "Frontend" +SvelteEntry["Svelte Entry
Index.svelte"] +ReactWrapper["React Wrapper
monaco-editor.tsx"] +Loader["Loader
loader.ts"] +ValueHook["Value Change Hook
useValueChange.ts"] +end +PyComp --> SvelteEntry +SvelteEntry --> Loader +SvelteEntry --> ReactWrapper +ReactWrapper --> ValueHook +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/Index.svelte:1-100](file://frontend/pro/monaco-editor/Index.svelte#L1-L100) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-94](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L94) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) + +Section Sources + +- [frontend/pro/monaco-editor/Index.svelte:1-100](file://frontend/pro/monaco-editor/Index.svelte#L1-L100) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-94](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L94) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:1-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L1-L107) +- [docs/components/pro/monaco_editor/README.md:1-89](file://docs/components/pro/monaco_editor/README.md#L1-L89) +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:1-34](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L1-L34) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## Core Components + +- **Backend component**: `ModelScopeProMonacoEditor` (supports language, height, options, read-only, before/after mount callbacks, etc.) +- **Frontend wrapper**: `MonacoEditor` (based on `@monaco-editor/react`, responsible for rendering and event bridging) +- **Loader**: Supports local bundling or CDN mode for loading Monaco dependencies +- **Value change hook**: `useValueChange` (debounces and merges inputs to avoid frequent triggers) + +Section Sources + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:46-85](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L46-L85) +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-19](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L19) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/useValueChange.ts:4-43](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L43) + +## Architecture Overview + +The MonacoEditor call chain goes from the Python component to the Svelte entry, then to the React wrapper, and is finally rendered by `@monaco-editor/react`. The loader is responsible for initializing the Monaco environment in either local or CDN mode. + +```mermaid +sequenceDiagram +participant Py as "Python Component" +participant Svelte as "Svelte Entry (Index.svelte)" +participant Loader as "Loader (loader.ts)" +participant React as "React Wrapper (monaco-editor.tsx)" +participant Monaco as "@monaco-editor/react" +Py->>Svelte : Pass properties and value +Svelte->>Loader : Initialize local/CDN loader +Loader-->>Svelte : Return monacoLoader configuration complete +Svelte->>React : Forward properties and render +React->>Monaco : Create editor instance +Monaco-->>React : Mount complete callback +React-->>Svelte : Trigger mount/change/validate events +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/Index.svelte:64-99](file://frontend/pro/monaco-editor/Index.svelte#L64-L99) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/monaco-editor.tsx:21-92](file://frontend/pro/monaco-editor/monaco-editor.tsx#L21-L92) + +## Detailed Component Analysis + +### Backend Component: ModelScopeProMonacoEditor + +- **Supported key parameters** + - `value`: Initial editor value + - `language`: Language mode (e.g., python/javascript) + - `height`: Editor height (number = px, string = CSS unit) + - `options`: Monaco editor constructor options dictionary + - `read_only`: Whether read-only + - `before_mount`/`after_mount`: JS callback strings executed before/after mounting + - `line`: Scroll to specified line + - `loading`: Loading prompt text + - `override_services`: Override service configuration + - `_loader`: Loader configuration (mode/cdn_url) +- **Events** + - `mount`: Triggered when the editor mounts + - `change`: Triggered when the editor value changes + - `validate`: Triggered when validation markers are ready (supported by certain languages) +- **Slots** + - `loading`: Custom loading state content + +Section Sources + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:46-85](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L46-L85) +- [docs/components/pro/monaco_editor/README.md:29-89](file://docs/components/pro/monaco_editor/README.md#L29-L89) + +### Frontend Wrapper: MonacoEditor (React) + +- **Property mapping** + - Receives all properties from the backend and passes them through to the `@monaco-editor/react` Editor + - Internally handles `themeMode` (dark/light), `height`, `options` (including `readOnly`), etc. + - Provides bridging between `onValueChange` and `onChange` +- **Loading state** + - Uses the Spin component as the default loading indicator; can be replaced via a slot +- **Event bridging** + - `onMount`/`afterMount`: Uniformly triggers mount events + - `onChange`: Combines with `useValueChange` for debounced updates + +Section Sources + +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-19](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L19) +- [frontend/pro/monaco-editor/monaco-editor.tsx:21-92](file://frontend/pro/monaco-editor/monaco-editor.tsx#L21-L92) + +### Loader: Local/CDN Mode + +- **Local mode** + - Dynamically imports `monaco-editor` and various workers + - Sets `MonacoEnvironment.getWorker` to dispatch the appropriate worker by language type + - Injects the monaco instance via `monacoLoader.config` +- **CDN mode** + - Specifies the `vs` path via `monacoLoader.config` (points to a public CDN by default) + - Supports custom `cdn_url` + +Section Sources + +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +### Value Change Handling: useValueChange + +- **Design goal** + - Avoid frequent external callbacks during user input + - Decouples the "typing" state from the final value using a timer +- **Behavior** + - Input start: Enters `typing` state + - Input end (timer): Syncs the displayed value and triggers `onValueChange` + - Component unmount: Clears the timer + +Section Sources + +- [frontend/pro/monaco-editor/useValueChange.ts:4-43](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L43) + +### Svelte Entry: Index.svelte + +- **Responsibilities** + - Parses backend-provided properties and additional attributes + - Selects the local or CDN loader based on `_loader` configuration + - Forwards theme, styles, id, class names, value, etc. to the React wrapper + - Handles visibility and slot rendering + +Section Sources + +- [frontend/pro/monaco-editor/Index.svelte:14-99](file://frontend/pro/monaco-editor/Index.svelte#L14-L99) + +### Example: Minimal Usage + +- Python-side example (path) + - [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:6-30](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L6-L30) +- Runtime behavior + - Displays an editor with default height and syntax highlighting + - Language can be switched via `language`; height can be adjusted via `height` + - Disable minimap and line numbers via `options` + +Section Sources + +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:6-30](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L6-L30) + +### Parameter Details and Best Practices + +- **language** + - Purpose: Enables syntax highlighting and IntelliSense for the corresponding language + - Recommendation: Match the actual content for better readability and validation +- **height** + - Purpose: Controls the editor container height + - Recommendation: Use a number (px) or CSS unit string (e.g., `"50vh"`) +- **options** + - Purpose: Passes Monaco constructor options such as `minimap`, `lineNumbers`, `scrollbar`, etc. + - Recommendation: Enable only necessary features to avoid excessive decoration impacting performance +- **read_only** + - Purpose: Disables editing capability + - Recommendation: Use with diff editor or read-only display scenarios +- **before_mount/after_mount** + - Purpose: Injects JS logic before/after mounting (accessing `monaco` or `editor` objects) + - Recommendation: Use with caution to avoid blocking initialization +- **line** + - Purpose: Scrolls to the specified line after the first render + - Recommendation: Combine with `value`/`modified` to ensure the editor is ready before scrolling + +Section Sources + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:46-85](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L46-L85) +- [docs/components/pro/monaco_editor/README.md:29-89](file://docs/components/pro/monaco_editor/README.md#L29-L89) + +## Dependency Analysis + +- **Frontend dependencies** + - `@monaco-editor/react`: Core editor wrapper + - `monaco-editor`: Editor and workers + - `antd`: Spin loading state component + - `svelte`: Component framework +- **Backend dependencies** + - Gradio component base class and event system + +```mermaid +graph LR +Py["Python Component"] --> FE["Svelte + React Wrapper"] +FE --> ReactMonaco["@monaco-editor/react"] +FE --> Antd["antd (Spin)"] +FE --> Monaco["monaco-editor"] +``` + +Diagram Sources + +- [frontend/package.json:17-31](file://frontend/package.json#L17-L31) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-10](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L10) + +Section Sources + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-10](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L10) + +## Performance Considerations + +- **Option trimming**: Disable unnecessary features via `options` (e.g., minimap, scrollbar, line numbers) to reduce DOM and rendering overhead +- **Debounced input**: `useValueChange` delays callbacks during input to reduce jitter from frequent updates +- **Local/CDN choice**: Local mode has a larger bundle but works offline; CDN mode has a faster initial load but requires stable network +- **Read-only scenarios**: `read_only` can significantly reduce interaction and validation costs + +## Troubleshooting Guide + +- **Editor not displayed or blank** + - Check whether the `_loader` configuration (mode/cdn_url) is correct + - Confirm the loader initialization is complete before rendering the editor +- **Language highlighting not working** + - Confirm `language` is set correctly and the corresponding language exists + - If using a custom worker, check the `MonacoEnvironment.getWorker` dispatch logic +- **Loading state not disappearing** + - Confirm the loader `done()` has been called + - If using a custom loading slot, ensure the slot content renders correctly +- **Input lag** + - Check whether `options` enables many decorations (e.g., minimap, large font, complex themes) + - Adjust the `useValueChange` throttle strategy or reduce external listeners + +Section Sources + +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/monaco-editor.tsx:71-82](file://frontend/pro/monaco-editor/monaco-editor.tsx#L71-L82) +- [frontend/pro/monaco-editor/useValueChange.ts:14-24](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L24) + +## Conclusion + +With the components and flow described above, ModelScope Studio's MonacoEditor can fulfill basic editing requirements in the Python environment with minimal configuration. It is recommended to start with the minimal configuration (`language`, `height`, `options`) and progressively introduce advanced capabilities such as read-only mode, mount callbacks, and line positioning for a better development experience and performance. + +## Appendix + +- **Quick example (Python)** + - Example path: [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:6-30](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L6-L30) +- **API reference** + - Property and event descriptions: [docs/components/pro/monaco_editor/README.md:29-89](file://docs/components/pro/monaco_editor/README.md#L29-L89) +- **Initialization flow diagram** + +```mermaid +flowchart TD +Start(["Start"]) --> ParseProps["Parse backend properties
value/language/height/options, etc."] +ParseProps --> DecideLoader{"Select loader mode"} +DecideLoader --> |Local| LocalInit["Dynamically import monaco and workers
Configure MonacoEnvironment"] +DecideLoader --> |CDN| CDNInit["Configure vs path
Point to CDN"] +LocalInit --> Render["Render React wrapper"] +CDNInit --> Render +Render --> Mount["Mount editor
Trigger mount/change/validate"] +Mount --> End(["Done"]) +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/Index.svelte:64-99](file://frontend/pro/monaco-editor/Index.svelte#L64-L99) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/monaco-editor.tsx:21-92](file://frontend/pro/monaco-editor/monaco-editor.tsx#L21-L92) diff --git a/.wiki/en/Pro Components/MonacoEditor/MonacoEditor.md b/.wiki/en/Pro Components/MonacoEditor/MonacoEditor.md new file mode 100644 index 00000000..461b2596 --- /dev/null +++ b/.wiki/en/Pro Components/MonacoEditor/MonacoEditor.md @@ -0,0 +1,367 @@ +# MonacoEditor + + +**Files Referenced in This Document** +- [backend/modelscope_studio/components/pro/monaco_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [frontend/pro/monaco-editor/monaco-editor.tsx](file://frontend/pro/monaco-editor/monaco-editor.tsx) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx) +- [frontend/pro/monaco-editor/loader.ts](file://frontend/pro/monaco-editor/loader.ts) +- [frontend/pro/monaco-editor/useValueChange.ts](file://frontend/pro/monaco-editor/useValueChange.ts) +- [frontend/pro/monaco-editor/monaco-editor.less](file://frontend/pro/monaco-editor/monaco-editor.less) +- [docs/components/pro/monaco_editor/README.md](file://docs/components/pro/monaco_editor/README.md) +- [docs/components/pro/monaco_editor/README-zh_CN.md](file://docs/components/pro/monaco_editor/README-zh_CN.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is intended for developers who need to integrate a professional code editor into their applications. It systematically introduces the code editing capabilities based on Monaco Editor: syntax highlighting, IntelliSense, code completion, Diff editor, and more. The document covers component configuration (editor options, JavaScript customization, diff editor, etc.), usage examples (support for different programming languages and custom configurations), the editor loading mechanism and performance optimization strategies, theme configuration, keyboard shortcut binding, and plugin extension approaches. The content balances technical depth with readability to help you quickly deliver a high-quality code editing experience. + +## Project Structure + +This component is built on a clearly layered frontend/backend architecture, using a hybrid approach of "Python backend + React frontend + Svelte preprocessing": + +- The backend is wrapped as a Gradio component, providing a unified Python API and event bindings +- The frontend uses `@monaco-editor/react` as the rendering layer, combined with a local/CDN loader to initialize the Monaco environment +- Two forms are provided: a standard editor and a Diff editor, supporting theme switching, read-only mode, line positioning, and custom loading states + +```mermaid +graph TB +subgraph "Backend" +PY_API["Python Interface
Gradio Component Wrapper"] +end +subgraph "Frontend" +IDX["Svelte Entry
Index.svelte"] +EDIT["Standard Editor
monaco-editor.tsx"] +DIFF["Diff Editor
diff-editor/monaco-editor.diff-editor.tsx"] +LDR["Loader
loader.ts"] +VAL["Value Sync Hook
useValueChange.ts"] +CSS["Styles
monaco-editor.less"] +end +PY_API --> IDX +IDX --> EDIT +IDX --> DIFF +EDIT --> LDR +DIFF --> LDR +EDIT --> VAL +DIFF --> VAL +EDIT --> CSS +DIFF --> CSS +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-160](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L160) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) + +Section Sources + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:1-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L1-L107) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:68-105](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L68-L105) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## Core Components + +- **Standard Editor Component**: Provides basic code editing capabilities, supporting theme mode, read-only, height, loading state, event bindings, JavaScript customization hooks, etc. +- **Diff Editor Component (MonacoEditorDiffEditor)**: Used to compare the differences between two texts, with independent language settings for the left and right sides, line positioning, and validation callbacks. + - **Backend export entry**: `MonacoEditorDiffEditor` is exported through [backend/modelscope_studio/components/pro/**init**.py](file://backend/modelscope_studio/components/pro/__init__.py); import with `from modelscope_studio.components.pro import MonacoEditorDiffEditor` + - **Relationship with the standard editor**: `MonacoEditorDiffEditor` is a sub-component of `MonacoEditor`, both belonging to the `pro` module. The standard editor is for single-file editing; the diff editor is specifically for displaying a diff comparison between two versions of code. +- **Loader**: Supports both local bundling and CDN loading modes, automatically injecting the Monaco environment and multi-language Workers +- **Value sync hook**: Performs debouncing for high-frequency input scenarios to avoid frequently triggering upper-level logic + +Section Sources + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:68-105](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L68-L105) +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-160](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L160) +- [frontend/pro/monaco-editor/loader.ts:27-95](file://frontend/pro/monaco-editor/loader.ts#L27-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:4-44](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L44) + +## Architecture Overview + +The overall call chain is as follows: + +- The backend component instantiation sets loader mode, language, read-only, height, and other parameters +- The frontend entry initializes the Monaco environment (local or CDN) based on the loader configuration +- The React layer renders the editor via `@monaco-editor/react`, bridging lifecycle hooks and events +- Value changes are debounced by `useValueChange` to ensure performance and consistency + +```mermaid +sequenceDiagram +participant Py as "Backend Component" +participant FE as "Frontend Entry" +participant L as "Loader" +participant R as "React Editor" +participant M as "Monaco Environment" +Py->>FE : Pass loader configuration and properties +FE->>L : Initialize local/CDN loader +L->>M : Inject monaco instance and Workers +FE->>R : Render editor with options +R->>M : onMount lifecycle callback +R-->>Py : Change events and value return +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/loader.ts:3-95](file://frontend/pro/monaco-editor/loader.ts#L3-L95) +- [frontend/pro/monaco-editor/monaco-editor.tsx:38-92](file://frontend/pro/monaco-editor/monaco-editor.tsx#L38-L92) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:67-158](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L67-L158) + +## Detailed Component Analysis + +### Standard Editor Component + +- **Responsibility**: Wraps Monaco Editor as a React component, providing a unified property interface and event bindings +- **Key features**: + - Theme mode: Switches between `vs-dark` or `light` based on `themeMode` + - Read-only mode: Controlled via `readOnly` + - Height control: `height` supports numeric values (px) and CSS strings + - Loading state: Supports custom loading slots or default Spin + - Event bindings: Supports `mount` / `change` / `validate` and other events + - JavaScript customization: `before_mount`/`after_mount` accept JS string functions to execute before/after loading + - Value sync: Internally uses `useValueChange` for debouncing to avoid performance issues from high-frequency input + +```mermaid +classDiagram +class StandardEditorProps { ++string|undefined value ++string|undefined language ++boolean|undefined readOnly ++string|number|undefined height ++object|undefined options ++string|undefined themeMode ++function|undefined beforeMount ++function|undefined afterMount ++function|undefined onValueChange +} +class useValueChange { ++Returns : [value, setValue] ++Purpose : Debounced value update +} +StandardEditorProps --> useValueChange : "uses" +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:4-44](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L44) + +Section Sources + +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) + +### Diff Editor Component + +- **Responsibility**: Compares differences between two texts, with independent language settings for left/right sides, line positioning, read-only, and validation callbacks +- **Key features**: + - Left and right values: `original` (left original value), `value`/`modified` (right modified value) + - Independent language settings: `original_language` and `modified_language` can be set independently + - Line positioning: `line` specifies the initial visible line, with runtime update support + - Validation callback: `onValidate` retrieves validation results for easy integration with error markers + - Event binding: `onChange` fires when the right editor content changes + - Loading state: Supports custom loading slots or default Spin + +```mermaid +sequenceDiagram +participant FE as "Frontend Diff Editor" +participant E as "DiffEditor" +participant V as "useValueChange" +participant CB as "Callbacks" +FE->>E : Render with options/readOnly +E-->>FE : onMount returns editor instance +FE->>CB : afterMount callback can access editor and monaco +E->>V : Content change setValue +V-->>FE : Return new value after debounce +FE-->>CB : onChange/onValidate callbacks +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:35-159](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L35-L159) + +Section Sources + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-160](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L160) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:68-105](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L68-L105) + +### Loader and Environment Initialization + +- **Local loading (recommended for offline/intranet deployment)** + - Dynamically imports `monaco-editor` and various language Workers + - Sets `MonacoEnvironment.getWorker` to select the corresponding Worker by label + - Injects the monaco instance via `monacoLoader.config` +- **CDN loading** + - Specifies the `vs` path via `monacoLoader.config` + - Suitable for scenarios where external network access is available +- **Concurrent initialization** + - Uses a global Promise to avoid duplicate initialization + - Supports safe completion callbacks for multiple calls + +```mermaid +flowchart TD +Start(["Start"]) --> Mode{"Loading Mode"} +Mode --> |Local| Local["Dynamically import monaco and Workers"] +Mode --> |CDN| CDN["Set vs path"] +Local --> Env["Configure MonacoEnvironment.getWorker"] +Env --> Config["monacoLoader.config injection"] +CDN --> Config +Config --> Done(["Done"]) +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/loader.ts:27-95](file://frontend/pro/monaco-editor/loader.ts#L27-L95) + +Section Sources + +- [frontend/pro/monaco-editor/loader.ts:3-95](file://frontend/pro/monaco-editor/loader.ts#L3-L95) + +### Value Sync and Debounce Strategy + +- **Scenario**: High-frequency `onChange` triggered from the editor; upper-level logic may be expensive +- **Strategy**: `useValueChange` merges updates within a short time window and returns the latest value only after the debounce period ends +- **Behavior**: Manages typing state and timers to ensure a smooth experience during input + +```mermaid +flowchart TD +Enter(["Input Event"]) --> SetTyping["Mark as typing"] +SetTyping --> Debounce["Start debounce timer (~100ms)"] +Debounce --> Update["Timer ends, update displayed value"] +Update --> Callback["Trigger upper-level onValueChange"] +Callback --> Clear["Clear timer"] +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/useValueChange.ts:14-32](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L32) + +Section Sources + +- [frontend/pro/monaco-editor/useValueChange.ts:4-44](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L44) + +## Dependency Analysis + +- **Component exports** + - Backend exports both the standard editor and diff editor classes +- **Frontend dependencies** + - `@monaco-editor/react`: Editor rendering and event bridging + - `@svelte-preprocess-react`: Svelte and React interoperability + - Ant Design Spin: Default loading state component + - `useValueChange`: Custom hook for value sync and debouncing +- **External interfaces** + - Monaco Editor official types and API + - Gradio event listening and property forwarding + +```mermaid +graph LR +BE["Backend Component"] --> FEI["Frontend Entry"] +FEI --> REACT["@monaco-editor/react"] +FEI --> PRE["@svelte-preprocess-react"] +FEI --> ANT["Ant Design Spin"] +REACT --> MONACO["Monaco Editor"] +PRE --> HOOKS["useValueChange"] +``` + +Diagram Sources + +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-10](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L10) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-17](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L17) + +Section Sources + +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## Performance Considerations + +- **Debounced updates**: `useValueChange` merges high-frequency changes to reduce processing pressure on the upper layer +- **On-demand loading**: CDN mode loads only necessary resources; local mode selects Workers by label to avoid overhead from irrelevant language parsing +- **Rendering isolation**: The editor container has independent styles to prevent global style pollution +- **Event minimization**: `onChange`/`validate` fires only when necessary to avoid unnecessary re-renders +- **Line positioning**: The Diff editor supports the `line` parameter to avoid full-page scroll searching + +## Troubleshooting Guide + +- **Editor not loading** + - Check whether loader initialization is complete (local/CDN) + - Confirm that `monacoLoader.config` is correctly set +- **Worker loading failed** + - Verify Worker import paths match the labels (json/css/html/typescript/javascript) + - If using CDN, confirm the `vs` path is accessible +- **Input lag** + - Check whether `onChange` subscriptions are too frequent; use the debounce strategy + - Reduce complexity: disable unnecessary syntax highlighting/autocomplete options +- **Diff editor not showing differences** + - Confirm that `original` and `modified` values are correctly passed in + - Check whether language settings are consistent or independently configured +- **Theme not applied** + - Confirm `themeMode` and Monaco theme mapping (`dark` → `vs-dark`, `light` → `light`) + +Section Sources + +- [frontend/pro/monaco-editor/loader.ts:53-78](file://frontend/pro/monaco-editor/loader.ts#L53-L78) +- [frontend/pro/monaco-editor/monaco-editor.tsx:83-88](file://frontend/pro/monaco-editor/monaco-editor.tsx#L83-L88) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:127-153](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L127-L153) + +## Conclusion + +This component uses Gradio as the backend interface, combined with `@monaco-editor/react` and a custom loader, to provide stable and extensible code editing capabilities. Through local/CDN dual-mode loading, debounced value sync, theme and read-only control, and Diff comparison features, it meets the requirements of most application scenarios. It is recommended to prefer local loading in production for improved stability, and to configure languages, Workers, and editor options appropriately for your use case to achieve the best performance and user experience. + +## Appendix + +### Configuration Quick Reference (Standard Editor) + +- `value`: Initial editor value +- `language`: Editor language (supports all Monaco base languages) +- `read_only`: Whether read-only +- `height`: Height (number = px, string = CSS unit) +- `options`: Editor constructor options (see Monaco official types) +- `theme_mode`: Theme mode (dark/light) +- `before_mount`/`after_mount`: JS string functions executed before/after loading +- `loading`: Loading text or custom loading slot +- `on_value_change`: Value change callback + +Section Sources + +- [docs/components/pro/monaco_editor/README.md:48-64](file://docs/components/pro/monaco_editor/README.md#L48-L64) +- [docs/components/pro/monaco_editor/README-zh_CN.md:48-64](file://docs/components/pro/monaco_editor/README-zh_CN.md#L48-L64) + +### Configuration Quick Reference (Diff Editor) + +- `value`: Right modified value (alternative to `modified`) +- `original`: Left original value +- `language`: Unified language (if not set independently) +- `original_language`: Left side language +- `modified_language`: Right side language +- `line`: Initial visible line +- `read_only`: Whether read-only +- `options`: Editor constructor options +- `before_mount`/`after_mount`: JS string functions +- `loading`: Loading text or custom loading slot +- `on_change`: Right side content change callback +- `on_validate`: Validation callback + +Section Sources + +- [docs/components/pro/monaco_editor/README.md:48-64](file://docs/components/pro/monaco_editor/README.md#L48-L64) +- [docs/components/pro/monaco_editor/README-zh_CN.md:48-64](file://docs/components/pro/monaco_editor/README-zh_CN.md#L48-L64) diff --git a/.wiki/en/Pro Components/MultimodalInput/Basic Usage.md b/.wiki/en/Pro Components/MultimodalInput/Basic Usage.md new file mode 100644 index 00000000..a1d51ae2 --- /dev/null +++ b/.wiki/en/Pro Components/MultimodalInput/Basic Usage.md @@ -0,0 +1,324 @@ +# Component Overview + + +**Files Referenced in This Document** +- [multimodal-input.tsx](file://frontend/pro/multimodal-input/multimodal-input.tsx) +- [recorder.ts](file://frontend/pro/multimodal-input/recorder.ts) +- [utils.ts](file://frontend/pro/multimodal-input/utils.ts) +- [multimodal-input.less](file://frontend/pro/multimodal-input/multimodal-input.less) +- [__init__.py](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py) +- [README.md](file://docs/components/pro/multimodal_input/README.md) +- [upload_config.py](file://docs/components/pro/multimodal_input/demos/upload_config.py) +- [basic.py](file://docs/components/pro/multimodal_input/demos/basic.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +MultimodalInput is a multimodal input component based on Ant Design X, supporting text input, image upload, audio recording, file drag-and-drop, and other input modes. It has significant value in machine learning and conversational applications: it can carry natural language instructions as well as receive multimedia data such as images and audio, making it easy to build richer interaction experiences and multimodal model training/inference pipelines. + +Component design philosophy: + +- Uses "text + file" as the core data model, uniformly exposing `value` and change events externally. +- Based on the combination of Ant Design X's `Sender` and `Attachments`, providing a consistent input and attachment management experience. +- Supports `inline`/`block` two rendering modes to adapt to different layout requirements. +- Provides flexible upload configuration (type restrictions, quantity limits, paste upload, fullscreen drag, etc.) and pluggable recording capability. + +## Project Structure + +MultimodalInput adopts a React + Svelte Preprocess bridging approach on the frontend, and interfaces with the Python environment via Gradio data classes and event bindings on the backend. Core file distribution: + +- **Frontend**: `multimodal-input.tsx` (main component), `recorder.ts` (recording hook), `utils.ts` (audio processing), `multimodal-input.less` (styles) +- **Backend**: `__init__.py` (data model, events, pre/post-processing) +- **Documentation and examples**: `README.md` (API description), example scripts in `demos` + +```mermaid +graph TB +subgraph "Frontend" +A["multimodal-input.tsx
Main Component"] +B["recorder.ts
Recording Hook"] +C["utils.ts
Audio Processing"] +D["multimodal-input.less
Styles"] +end +subgraph "Backend" +E["__init__.py
Data Model/Events/Pre&Post-processing"] +end +A --> B +A --> C +A --> D +A --> E +``` + +**Diagram Sources** + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [recorder.ts:1-48](file://frontend/pro/multimodal-input/recorder.ts#L1-L48) +- [utils.ts:1-127](file://frontend/pro/multimodal-input/utils.ts#L1-L127) +- [multimodal-input.less:1-13](file://frontend/pro/multimodal-input/multimodal-input.less#L1-L13) +- [**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) + +**Section Sources** + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) + +## Core Components + +- **Main component**: `MultimodalInput` (React-wrapped Svelte component), responsible for text input, attachment panel, record button, submit/cancel, and other interactions. +- **Recording hook**: `useRecorder`, encapsulates recording start/stop and state management, and callbacks the generated audio Blob when recording ends. +- **Audio processing**: `processAudio`/`process_audio`, converts recordings to WAV format and returns binary data. +- **Data model**: `MultimodalInputValue` (files/text), `MultimodalInputUploadConfig` (upload configuration). +- **Backend component**: `ModelScopeProMultimodalInput`, defines events, slots, pre/post-processing logic, and default upload configuration. + +**Section Sources** + +- [multimodal-input.tsx:32-104](file://frontend/pro/multimodal-input/multimodal-input.tsx#L32-L104) +- [recorder.ts:6-47](file://frontend/pro/multimodal-input/recorder.ts#L6-L47) +- [utils.ts:60-126](file://frontend/pro/multimodal-input/utils.ts#L60-L126) +- [**init**.py:18-79](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L18-L79) +- [**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) + +## Architecture Overview + +MultimodalInput integrates "text input + attachment upload + audio recording" into a unified data flow: + +- **Input layer**: `Sender` handles text input; the attachment panel is provided by `Attachments`. +- **Capture layer**: Recording is implemented via wavesurfer.js + record plugin; after completion it converts to WAV and triggers upload. +- **Upload layer**: Calls the external `upload` callback to write files to the backend and returns a `FileData` list to update the internal file list. +- **Event layer**: Events such as `onChange`/`onSubmit`/`onUpload`/`onRemove`/`onPasteFile` run through the entire flow, making it easy for upstream business logic to subscribe. + +```mermaid +sequenceDiagram +participant U as "User" +participant S as "Sender (Text)" +participant A as "Attachments" +participant R as "Recording Hook (useRecorder)" +participant P as "Audio Processing (utils)" +participant F as "Upload (upload callback)" +participant M as "MultimodalInput (Main Component)" +U->>S : Input text +S->>M : onChange(text) +U->>A : Drag / select file +A->>M : onChange(file list) +U->>R : Start recording +R->>P : Recording end callback with Blob +P-->>R : WAV binary +R->>F : Upload WAV +F-->>M : Return FileData[] +M->>M : Update files list +M-->>U : Trigger onUpload/onValueChange +U->>S : Submit +S->>M : onSubmit +M-->>U : Trigger onSubmit +``` + +**Diagram Sources** + +- [multimodal-input.tsx:157-169](file://frontend/pro/multimodal-input/multimodal-input.tsx#L157-L169) +- [utils.ts:94-126](file://frontend/pro/multimodal-input/utils.ts#L94-L126) +- [multimodal-input.tsx:181-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L181-L246) +- [multimodal-input.tsx:336-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L336-L360) + +## Detailed Component Analysis + +### Component Interface and Data Model + +- `MultimodalInputValue`: Contains two fields, `files` (file array) and `text` (text), serving as the component's value object. +- `MultimodalInputChangedValue`: The externally exposed change value; `files` is an array of string paths, `text` is a string. +- `MultimodalInputUploadConfig`: Upload-related configuration items, such as `accept`, `max_count`, `allow_speech`, `allow_paste_file`, `fullscreen_drop`, `multiple`, `directory`, `overflow`, `title`, `image_props`, `placeholder`, etc. + +**Section Sources** + +- [multimodal-input.tsx:32-66](file://frontend/pro/multimodal-input/multimodal-input.tsx#L32-L66) +- [multimodal-input.tsx:42-57](file://frontend/pro/multimodal-input/multimodal-input.tsx#L42-L57) +- [**init**.py:18-79](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L18-L79) + +### Rendering Modes and Slots + +- `mode`: Two modes, `inline` and `block`. In block mode, the input area is separated from the send/loading button; the footer provides an extra operations area and action area. +- `slots`: Supports `suffix`/`header`/`prefix`/`footer` and `skill.*` series slots for extending UI with skill prompts, close icons, etc. + +**Section Sources** + +- [multimodal-input.tsx:86-104](file://frontend/pro/multimodal-input/multimodal-input.tsx#L86-L104) +- [multimodal-input.tsx:426-457](file://frontend/pro/multimodal-input/multimodal-input.tsx#L426-L457) +- [**init**.py:139-143](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L139-L143) + +### Upload and File Management + +- **Upload entry**: Writes files to the backend via the `upload` callback, returns a `FileData` list, and merges into the current file list. +- **Restriction strategy**: Supports `max_count` for single-file replacement or batch appending; supports `multiple`/`directory`/`fullscreen_drop`, etc. +- **Event callbacks**: `onUpload`/`onRemove`/`onPreview`/`onDownload`/`onDrop`, etc., for upstream handling of download/preview/remove behaviors. + +**Section Sources** + +- [multimodal-input.tsx:181-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L181-L246) +- [multimodal-input.tsx:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) +- [**init**.py:111-135](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L111-L135) + +### Recording and Audio Processing + +- **Recording hook**: `useRecorder` provides `recording` state and `start`/`stop` methods, with a callback for the Blob when recording ends. +- **Audio processing**: `processAudio` decodes the Blob to an `AudioBuffer`, trims as needed, converts to a WAV byte stream, and wraps as a `File` object to trigger upload. + +**Section Sources** + +- [recorder.ts:6-47](file://frontend/pro/multimodal-input/recorder.ts#L6-L47) +- [utils.ts:94-126](file://frontend/pro/multimodal-input/utils.ts#L94-L126) +- [multimodal-input.tsx:157-169](file://frontend/pro/multimodal-input/multimodal-input.tsx#L157-L169) + +### Events and Lifecycle + +- **Events**: `change`/`submit`/`cancel`/`key_down`/`key_press`/`focus`/`blur`/`upload`/`paste`/`paste_file`/`skill_closable_close`/`drop`/`download`/`preview`/`remove` +- **Lifecycle**: The component internally maintains `value` and `fileList`; callbacks such as `onChange`/`onSubmit`/`onUpload`/`onRemove` chain together frontend-backend interactions. + +**Section Sources** + +- [**init**.py:86-135](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L86-L135) +- [multimodal-input.tsx:336-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L336-L360) +- [multimodal-input.tsx:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) + +### Class Diagram (Code Level) + +```mermaid +classDiagram +class MultimodalInputValue { ++files : FileData[] ++text : string +} +class MultimodalInputChangedValue { ++files : string[] ++text : string +} +class MultimodalInputUploadConfig { ++fullscreen_drop : bool ++allow_upload : bool ++allow_paste_file : bool ++allow_speech : bool ++show_count : bool ++upload_button_tooltip : string ++accept : string ++max_count : int ++directory : bool ++multiple : bool ++disabled : bool ++overflow : wrap|scrollX|scrollY ++title : string ++image_props : dict ++placeholder : dict +} +class ModelScopeProMultimodalInput { ++EVENTS ++SLOTS ++preprocess(payload) ++postprocess(value) +} +class useRecorder { ++recording : bool ++start() ++stop() +} +class Utils { ++processAudio(blob, start?, end?) : Promise
Component Wrapper & Logic"] +B["multimodal-input.less
Styles"] +C["recorder.ts
Recording Capability"] +D["utils.ts
Utility Functions"] +end +subgraph "Backend" +E["components.py
Export ProMultimodalInput"] +F["multimodal_input/__init__.py
Type Definitions & Component Class"] +end +subgraph "Documentation" +G["README.md
API & Type Descriptions"] +end +A --> E +E --> F +A --> B +A --> C +A --> D +G --> A +G --> F +``` + +**Diagram Sources** + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [README.md:1-119](file://docs/components/pro/multimodal_input/README.md#L1-L119) + +**Section Sources** + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [README.md:1-119](file://docs/components/pro/multimodal_input/README.md#L1-L119) + +## Core Components + +- **`MultimodalInputUploadConfig`**: Configures the behavior and appearance of the file upload area, including accepted types, quantity limits, directory upload, multi-select, disabled state, overflow behavior, placeholder information, title, image properties, etc. +- **`MultimodalInput`**: Based on the combination of Ant Design X's Sender and Attachments, supports text input, file upload, voice recording, paste files, and other capabilities; controls upload area behavior via `uploadConfig`. + +**Section Sources** + +- [multimodal-input.tsx:42-57](file://frontend/pro/multimodal-input/multimodal-input.tsx#L42-L57) +- [README.md:56-118](file://docs/components/pro/multimodal_input/README.md#L56-L118) + +## Architecture Overview + +MultimodalInput converts the externally passed `uploadConfig` to an internally usable configuration object, passes it to the `Attachments` component, and controls feature enabled states based on switches like `allowUpload`/`allowSpeech`/`allowPasteFile`. During the upload process, file collection merging and deduplication are performed according to `maxCount` and directory/multi-select strategies. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant MI as "MultimodalInput" +participant CFG as "uploadConfig" +participant ATT as "Attachments" +participant SEN as "Sender" +Dev->>MI : Pass uploadConfig and props +MI->>CFG : Convert to camelCase keys and merge defaults +MI->>ATT : Pass through configuration (except special fields) +MI->>SEN : Configure allowed input modes (voice/paste) +SEN-->>MI : User submit or cancel +ATT-->>MI : File add/remove/drag/select events +MI->>MI : Process file list per maxCount/directory/multiple strategy +MI-->>Dev : Trigger onValueChange/onUpload/onPasteFile callbacks +``` + +**Diagram Sources** + +- [multimodal-input.tsx:174-177](file://frontend/pro/multimodal-input/multimodal-input.tsx#L174-L177) +- [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) +- [multimodal-input.tsx:282-284](file://frontend/pro/multimodal-input/multimodal-input.tsx#L282-L284) + +**Section Sources** + +- [multimodal-input.tsx:174-177](file://frontend/pro/multimodal-input/multimodal-input.tsx#L174-L177) +- [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) +- [multimodal-input.tsx:282-284](file://frontend/pro/multimodal-input/multimodal-input.tsx#L282-L284) + +## Detailed Component Analysis + +### MultimodalInputUploadConfig Parameter Reference + +All parameters below come from backend type definitions and frontend implementation mappings. Purposes and default values are based on documentation and source code. + +- **`fullscreen_drop`** + - Purpose: Whether to allow dragging files to the entire page window to trigger the attachment panel. + - Default: `False` + - Use case: When you need to open the attachment panel by releasing files anywhere on the page. + - Implementation note: When enabled, `getDropContainer` returns `document.body`, expanding the drag range to global. + - Reference: [multimodal-input.tsx:480-486](file://frontend/pro/multimodal-input/multimodal-input.tsx#L480-L486) + +- **`allow_upload`** + - Purpose: Whether to enable the upload area and file selection/drag features. + - Default: `True` + - Use case: Only need text input, don't want users to upload files. + - Implementation note: Affects the availability of `allowSpeech`/`allowPasteFile` (both only work when `allowUpload` is true). + - Reference: [multimodal-input.tsx:282-284](file://frontend/pro/multimodal-input/multimodal-input.tsx#L282-L284) + +- **`allow_paste_file`** + - Purpose: Whether to allow pasting files via clipboard. + - Default: `True` + - Use case: Improves convenience by allowing users to paste file content directly. + - Implementation note: Controlled by `allow_upload`; if disabled, paste events are ignored. + - Reference: [multimodal-input.tsx:352-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L352-L360) + +- **`allow_speech`** + - Purpose: Whether to enable voice input (microphone recording). + - Default: `False` + - Use case: Needed for speech-to-text or uploading audio files. + - Implementation note: Only takes effect when `allowUpload` is true; upload is automatically triggered after recording ends. + - References: [multimodal-input.tsx:317-333](file://frontend/pro/multimodal-input/multimodal-input.tsx#L317-L333), [multimodal-input.tsx:157-169](file://frontend/pro/multimodal-input/multimodal-input.tsx#L157-L169) + +- **`show_count`** + - Purpose: Whether to show a file count badge when the attachment panel is closed. + - Default: `True` + - Use case: Indicates the number of added files without expanding the panel. + - Reference: [multimodal-input.tsx:288-294](file://frontend/pro/multimodal-input/multimodal-input.tsx#L288-L294) + +- **`upload_button_tooltip`** + - Purpose: Hover tooltip text for the upload button. + - Default: None (empty string) + - Use case: Provides additional description for the upload entry. + - Reference: [multimodal-input.tsx:287-305](file://frontend/pro/multimodal-input/multimodal-input.tsx#L287-L305) + +- **`accept`** + - Purpose: Restricts the selectable file types (HTML input accept attribute semantics). + - Default: `None` + - Use case: Only allow images, documents, or specific format files. + - Reference: [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) + +- **`max_count`** + - Purpose: Limits the total number of uploadable files; replaces the current file when set to 1. + - Default: `None` + - Use case: Single-file replacement upload (e.g., avatar), batch upload quota control. + - Implementation note: Truncates valid file list based on remaining quota when adding/pasting/dragging. + - References: [multimodal-input.tsx:187-204](file://frontend/pro/multimodal-input/multimodal-input.tsx#L187-L204), [multimodal-input.tsx:543-552](file://frontend/pro/multimodal-input/multimodal-input.tsx#L543-L552) + +- **`directory`** + - Purpose: Whether to support uploading entire directories (all files within a folder). + - Default: `False` + - Use case: Need to batch upload a directory structure. + - Reference: [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) + +- **`multiple`** + - Purpose: Whether to allow multi-file selection (with Ctrl/Cmd multi-select). + - Default: `False` + - Use case: Need to select multiple files at once. + - Reference: [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) + +- **`disabled`** + - Purpose: Globally disable the upload area and buttons. + - Default: `False` + - Use case: Read-only mode or waiting for conditions to be met before enabling. + - Implementation note: `uploadDisabled` is computed from `disabled`/`loading`/`readOnly`/`uploading` combined. + - Reference: [multimodal-input.tsx:178-179](file://frontend/pro/multimodal-input/multimodal-input.tsx#L178-L179) + +- **`overflow`** + - Purpose: Overflow behavior when the file list exceeds the display area (`wrap`/`scrollX`/`scrollY`). + - Default: `None` + - Use case: Display a large number of files in a limited space. + - Reference: [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) + +- **`image_props`** + - Purpose: Configuration passed to the internal image preview component (same as Ant Design Image). + - Default: `None` + - Use case: Customize image zoom, load failure fallback, etc. + - Reference: [multimodal-input.tsx:476-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L476-L478) + +- **`placeholder`** + - Purpose: Placeholder information when there are no files, supporting `inline` and `drop` shapes. + - Default: Built-in values including `inline`/`title`/`description`/`icon` and `drop`/`title`. + - Use case: Guide users to click/drag to upload. + - References: [multimodal-input.tsx:488-507](file://frontend/pro/multimodal-input/multimodal-input.tsx#L488-L507), [README.md:103-112](file://docs/components/pro/multimodal_input/README.md#L103-L112) + +- **`title`** + - Purpose: Attachment panel title. + - Default: `"Attachments"` + - Use case: Localization or business-customized title. + - References: [multimodal-input.tsx:461-461](file://frontend/pro/multimodal-input/multimodal-input.tsx#L461-L461), [README.md:101-101](file://docs/components/pro/multimodal_input/README.md#L101-L101) + +**Section Sources** + +- [multimodal-input.tsx:42-57](file://frontend/pro/multimodal-input/multimodal-input.tsx#L42-L57) +- [multimodal-input.tsx:174-507](file://frontend/pro/multimodal-input/multimodal-input.tsx#L174-L507) +- [README.md:56-118](file://docs/components/pro/multimodal_input/README.md#L56-L118) + +### Configuration Combination Examples (Path References) + +All examples below come from documentation and sample applications. Refer to the corresponding paths for complete implementations and results: + +- **Basic example (with upload configuration)**: + - Example path: [README.md:23-25](file://docs/components/pro/multimodal_input/README.md#L23-L25) + +- **Upload configuration example (demonstrating multiple options)**: + - Example path: [README.md:23-25](file://docs/components/pro/multimodal_input/README.md#L23-L25) + +- **Integration with Chatbot example**: + - Example path: [README.md:11-13](file://docs/components/pro/multimodal_input/README.md#L11-L13) + +- **Block Mode**: + - Example path: [README.md:19-21](file://docs/components/pro/multimodal_input/README.md#L19-L21) + +- **Additional button configuration example**: + - Example path: [README.md:15-17](file://docs/components/pro/multimodal_input/README.md#L15-L17) + +- **Basic example**: + - Example path: [README.md:7-9](file://docs/components/pro/multimodal_input/README.md#L7-L9) + +**Section Sources** + +- [README.md:7-25](file://docs/components/pro/multimodal_input/README.md#L7-L25) + +## Dependency Analysis + +- **Frontend dependencies**: + - `@ant-design/x`: Sender and Attachments components provide input and attachment management capabilities. + - `antd`: UI components such as Button, Badge, Flex, Tooltip for interface and interaction. + - `lodash-es`: Utility functions (e.g., `omit`) for configuration and event handling. +- **Backend dependencies**: + - `GradioModel`: Base class for `MultimodalInputUploadConfig` and `MultimodalInputValue` data models. + - `components.py`: Exports `ProMultimodalInput` for use by upstream applications. + +```mermaid +graph LR +MI["MultimodalInput.tsx"] --> X["@ant-design/x
Sender/Attachments"] +MI --> ANT["antd
UI Component Library"] +MI --> LODASH["lodash-es
Utility Functions"] +CFG["MultimodalInputUploadConfig"] --> GR["GradioModel
Data Model"] +PRO["components.py"] --> MI +``` + +**Diagram Sources** + +- [multimodal-input.tsx:1-26](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L26) +- [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [README.md:56-118](file://docs/components/pro/multimodal_input/README.md#L56-L118) + +**Section Sources** + +- [multimodal-input.tsx:1-26](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L26) +- [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [README.md:56-118](file://docs/components/pro/multimodal_input/README.md#L56-L118) + +## Performance Considerations + +- **File quantity and size**: Use `max_count` to control concurrency and storage pressure; for large files, consider chunked uploads or server-side validation. +- **Rendering and updates**: Optimize rendering and state sync with `useMemo` and `useValueChange` to avoid unnecessary re-renders. +- **Upload strategy**: Short-circuit the upload flow when `allowUpload=false` or `disabled`/`loading`/`readOnly` to reduce invalid requests. +- **Drag range**: `fullscreen_drop` sets the drag container to `document.body`; be aware of additional event overhead in complex pages. + +**Section Sources** + +- [multimodal-input.tsx:174-177](file://frontend/pro/multimodal-input/multimodal-input.tsx#L174-L177) +- [multimodal-input.tsx:178-179](file://frontend/pro/multimodal-input/multimodal-input.tsx#L178-L179) +- [multimodal-input.tsx:480-486](file://frontend/pro/multimodal-input/multimodal-input.tsx#L480-L486) + +## Troubleshooting Guide + +- **Cannot upload files**: + - Check whether `allow_upload` is true; confirm `disabled`/`loading`/`readOnly`/`uploading` states. + - Confirm `accept` and `multiple` settings meet expectations. + - References: [multimodal-input.tsx:282-284](file://frontend/pro/multimodal-input/multimodal-input.tsx#L282-L284), [multimodal-input.tsx:178-179](file://frontend/pro/multimodal-input/multimodal-input.tsx#L178-L179), [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) + +- **Paste file not working**: + - Check whether `allow_paste_file` is true; ensure browser permissions and clipboard content is recognizable. + - Reference: [multimodal-input.tsx:352-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L352-L360) + +- **Voice input unavailable**: + - Check `allow_speech` and `allow_upload`; confirm browser microphone permissions. + - References: [multimodal-input.tsx:317-333](file://frontend/pro/multimodal-input/multimodal-input.tsx#L317-L333), [multimodal-input.tsx:282-284](file://frontend/pro/multimodal-input/multimodal-input.tsx#L282-L284) + +- **File count exceeds limit**: + - Check `max_count`; when set to 1 the current file will be replaced; when greater than 1, truncates based on remaining quota. + - References: [multimodal-input.tsx:187-204](file://frontend/pro/multimodal-input/multimodal-input.tsx#L187-L204), [multimodal-input.tsx:543-552](file://frontend/pro/multimodal-input/multimodal-input.tsx#L543-L552) + +- **Drag range is abnormal**: + - When `fullscreen_drop` is true, the drag range extends to `document.body`; confirm page structure and event conflicts. + - Reference: [multimodal-input.tsx:480-486](file://frontend/pro/multimodal-input/multimodal-input.tsx#L480-L486) + +**Section Sources** + +- [multimodal-input.tsx:178-179](file://frontend/pro/multimodal-input/multimodal-input.tsx#L178-L179) +- [multimodal-input.tsx:187-204](file://frontend/pro/multimodal-input/multimodal-input.tsx#L187-L204) +- [multimodal-input.tsx:282-284](file://frontend/pro/multimodal-input/multimodal-input.tsx#L282-L284) +- [multimodal-input.tsx:317-333](file://frontend/pro/multimodal-input/multimodal-input.tsx#L317-L333) +- [multimodal-input.tsx:352-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L352-L360) +- [multimodal-input.tsx:480-486](file://frontend/pro/multimodal-input/multimodal-input.tsx#L480-L486) +- [multimodal-input.tsx:543-552](file://frontend/pro/multimodal-input/multimodal-input.tsx#L543-L552) + +## Conclusion + +`MultimodalInputUploadConfig` provides comprehensive configuration capabilities from file types, quantities, directories, multi-select to upload area behavior and placeholder information. By reasonably combining parameters like `allow_upload`, `allow_speech`, `allow_paste_file`, `max_count`, `fullscreen_drop`, `accept`, `multiple`, `directory`, `disabled`, `overflow`, `image_props`, `placeholder`, `title`, and `upload_button_tooltip`, you can quickly adapt to various scenarios from simple text input to complex multimodal interaction. It is recommended to first clarify the business goal (single/multi-file, whether to allow directories, whether speech/paste is needed), then choose appropriate default values and overrides. + +## Appendix + +- **Related type definitions and default value references**: + - [README.md:56-118](file://docs/components/pro/multimodal_input/README.md#L56-L118) +- **Component export and integration**: + - [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) diff --git a/.wiki/en/Pro Components/MultimodalInput/File Upload.md b/.wiki/en/Pro Components/MultimodalInput/File Upload.md new file mode 100644 index 00000000..94a32ce6 --- /dev/null +++ b/.wiki/en/Pro Components/MultimodalInput/File Upload.md @@ -0,0 +1,464 @@ +# Data Processing Mechanism + + +**Files Referenced in This Document** +- [multimodal-input.tsx](file://frontend/pro/multimodal-input/multimodal-input.tsx) +- [recorder.ts](file://frontend/pro/multimodal-input/recorder.ts) +- [utils.ts](file://frontend/pro/multimodal-input/utils.ts) +- [useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [useMemoizedFn.ts](file://frontend/utils/hooks/useMemoizedFn.ts) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [convertToCamelCase.ts](file://frontend/utils/convertToCamelCase.ts) +- [createFunction.ts](file://frontend/utils/createFunction.ts) +- [omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) +- [multimodal-input.less](file://frontend/pro/multimodal-input/multimodal-input.less) +- [__init__.py](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py) +- [index.js](file://backend/modelscope_studio/components/pro/multimodal_input/templates/component/index.js) +- [basic.py](file://docs/components/pro/multimodal_input/demos/basic.py) +- [README.md](file://docs/components/pro/multimodal_input/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document focuses on the data processing mechanism of the MultimodalInput component, systematically explaining: + +- Data models and conversion flows between frontend and backend (preprocess/postprocess) +- File upload, download, and caching strategies +- Event listening mechanisms (change, submit, cancel, upload, paste, etc.), their triggering conditions, and callback handling +- Best practices for data format conversion and error handling + +## Project Structure + +MultimodalInput's implementation spans both frontend and backend: + +- **Frontend**: Based on Ant Design X's Sender and Attachments, combined with recording and upload logic, responsible for user interaction and data formatting +- **Backend**: Based on Gradio's data classes and event binding, responsible for input pre-processing and output post-processing + +```mermaid +graph TB +subgraph "Frontend" +MI["MultimodalInput Component
multimodal-input.tsx"] +REC["Recording Hook
recorder.ts"] +UTIL["Audio Processing Utilities
utils.ts"] +HVC["Value Sync Hook
useValueChange.ts"] +HMF["Memoized Function Hook
useMemoizedFn.ts"] +HF["Function Creation Hook
useFunction.ts"] +CCC["Key Camel-Case Conversion
convertToCamelCase.ts"] +CF["String to Function
createFunction.ts"] +OUP["Property Filter
omitUndefinedProps.ts"] +CSS["Styles
multimodal-input.less"] +end +subgraph "Backend" +PY["Component Definition & Events
__init__.py"] +IDX["Frontend Bundle Entry
index.js"] +end +MI --- REC +MI --- UTIL +MI --- HVC +MI --- HMF +MI --- HF +MI --- CCC +MI --- CF +MI --- OUP +MI --- CSS +PY --- IDX +``` + +**Diagram Sources** + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [recorder.ts:1-48](file://frontend/pro/multimodal-input/recorder.ts#L1-L48) +- [utils.ts:1-127](file://frontend/pro/multimodal-input/utils.ts#L1-L127) +- [useValueChange.ts:1-30](file://frontend/utils/hooks/useValueChange.ts#L1-L30) +- [useMemoizedFn.ts:1-11](file://frontend/utils/hooks/useMemoizedFn.ts#L1-L11) +- [useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [convertToCamelCase.ts:1-22](file://frontend/utils/convertToCamelCase.ts#L1-L22) +- [createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) +- [omitUndefinedProps.ts:1-17](file://frontend/utils/omitUndefinedProps.ts#L1-L17) +- [multimodal-input.less:1-13](file://frontend/pro/multimodal-input/multimodal-input.less#L1-L13) +- [**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) +- [index.js:1-6](file://backend/modelscope_studio/components/pro/multimodal_input/templates/component/index.js#L1-L6) + +**Section Sources** + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) + +## Core Components + +- **Frontend component**: `MultimodalInput` (React component wrapped via `sveltify`), internally combines `Sender` and `Attachments`, and integrates recording capability +- **Backend component**: `ModelScopeProMultimodalInput` (Gradio component), defines data model and event binding + +Key responsibilities: + +- **Frontend**: Maintains local state (text and file list), handles upload/paste/delete interactions, formats change values, triggers event callbacks +- **Backend**: `preprocess` converts file paths passed in from the frontend to locally cached files; `postprocess` restores local files to a displayable `FileData` list + +**Section Sources** + +- [multimodal-input.tsx:32-104](file://frontend/pro/multimodal-input/multimodal-input.tsx#L32-L104) +- [**init**.py:76-137](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L76-L137) + +## Architecture Overview + +MultimodalInput's data flow starts from user interaction, traverses frontend state management, upload processing, backend pre-processing and post-processing, and returns to frontend rendering. + +```mermaid +sequenceDiagram +participant U as "User" +participant MI as "MultimodalInput (Frontend)" +participant SEN as "Sender (Frontend)" +participant ATT as "Attachments (Frontend)" +participant UP as "Upload Function (upload)" +participant BE as "MultimodalInput (Backend)" +participant FS as "File System / Cache" +U->>MI : Input text / select file / paste / record +MI->>SEN : Text change callback +SEN-->>MI : onChange(value) +MI->>MI : formatChangedValue() generates change value +MI-->>U : onChange callback +U->>ATT : Select / drag / delete file +ATT-->>MI : onChange(info) +MI->>UP : Upload selected files +UP-->>MI : Return FileData[] +MI->>MI : Merge file list / update state +MI-->>U : onUpload/onValueChange/onChange +U->>SEN : Submit +SEN-->>BE : Trigger submit event +BE->>BE : preprocess() convert file paths to local files +BE-->>U : Return processed value +BE->>FS : Cache / read files +BE-->>MI : postprocess() restore to FileData list +MI-->>U : Render attachment list +``` + +**Diagram Sources** + +- [multimodal-input.tsx:336-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L336-L360) +- [multimodal-input.tsx:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) +- [multimodal-input.tsx:220-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L220-L246) +- [**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) + +## Detailed Component Analysis + +### Data Model and Field Meanings + +- **Frontend data model**: + - `MultimodalInputValue`: Contains `text` (text) and `files` (file array) fields + - `MultimodalInputChangedValue`: Used for `onChange` callback; `files` is an array of file path strings, `text` is a string +- **Backend data model**: + - `MultimodalInputValue`: Consistent with frontend, but `files` is of Gradio's `ListFiles` type + - `MultimodalInputUploadConfig`: Controls upload behavior (e.g., whether to allow upload, paste, voice, maximum count, etc.) + +Field descriptions (from type definitions and comments): + +- `files`: File collection, supports multi-file and single-file modes +- `text`: Text content entered by the user +- `upload_config`: Upload configuration object, including `fullscreen_drop`, `allow_upload`, `allow_paste_file`, `allow_speech`, `max_count`, `placeholder`, etc. + +**Section Sources** + +- [multimodal-input.tsx:32-57](file://frontend/pro/multimodal-input/multimodal-input.tsx#L32-L57) +- [**init**.py:18-74](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L18-L74) +- [README.md:54-118](file://docs/components/pro/multimodal_input/README.md#L54-L118) + +### How preprocess and postprocess Work + +- **preprocess (backend)**: + - Input: `MultimodalInputValue` (containing `text` and `files`) + - Processing: Iterates over `files`, writes each file path to a temporary file, and returns a dict containing `text` and local file paths + - Purpose: Ensures the backend can stably access files, preventing external links from becoming invalid +- **postprocess (backend)**: + - Input: Backend processing result (may contain file paths) + - Processing: Downloads or locally caches the file paths, then wraps them as a `FileData` list to return to the frontend + - Purpose: Restores file paths stored in the backend to displayable file information for the frontend (including original name, size, etc.) + +```mermaid +flowchart TD +Start(["Enter preprocess"]) --> CheckPayload{"payload is empty?"} +CheckPayload --> |Yes| ReturnEmpty["Return empty file list"] +CheckPayload --> |No| IterateFiles["Iterate files list"] +IterateFiles --> TempFile["Write to temp file / get local path"] +TempFile --> BuildOut["Build output dict {text, files}"] +BuildOut --> End(["End"]) +subgraph "postprocess" +PStart(["Enter postprocess"]) --> PCheck{"value is empty?"} +PCheck --> |Yes| PReturnEmpty["Return empty value"] +PCheck --> |No| PIterate["Iterate files list"] +PIterate --> PDownload{"Is HTTP link?"} +PDownload --> |Yes| SaveUrl["Save to cache"] +PDownload --> |No| KeepLocal["Use local path"] +SaveUrl --> Pack["Wrap as FileData list"] +KeepLocal --> Pack +Pack --> PEnd(["End"]) +end +``` + +**Diagram Sources** + +- [**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) + +**Section Sources** + +- [**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) + +### File Upload, Download, and Caching + +- **Upload flow**: + - User selects/drags files in Attachments, triggering `onChange` + - Frontend limits valid file count based on `maxCount`, generates temporary upload items, sets state to `uploading` + - Calls the `upload` function (injected by the parent) to perform actual upload, returning a `FileData` array + - Merges file lists, triggers `onUpload`, `onValueChange`, `onChange` +- **Download and caching**: + - Backend saves remote files to a local cache directory in `preprocess` + - In `postprocess`, restores local file paths to `FileData` for frontend display + +```mermaid +sequenceDiagram +participant ATT as "Attachments (Frontend)" +participant MI as "MultimodalInput (Frontend)" +participant UP as "upload function" +participant BE as "Backend Component" +participant FS as "Cache / File System" +ATT->>MI : onChange(info) +MI->>MI : Validate maxCount / generate temp items +MI->>UP : Upload files +UP-->>MI : Return FileData[] +MI->>MI : Merge file list / update state +MI-->>ATT : Update display +MI->>BE : Trigger event / submit data +BE->>FS : Save / read files +BE-->>MI : Return processed value +``` + +**Diagram Sources** + +- [multimodal-input.tsx:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) +- [multimodal-input.tsx:220-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L220-L246) +- [**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) + +**Section Sources** + +- [multimodal-input.tsx:181-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L181-L246) +- [multimodal-input.tsx:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) +- [**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) + +### Event Listening Mechanism + +- **Event binding (backend)**: + - Supported events: `change`, `submit`, `cancel`, `key_down`, `key_press`, `focus`, `blur`, `upload`, `paste`, `paste_file`, `skill_closable_close`, `drop`, `download`, `preview`, `remove` + - Registered via `EventListener`, bound to the component's internal update flow +- **Frontend event triggering**: + - Text change: `Sender.onChange` → `onChange` (formatted to change value) + - Submit: `Sender.onSubmit` → `onSubmit` (only when suggestion panel is not open) + - Cancel: `Sender.onCancel` → `onCancel` + - Paste: `Sender.onPasteFile` → `onPasteFile` (if paste is allowed) + - Upload: `Attachments.onChange` → `onUpload` + `onValueChange` + `onChange` + - Remove: `Attachments.onChange` → `onRemove` + state update + - Recording: `useRecorder` triggers recording state changes; on stop, calls the upload function + +```mermaid +sequenceDiagram +participant SEN as "Sender (Frontend)" +participant ATT as "Attachments (Frontend)" +participant MI as "MultimodalInput (Frontend)" +participant BE as "Backend Component" +SEN->>MI : onChange(text) +MI-->>SEN : onChange({text, files}) +SEN->>MI : onSubmit() +MI-->>SEN : onSubmit({text, files}) +SEN->>MI : onCancel() +MI-->>SEN : onCancel() +SEN->>MI : onPasteFile(files) +MI-->>SEN : onPasteFile(paths) +ATT->>MI : onChange(info) +MI-->>ATT : onUpload + onValueChange + onChange +ATT->>MI : onRemove(file) +MI-->>ATT : state update +``` + +**Diagram Sources** + +- [multimodal-input.tsx:344-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L344-L360) +- [multimodal-input.tsx:336-343](file://frontend/pro/multimodal-input/multimodal-input.tsx#L336-L343) +- [multimodal-input.tsx:352-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L352-L360) +- [multimodal-input.tsx:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) +- [**init**.py:86-135](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L86-L135) + +**Section Sources** + +- [multimodal-input.tsx:344-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L344-L360) +- [multimodal-input.tsx:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) +- [**init**.py:86-135](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L86-L135) + +### Data Format Conversion and Best Practices + +- **Frontend formatting**: + - `formatChangedValue`: Converts `MultimodalInputValue` to `MultimodalInputChangedValue` for callback passing + - `convertObjectKeyToCamelCase`: Converts `snake_case` key names in upload configuration to `camelCase` to match component props + - `omitUndefinedProps`: Filters out `undefined`/`null` properties to avoid passing invalid configurations + - `createFunction`/`useFunction`: Parses string-form function expressions to executable functions, supporting slots and formatting +- **Backend conversion**: + - `preprocess`: Writes file paths to temporary files to ensure backend accessibility + - `postprocess`: Restores local files to `FileData`, including original name and size metadata + +```mermaid +flowchart TD +A["Input payload"] --> B["preprocess: path -> local file"] +B --> C["Backend processing"] +C --> D["postprocess: local file -> FileData list"] +D --> E["Return to frontend rendering"] +F["Frontend value"] --> G["formatChangedValue: {files[], text}"] +G --> H["onChange callback"] +``` + +**Diagram Sources** + +- [multimodal-input.tsx:59-66](file://frontend/pro/multimodal-input/multimodal-input.tsx#L59-L66) +- [convertToCamelCase.ts:13-21](file://frontend/utils/convertToCamelCase.ts#L13-L21) +- [omitUndefinedProps.ts:1-17](file://frontend/utils/omitUndefinedProps.ts#L1-L17) +- [createFunction.ts:10-37](file://frontend/utils/createFunction.ts#L10-L37) +- [**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) + +**Section Sources** + +- [multimodal-input.tsx:59-66](file://frontend/pro/multimodal-input/multimodal-input.tsx#L59-L66) +- [convertToCamelCase.ts:13-21](file://frontend/utils/convertToCamelCase.ts#L13-L21) +- [**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) + +### Recording and Audio Processing + +- **Recording hook**: + - `useRecorder`: Based on wavesurfer.js and the record plugin, provides recording state and `start`/`stop` control + - On recording stop, the callback returns a Blob; the frontend converts it to WAV format and triggers upload +- **Audio processing utilities**: + - `processAudio`: Decodes the Blob to an `AudioBuffer`, trims as needed, then encodes to a WAV byte stream + +```mermaid +sequenceDiagram +participant UI as "User Interface" +participant REC as "useRecorder" +participant WA as "wavesurfer.js" +participant UT as "processAudio" +participant MI as "MultimodalInput" +UI->>REC : Start recording +REC->>WA : startRecording() +WA-->>REC : record-start +REC-->>UI : Set recording=true +UI->>REC : End recording +REC->>WA : stopRecording() +WA-->>REC : record-end(Blob) +REC->>UT : Process Blob -> WAV +UT-->>REC : Uint8Array +REC->>MI : Upload audio file +``` + +**Diagram Sources** + +- [recorder.ts:11-47](file://frontend/pro/multimodal-input/recorder.ts#L11-L47) +- [utils.ts:94-126](file://frontend/pro/multimodal-input/utils.ts#L94-L126) +- [multimodal-input.tsx:157-169](file://frontend/pro/multimodal-input/multimodal-input.tsx#L157-L169) + +**Section Sources** + +- [recorder.ts:11-47](file://frontend/pro/multimodal-input/recorder.ts#L11-L47) +- [utils.ts:94-126](file://frontend/pro/multimodal-input/utils.ts#L94-L126) +- [multimodal-input.tsx:157-169](file://frontend/pro/multimodal-input/multimodal-input.tsx#L157-L169) + +### Frontend State and UI Slots + +- **Value sync**: `useValueChange` ensures bidirectional consistency between `valueProp` and internal state, avoiding jitter +- **Function memoization**: `useMemoizedFn` keeps callback references stable to reduce re-renders +- **Slots and formatting**: `useFunction` + `createFunction` support string function expressions, combined with `slotConfig` for structured input +- **UI structure**: Switches header/footer layout based on `mode` (`inline`/`block`), supporting skill prompts and closable icon extensions + +**Section Sources** + +- [useValueChange.ts:9-29](file://frontend/utils/hooks/useValueChange.ts#L9-L29) +- [useMemoizedFn.ts:1-11](file://frontend/utils/hooks/useMemoizedFn.ts#L1-L11) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [multimodal-input.tsx:407-457](file://frontend/pro/multimodal-input/multimodal-input.tsx#L407-L457) + +## Dependency Analysis + +- **Component coupling**: MultimodalInput depends on multiple utility hooks and functions, forming a highly cohesive, loosely coupled modular design; upload configuration is robustly handled through `convertObjectKeyToCamelCase` and `omitUndefinedProps` +- **External dependencies**: Ant Design X (Sender/Attachments), Ant Design (Button/Badge/Flex), wavesurfer.js (recording), Gradio (backend data classes and event system) + +```mermaid +graph LR +MI["MultimodalInput.tsx"] --> SEN["Sender (ANTDX)"] +MI --> ATT["Attachments (ANTDX)"] +MI --> REC["useRecorder.ts"] +MI --> UTIL["utils.ts"] +MI --> HVC["useValueChange.ts"] +MI --> HMF["useMemoizedFn.ts"] +MI --> HF["useFunction.ts"] +MI --> CCC["convertToCamelCase.ts"] +MI --> CF["createFunction.ts"] +MI --> OUP["omitUndefinedProps.ts"] +MI --> CSS["multimodal-input.less"] +BE["__init__.py"] --> IDX["index.js"] +``` + +**Diagram Sources** + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) +- [index.js:1-6](file://backend/modelscope_studio/components/pro/multimodal_input/templates/component/index.js#L1-L6) + +**Section Sources** + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) +- [index.js:1-6](file://backend/modelscope_studio/components/pro/multimodal_input/templates/component/index.js#L1-L6) + +## Performance Considerations + +- **Upload concurrency and throttling**: Use `uploading` state to prevent repeated uploads; limit one-time upload quantity with `maxCount` to reduce memory and network pressure +- **Rendering optimization**: `useMemoizedFn` keeps callback references stable to reduce sub-component re-renders; `useValueChange` only updates when the value changes, avoiding unnecessary side effects +- **Audio processing**: Decode and encode immediately after recording ends to shorten main thread blocking time; use chunked or streaming processing for large files (based on business requirements) + +## Troubleshooting Guide + +- **Upload failure**: + - Check that the `upload` function return value is `FileData[]` and the `uid` corresponds to the temporary item + - Pay attention to exception catching and `uploading` state recovery +- **Incorrect file count**: + - Confirm `maxCount` configuration and merge logic (single-file mode clears the old list) +- **Events not triggered**: + - Confirm backend `EVENTS` binding is enabled and frontend callbacks are correctly passed +- **Recording no output**: + - Check recording container availability, browser permissions, and audio context initialization + +**Section Sources** + +- [multimodal-input.tsx:242-245](file://frontend/pro/multimodal-input/multimodal-input.tsx#L242-L245) +- [multimodal-input.tsx:598-601](file://frontend/pro/multimodal-input/multimodal-input.tsx#L598-L601) +- [**init**.py:86-135](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L86-L135) + +## Conclusion + +MultimodalInput achieves a complete multimodal input experience through frontend-backend collaboration: text input, file upload, paste, and recording, combined with strict pre/post-processing flows to ensure data consistency and stability. Its modular frontend implementation and clear event system provide a solid foundation for extending more interaction capabilities. + +## Appendix + +- Sample applications: Basic usage and integration with Chatbot +- API documentation: Properties, slots, and type definition references + +**Section Sources** + +- [basic.py:7-16](file://docs/components/pro/multimodal_input/demos/basic.py#L7-L16) +- [README.md:27-118](file://docs/components/pro/multimodal_input/README.md#L27-L118) diff --git a/.wiki/en/Pro Components/MultimodalInput/Integration Examples.md b/.wiki/en/Pro Components/MultimodalInput/Integration Examples.md new file mode 100644 index 00000000..000c3aec --- /dev/null +++ b/.wiki/en/Pro Components/MultimodalInput/Integration Examples.md @@ -0,0 +1,333 @@ +# Integration Examples + + +**Files Referenced in This Document** +- [Backend module: MultimodalInput definition](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py) +- [Frontend index: MultimodalInput component entry](file://frontend/pro/multimodal-input/Index.svelte) +- [Frontend implementation: MultimodalInput React component](file://frontend/pro/multimodal-input/multimodal-input.tsx) +- [Example: Basic usage](file://docs/components/pro/multimodal_input/demos/basic.py) +- [Example: Block mode](file://docs/components/pro/multimodal_input/demos/block_mode.py) +- [Example: Extra buttons and custom actions](file://docs/components/pro/multimodal_input/demos/extra_button.py) +- [Example: Upload configuration](file://docs/components/pro/multimodal_input/demos/upload_config.py) +- [Example: Integration with Chatbot component](file://docs/components/pro/multimodal_input/demos/with_chatbot.py) +- [Chatbot component documentation (Chinese)](file://docs/components/pro/chatbot/README-zh_CN.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is aimed at developers who want to use the MultimodalInput component in the Gradio/ModelScope Studio ecosystem, providing complete usage examples and descriptions ranging from basic text input to integration with Chatbot. Topics covered: + +- **Basic usage**: The simplest text input and submit flow +- **Block mode**: Rendering the input area and send button separately for more complex layouts +- **Custom actions**: Adding prefix/suffix buttons and toolbars via slots +- **Upload configuration**: Restricting file types, counts, paste/voice capabilities +- **Integration with Chatbot**: Receiving user text and files in real chat applications while handling cancellation and loading states + +## Project Structure + +MultimodalInput consists of a backend Python component and a frontend React/Svelte implementation. Documentation examples are in `docs/components/pro/multimodal_input/demos`. + +```mermaid +graph TB +subgraph "Backend" +PY["Python Component
MultimodalInput Definition"] +end +subgraph "Frontend" +IDX["Svelte Entry
Index.svelte"] +CMP["React Component
multimodal-input.tsx"] +end +subgraph "Examples" +DEMO_BASIC["Basic Usage"] +DEMO_BLOCK["Block Mode"] +DEMO_EXTRA["Extra Buttons & Custom Actions"] +DEMO_UPLOAD["Upload Configuration"] +DEMO_CHATBOT["Integration with Chatbot"] +end +PY --> IDX --> CMP +DEMO_BASIC --> PY +DEMO_BLOCK --> PY +DEMO_EXTRA --> PY +DEMO_UPLOAD --> PY +DEMO_CHATBOT --> PY +``` + +**Diagram Sources** + +- [Frontend index: MultimodalInput component entry:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) +- [Frontend implementation: MultimodalInput React component:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [Example: Basic usage:1-17](file://docs/components/pro/multimodal_input/demos/basic.py#L1-L17) +- [Example: Block mode:1-81](file://docs/components/pro/multimodal_input/demos/block_mode.py#L1-L81) +- [Example: Extra buttons and custom actions:1-78](file://docs/components/pro/multimodal_input/demos/extra_button.py#L1-L78) +- [Example: Upload configuration:1-38](file://docs/components/pro/multimodal_input/demos/upload_config.py#L1-L38) +- [Example: Integration with Chatbot component:1-57](file://docs/components/pro/multimodal_input/demos/with_chatbot.py#L1-L57) + +**Section Sources** + +- [Frontend index: MultimodalInput component entry:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) +- [Frontend implementation: MultimodalInput React component:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [Example: Basic usage:1-17](file://docs/components/pro/multimodal_input/demos/basic.py#L1-L17) + +## Core Components + +- **Backend component**: `ModelScopeProMultimodalInput` provides value model, event binding, pre/post-processing logic, and frontend directory mapping +- **Frontend component**: `MultimodalInput` (React) wraps `Sender` and `Attachments`, supporting text input, file upload, voice recording, paste files, slot extensions, etc. +- **Slots**: Supports `header`/`prefix`/`footer`/`suffix` and skill-related slots (`skill.*`) + +Key points: + +- **Value model**: `MultimodalInputValue` contains `text` and `files` fields +- **Events**: `change`/`submit`/`cancel`/`key_down`/`key_press`/`focus`/`blur`/`upload`/`paste`/`paste_file`/`skill_closable_close`/`drop`/`download`/`preview`/`remove` +- **Mode**: `mode` supports `inline` and `block`; in block mode, `footer` is rendered as an independent area containing send/loading/voice and other controls + +**Section Sources** + +- [Backend module: MultimodalInput definition:76-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L76-L259) +- [Frontend implementation: MultimodalInput React component:32-104](file://frontend/pro/multimodal-input/multimodal-input.tsx#L32-L104) + +## Architecture Overview + +MultimodalInput imports the React component through the Svelte entry on the frontend, bridges the Gradio-side props and events to the React component internals, and passes value changes back to Gradio. + +```mermaid +sequenceDiagram +participant U as "User" +participant G as "Gradio Application" +participant S as "Svelte Entry (Index.svelte)" +participant R as "React Component (MultimodalInput)" +participant A as "Attachment Panel (Attachments)" +participant E as "Sender" +U->>G : Input text / select file / click send +G->>S : Push value/events +S->>R : Pass through props and events +R->>A : Upload files / manage file list +R->>E : Text change / submit / cancel +E-->>R : Trigger onChange/onSubmit/onCancel +R-->>S : onValueChange return +S-->>G : Update component value +``` + +**Diagram Sources** + +- [Frontend index: MultimodalInput component entry:68-98](file://frontend/pro/multimodal-input/Index.svelte#L68-L98) +- [Frontend implementation: MultimodalInput React component:311-351](file://frontend/pro/multimodal-input/multimodal-input.tsx#L311-L351) + +## Detailed Component Analysis + +### Basic Usage + +- **Goal**: Demonstrates the most basic text input and submission +- **Key points**: Create a `MultimodalInput` and bind the `submit` event; the function receives the input value (containing `text` and `files`) +- **Applicable scenarios**: Quickly build a chat input box without file upload or extra buttons + +```mermaid +flowchart TD +Start(["Start"]) --> Create["Create MultimodalInput"] +Create --> Bind["Bind submit event"] +Bind --> Submit["User clicks send"] +Submit --> Fn["Callback function receives input value"] +Fn --> End(["End"]) +``` + +**Diagram Sources** + +- [Example: Basic usage:7-16](file://docs/components/pro/multimodal_input/demos/basic.py#L7-L16) + +**Section Sources** + +- [Example: Basic usage:1-17](file://docs/components/pro/multimodal_input/demos/basic.py#L1-L17) + +### Block Mode + +- **Goal**: Separates the input area and send button; customizes footer area layout +- **Key points**: `mode="block"`; the `footer` slot can contain "clear history" and other buttons; `auto_size` controls row range +- **Applicable scenarios**: Scenarios requiring clearer input/action separation, such as a vertically laid out chat window + +```mermaid +flowchart TD +Init(["Initialize MultimodalInput (mode='block')"]) --> Footer["Customize footer slot"] +Footer --> AutoSize["Configure auto_size (minRows, maxRows)"] +AutoSize --> Submit["User clicks send/cancel"] +Submit --> Update["Update input value and chat history"] +Update --> End(["Complete one round of interaction"]) +``` + +**Diagram Sources** + +- [Example: Block mode:57-77](file://docs/components/pro/multimodal_input/demos/block_mode.py#L57-L77) + +**Section Sources** + +- [Example: Block mode:1-81](file://docs/components/pro/multimodal_input/demos/block_mode.py#L1-L81) + +### Adding Extra Buttons and Custom Actions + +- **Goal**: Add buttons and icons in the prefix/suffix area via slots +- **Key points**: Use `ms.Slot("prefix")`/`("suffix")` to inject buttons; combine Tooltip/Button/Icon to implement "clear history" and other operations +- **Applicable scenarios**: Adding frequently used operation entries beside the input box to improve interaction efficiency + +```mermaid +sequenceDiagram +participant U as "User" +participant I as "MultimodalInput" +participant P as "prefix slot" +participant Btn as "Clear History Button" +U->>I : Click input box +I->>P : Render prefix slot +P->>Btn : Render button +U->>Btn : Click clear history +Btn-->>I : Trigger click event +I-->>U : Update chat history +``` + +**Diagram Sources** + +- [Example: Extra buttons and custom actions:59-74](file://docs/components/pro/multimodal_input/demos/extra_button.py#L59-L74) + +**Section Sources** + +- [Example: Extra buttons and custom actions:1-78](file://docs/components/pro/multimodal_input/demos/extra_button.py#L1-L78) + +### Upload Configuration (File types, count, paste/voice, etc.) + +- **Goal**: Flexibly control file upload behavior and appearance +- **Key points**: `MultimodalInputUploadConfig` supports `accept`, `max_count`, `fullscreen_drop`, `multiple`, `allow_speech`, `allow_paste_file`, `placeholder`, etc. +- **Applicable scenarios**: Restricting upload types (e.g., images only), limiting count, enabling fullscreen drag, allowing voice/paste file + +```mermaid +flowchart TD +Cfg["Configure upload_config"] --> Accept["Set accept (e.g., image/*)"] +Cfg --> Max["Set max_count to limit count"] +Cfg --> Full["Enable fullscreen_drop"] +Cfg --> Other["Enable allow_speech / allow_paste_file"] +Accept --> Render["Render upload button and placeholder"] +Max --> Render +Full --> Render +Other --> Render +Render --> Upload["User uploads / pastes / records"] +Upload --> Done["Complete upload and update file list"] +``` + +**Diagram Sources** + +- [Example: Upload configuration:12-34](file://docs/components/pro/multimodal_input/demos/upload_config.py#L12-L34) + +**Section Sources** + +- [Example: Upload configuration:1-38](file://docs/components/pro/multimodal_input/demos/upload_config.py#L1-L38) + +### Integration with Chatbot Component + +- **Goal**: Receive user text and files in a real chat application while handling cancellation and loading states +- **Key points**: `MultimodalInput.submit` outputs `{text, files}`; Chatbot supports multimodal messages (text/file/tool/suggestion) and can manage message streams via the `value` list +- **Applicable scenarios**: Building intelligent customer service, Q&A assistants, etc. with file/voice input + +```mermaid +sequenceDiagram +participant U as "User" +participant MI as "MultimodalInput" +participant FN as "Submit Callback" +participant CB as "Chatbot" +U->>MI : Input text / select file / click send +MI->>FN : Trigger submit with {text, files} +FN->>CB : Append user message (with text/file) +FN->>CB : Append bot "generating..." message +FN-->>MI : Clear input and set loading +CB-->>U : Display message stream +U->>MI : Click cancel +MI->>FN : Trigger cancel +FN->>CB : End loading and mark as complete +``` + +**Diagram Sources** + +- [Example: Integration with Chatbot component:10-53](file://docs/components/pro/multimodal_input/demos/with_chatbot.py#L10-L53) +- [Chatbot component documentation (Chinese):298-349](file://docs/components/pro/chatbot/README-zh_CN.md#L298-L349) + +**Section Sources** + +- [Example: Integration with Chatbot component:1-57](file://docs/components/pro/multimodal_input/demos/with_chatbot.py#L1-L57) +- [Chatbot component documentation (Chinese):1-354](file://docs/components/pro/chatbot/README-zh_CN.md#L1-L354) + +## Dependency Analysis + +- **Backend dependencies**: Gradio data classes, event system, file processing utilities +- **Frontend dependencies**: `@ant-design/x`'s Sender/Attachments, Ant Design icons and components, Gradio client upload tools +- **Slots and events**: Bridged to the React side via slot and event name mappings (e.g., `key_press`/`paste_file`) + +```mermaid +graph LR +PY["Backend Component"] --> FE_IDX["Svelte Entry"] +FE_IDX --> FE_CMP["React Component"] +FE_CMP --> ADX["Ant Design X (Sender/Attachments)"] +FE_CMP --> ANT["Ant Design (buttons/tooltips, etc.)"] +FE_CMP --> GRCL["Gradio Client Upload"] +``` + +**Diagram Sources** + +- [Frontend implementation: MultimodalInput React component:1-26](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L26) +- [Frontend index: MultimodalInput component entry:1-15](file://frontend/pro/multimodal-input/Index.svelte#L1-L15) + +**Section Sources** + +- [Frontend implementation: MultimodalInput React component:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [Frontend index: MultimodalInput component entry:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) + +## Performance Considerations + +- **Upload throttling and concurrency**: Frontend marks `uploading` state to avoid repeated uploads +- **File deduplication and merging**: Merge temporary files and server-returned data based on `uid` to reduce repeated renders +- **Behavioral limits**: `max_count` and `multiple` can reduce one-time upload pressure +- **Loading state and cancellation**: `loading` and `cancel` events are used to interrupt long tasks, improving user experience + +[This section provides general guidance and requires no specific file references] + +## Troubleshooting Guide + +- **Cannot upload files**: + - Check `upload_config`'s `allow_upload`/`disabled` and `max_count` + - Confirm file type and `accept` settings +- **File not displayed after upload**: + - Confirm that `onUpload` callback and `onChange` correctly update `value` +- **Send button unavailable**: + - Check `disabled`/`loading`/`read_only` states +- **Cancel not working**: + - Ensure `cancel`'s `cancels` correctly points to the `submit` event +- **Block mode footer not displayed**: + - Confirm `mode="block"` and the `footer` slot is correctly injected + +**Section Sources** + +- [Frontend implementation: MultimodalInput React component:174-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L174-L246) +- [Example: Block mode:69-77](file://docs/components/pro/multimodal_input/demos/block_mode.py#L69-L77) + +## Conclusion + +MultimodalInput provides an integrated capability from basic text input to complex multimodal interaction: through a concise API and flexible slot system, it can both meet quick integration needs and support richer interaction designs. Combined with the Chatbot component, you can easily build intelligent chat applications with file/voice input capabilities. + +[This section is a summary and requires no specific file references] + +## Appendix + +- **Value model and event reference**: + - Value model: `MultimodalInputValue(text, files)` + - Events: `change`/`submit`/`cancel`/`key_down`/`key_press`/`focus`/`blur`/`upload`/`paste`/`paste_file`/`skill_closable_close`/`drop`/`download`/`preview`/`remove` +- **Slot list**: `suffix`/`header`/`prefix`/`footer`/`skill.title`/`skill.toolTip.title`/`skill.closable.closeIcon` + +**Section Sources** + +- [Backend module: MultimodalInput definition:76-143](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L76-L143) +- [Frontend implementation: MultimodalInput React component:95-104](file://frontend/pro/multimodal-input/multimodal-input.tsx#L95-L104) diff --git a/.wiki/en/Pro Components/MultimodalInput/MultimodalInput.md b/.wiki/en/Pro Components/MultimodalInput/MultimodalInput.md new file mode 100644 index 00000000..ce098047 --- /dev/null +++ b/.wiki/en/Pro Components/MultimodalInput/MultimodalInput.md @@ -0,0 +1,399 @@ +# MultimodalInput + + +**Files Referenced in This Document** +- [Backend module definition](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py) +- [Frontend component implementation](file://frontend/pro/multimodal-input/multimodal-input.tsx) +- [Frontend entry wrapper](file://frontend/pro/multimodal-input/Index.svelte) +- [Recording hook](file://frontend/pro/multimodal-input/recorder.ts) +- [Audio processing utilities](file://frontend/pro/multimodal-input/utils.ts) +- [Component documentation](file://docs/components/pro/multimodal_input/README.md) +- [Component package export config](file://frontend/pro/multimodal-input/package.json) +- [Component build config](file://frontend/pro/multimodal-input/gradio.config.js) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +MultimodalInput is a multimodal input component based on Ant Design X, supporting multiple interaction modes including text input, file upload, voice recording, paste upload, and drag-and-drop upload. The component is implemented in React on the frontend and bridged to the backend via Gradio components, providing comprehensive multimodal data processing capabilities. + +Key features include: + +- Text input with automatic height adjustment +- File upload (single/multiple files, directory upload) +- Voice recording (based on Web Audio API) +- Paste upload (clipboard files) +- Drag-and-drop upload (supports fullscreen drag) +- Real-time preview and download +- Configurable attachment panel +- Structured input support (skill/slot mode) + +## Project Structure + +MultimodalInput adopts a frontend-backend separated architecture: + +```mermaid +graph TB +subgraph "Backend (Python)" +Backend[ModelScopeProMultimodalInput] +UploadConfig[MultimodalInputUploadConfig] +ValueModel[MultimodalInputValue] +end +subgraph "Frontend (React)" +Frontend[MultimodalInput Component] +Recorder[Recording Hook] +Utils[Audio Processing Utilities] +Wrapper[Index.svelte Wrapper] +end +subgraph "External Dependencies" +Antd[Ant Design X] +Gradio[Gradio Client] +Wavesurfer[Wavesurfer.js] +end +Backend --> Frontend +Frontend --> Antd +Frontend --> Gradio +Frontend --> Recorder +Recorder --> Wavesurfer +Frontend --> Utils +Wrapper --> Frontend +``` + +**Diagram Sources** + +- [Backend module definition:18-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L18-L259) +- [Frontend component implementation:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [Frontend entry wrapper:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) + +**Section Sources** + +- [Backend module definition:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) +- [Frontend component implementation:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [Frontend entry wrapper:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) + +## Core Components + +MultimodalInput consists of three core parts: + +### Backend Component Class + +The backend is implemented via the `ModelScopeProMultimodalInput` class, which inherits from `ModelScopeDataLayoutComponent` and provides complete Gradio component lifecycle management. + +### Frontend Component Implementation + +The frontend is implemented using React + TypeScript, built on the `Sender` and `Attachments` components from `@ant-design/x`. + +### Recording Module + +Integrates Wavesurfer.js to provide recording functionality, supporting real-time waveform display and audio format conversion. + +**Section Sources** + +- [Backend module definition:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) +- [Frontend component implementation:75-104](file://frontend/pro/multimodal-input/multimodal-input.tsx#L75-L104) +- [Recording hook:11-47](file://frontend/pro/multimodal-input/recorder.ts#L11-L47) + +## Architecture Overview + +MultimodalInput uses a layered architecture to ensure clear separation of the frontend-backend data flow: + +```mermaid +sequenceDiagram +participant User as User +participant UI as Frontend UI +participant Recorder as Recording Module +participant Uploader as Upload Module +participant Backend as Backend Component +participant Gradio as Gradio Client +User->>UI : Input text / select file +UI->>Uploader : Trigger file upload +Uploader->>Gradio : Call upload API +Gradio-->>Uploader : Return FileData list +Uploader-->>UI : Update file list +User->>Recorder : Start / stop recording +Recorder->>Recorder : Record audio data +Recorder->>Uploader : Upload recording file +Uploader->>Gradio : Call upload API +Gradio-->>Uploader : Return FileData +Uploader-->>UI : Display upload result +UI->>Backend : Trigger change event +Backend->>Backend : Data pre-processing +Backend-->>User : Return normalized data +``` + +**Diagram Sources** + +- [Frontend component implementation:157-169](file://frontend/pro/multimodal-input/multimodal-input.tsx#L157-L169) +- [Frontend component implementation:220-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L220-L246) +- [Frontend entry wrapper:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) + +## Detailed Component Analysis + +### Data Model and Type Definitions + +```mermaid +classDiagram +class MultimodalInputValue { ++files : FileData[] ++text : string +} +class MultimodalInputUploadConfig { ++fullscreenDrop : boolean ++allowUpload : boolean ++allowPasteFile : boolean ++allowSpeech : boolean ++showCount : boolean ++uploadButtonTooltip : string ++accept : string ++maxCount : number ++directory : boolean ++multiple : boolean ++disabled : boolean ++overflow : string ++title : string ++imageProps : dict ++placeholder : dict +} +class ModelScopeProMultimodalInput { ++mode : string ++autoSize : boolean|dict ++uploadConfig : dict ++preprocess(payload) dict ++postprocess(value) MultimodalInputValue ++_processSingleFile(f) NamedString +} +MultimodalInputValue --> ModelScopeProMultimodalInput : uses +MultimodalInputUploadConfig --> ModelScopeProMultimodalInput : configures +``` + +**Diagram Sources** + +- [Backend module definition:18-80](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L18-L80) +- [Backend module definition:82-205](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L205) + +### Upload Configuration Reference + +| Option | Type | Default | Description | +| --------------------- | ------- | ------------- | -------------------------------------------------------------------------------------- | +| `fullscreenDrop` | boolean | false | Whether to allow dragging files to the entire page window to open the attachment panel | +| `allowUpload` | boolean | true | Whether to enable file upload | +| `allowPasteFile` | boolean | true | Whether to allow paste file upload | +| `allowSpeech` | boolean | false | Whether to allow voice input | +| `showCount` | boolean | true | Whether to show file count badge when attachment panel is closed | +| `uploadButtonTooltip` | string | null | Tooltip text for the upload button | +| `accept` | string | null | Accepted file types | +| `maxCount` | number | null | Maximum number of files | +| `directory` | boolean | false | Support uploading entire directories | +| `multiple` | boolean | false | Support multi-file selection | +| `disabled` | boolean | false | Disable file upload | +| `overflow` | string | null | File list overflow behavior | +| `title` | string | "Attachments" | Attachment panel title | +| `imageProps` | dict | null | Image configuration | +| `placeholder` | dict | built-in | Placeholder info when no files | + +### Event Handling Mechanism + +```mermaid +flowchart TD +Start([User Action]) --> CheckType{"Action type"} +CheckType --> |Text input| TextChange["Update text value
Trigger onChange event"] +CheckType --> |File add| FileAdd["Validate file count
Add to temporary list"] +CheckType --> |File remove| FileRemove["Remove from list
Update file list"] +CheckType --> |Drag upload| DragUpload["Handle dragged files
Call upload API"] +CheckType --> |Paste upload| PasteUpload["Handle pasted files
Call upload API"] +CheckType --> |Voice upload| RecordUpload["Record audio
Convert format and upload"] +FileAdd --> UploadCall["Call upload API"] +UploadCall --> UploadSuccess{"Upload successful?"} +UploadSuccess --> |Yes| UpdateList["Update final file list
Trigger callback"] +UploadSuccess --> |No| ErrorHandle["Error handling
Restore state"] +TextChange --> End([Done]) +FileRemove --> End +DragUpload --> End +PasteUpload --> End +RecordUpload --> End +UpdateList --> End +ErrorHandle --> End +``` + +**Diagram Sources** + +- [Frontend component implementation:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) +- [Frontend component implementation:352-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L352-L360) + +### Recording Feature Implementation + +The recording feature is implemented via Wavesurfer.js, supporting: + +- Real-time waveform display +- Audio format conversion (WAV) +- Automatic trimming and resampling +- Recording state management + +```mermaid +sequenceDiagram +participant User as User +participant Recorder as Recording Hook +participant WaveSurfer as Wavesurfer Instance +participant AudioContext as Audio Context +participant Uploader as Upload Module +User->>Recorder : Click record button +Recorder->>WaveSurfer : Initialize recorder +WaveSurfer->>AudioContext : Create audio context +AudioContext->>WaveSurfer : Configure recording parameters +User->>Recorder : Start recording +Recorder->>WaveSurfer : startRecording() +WaveSurfer->>AudioContext : Start capturing audio +User->>Recorder : Stop recording +Recorder->>WaveSurfer : stopRecording() +WaveSurfer->>AudioContext : Get audio buffer +AudioContext->>Recorder : Convert to WAV format +Recorder->>Uploader : Upload audio file +Uploader->>Uploader : Call upload API +Uploader-->>Recorder : Return FileData +Recorder-->>User : Display upload result +``` + +**Diagram Sources** + +- [Recording hook:24-41](file://frontend/pro/multimodal-input/recorder.ts#L24-L41) +- [Audio processing utilities:94-126](file://frontend/pro/multimodal-input/utils.ts#L94-L126) + +**Section Sources** + +- [Recording hook:1-48](file://frontend/pro/multimodal-input/recorder.ts#L1-L48) +- [Audio processing utilities:1-127](file://frontend/pro/multimodal-input/utils.ts#L1-L127) + +## Dependency Analysis + +```mermaid +graph TB +subgraph "Core Dependencies" +React[React 18+] +Antd[Ant Design 5.x] +ADX[Ant Design X] +Gradio[Gradio Client] +end +subgraph "Recording Related" +Wavesurfer[Wavesurfer.js] +RecordPlugin[Record Plugin] +end +subgraph "Utilities" +Lodash[LoDash] +Classnames[ClassNames] +Moment[Moment.js] +end +subgraph "Component Internals" +MultimodalInput[MultimodalInput Component] +Recorder[useRecorder Hook] +Utils[Audio Processing Utilities] +Wrapper[Index.svelte Wrapper] +end +MultimodalInput --> React +MultimodalInput --> Antd +MultimodalInput --> ADX +MultimodalInput --> Gradio +MultimodalInput --> Recorder +MultimodalInput --> Utils +Recorder --> Wavesurfer +Recorder --> RecordPlugin +Wrapper --> MultimodalInput +MultimodalInput --> Lodash +MultimodalInput --> Classnames +``` + +**Diagram Sources** + +- [Frontend component implementation:1-26](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L26) +- [Recording hook:1-5](file://frontend/pro/multimodal-input/recorder.ts#L1-L5) +- [Component package export config:1-15](file://frontend/pro/multimodal-input/package.json#L1-L15) + +**Section Sources** + +- [Component package export config:1-15](file://frontend/pro/multimodal-input/package.json#L1-L15) +- [Component build config:1-4](file://frontend/pro/multimodal-input/gradio.config.js#L1-L4) + +## Performance Considerations + +### File Upload Optimization + +- Supports batch upload control; use `maxCount` to limit simultaneously uploading files +- Uses a temporary file list mechanism to avoid redundant renders +- Asynchronous upload processing to avoid blocking the main thread + +### Memory Management + +- Release audio context resources promptly after recording ends +- Clear temporary file references after file upload completes +- Use `useMemoizedFn` to optimize function references + +### Rendering Optimization + +- Conditionally render the attachment panel to reduce unnecessary DOM elements +- Use virtual scrolling to handle large file lists +- Load recording plugin on demand + +## Troubleshooting Guide + +### Common Issues and Solutions + +**Issue 1: Recording feature not working** + +- Check browser permission settings +- Confirm HTTPS environment (recording requires a secure context) +- Verify microphone device availability + +**Issue 2: File upload failed** + +- Check network connection status +- Verify file size limits +- Confirm server upload API is working properly + +**Issue 3: Drag-and-drop upload unresponsive** + +- Confirm `fullscreenDrop` configuration is correct +- Check for CSS style conflicts +- Verify browser compatibility + +**Issue 4: Audio format incompatibility** + +- Confirm browser supports WAV format +- Check audio sample rate settings +- Verify audio channel count configuration + +**Section Sources** + +- [Recording hook:24-41](file://frontend/pro/multimodal-input/recorder.ts#L24-L41) +- [Frontend component implementation:178-179](file://frontend/pro/multimodal-input/multimodal-input.tsx#L178-L179) + +## Conclusion + +MultimodalInput is a feature-complete, architecturally clear multimodal input component. Through a well-designed layered architecture and comprehensive error handling mechanisms, it provides developers with powerful rich media input capabilities. The component supports multiple input modes, has good extensibility and configurability, and is suitable for building various complex rich media application interfaces. + +## Appendix + +### Usage Example Overview + +Due to the extensive code examples, it is recommended to refer to the example pages in the official documentation for complete usage samples. + +### API Reference + +For the complete set of properties and event interfaces supported by the component, refer to the API section in the component documentation. + +### Version Compatibility + +- React 18+ +- Ant Design 5.x +- Ant Design X +- Gradio 3.x+ diff --git a/.wiki/en/Pro Components/Pro Components.md b/.wiki/en/Pro Components/Pro Components.md new file mode 100644 index 00000000..281d4b7e --- /dev/null +++ b/.wiki/en/Pro Components/Pro Components.md @@ -0,0 +1,355 @@ +# Pro Components + + +**Files Referenced in This Document** +- [chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) +- [type.ts](file://frontend/pro/chatbot/type.ts) +- [utils.ts](file://frontend/pro/chatbot/utils.ts) +- [multimodal-input.tsx](file://frontend/pro/multimodal-input/multimodal-input.tsx) +- [recorder.ts](file://frontend/pro/multimodal-input/recorder.ts) +- [utils.ts](file://frontend/pro/multimodal-input/utils.ts) +- [web-sandbox.tsx](file://frontend/pro/web-sandbox/web-sandbox.tsx) +- [monaco-editor.tsx](file://frontend/pro/monaco-editor/monaco-editor.tsx) +- [components.py](file://backend/modelscope_studio/components/pro/components.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is aimed at experienced developers and systematically covers the advanced components in the ModelScope Studio Pro component library: Chatbot, MultimodalInput, WebSandbox, and MonacoEditor. The document provides in-depth explanations from architecture design, data flow, processing logic, integration methods, performance optimization, to troubleshooting, with source code path references to help developers efficiently deploy in complex professional scenarios. + +## Project Structure + +Pro components are located in the `pro` submodule of the frontend directory; the backend aggregates and exports them via components.py to form a unified component entry. Each component is encapsulated in React + Svelte preprocessing mode, reusing the capabilities of Ant Design X and Ant Design, and achieving high-performance interaction integrated with the Gradio ecosystem. + +```mermaid +graph TB +subgraph "Backend" +A["components.py
Unified export of Pro components"] +end +subgraph "Frontend Pro Components" +B["Chatbot"] +C["MultimodalInput"] +D["WebSandbox"] +E["MonacoEditor"] +end +A --> B +A --> C +A --> D +A --> E +``` + +Diagram sources + +- [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +Section sources + +- [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## Core Components + +- Chatbot: A conversational component based on bubble message lists, supporting user/assistant roles, welcome prompts, and interactions such as copy/like/retry/edit/delete, with built-in scroll control and Markdown rendering. +- MultimodalInput: An input component supporting text and file uploads, with built-in extension slots for voice recording, paste upload, attachment management, and skill panels. +- WebSandbox: Compiles multi-file/HTML source code into a sandbox environment that runs safely in an iframe, supporting React/HTML templates and theme injection. +- MonacoEditor: A lightweight encapsulation of the Monaco editor, providing read-only mode, theme switching, value change callbacks, and loading placeholders. + +Section sources + +- [chatbot.tsx:51-76](file://frontend/pro/chatbot/chatbot.tsx#L51-L76) +- [multimodal-input.tsx:75-94](file://frontend/pro/multimodal-input/multimodal-input.tsx#L75-L94) +- [web-sandbox.tsx:21-35](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L35) +- [monaco-editor.tsx:12-19](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L19) + +## Architecture Overview + +All four pro components are organized using a "property-driven + context/utility functions" pattern. Internally, they achieve a data loop through state management and event callbacks; externally, they provide unified callbacks such as onValueChange/onChange/onSubmit for easy integration with upper-level applications or servers. + +```mermaid +graph TB +subgraph "Chatbot" +CB_API["Props: value/onValueChange/markdownConfig etc."] +CB_CORE["Render: Bubble messages/welcome prompt/action bar"] +CB_EVT["Events: onCopy/onEdit/onLike/onRetry etc."] +end +subgraph "MultimodalInput" +MI_API["Props: value/upload/onSubmit/uploadConfig"] +MI_CORE["Render: Sender + Attachments + Skill panel"] +MI_EVT["Events: onUpload/onPasteFile/onRemove etc."] +end +subgraph "WebSandbox" +WS_API["Props: value/imports/template/themeMode"] +WS_PARSER["Parse: WebSandboxParser/template rendering"] +WS_IFRAME["Output: iframe + theme injection + error reporting"] +end +subgraph "MonacoEditor" +ME_API["Props: value/options/themeMode/readOnly"] +ME_EDITOR["Render: @monaco-editor/react"] +end +CB_API --> CB_CORE --> CB_EVT +MI_API --> MI_CORE --> MI_EVT +WS_API --> WS_PARSER --> WS_IFRAME +ME_API --> ME_EDITOR +``` + +Diagram sources + +- [chatbot.tsx:77-472](file://frontend/pro/chatbot/chatbot.tsx#L77-L472) +- [multimodal-input.tsx:105-616](file://frontend/pro/multimodal-input/multimodal-input.tsx#L105-L616) +- [web-sandbox.tsx:37-362](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L362) +- [monaco-editor.tsx:21-93](file://frontend/pro/monaco-editor/monaco-editor.tsx#L21-L93) + +## Detailed Component Analysis + +### Chatbot + +- Feature Highlights + - Role-based message rendering: User/assistant/system/separator role mapping, supporting custom head/body/footer/avatar. + - Welcome prompt: Built-in welcome message area with prompt selection callback support. + - Interaction capabilities: Copy, like/dislike, retry, edit, delete, suggestion item selection. + - Auto-scroll and scroll-to-bottom button: Configurable auto-scroll and "scroll to bottom" button. + - Markdown rendering: Unified Markdown configuration with line break and rendering toggle support. +- Key Properties and Callbacks + - Basic: rootUrl, apiPrefix, themeMode, height/minHeight/maxHeight, autoScroll, showScrollToBottomButton, scrollToBottomButtonOffset. + - Configuration: userConfig, botConfig, markdownConfig, welcomeConfig. + - Data: value (message array), onValueChange. + - Callbacks: onCopy, onEdit, onDelete, onLike, onRetry, onSuggestionSelect, onWelcomePromptSelect. +- Internal Mechanism + - Uses context providers and role preprocessing to normalize external messages into bubble items. + - Uses Immer for immutable updates to ensure stability of edit/like/delete operations. + - Uses scroll hooks to control scroll position and button display. + +```mermaid +sequenceDiagram +participant U as "User" +participant C as "Chatbot" +participant L as "Bubble.List" +participant F as "ChatbotFooter" +participant M as "Message" +U->>C : Input message / click action +C->>C : Parse config / normalize messages +C->>L : Render message list +L->>M : Render message content (with Markdown) +L->>F : Render action bar (copy/like/retry/edit/delete) +F-->>C : Trigger callbacks (onLike/onRetry/onEdit/onDelete) +C->>C : Update message array (Immer) +C-->>U : onValueChange(value) +``` + +Diagram sources + +- [chatbot.tsx:107-472](file://frontend/pro/chatbot/chatbot.tsx#L107-L472) + +Section sources + +- [chatbot.tsx:51-475](file://frontend/pro/chatbot/chatbot.tsx#L51-L475) +- [type.ts](file://frontend/pro/chatbot/type.ts) +- [utils.ts](file://frontend/pro/chatbot/utils.ts) + +### MultimodalInput + +- Feature Highlights + - Text input and submission: Based on the Sender component, supports voice recording, paste upload, and submit callback. + - File upload: Based on Attachments, supports drag-and-drop, fullscreen drag, count display, and maximum count limit. + - Attachment management: Supports download, preview, removal, and customization of placeholders and icons. + - Skill panel: Extension slots for title, prompt, closable, supporting custom rendering and functional configuration. + - State and disable: loading/disabled/readOnly controls the upload flow. +- Key Properties and Callbacks + - Basic: value, mode (inline/block), upload (file upload function), onValueChange/onChange/onSubmit. + - Upload config: uploadConfig (allowUpload/allowSpeech/allowPasteFile/showCount/title/placeholder/fullscreenDrop/maxCount, etc.). + - Events: onUpload/onPasteFile/onRemove/onDownload/onDrop/onPreview. +- Internal Mechanism + - Uses useValueChange to sync external value with internal state. + - Recorder hook supports microphone recording and converts to audio file before uploading. + - Maintains a temporary file list during upload, merges into the final file list upon completion, and triggers callbacks. + +```mermaid +flowchart TD +Start(["Start"]) --> CheckMode["Check mode"] +CheckMode --> |inline| RenderInline["Render Sender + optional attachment header"] +CheckMode --> |block| RenderBlock["Render Sender + bottom action area"] +RenderInline --> Interact["Text input / voice / paste / drag"] +RenderBlock --> Interact +Interact --> Upload["Call upload(files)"] +Upload --> OnUpload["Trigger onUpload/onValueChange/onChange"] +OnUpload --> End(["End"]) +``` + +Diagram sources + +- [multimodal-input.tsx:105-616](file://frontend/pro/multimodal-input/multimodal-input.tsx#L105-L616) + +Section sources + +- [multimodal-input.tsx:75-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L75-L619) +- [recorder.ts](file://frontend/pro/multimodal-input/recorder.ts) +- [utils.ts](file://frontend/pro/multimodal-input/utils.ts) + +### WebSandbox + +- Feature Highlights + - Multi-file/HTML source code compilation: Parses entry files, extracts stylesheets and scripts, and generates runnable HTML or React entry points. + - Secure sandbox: Hosted in an iframe to avoid conflicts with the host page. + - Theme injection: Supports passing theme mode to iframe content. + - Error handling: Visual display and callback notification for compile and render errors. +- Key Properties and Callbacks + - Basic: value (file dictionary), imports (third-party dependency mapping), template (react/html), themeMode, height. + - Behavior: showRenderError/showCompileError, onCompileError/onCompileSuccess/onRenderError/onCustom. + - Customization: compileErrorRender slot and function. +- Internal Mechanism + - Selects parsing strategy based on template: extracts and replaces inline scripts in HTML mode; generates entry URL in React mode. + - Uses WebSandboxParser to parse files and map dependencies, generating import maps and stylesheet links. + - Communicates with the iframe via postMessage, receiving events such as sandbox-ready/sandbox-error. + +```mermaid +sequenceDiagram +participant App as "Application" +participant WS as "WebSandbox" +participant Parser as "WebSandboxParser" +participant Ifr as "iframe" +App->>WS : Pass value/imports/template/themeMode +WS->>Parser : Parse files / generate entry / stylesheets +Parser-->>WS : Return entryUrl/styleSheetUrls or html +WS->>Ifr : Set srcObject (URL.createObjectURL) +Ifr-->>WS : postMessage (sandbox-ready/error) +WS-->>App : onCompileSuccess/onRenderError/onCustom +``` + +Diagram sources + +- [web-sandbox.tsx:37-362](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L362) + +Section sources + +- [web-sandbox.tsx:21-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L365) + +### MonacoEditor + +- Feature Highlights + - Theme adaptation: Switches between vs-dark/light based on themeMode. + - Read-only mode: Controls editing behavior via the readOnly property. + - Loading placeholder: Supports custom loading slot or default Spin. + - Value synchronization: Unified useValueChange implements two-way binding. +- Key Properties and Callbacks + - Basic: value, options, themeMode, readOnly, height. + - Callbacks: onMount/beforeMount/afterMount, onChange/onValueChange. +- Internal Mechanism + - Passes props directly to the Editor component of @monaco-editor/react. + - Chains onMount/afterMount in the mount lifecycle to ensure initialization order. + +```mermaid +sequenceDiagram +participant App as "Application" +participant ME as "MonacoEditor" +participant E as "@monaco-editor/react" +App->>ME : Pass value/options/themeMode/readOnly +ME->>E : Render Editor (set value/options/loading) +E-->>ME : onChange/value update +ME-->>App : onValueChange(value) +``` + +Diagram sources + +- [monaco-editor.tsx:21-93](file://frontend/pro/monaco-editor/monaco-editor.tsx#L21-L93) + +Section sources + +- [monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) + +## Dependency Analysis + +- Inter-component Coupling + - Each component maintains low coupling, decoupled from upper-level applications through unified callbacks such as onValueChange/onChange/onSubmit. + - Chatbot/MultimodalInput/WebSandbox/MonacoEditor are independently encapsulated with clear responsibilities. +- External Dependencies + - Chatbot: @ant-design/x (Bubble.List), Ant Design (Avatar/Button), Immer, Lodash. + - MultimodalInput: @ant-design/x (Sender/Attachments), Ant Design (Badge/Button/Flex/Tooltip), audio recording and file processing utilities. + - WebSandbox: @ant-design/x (HTML parsing and event listening), DOM parsing and traversal utilities, iframe communication. + - MonacoEditor: @monaco-editor/react, Antd Spin. + +```mermaid +graph LR +CB_DEPS["@ant-design/x(Bubble)
Antd(Avatar/Button)
Immer/Lodash"] --> CB["Chatbot"] +MI_DEPS["@ant-design/x(Sender/Attachments)
Antd(Badge/Button/Flex/Tooltip)"] --> MI["MultimodalInput"] +WS_DEPS["DOM/Traversal/iframe"] --> WS["WebSandbox"] +ME_DEPS["@monaco-editor/react/Antd(Spin)"] --> ME["MonacoEditor"] +``` + +Diagram sources + +- [chatbot.tsx:1-25](file://frontend/pro/chatbot/chatbot.tsx#L1-L25) +- [multimodal-input.tsx:1-26](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L26) +- [web-sandbox.tsx:1-17](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L17) +- [monaco-editor.tsx:1-10](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L10) + +Section sources + +- [chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [monaco-editor.tsx:1-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L95) + +## Performance Considerations + +- Chatbot + - Uses useMemo and useMemoizedFn to reduce rendering and callback overhead; uses Immer for partial immutable updates to avoid deep copying. + - Scroll control is triggered only when necessary to reduce DOM operations. +- MultimodalInput + - Validates maximum count and disabled state before upload to reduce invalid requests; the temporary file list only exists during the upload phase and is cleaned up promptly. + - Audio transcoding and upload are executed asynchronously to avoid blocking the UI. +- WebSandbox + - Generates import maps and stylesheet links during the parsing phase to avoid repeated computation; iframe URLs use revokeObjectURL to release memory promptly. + - Compile and render errors are quickly fed back to avoid long waits. +- MonacoEditor + - Reduces unnecessary redraws through options merging and read-only control; loading placeholders avoid blank flickering. + +## Troubleshooting Guide + +- Chatbot + - Symptom: Messages not displaying or style abnormal + - Diagnosis: Confirm whether value is empty or not normalized; check whether userConfig/botConfig/class_names are passed correctly. + - Reference: [chatbot.tsx:108-165](file://frontend/pro/chatbot/chatbot.tsx#L108-L165) +- MultimodalInput + - Symptom: Upload not responding or files not displaying + - Diagnosis: Check whether the upload function returns a FileData array; confirm maxCount and disabled state; check whether onUpload/onValueChange is triggered. + - Reference: [multimodal-input.tsx:174-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L174-L246) +- WebSandbox + - Symptom: Compile failure or render error + - Diagnosis: Check whether an entry file exists in value; confirm whether the imports mapping is complete; check onCompileError/onRenderError callbacks and the compileErrorRender slot. + - Reference: [web-sandbox.tsx:95-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L95-L218) +- MonacoEditor + - Symptom: Editor not displaying or theme not taking effect + - Diagnosis: Confirm themeMode and options; check whether the beforeMount/afterMount lifecycle is correctly chained. + - Reference: [monaco-editor.tsx:39-87](file://frontend/pro/monaco-editor/monaco-editor.tsx#L39-L87) + +Section sources + +- [chatbot.tsx:108-165](file://frontend/pro/chatbot/chatbot.tsx#L108-L165) +- [multimodal-input.tsx:174-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L174-L246) +- [web-sandbox.tsx:95-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L95-L218) +- [monaco-editor.tsx:39-87](file://frontend/pro/monaco-editor/monaco-editor.tsx#L39-L87) + +## Conclusion + +Through high cohesion and low coupling design, the ModelScope Studio Pro component library provides plug-and-play capabilities for complex professional scenarios: Chatbot provides an extensible message and interaction model; MultimodalInput combines text and file capabilities to meet multimodal input requirements; WebSandbox combines frontend engineering with sandbox security; MonacoEditor provides a consistent editing experience through a concise encapsulation. With a unified callback and configuration system, developers can quickly build high-quality professional applications. + +## Appendix + +- Component Export Entry + - Unified backend export: [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + - **MonacoEditorDiffEditor Export Entry**: `MonacoEditorDiffEditor` is exported in [backend/modelscope_studio/components/pro/**init**.py](file://backend/modelscope_studio/components/pro/__init__.py), imported as `from modelscope_studio.components.pro import MonacoEditorDiffEditor`. This component is a sub-component of MonacoEditor, specifically designed for code diff comparison scenarios. +- Types and Utilities + - Chatbot types and utilities: [type.ts](file://frontend/pro/chatbot/type.ts), [utils.ts](file://frontend/pro/chatbot/utils.ts) + - MultimodalInput utilities and recording: [recorder.ts](file://frontend/pro/multimodal-input/recorder.ts), [utils.ts](file://frontend/pro/multimodal-input/utils.ts) diff --git a/.wiki/en/Pro Components/WebSandbox/Basic Usage.md b/.wiki/en/Pro Components/WebSandbox/Basic Usage.md new file mode 100644 index 00000000..86a2a3b1 --- /dev/null +++ b/.wiki/en/Pro Components/WebSandbox/Basic Usage.md @@ -0,0 +1,329 @@ +# Component Overview + + +**Files Referenced in This Document** +- [web-sandbox.tsx](file://frontend/pro/web-sandbox/web-sandbox.tsx) +- [parser.ts](file://frontend/pro/web-sandbox/parser.ts) +- [utils.ts](file://frontend/pro/web-sandbox/utils.ts) +- [react-iframe-template.html](file://frontend/pro/web-sandbox/react-iframe-template.html) +- [html-iframe-event-listener.js](file://frontend/pro/web-sandbox/html-iframe-event-listener.js) +- [README.md (WebSandbox Docs)](file://docs/components/pro/web_sandbox/README.md) +- [react.py (Example)](file://docs/components/pro/web_sandbox/demos/react.py) +- [html.py (Example)](file://docs/components/pro/web_sandbox/demos/html.py) +- [error_handling.py (Example)](file://docs/components/pro/web_sandbox/demos/error_handling.py) +- [custom_sandbox_event.py (Example)](file://docs/components/pro/web_sandbox/demos/custom_sandbox_event.py) +- [__init__.py (Backend Component Entry)](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py) +- [components.py (Backend Component Export)](file://backend/modelscope_studio/components/pro/components.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Quick Start and Basic Usage](#appendix-quick-start-and-basic-usage) + +## Introduction + +WebSandbox is a secure sandbox component for compiling and previewing React or HTML code within a page. It parses, transforms, and bundles user-provided source files, then runs them in an isolated iframe to safely render third-party content. This component is widely applicable for online code demos, tutorial examples, and low-trust frontend content previews. + +## Project Structure + +The WebSandbox component consists of two parts: frontend and backend. + +- **Frontend (Svelte/React)**: Parses and compiles user code, generates iframe content, handles errors and theme injection, and communicates with the parent page. +- **Backend (Python)**: Exposes the component as a Gradio Pro component, binding events and slots for use on the Python side. + +```mermaid +graph TB +subgraph "Frontend" +A["web-sandbox.tsx
Component main entry"] +B["parser.ts
File parsing and transformation"] +C["utils.ts
Utility functions"] +D["react-iframe-template.html
React template"] +E["html-iframe-event-listener.js
HTML event listener"] +end +subgraph "Backend" +F["__init__.py
Pro component definition"] +G["components.py
Component export"] +end +A --> B +A --> C +A --> D +A --> E +F --> G +F --> A +``` + +Diagram Sources + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [**init**.py (Backend Component Entry):1-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L1-L86) +- [components.py (Backend Component Export):1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +Section Sources + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [**init**.py (Backend Component Entry):1-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L1-L86) +- [components.py (Backend Component Export):1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## Core Components + +- **Component Name**: WebSandbox (Pro) +- **Purpose**: Compile and render React or HTML code in a securely isolated iframe, supporting error messages, theme injection, and custom event forwarding. +- **Key Capabilities**: + - Multi-template support: React and HTML template types. + - Automatic dependency mapping: Injects third-party dependencies (e.g., React ecosystem) via importmap. + - Compilation and bundling: Transforms and bundles JS/TS/JSX/TSX, inlines relative CSS, and links external CSS. + - Security isolation: Isolates resources and scripts via Blob URLs and iframes. + - Error handling: Compile errors and render errors are reported separately with optional display. + - Theme and events: Injects theme information into the iframe; supports custom events forwarded from iframe to parent page. + +Section Sources + +- [README.md (WebSandbox Docs):1-70](file://docs/components/pro/web_sandbox/README.md#L1-L70) +- [web-sandbox.tsx:21-35](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L35) +- [parser.ts:176-283](file://frontend/pro/web-sandbox/parser.ts#L176-L283) +- [utils.ts:48-75](file://frontend/pro/web-sandbox/utils.ts#L48-L75) + +## Architecture Overview + +The overall WebSandbox flow includes: receive user files → parse and dependency analysis → transform and bundle → generate iframe content → render and error reporting → theme injection and event forwarding. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Front as "WebSandbox (Frontend)" +participant Parser as "WebSandboxParser" +participant Iframe as "iframe (Child Page)" +participant Parent as "Parent Page" +Dev->>Front : Pass value, template, imports, and other parameters +Front->>Parser : Parse files, build dependency graph, topological sort +Parser-->>Front : Return entryUrl/styleSheetUrls/normalizedFiles +Front->>Front : Generate iframe HTML (Blob URL) +Front->>Iframe : Load iframe +Iframe-->>Parent : postMessage("sandbox-ready") +Parent-->>Front : Trigger compile_success +Iframe-->>Parent : postMessage("sandbox-error", message) +Parent-->>Front : Trigger render_error +``` + +Diagram Sources + +- [web-sandbox.tsx:94-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L94-L218) +- [parser.ts:285-312](file://frontend/pro/web-sandbox/parser.ts#L285-L312) +- [react-iframe-template.html:24-28](file://frontend/pro/web-sandbox/react-iframe-template.html#L24-L28) +- [html-iframe-event-listener.js:8-12](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L8-L12) + +## Detailed Component Analysis + +### Component Class and Interface (Frontend) + +WebSandbox, as a Svelte-wrapped React component, defines props, events, and slots, and internally maintains loading state, compile errors, and parse results. + +```mermaid +classDiagram +class WebSandboxProps { ++value ++imports ++showRenderError ++showCompileError ++template ++onCompileError ++onCompileSuccess ++onRenderError ++onCustom ++height ++themeMode ++compileErrorRender ++children +} +class WebSandbox { ++iframeRef ++divRef ++loading ++compileError ++parsedValue ++resolvedImportMap ++useEffect(handleFiles) ++useMemo(generateIframeUrl) ++useEffect(messageListener) +} +WebSandbox --> WebSandboxProps : "uses" +``` + +Diagram Sources + +- [web-sandbox.tsx:21-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L365) + +Section Sources + +- [web-sandbox.tsx:21-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L365) + +### Parser + +WebSandboxParser is responsible for: + +- Normalizing file paths and content +- Building the dependency graph (AST analysis of imports) +- Topological sorting to detect circular dependencies +- Transforming and bundling (JS/TS/JSX/TSX), replacing relative imports with Blob URLs, inlining/linking CSS +- Generating entry file URL and stylesheet URL list + +```mermaid +flowchart TD +Start(["Start"]) --> Normalize["Normalize file paths and content"] +Normalize --> BuildGraph["Build dependency graph (AST)"] +BuildGraph --> Sort["Topological sort"] +Sort --> Transform["Transform and bundle each file"] +Transform --> CSS["Collect relative/external CSS"] +CSS --> Output["Output: entryUrl/styleSheetUrls/cleanup"] +Output --> End(["End"]) +``` + +Diagram Sources + +- [parser.ts:28-312](file://frontend/pro/web-sandbox/parser.ts#L28-L312) + +Section Sources + +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) + +### Utility Functions (Utils) + +- File extension and default entry file sets +- Path normalization +- Template rendering +- Entry file selection logic + +Section Sources + +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) + +### iframe Template and Event Listeners + +- **React template**: Injects importmap, stylesheets, and entry module, listens for error and ready events, and notifies the parent page via postMessage. +- **HTML event listener**: Injects event listener script in HTML mode; behavior is consistent with the template. + +Section Sources + +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +### Backend Component (Python) + +- Registers the frontend component as a Pro component, supporting event binding and slot configuration. +- Provides typed file data structures for easy parameter passing on the Python side. + +Section Sources + +- [**init**.py (Backend Component Entry):1-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L1-L86) +- [components.py (Backend Component Export):1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## Dependency Analysis + +- **Component coupling points**: + - WebSandbox depends on Parser for file parsing and bundling. + - WebSandbox depends on utility functions from utils (path, entry selection, template rendering). + - iframe templates and event listener scripts are injected into the iframe via Blob URLs. +- **External dependencies**: + - importmap for online dependency mapping (e.g., React ecosystem). + - Babel Standalone for code transformation and AST analysis. +- **Potential circular dependencies**: + - Parser avoids circular dependencies via topological sorting; circular dependencies will throw an exception. + +```mermaid +graph LR +WS["WebSandbox (Frontend)"] --> P["WebSandboxParser"] +WS --> U["utils"] +WS --> T["react-iframe-template.html"] +WS --> L["html-iframe-event-listener.js"] +P --> B["Babel Standalone"] +WS --> IM["importmap (Third-party dependencies)"] +``` + +Diagram Sources + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +Section Sources + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) + +## Performance Considerations + +- **Transformation and bundling cost**: Transformation and AST analysis are performed on each JS/TS file; it is recommended to keep the number and size of files under control. +- **Blob URL management**: Release Blob URLs promptly after bundling to avoid memory leaks. +- **Stylesheet strategy**: Relative CSS is inlined as Blob URLs; external CSS is linked directly to reduce redundant requests. +- **Theme injection and message communication**: Theme is injected only when `iframeUrl` changes to avoid frequent operations. + +## Troubleshooting Guide + +- **Compile error** + - Symptom: Component displays a compile error or triggers the `compile_error` event. + - Diagnosis: Check whether the entry file exists, whether the template type matches, and whether third-party dependencies are correctly mapped. +- **Render error** + - Symptom: A runtime error occurs inside the iframe, triggering the `render_error` event and displaying a notification (depending on `show_render_error`). + - Diagnosis: Check the iframe console logs, confirm dependencies and entry module correctness. +- **Circular dependency** + - Symptom: A circular dependency exception is thrown during the parsing phase. + - Diagnosis: Inspect import relationships, split modules, or adjust import paths. +- **Theme not applied** + - Symptom: Theme inside the iframe is not updated. + - Diagnosis: Confirm that the `themeMode` parameter is passed correctly and that postMessage succeeded. + +Section Sources + +- [web-sandbox.tsx:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- [parser.ts:128-174](file://frontend/pro/web-sandbox/parser.ts#L128-L174) +- [README.md (WebSandbox Docs):34-70](file://docs/components/pro/web_sandbox/README.md#L34-L70) + +## Conclusion + +WebSandbox implements safe rendering of third-party frontend code through a complete pipeline of "parse → transform → bundle → iframe isolation". Its multi-template support, automatic dependency mapping, comprehensive error handling, and event forwarding mechanism make it well-suited for teaching, demonstration, and low-trust content preview scenarios. + +## Appendix: Quick Start and Basic Usage + +- **Use Cases** + - Online React demo showcase + - Instant HTML page preview + - Forwarding custom events from iframe to Python + - Visual feedback for compile/render errors +- **Quick Start Steps** + - Prepare files: Provide file content as a dictionary, specifying the entry file (or use the default entry). + - Choose a template: Set `template` to `'react'` or `'html'`. + - Add dependencies: Provide importmap mappings (e.g., React ecosystem) via `imports`. + - Render the component: Configure height, theme mode, and error handling strategy. +- **Basic Example References** + - React example: [react.py:1-171](file://docs/components/pro/web_sandbox/demos/react.py#L1-L171) + - HTML example: [html.py:1-113](file://docs/components/pro/web_sandbox/demos/html.py#L1-L113) + - Error handling example: [error_handling.py:1-29](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L29) + - Custom event example: [custom_sandbox_event.py:1-27](file://docs/components/pro/web_sandbox/demos/custom_sandbox_event.py#L1-L27) + +Section Sources + +- [README.md (WebSandbox Docs):1-70](file://docs/components/pro/web_sandbox/README.md#L1-L70) +- [react.py (Example):1-171](file://docs/components/pro/web_sandbox/demos/react.py#L1-L171) +- [html.py (Example):1-113](file://docs/components/pro/web_sandbox/demos/html.py#L1-L113) +- [error_handling.py (Example):1-29](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L29) +- [custom_sandbox_event.py (Example):1-27](file://docs/components/pro/web_sandbox/demos/custom_sandbox_event.py#L1-L27) diff --git a/.wiki/en/Pro Components/WebSandbox/Configuration Options.md b/.wiki/en/Pro Components/WebSandbox/Configuration Options.md new file mode 100644 index 00000000..321e5b03 --- /dev/null +++ b/.wiki/en/Pro Components/WebSandbox/Configuration Options.md @@ -0,0 +1,381 @@ +# Configuration Options + + +**Files Referenced in This Document** +- [web_sandbox.tsx](file://frontend/pro/web-sandbox/web-sandbox.tsx) +- [parser.ts](file://frontend/pro/web-sandbox/parser.ts) +- [utils.ts](file://frontend/pro/web-sandbox/utils.ts) +- [react-iframe-template.html](file://frontend/pro/web-sandbox/react-iframe-template.html) +- [html-iframe-event-listener.js](file://frontend/pro/web-sandbox/html-iframe-event-listener.js) +- [__init__.py (Backend Component)](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py) +- [README (English)](file://docs/components/pro/web_sandbox/README.md) +- [README (Chinese)](file://docs/components/pro/web_sandbox/README-zh_CN.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is intended for users and maintainers of the WebSandbox component. It systematically covers configuration parameters and behaviors, including the purpose, default values, and applicable scenarios of key parameters such as `template`, `show_render_error`, `show_compile_error`, `imports`, and `height`. It also provides typical configuration examples, best practices, and solutions to common issues to help readers quickly understand and correctly use the component. + +## Project Structure + +WebSandbox consists of three parts: "backend component definition + frontend rendering implementation + sandbox parsing and bundling tools": + +- **Backend component**: Receives parameters from the Python layer, exposes events and slots, and determines the frontend resource directory. +- **Frontend component**: Builds the importmap, parses files, generates Blob URLs, injects them into the iframe, and handles errors and events. +- **Tools and templates**: The parser handles dependency graph construction, topological sorting, and code transformation; templates and event listener scripts manage iframe lifecycle and error reporting. + +```mermaid +graph TB +Backend["Backend Component
__init__.py"] --> Frontend["Frontend Component
web-sandbox.tsx"] +Frontend --> Parser["Parser
parser.ts"] +Frontend --> Utils["Utilities
utils.ts"] +Frontend --> Template["React Template
react-iframe-template.html"] +Frontend --> HtmlListener["HTML Event Listener Script
html-iframe-event-listener.js"] +``` + +**Diagram Sources** + +- [**init**.py (Backend Component):15-73](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L73) +- [web_sandbox.tsx:37-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L365) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +**Section Sources** + +- [**init**.py (Backend Component):15-73](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L73) +- [web_sandbox.tsx:37-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L365) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## Core Components + +- **Backend component class**: Defines the component's constructor parameters, event bindings, and frontend resource directory mapping. +- **Frontend component**: Receives props, builds importmap, parses files and generates iframe content, handles compile and render errors, and dispatches events. +- **Parser**: Builds a dependency graph from input files, performs topological sorting followed by code transformation, and generates Blob URLs and stylesheet links. +- **Utilities**: Provides default entry file lists, path normalization, template rendering, and entry file selection helpers. +- **Templates and event listeners**: Inject importmap and styles into the React template; listen for load completion and error events and report them via postMessage. + +**Section Sources** + +- [**init**.py (Backend Component):15-73](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L73) +- [web_sandbox.tsx:37-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L365) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:20-83](file://frontend/pro/web-sandbox/utils.ts#L20-L83) +- [react-iframe-template.html:7-42](file://frontend/pro/web-sandbox/react-iframe-template.html#L7-L42) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## Architecture Overview + +The diagram below shows the overall flow from backend to frontend to iframe: backend passes parameters → frontend builds importmap and parses files → generates iframe content → main window listens for messages and handles error and success events. + +```mermaid +sequenceDiagram +participant Py as "Python Backend" +participant FE as "Frontend Component web-sandbox.tsx" +participant PR as "Parser parser.ts" +participant IF as "iframe" +participant TH as "Theme/Events" +Py->>FE : Pass parameters value/template/imports/... +FE->>PR : Parse files and build dependency graph +PR-->>FE : Return entry URL, stylesheet URLs, cleanup function +FE->>IF : Inject importmap/styles/entry script +IF->>TH : Send sandbox-ready after load completes +FE-->>Py : Trigger compile_success event +IF->>FE : Send sandbox-error (render error) +FE-->>Py : Trigger render_error event +``` + +**Diagram Sources** + +- [web_sandbox.tsx:79-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L79-L218) +- [parser.ts:285-312](file://frontend/pro/web-sandbox/parser.ts#L285-L312) +- [react-iframe-template.html:16-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L16-L40) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## Detailed Component Analysis + +### Parameter Overview and Defaults + +- **template** + - Type: `'react'` | `'html'` + - Default: `'react'` + - Purpose: Determines the rendering template type, affecting the default entry file and automatically injected React dependencies. + - Use case: Previewing React or HTML code. +- **show_render_error** + - Type: `bool` + - Default: `True` + - Purpose: Whether to display a notification and trigger an event callback when a render-time error occurs. + - Use case: Show runtime errors explicitly during development and debugging. +- **show_compile_error** + - Type: `bool` + - Default: `True` + - Purpose: Whether to display an error UI when compilation fails (can be replaced with a custom slot or function). + - Use case: Directly display compile error messages in the UI. +- **compile_error_render** + - Type: `str | None` + - Default: `None` + - Purpose: A JavaScript function string for customizing the compile failure rendering logic. + - Use case: Need more refined error display or theme-consistent styling. +- **imports** + - Type: `Dict[str, str] | None` + - Default: `None` + - Purpose: Corresponds to the `imports` field of importmap, used for adding online dependencies. When `template='react'`, React-related dependencies are automatically injected. + - Use case: Importing third-party libraries, CDN resources, or overriding the default React version. +- **height** + - Type: `str | float | int` + - Default: `400` + - Purpose: Component height; a number represents pixels, a string represents a CSS unit. + - Use case: Adapting to different layouts and responsive requirements. + +**Section Sources** + +- [README (English):38-46](file://docs/components/pro/web_sandbox/README.md#L38-L46) +- [README (Chinese):38-46](file://docs/components/pro/web_sandbox/README-zh_CN.md#L38-L46) +- [web_sandbox.tsx:21-35](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L35) +- [**init**.py (Backend Component):37-67](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L37-L67) + +### Parameter Details and Behavior + +#### template + +- **Impact points**: + - Default entry file: When `template='react'`, the default entry is `index.tsx/index.jsx/index.ts/index.js`; when `template='html'`, the default entry is `index.html`. + - Automatic React dependency injection: When `template='react'` and `imports` does not override, CDN mappings for `react` and `react-dom` are automatically added. +- **Typical usage**: + - Preview a React app: `template='react'`, provide the entry file (e.g., `index.tsx`). + - Preview static HTML: `template='html'`, provide `index.html`. +- **Notes**: + - If multiple candidate entry files are provided, use the `is_entry` flag to explicitly mark the main entry. + +**Section Sources** + +- [utils.ts:20-26](file://frontend/pro/web-sandbox/utils.ts#L20-L26) +- [utils.ts:48-75](file://frontend/pro/web-sandbox/utils.ts#L48-L75) +- [web_sandbox.tsx:80-92](file://frontend/pro/web-sandbox/web-sandbox.tsx#L80-L92) + +#### show_render_error + +- **Behavior**: + - When a render error occurs inside the iframe (captured by `window.error` or the HTML event listener), if enabled, a notification is displayed and the `render_error` event is triggered. +- **Recommendations**: + - Keep it `True` during development for quick problem identification. + - Can be disabled in production based on business policy to avoid exposing low-level errors to users. + +**Section Sources** + +- [web_sandbox.tsx:262-281](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L281) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +#### show_compile_error + +- **Behavior**: + - When compilation fails (parser throws an error or entry is missing), if enabled, an error UI is displayed; otherwise, no error interface is shown. + - Can be combined with `compile_error_render` or the `compileErrorRender` slot for custom display. +- **Recommendations**: + - Recommended to enable when there are many frontend errors so users can intuitively perceive problems. + +**Section Sources** + +- [web_sandbox.tsx:317-342](file://frontend/pro/web-sandbox/web-sandbox.tsx#L317-L342) +- [web_sandbox.tsx:203-217](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L217) + +#### compile_error_render + +- **Behavior**: + - Accepts a JavaScript function string to customize compile failure rendering. + - Can also be provided as a React node via the `compileErrorRender` slot. +- **Recommendations**: + - Use theme-consistent error styling, or add interactive elements like retry buttons or copy error info. + +**Section Sources** + +- [web_sandbox.tsx:317-342](file://frontend/pro/web-sandbox/web-sandbox.tsx#L317-L342) +- [**init**.py (Backend Component):35-35](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L35-L35) + +#### imports + +- **Behavior**: + - Used as `importmap.imports`. When `template='react'`, built-in React mappings are merged first, then user-provided `imports` are layered on top. + - Supports overriding the default React version or adding other dependencies. +- **Recommendations**: + - Prefer stable CDNs; ensure cross-origin accessibility. + - For local dependencies, consider bundling strategies or Blob URL approaches. + +**Section Sources** + +- [web_sandbox.tsx:80-92](file://frontend/pro/web-sandbox/web-sandbox.tsx#L80-L92) +- [README (English):45-45](file://docs/components/pro/web_sandbox/README.md#L45-L45) +- [README (Chinese):45-45](file://docs/components/pro/web_sandbox/README-zh_CN.md#L45-L45) + +#### height + +- **Behavior**: + - Number: interpreted in pixels; string: parsed as CSS units. +- **Recommendations**: + - Maintain consistent unit style within the container layout; works more flexibly with CSS Grid/Flex. + +**Section Sources** + +- [web_sandbox.tsx:312-315](file://frontend/pro/web-sandbox/web-sandbox.tsx#L312-L315) +- [README (English):46-46](file://docs/components/pro/web_sandbox/README.md#L46-L46) +- [README (Chinese):46-46](file://docs/components/pro/web_sandbox/README-zh_CN.md#L46-L46) + +### Typical Configuration Combinations + +- **Preview a React app (default)** + - `template='react'`, `imports` empty or only overriding the React version, `value` provides the entry file. +- **Preview an HTML page** + - `template='html'`, `value` provides `index.html`, inline scripts in HTML if necessary. +- **Custom error display** + - `show_compile_error=True`, `compile_error_render` provides a function string or use the `compileErrorRender` slot. +- **Adaptive height** + - `height='100%'` or a specific pixel value, combined with parent container layout. + +**Section Sources** + +- [README (English):7-18](file://docs/components/pro/web_sandbox/README.md#L7-L18) +- [README (Chinese):7-18](file://docs/components/pro/web_sandbox/README-zh_CN.md#L7-L18) +- [web_sandbox.tsx:317-342](file://frontend/pro/web-sandbox/web-sandbox.tsx#L317-L342) + +## Dependency Analysis + +- The frontend component depends on the parser and utilities; the parser internally uses Babel Standalone for code transformation and dependency analysis. +- Templates and event listener scripts are injected into the iframe, managing lifecycle and error reporting. +- The backend component defines events and slots; the frontend component binds and triggers them at runtime. + +```mermaid +classDiagram +class WebSandboxProps { ++value ++imports ++showRenderError ++showCompileError ++template ++onCompileError ++onCompileSuccess ++onRenderError ++onCustom ++height ++themeMode ++compileErrorRender +} +class WebSandbox { ++useEffect() ++useMemo() ++useState() ++iframeRef ++divRef +} +class WebSandboxParser { ++_normalizeFiles() ++_buildDependencyGraph() ++_topologicalSort() ++_transform() ++parse() +} +class Utils { ++getEntryFile() ++getFileCode() ++renderHtmlTemplate() ++normalizePath() +} +WebSandbox --> WebSandboxParser : "calls" +WebSandbox --> Utils : "uses" +WebSandboxParser --> Utils : "uses" +``` + +**Diagram Sources** + +- [web_sandbox.tsx:21-35](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L35) +- [web_sandbox.tsx:37-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L365) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) + +**Section Sources** + +- [web_sandbox.tsx:37-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L365) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) + +## Performance Considerations + +- **Compilation and transformation** + - The parser performs transformation and dependency analysis on each JS/CSS file; the number and size of files directly affect compile time. + - Recommendation: Reduce unnecessary dependencies, split entry files, and avoid circular dependencies. +- **Blob URLs and memory** + - Transformed code and styles generate Blob URLs that are reclaimed when the component unmounts; still monitor memory usage with large numbers of files. +- **iframe rendering** + - The React template injects importmap and entry modules; initial loading may be affected by network and CDN performance. +- **Theme and events** + - Theme switching is passed via postMessage to avoid frequent redraws; error notifications only appear when the relevant switch is enabled. + +[This section contains general performance recommendations with no specific file references] + +## Troubleshooting Guide + +- **Compilation failure** + - Symptom: UI displays a compile error or triggers the `compile_error` event. + - Diagnosis points: + - Check whether there is a valid entry file in `value` (default filename for the template type or an `is_entry` marker). + - Check whether dependencies in `imports` are accessible and match the template type. + - Check whether the error message contains specific files and error stack traces. +- **Render error** + - Symptom: An error is thrown inside the iframe; the main window shows a notification and triggers the `render_error` event. + - Diagnosis points: + - Disable `show_render_error` and observe if the error still occurs, to determine if the error is caused by the UI display. + - Check that importmap and styles are correctly injected into the template. +- **Circular dependency** + - Symptom: The parser throws a circular dependency error. + - Diagnosis points: + - Inspect inter-file import relationships; split or abstract common modules. +- **Height issue** + - Symptom: Content is clipped or scrollbar behavior is abnormal. + - Diagnosis points: + - Confirm that the `height` input format (number vs. CSS unit string) is consistent with the parent container dimensions. + +**Section Sources** + +- [web_sandbox.tsx:203-217](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L217) +- [web_sandbox.tsx:262-281](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L281) +- [parser.ts:128-174](file://frontend/pro/web-sandbox/parser.ts#L128-L174) +- [react-iframe-template.html:7-12](file://frontend/pro/web-sandbox/react-iframe-template.html#L7-L12) + +## Conclusion + +WebSandbox provides a safe and controlled sandbox preview capability for React and HTML code through a clear parameter system and comprehensive error handling mechanism. Properly configuring `template`, `imports`, `show_*` toggles, and `height` can meet the needs of various scenarios from development debugging to production display. For complex projects, it is recommended to standardize dependency and entry file naming first, and combine custom error display to improve observability and user experience. + +[This section is a summary with no specific file references] + +## Appendix + +### API Reference (Parameters, Events, Slots) + +- **Parameters** + - `value`: File collection; `template`: `'react'|'html'`; `imports`: importmap.imports; `show_render_error`/`show_compile_error`: Boolean toggles; `compile_error_render`: JS function string; `height`: height. +- **Events** + - `compile_success`, `compile_error`, `render_error`, `custom`. +- **Slots** + - `compileErrorRender`. + +**Section Sources** + +- [README (English):38-61](file://docs/components/pro/web_sandbox/README.md#L38-L61) +- [README (Chinese):38-70](file://docs/components/pro/web_sandbox/README-zh_CN.md#L38-L70) +- [**init**.py (Backend Component):19-35](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L19-L35) diff --git a/.wiki/en/Pro Components/WebSandbox/Event Handling.md b/.wiki/en/Pro Components/WebSandbox/Event Handling.md new file mode 100644 index 00000000..27d8dee9 --- /dev/null +++ b/.wiki/en/Pro Components/WebSandbox/Event Handling.md @@ -0,0 +1,300 @@ +# Event Handling + + +**Files Referenced in This Document** +- [web-sandbox.tsx](file://frontend/pro/web-sandbox/web-sandbox.tsx) +- [html-iframe-event-listener.js](file://frontend/pro/web-sandbox/html-iframe-event-listener.js) +- [react-iframe-template.html](file://frontend/pro/web-sandbox/react-iframe-template.html) +- [parser.ts](file://frontend/pro/web-sandbox/parser.ts) +- [utils.ts](file://frontend/pro/web-sandbox/utils.ts) +- [README.md](file://docs/components/pro/web_sandbox/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) + +## Introduction + +This chapter is intended for developers using the WebSandbox component. It systematically explains the event types supported by the component, when they are triggered, callback parameters, and usage patterns. It also analyzes the relationship between events and the sandbox security mechanism based on the source code, and provides reference paths, debugging tips, and troubleshooting guidance to help quickly identify issues and achieve stable integration. + +## Project Structure + +WebSandbox resides in the frontend `pro` component directory. Its core consists of the following files: + +- Component implementation: web-sandbox.tsx +- Sandbox iframe event listener script: html-iframe-event-listener.js +- React template (iframe content): react-iframe-template.html +- File parsing and bundling: parser.ts +- Utility functions: utils.ts +- Documentation and examples: docs/components/pro/web_sandbox/README.md + +```mermaid +graph TB +A["WebSandbox Component
web-sandbox.tsx"] --> B["Event Listener Script
html-iframe-event-listener.js"] +A --> C["React Template
react-iframe-template.html"] +A --> D["Parser
parser.ts"] +A --> E["Utility Functions
utils.ts"] +B --> F["iframe Window
window.onerror / DOMContentLoaded"] +C --> F +D --> A +E --> A +``` + +Diagram Sources + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) + +Section Sources + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [README.md:1-70](file://docs/components/pro/web_sandbox/README.md#L1-L70) + +## Core Components + +WebSandbox is a sandbox component that renders React or HTML code inside an iframe on the page. It is responsible for: + +- Parsing the incoming file set, building a dependency graph, and performing transformation +- Generating styles and entry resources, injecting them into the iframe +- Passing events between the host and iframe via postMessage +- Exposing event callbacks for the compile and render phases to the caller + +Section Sources + +- [web-sandbox.tsx:21-35](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L35) +- [web-sandbox.tsx:79-92](file://frontend/pro/web-sandbox/web-sandbox.tsx#L79-L92) +- [web-sandbox.tsx:284-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L284-L297) + +## Architecture Overview + +WebSandbox's event flow originates from inside the iframe, is forwarded via window event listeners as postMessage, and is then received by the host listening to window messages and dispatched to corresponding callbacks. + +```mermaid +sequenceDiagram +participant Host as "Host Application
web-sandbox.tsx" +participant Iframe as "iframe Content
react-iframe-template.html / html-iframe-event-listener.js" +participant Parser as "Parser
parser.ts" +Host->>Parser : "Parse files / Build dependency graph / Transform code" +Parser-->>Host : "Return entry URL / style URL / cleanup function" +Host->>Iframe : "Set iframe content (React template or HTML)" +Iframe->>Iframe : "window.addEventListener('DOMContentLoaded')" +Iframe-->>Host : "postMessage({type: 'sandbox-ready'})" +Host->>Host : "onCompileSuccessMemoized()" +Host->>Host : "setLoading(false)" +Iframe->>Iframe : "window.addEventListener('error')" +Iframe-->>Host : "postMessage({type: 'sandbox-error', message})" +Note over Host,Iframe : "Event listening and callbacks are handled uniformly on the host side" +``` + +Diagram Sources + +- [web-sandbox.tsx:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- [react-iframe-template.html:17-28](file://frontend/pro/web-sandbox/react-iframe-template.html#L17-L28) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## Detailed Component Analysis + +### Event Types and Trigger Timing + +- **compile_success** (Compilation Success) + - Trigger: After `DOMContentLoaded` fires inside the iframe, a `sandbox-ready` message is sent to the parent window; the host calls the `onCompileSuccess` callback upon receiving the message. + - Callback parameters: None + - Usage: Register an `onCompileSuccess` callback on WebSandbox to execute subsequent logic when the sandbox is ready (e.g., hiding loading state, enabling interactions). + - Reference paths: + - [web-sandbox.tsx:277-279](file://frontend/pro/web-sandbox/web-sandbox.tsx#L277-L279) + - [react-iframe-template.html:24-28](file://frontend/pro/web-sandbox/react-iframe-template.html#L24-L28) + +- **compile_error** (Compilation Error) + - Trigger: When an exception occurs during parsing and transformation, the component catches it and calls the `onCompileError` callback; the error message is also saved to local state and can be combined with `showCompileError` and `compileErrorRender` to control error display. + - Callback parameters: `message` (string) + - Usage: Register an `onCompileError` callback on WebSandbox for logging, reporting, or guiding users to fix their code. + - Reference paths: + - [web-sandbox.tsx:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218) + - [parser.ts:285-312](file://frontend/pro/web-sandbox/parser.ts#L285-L312) + +- **render_error** (Render Error) + - Trigger: When a runtime error occurs inside the iframe (`window.onerror`), a `sandbox-error` message is sent to the parent window; the host calls the `onRenderError` callback and decides whether to show a notification based on `showRenderError`. + - Callback parameters: `message` (string) + - Usage: Register an `onRenderError` callback on WebSandbox to catch render-time exceptions and perform fallback handling. + - Reference paths: + - [web-sandbox.tsx:267-276](file://frontend/pro/web-sandbox/web-sandbox.tsx#L267-L276) + - [html-iframe-event-listener.js:1-6](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L6) + - [react-iframe-template.html:17-22](file://frontend/pro/web-sandbox/react-iframe-template.html#L17-L22) + +- **custom** (Custom Event) + - Trigger: The host injects a `dispatch` function into the iframe's `window`; code inside the iframe can actively dispatch custom events to the host via `window.dispatch(...args)`; the host calls the `onCustom` callback upon receiving the message. + - Callback parameters: `...args` (any parameter sequence) + - Usage: Register an `onCustom` callback on WebSandbox to receive custom business events from inside the iframe (e.g., clicks, state changes). + - Reference paths: + - [web-sandbox.tsx:249-256](file://frontend/pro/web-sandbox/web-sandbox.tsx#L249-L256) + - [web-sandbox.tsx:299-306](file://frontend/pro/web-sandbox/web-sandbox.tsx#L299-L306) + +Section Sources + +- [web-sandbox.tsx:262-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L297) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [react-iframe-template.html:17-28](file://frontend/pro/web-sandbox/react-iframe-template.html#L17-L28) +- [README.md:48-56](file://docs/components/pro/web_sandbox/README.md#L48-L56) + +### Event Listening and Handling Flow + +```mermaid +flowchart TD +Start(["Start"]) --> Parse["Parse files / Build dependency graph / Transform code"] +Parse --> BuildIframe["Generate iframe content (React template or HTML)"] +BuildIframe --> Ready["iframe DOMContentLoaded"] +Ready --> PostReady["postMessage({type:'sandbox-ready'})"] +PostReady --> OnSuccess["Call onCompileSuccess()"] +BuildIframe --> Error["Runtime error occurs inside iframe"] +Error --> PostErr["postMessage({type:'sandbox-error', message})"] +PostErr --> OnRenderError["Call onRenderError(message)"] +BuildIframe --> Custom["iframe calls window.dispatch(...)"] +Custom --> OnCustom["Call onCustom(...args)"] +OnSuccess --> End(["End"]) +OnRenderError --> End +OnCustom --> End +``` + +Diagram Sources + +- [web-sandbox.tsx:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- [react-iframe-template.html:24-28](file://frontend/pro/web-sandbox/react-iframe-template.html#L24-L28) +- [html-iframe-event-listener.js:1-6](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L6) + +### Relationship Between Events and Sandbox Security Mechanism + +- **Same-origin policy and postMessage**: The iframe and host communicate via postMessage, avoiding direct cross-origin access and reducing XSS risks. +- **Only necessary interfaces exposed**: The host injects `dispatch` into the iframe's `window`, allowing the iframe to actively report events, but it cannot directly access the host's DOM or global objects. +- **Error isolation**: Errors inside the iframe are captured via `window.onerror` and reported without disrupting the host runtime environment. +- **Theme injection**: The host injects the theme mode via postMessage; the iframe can only read this read-only information and cannot tamper with the host context. +- Reference paths: + - [web-sandbox.tsx:249-261](file://frontend/pro/web-sandbox/web-sandbox.tsx#L249-L261) + - [html-iframe-event-listener.js:1-6](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L6) + - [react-iframe-template.html:17-22](file://frontend/pro/web-sandbox/react-iframe-template.html#L17-L22) + +Section Sources + +- [web-sandbox.tsx:249-261](file://frontend/pro/web-sandbox/web-sandbox.tsx#L249-L261) +- [html-iframe-event-listener.js:1-6](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L6) +- [react-iframe-template.html:17-22](file://frontend/pro/web-sandbox/react-iframe-template.html#L17-L22) + +### Complete Examples of Event Listening and Handling (Reference Paths) + +- React template example (HTML/JSX/TSX entry files) + - [react-iframe-template.html:30-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L30-L40) +- Compile error handling (`onCompileError`) + - [web-sandbox.tsx:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218) +- Render error handling (`onRenderError`) + - [web-sandbox.tsx:267-276](file://frontend/pro/web-sandbox/web-sandbox.tsx#L267-L276) +- Compile success handling (`onCompileSuccess`) + - [web-sandbox.tsx:277-279](file://frontend/pro/web-sandbox/web-sandbox.tsx#L277-L279) +- Custom event handling (`onCustom`) + - [web-sandbox.tsx:249-256](file://frontend/pro/web-sandbox/web-sandbox.tsx#L249-L256) + +Section Sources + +- [react-iframe-template.html:30-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L30-L40) +- [web-sandbox.tsx:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218) +- [web-sandbox.tsx:267-276](file://frontend/pro/web-sandbox/web-sandbox.tsx#L267-L276) +- [web-sandbox.tsx:277-279](file://frontend/pro/web-sandbox/web-sandbox.tsx#L277-L279) +- [web-sandbox.tsx:249-256](file://frontend/pro/web-sandbox/web-sandbox.tsx#L249-L256) + +## Dependency Analysis + +- **Component and template/script coupling** + - WebSandbox injects importmap, styles, and entry modules via `react-iframe-template.html`; it uses `html-iframe-event-listener.js` to uniformly forward error and ready events. +- **Parser and utility functions** + - `parser.ts` handles dependency analysis, transformation, and resource generation; `utils.ts` provides path normalization, entry file selection, and other helpers. +- **Event source and destination** + - Event source: `window.onerror` and `DOMContentLoaded` inside the iframe; `dispatch` calls from inside the iframe + - Event destination: Host window message listener dispatches to `onCompileSuccess` / `onCompileError` / `onRenderError` / `onCustom` + +```mermaid +graph LR +WS["WebSandbox
web-sandbox.tsx"] --> RT["React Template
react-iframe-template.html"] +WS --> EL["Event Listener Script
html-iframe-event-listener.js"] +WS --> PR["Parser
parser.ts"] +PR --> UT["Utility Functions
utils.ts"] +EL --> WS +RT --> WS +``` + +Diagram Sources + +- [web-sandbox.tsx:1-20](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L20) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) + +Section Sources + +- [web-sandbox.tsx:1-20](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L20) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) + +## Performance Considerations + +- **Resource release**: Blob URLs generated by the parser are reclaimed uniformly in the cleanup function to prevent memory leaks. + - Reference path: [parser.ts:306-311](file://frontend/pro/web-sandbox/parser.ts#L306-L311) +- **Loading state control**: Close the loading state promptly after successful compilation to improve user experience. + - Reference path: [web-sandbox.tsx:277-279](file://frontend/pro/web-sandbox/web-sandbox.tsx#L277-L279) +- **Event listener deduplication**: The component rebinds the window message listener when `iframeUrl` updates, ensuring no duplicate bindings that could cause performance issues. + - Reference path: [web-sandbox.tsx:284-288](file://frontend/pro/web-sandbox/web-sandbox.tsx#L284-L288) + +## Troubleshooting Guide + +- **Compile error (compile_error)** + - Symptom: Component displays an error area or triggers the `onCompileError` callback + - Diagnosis: + - Check whether the entry file is correct (default entry for `template='react'` is `index.*`; for `html` it's `index.html`) + - Reference path: [utils.ts:48-75](file://frontend/pro/web-sandbox/utils.ts#L48-L75) + - Check whether third-party dependency mappings (`imports`) are correct + - Reference path: [web-sandbox.tsx:79-92](file://frontend/pro/web-sandbox/web-sandbox.tsx#L79-L92) + - Check the error stack thrown by the parser (circular dependencies, syntax errors, etc.) + - Reference path: [parser.ts:166-170](file://frontend/pro/web-sandbox/parser.ts#L166-L170), [parser.ts:292-298](file://frontend/pro/web-sandbox/parser.ts#L292-L298) +- **Render error (render_error)** + - Symptom: Runtime error inside the iframe triggers the `onRenderError` callback + - Diagnosis: + - Confirm that the entry module exported by the template is a function (React component) + - Reference path: [react-iframe-template.html:35-39](file://frontend/pro/web-sandbox/react-iframe-template.html#L35-L39) + - Check whether styles and importmap are correctly injected + - Reference path: [react-iframe-template.html:7-12](file://frontend/pro/web-sandbox/react-iframe-template.html#L7-L12) +- **Custom event (custom)** + - Symptom: Code inside the iframe actively reports an event via `window.dispatch(...)`, triggering the `onCustom` callback on the host + - Diagnosis: + - Confirm that the host has injected `dispatch` into the iframe's `window` + - Reference path: [web-sandbox.tsx:249-256](file://frontend/pro/web-sandbox/web-sandbox.tsx#L249-L256) +- **Event not triggered** + - Symptom: Compile success or render error events are not called back + - Diagnosis: + - Confirm that the event listener script is correctly injected inside the iframe + - Reference path: [react-iframe-template.html:17-28](file://frontend/pro/web-sandbox/react-iframe-template.html#L17-L28), [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + - Confirm that the host window message listener is correctly bound and unbound + - Reference path: [web-sandbox.tsx:284-288](file://frontend/pro/web-sandbox/web-sandbox.tsx#L284-L288) + +Section Sources + +- [utils.ts:48-75](file://frontend/pro/web-sandbox/utils.ts#L48-L75) +- [parser.ts:166-170](file://frontend/pro/web-sandbox/parser.ts#L166-L170) +- [parser.ts:292-298](file://frontend/pro/web-sandbox/parser.ts#L292-L298) +- [react-iframe-template.html:35-39](file://frontend/pro/web-sandbox/react-iframe-template.html#L35-L39) +- [react-iframe-template.html:7-12](file://frontend/pro/web-sandbox/react-iframe-template.html#L7-L12) +- [web-sandbox.tsx:249-256](file://frontend/pro/web-sandbox/web-sandbox.tsx#L249-L256) +- [web-sandbox.tsx:284-288](file://frontend/pro/web-sandbox/web-sandbox.tsx#L284-L288) + +## Conclusion + +WebSandbox provides controllable, observable, and easily extensible capabilities for frontend code preview through a standardized event model (`compile_success`, `compile_error`, `render_error`, `custom`) and iframe security boundaries. By making proper use of event callbacks and error handling mechanisms, rich interactive and debugging experiences can be achieved while maintaining security. diff --git a/.wiki/en/Pro Components/WebSandbox/Integration Examples.md b/.wiki/en/Pro Components/WebSandbox/Integration Examples.md new file mode 100644 index 00000000..369ba937 --- /dev/null +++ b/.wiki/en/Pro Components/WebSandbox/Integration Examples.md @@ -0,0 +1,309 @@ +# Integration Examples + + +**Files Referenced in This Document** +- [web-sandbox.tsx](file://frontend/pro/web-sandbox/web-sandbox.tsx) +- [Index.svelte](file://frontend/pro/web-sandbox/Index.svelte) +- [parser.ts](file://frontend/pro/web-sandbox/parser.ts) +- [utils.ts](file://frontend/pro/web-sandbox/utils.ts) +- [react-iframe-template.html](file://frontend/pro/web-sandbox/react-iframe-template.html) +- [README-zh_CN.md](file://docs/components/pro/web_sandbox/README-zh_CN.md) +- [__init__.py](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is intended for developers and systematically introduces the usage and best practices of the WebSandbox component, covering: + +- HTML rendering examples and considerations +- React component rendering examples and template type selection +- Error handling and event communication +- Complex scenarios: dynamic content rendering, event communication, and style customization +- A progressive example path from simple to complex +- Complete runnable example descriptions (provided as "code snippet paths") + +The goal is to help you quickly get started and correctly use the component without having to read the source code directly. + +## Project Structure + +WebSandbox consists of three parts: + +- **Frontend Svelte wrapper layer**: Responsible for property forwarding, slot rendering, and theme injection +- **Core React component**: Responsible for file parsing, dependency graph construction, compilation, and iframe rendering +- **Parser and utilities**: Responsible for file normalization, dependency analysis, transformation, and resource cleanup + +```mermaid +graph TB +A["Index.svelte
Property forwarding/slots/theme"] --> B["web-sandbox.tsx
Core logic/compilation/message listening"] +B --> C["parser.ts
Dependency graph/topological sort/transformation"] +B --> D["utils.ts
Entry location/path normalization/template rendering"] +B --> E["react-iframe-template.html
iframe template"] +``` + +Diagram Sources + +- [Index.svelte:1-75](file://frontend/pro/web-sandbox/Index.svelte#L1-L75) +- [web-sandbox.tsx:37-363](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L363) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:28-83](file://frontend/pro/web-sandbox/utils.ts#L28-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) + +Section Sources + +- [Index.svelte:1-75](file://frontend/pro/web-sandbox/Index.svelte#L1-L75) +- [web-sandbox.tsx:37-363](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L363) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:28-83](file://frontend/pro/web-sandbox/utils.ts#L28-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) + +## Core Components + +- **Component name**: WebSandbox +- **Supported template types**: react, html +- **Key capabilities**: + - Takes a set of frontend files (JS/TS/JSX/TSX/HTML/CSS) as input and generates runnable iframe content + - Automatically injects importmap, supporting third-party dependencies and style resources + - Provides compile/render event callbacks and error display + - Supports custom error render slots and functions + - Theme mode forwarding and event communication bridging + +Section Sources + +- [web-sandbox.tsx:21-35](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L35) +- [README-zh_CN.md:34-70](file://docs/components/pro/web_sandbox/README-zh_CN.md#L34-L70) + +## Architecture Overview + +WebSandbox's workflow is divided into two major phases: "file parsing and compilation" and "iframe rendering and event communication". + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Wrap as "Index.svelte" +participant Core as "web-sandbox.tsx" +participant Parser as "parser.ts" +participant Utils as "utils.ts" +participant Iframe as "react-iframe-template.html" +Dev->>Wrap : Pass props/value/template/imports +Wrap->>Core : Forward properties/slots/theme +Core->>Utils : Get entry file / normalize path +Core->>Parser : Parse files / Build dependency graph / Topological sort +Parser-->>Core : Return entryUrl/styleSheetUrls/cleanup +Core->>Iframe : Render iframe template (with importmap/styles/entry) +Core-->>Dev : Trigger compile_success/compile_error +Iframe-->>Core : sandbox-ready/sandbox-error +Core-->>Dev : Trigger render_error/custom +``` + +Diagram Sources + +- [Index.svelte:12-75](file://frontend/pro/web-sandbox/Index.svelte#L12-L75) +- [web-sandbox.tsx:94-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L94-L218) +- [parser.ts:285-312](file://frontend/pro/web-sandbox/parser.ts#L285-L312) +- [utils.ts:48-75](file://frontend/pro/web-sandbox/utils.ts#L48-L75) +- [react-iframe-template.html:7-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L7-L40) + +## Detailed Component Analysis + +### HTML Rendering Example + +- **Applicable scenario**: Directly render an HTML page, supporting inline scripts and stylesheets +- **Key points**: + - `template` must be set to `html` + - Default entry file is `index.html`; can also be manually specified with `is_entry` + - Inline scripts are extracted and included in compilation while preserving the original structure + - importmap and style links are automatically injected +- Example path: + - [HTML Example Placeholder:22-24](file://docs/components/pro/web_sandbox/README-zh_CN.md#L22-L24) + +Section Sources + +- [web-sandbox.tsx:110-186](file://frontend/pro/web-sandbox/web-sandbox.tsx#L110-L186) +- [utils.ts:48-75](file://frontend/pro/web-sandbox/utils.ts#L48-L75) +- [README-zh_CN.md:22-24](file://docs/components/pro/web_sandbox/README-zh_CN.md#L22-L24) + +### React Component Rendering Example + +- **Applicable scenario**: Render a single-file React component (functional or class component) +- **Key points**: + - `template` defaults to `react`; importmap for `react` and `react-dom` is automatically injected + - Default entry file is `index.(ts|tsx|js|jsx)` + - Supports TS/TSX and JSX; automatically enables React automatic runtime + - CSS imports are extracted as independent style resources +- Example path: + - [React Example Placeholder:7-18](file://docs/components/pro/web_sandbox/README-zh_CN.md#L7-L18) + +Section Sources + +- [web-sandbox.tsx:187-202](file://frontend/pro/web-sandbox/web-sandbox.tsx#L187-L202) +- [parser.ts:176-283](file://frontend/pro/web-sandbox/parser.ts#L176-L283) +- [README-zh_CN.md:7-18](file://docs/components/pro/web_sandbox/README-zh_CN.md#L7-L18) + +### Error Handling Example + +- **Compile-time errors**: File parsing/transformation exceptions, circular dependencies, missing entry files +- **Runtime errors**: `DOMContentLoaded` and global `error` events inside the iframe +- **Optional display strategies**: + - Built-in Alert error prompt + - Custom `compileErrorRender` slot or function + - Get status via event callbacks `onCompileError` / `onRenderError` / `onCompileSuccess` +- Example path: + - [Error Handling Example Placeholder:30-32](file://docs/components/pro/web_sandbox/README-zh_CN.md#L30-L32) + +Section Sources + +- [web-sandbox.tsx:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218) +- [web-sandbox.tsx:317-342](file://frontend/pro/web-sandbox/web-sandbox.tsx#L317-L342) +- [README-zh_CN.md:30-32](file://docs/components/pro/web_sandbox/README-zh_CN.md#L30-L32) + +### Event Communication Example + +- **Messages sent from the component to the outside**: + - `sandbox-ready`: Compilation complete, iframe is ready + - `sandbox-error`: Runtime error, with `message` payload +- **Events dispatched from outside to inside the component**: + - Via `window.dispatch` or custom event bridging (triggered by business code inside the iframe) +- Example path: + - [Event Communication Example Placeholder:26-28](file://docs/components/pro/web_sandbox/README-zh_CN.md#L26-L28) + +Section Sources + +- [web-sandbox.tsx:262-282](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L282) +- [react-iframe-template.html:17-28](file://frontend/pro/web-sandbox/react-iframe-template.html#L17-L28) +- [README-zh_CN.md:48-55](file://docs/components/pro/web_sandbox/README-zh_CN.md#L48-L55) + +### Style Customization and Import + +- **Third-party CSS**: Referenced via importmap mapping or `http(s)` address directly +- **Local CSS**: Extracted as independent Blob URLs and injected into the iframe +- **Custom styles**: Can inject additional `link` tags in the HTML template, or inject via the stylesheet resource list in the React template +- Example path: + - [Style Customization Example Placeholder:45-46](file://docs/components/pro/web_sandbox/README-zh_CN.md#L45-L46) + +Section Sources + +- [parser.ts:258-276](file://frontend/pro/web-sandbox/parser.ts#L258-L276) +- [web-sandbox.tsx:221-242](file://frontend/pro/web-sandbox/web-sandbox.tsx#L221-L242) + +### Complex Scenario: Dynamic Content Rendering and Event Bridging + +- **Dynamic content**: Dynamically update the file collection via `value`; the component re-parses and rebuilds the iframe +- **Event bridging**: Send custom events from inside the iframe via `window.dispatch`; the parent component receives them via `onCustom` +- **Theme synchronization**: The component injects `themeMode` into the iframe and synchronizes the theme via postMessage +- Example path: + - [Dynamic Content and Event Bridging Example Placeholder:26-28](file://docs/components/pro/web_sandbox/README-zh_CN.md#L26-L28) + +Section Sources + +- [web-sandbox.tsx:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- [Index.svelte:60-75](file://frontend/pro/web-sandbox/Index.svelte#L60-L75) + +### Best Practices + +- **Specify the entry file clearly**: Prefer the default entry; use the `is_entry` flag for custom entries +- **Control dependency size**: Split modules reasonably; avoid repeatedly importing large libraries +- **Error visibility**: In production, enable `showCompileError`/`showRenderError` and customize error rendering +- **Theme consistency**: Unify `themeMode` to ensure consistency with the host application +- **Performance optimization**: Use on-demand loading and caching for large CSS/JS files + +Section Sources + +- [utils.ts:48-75](file://frontend/pro/web-sandbox/utils.ts#L48-L75) +- [web-sandbox.tsx:317-342](file://frontend/pro/web-sandbox/web-sandbox.tsx#L317-L342) + +## Dependency Analysis + +The key dependency chain for WebSandbox is as follows: + +```mermaid +graph LR +WS["web-sandbox.tsx"] --> P["parser.ts"] +WS --> U["utils.ts"] +WS --> T["react-iframe-template.html"] +IDX["Index.svelte"] --> WS +BACK["backend/__init__.py"] --> IDX +``` + +Diagram Sources + +- [web-sandbox.tsx:1-19](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L19) +- [parser.ts:1-12](file://frontend/pro/web-sandbox/parser.ts#L1-L12) +- [utils.ts:1-1](file://frontend/pro/web-sandbox/utils.ts#L1-L1) +- [react-iframe-template.html:1-10](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L10) +- [Index.svelte:1-12](file://frontend/pro/web-sandbox/Index.svelte#L1-L12) +- [**init**.py:69-85](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L69-L85) + +Section Sources + +- [web-sandbox.tsx:1-19](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L19) +- [parser.ts:1-12](file://frontend/pro/web-sandbox/parser.ts#L1-L12) +- [utils.ts:1-1](file://frontend/pro/web-sandbox/utils.ts#L1-L1) +- [react-iframe-template.html:1-10](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L10) +- [Index.svelte:1-12](file://frontend/pro/web-sandbox/Index.svelte#L1-L12) +- [**init**.py:69-85](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L69-L85) + +## Performance Considerations + +- **File parsing and transformation**: Uses topological sorting to ensure dependency order and avoid redundant transformations +- **Blob URL management**: Transformed JS/CSS is injected uniformly as Blob URLs for easy cleanup +- **iframe lifecycle**: Actively calls `revokeObjectURL` when the component unmounts to prevent memory leaks +- **Style injection**: CSS resources are injected on demand to reduce loading of irrelevant styles +- **Theme synchronization**: Injected once via postMessage to avoid frequent redraws + +Section Sources + +- [parser.ts:129-174](file://frontend/pro/web-sandbox/parser.ts#L129-L174) +- [parser.ts:306-312](file://frontend/pro/web-sandbox/parser.ts#L306-L312) +- [web-sandbox.tsx:299-306](file://frontend/pro/web-sandbox/web-sandbox.tsx#L299-L306) + +## Troubleshooting Guide + +- **Compilation failure** + - Symptom: Built-in error prompt is displayed or `onCompileError` is triggered + - Diagnosis: Check whether the entry file exists, whether dependencies are in the importmap, and whether circular dependencies exist + - Reference path: [Compile error handling:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218) +- **Runtime failure** + - Symptom: `onRenderError` is triggered; a notification appears inside the iframe + - Diagnosis: Check iframe console errors; confirm that the entry export is a valid component + - Reference path: [Runtime error listener:262-282](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L282) +- **Event not received** + - Symptom: `onCustom` is not triggered + - Diagnosis: Confirm that `dispatch` is called inside the iframe and that theme synchronization has taken effect + - Reference path: [Theme injection and event dispatch:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- **Style not applied** + - Symptom: CSS is not loaded or there are style conflicts + - Diagnosis: Check importmap mappings; verify that relative CSS is correctly extracted as Blob URLs + - Reference path: [Style extraction and injection:258-276](file://frontend/pro/web-sandbox/parser.ts#L258-L276) + +Section Sources + +- [web-sandbox.tsx:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218) +- [web-sandbox.tsx:262-282](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L282) +- [web-sandbox.tsx:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- [parser.ts:258-276](file://frontend/pro/web-sandbox/parser.ts#L258-L276) + +## Conclusion + +WebSandbox provides complete capabilities for rendering React and HTML in a secure sandbox. Through clear file input, automated dependency analysis and transformation, and comprehensive event and error handling mechanisms, developers can quickly build dynamic preview and interactive demo scenarios. It is recommended to combine the example paths and best practices in this document to progressively expand to more complex dynamic rendering and event communication requirements. + +## Appendix + +- Component API and event reference + - [API and event descriptions:34-55](file://docs/components/pro/web_sandbox/README-zh_CN.md#L34-L55) +- Backend wrapper and frontend directory mapping + - [Backend component wrapper:69-85](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L69-L85) +- Svelte wrapper layer and property forwarding + - [Svelte wrapper layer:12-75](file://frontend/pro/web-sandbox/Index.svelte#L12-L75) diff --git a/.wiki/en/Pro Components/WebSandbox/Security Mechanism.md b/.wiki/en/Pro Components/WebSandbox/Security Mechanism.md new file mode 100644 index 00000000..491a0dfd --- /dev/null +++ b/.wiki/en/Pro Components/WebSandbox/Security Mechanism.md @@ -0,0 +1,294 @@ +# Security Mechanism + + +**Files Referenced in This Document** +- [web-sandbox.tsx](file://frontend/pro/web-sandbox/web-sandbox.tsx) +- [parser.ts](file://frontend/pro/web-sandbox/parser.ts) +- [utils.ts](file://frontend/pro/web-sandbox/utils.ts) +- [html-iframe-event-listener.js](file://frontend/pro/web-sandbox/html-iframe-event-listener.js) +- [react-iframe-template.html](file://frontend/pro/web-sandbox/react-iframe-template.html) +- [walkHtmlNodes.ts](file://frontend/utils/walkHtmlNodes.ts) +- [web-sandbox.less](file://frontend/pro/web-sandbox/web-sandbox.less) +- [package.json](file://frontend/package.json) +- [README.md (WebSandbox Docs)](file://docs/components/pro/web_sandbox/README.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance and Security Trade-offs](#performance-and-security-trade-offs) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Security Configuration and Best Practices](#appendix-security-configuration-and-best-practices) + +## Introduction + +This document focuses on the security mechanisms of the WebSandbox component, systematically explaining its browser iframe-based security isolation principles, how cross-origin and content security policies are implemented, the security implementation of event listeners and message passing, and key protections against malicious content injection and XSS. Actionable security configuration recommendations, audit checklists, and vulnerability protection guidelines are also provided. + +## Project Structure + +WebSandbox resides in the `pro` subdirectory of the frontend project. Its core consists of the following modules: + +- Component entry and render control: web-sandbox.tsx +- Sandbox parsing and bundling: parser.ts +- Utilities and templates: utils.ts, react-iframe-template.html, web-sandbox.less +- Event listener inside iframe: html-iframe-event-listener.js +- Script processing helper for HTML template mode: walkHtmlNodes.ts +- Dependency declarations: package.json +- Component documentation: docs/components/pro/web_sandbox/README.md + +```mermaid +graph TB +A["web-sandbox.tsx
Component entry and render control"] --> B["parser.ts
Dependency graph construction and transformation"] +A --> C["utils.ts
Path/template/entry resolution"] +A --> D["react-iframe-template.html
iframe template"] +A --> E["html-iframe-event-listener.js
Error and ready events inside iframe"] +A --> F["web-sandbox.less
Styles and iframe margins"] +A --> G["walkHtmlNodes.ts
HTML node traversal for script extraction"] +B --> H["@babel/standalone
Code transformation and importmap processing"] +C --> I["path-browserify-esm
Path normalization"] +``` + +Diagram Sources + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [walkHtmlNodes.ts:1-19](file://frontend/utils/walkHtmlNodes.ts#L1-L19) +- [package.json:1-59](file://frontend/package.json#L1-L59) + +Section Sources + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [walkHtmlNodes.ts:1-19](file://frontend/utils/walkHtmlNodes.ts#L1-L19) +- [package.json:1-59](file://frontend/package.json#L1-L59) +- [README.md (WebSandbox Docs):1-70](file://docs/components/pro/web_sandbox/README.md#L1-L70) + +## Core Components + +- **WebSandbox main component**: Responsible for receiving source code file sets, building importmaps, selecting template types, generating iframe content, handling compile/render errors, and communicating with the iframe via postMessage. +- **WebSandboxParser**: Performs dependency graph construction, topological sorting, Babel transformation, CSS processing, and Blob URL generation on input files; outputs the entry URL and stylesheet list; provides a cleanup function for memory reclamation. +- **Utilities**: Path normalization, default entry file identification, template rendering, HTML node traversal, etc. +- **iframe template and event listeners**: Injects importmap and styles into the template; inside the iframe, listens for error and ready events and reports them via postMessage. + +Section Sources + +- [web-sandbox.tsx:21-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L365) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:3-83](file://frontend/pro/web-sandbox/utils.ts#L3-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## Architecture Overview + +WebSandbox's security isolation is built on the browser iframe, combined with importmap, Babel transformation, Blob URLs, and the postMessage event channel to implement a "least privilege" runtime environment. + +```mermaid +sequenceDiagram +participant U as "Caller" +participant WS as "WebSandbox Component" +participant P as "WebSandboxParser" +participant IF as "iframe Content" +participant PM as "postMessage Channel" +U->>WS : Pass files and imports +WS->>P : Parse and build dependency graph / topological sort / transform +P-->>WS : Return entry URL and stylesheet list +WS->>WS : Generate iframe HTML (importmap/styles) +WS->>IF : Set src to Blob URL +IF->>PM : DOMContentLoaded -> sandbox-ready +WS->>PM : Listen for sandbox-ready +IF->>PM : error -> sandbox-error +WS->>U : Trigger compile_success/render_error events +``` + +Diagram Sources + +- [web-sandbox.tsx:94-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L94-L218) +- [parser.ts:285-312](file://frontend/pro/web-sandbox/parser.ts#L285-L312) +- [react-iframe-template.html:16-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L16-L40) +- [html-iframe-event-listener.js:1-12](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L12) + +## Detailed Component Analysis + +### Security Isolation Principles and Implementation + +- **Browser-level isolation**: By default, iframes operate in a different origin context from the parent page, with an independent execution environment and DOM, naturally blocking scripts from directly accessing parent page global objects. +- **Least privilege**: Only necessary importmap and styles are injected; no additional permissions or capabilities are granted. +- **Process boundary**: React/JS code inside the iframe executes in an isolated thread, avoiding shared state with the host's main thread. + +Section Sources + +- [web-sandbox.tsx:350-356](file://frontend/pro/web-sandbox/web-sandbox.tsx#L350-L356) +- [react-iframe-template.html:7-12](file://frontend/pro/web-sandbox/react-iframe-template.html#L7-L12) + +### iframe Security Policy and Cross-Origin Restrictions + +- **Same-origin policy**: When the iframe and parent page share the same origin, direct access is possible; for cross-origin scenarios, communication must go through postMessage. WebSandbox strictly limits message source and type, accepting only specific messages from the iframe. +- **CSP**: The component does not explicitly set CSP headers, but reduces external link risks via Blob URLs and importmap. For stronger guarantees, CSP headers can be set at the server or gateway layer. +- **Cross-site scripting**: Scripts inside the iframe cannot directly access the parent page's DOM unless the parent page explicitly exposes the iframe's `contentWindow` (WebSandbox only passes theme and custom dispatch functions, without exposing sensitive interfaces). + +Section Sources + +- [web-sandbox.tsx:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- [html-iframe-event-listener.js:1-12](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L12) +- [react-iframe-template.html:16-29](file://frontend/pro/web-sandbox/react-iframe-template.html#L16-L29) + +### Content Security Policy (CSP) and Resource Loading + +- **importmap**: Injected into the iframe to restrict the source of third-party dependencies, avoiding loading uncontrolled scripts. +- **Styles and CSS**: Relative CSS is injected via Blob URLs; external CSS only allows `http(s)` or addresses already mapped in the importmap. +- **Malicious script filtering**: In HTML template mode, the component scans and replaces inline scripts with transformed Blob URLs, avoiding direct execution of untrusted scripts. + +Section Sources + +- [react-iframe-template.html:7-12](file://frontend/pro/web-sandbox/react-iframe-template.html#L7-L12) +- [parser.ts:258-276](file://frontend/pro/web-sandbox/parser.ts#L258-L276) +- [web-sandbox.tsx:110-179](file://frontend/pro/web-sandbox/web-sandbox.tsx#L110-L179) + +### Event Listener and Message Passing Mechanism + +- **iframe ready and error reporting**: Inside the iframe, `DOMContentLoaded` and `error` events are listened to; `sandbox-ready` and `sandbox-error` messages are sent via postMessage. +- **Parent page listening**: The parent page only accepts messages from the iframe, dispatching them to corresponding callbacks (render error/compile success) based on `type`, and securely passing theme and custom dispatch functions. +- **Event source verification**: Message source is strictly limited to `iframe.contentWindow` to prevent spoofed messages. + +```mermaid +sequenceDiagram +participant Parent as "Parent Page" +participant Child as "iframe" +Parent->>Child : Set src to Blob URL +Child-->>Parent : postMessage(type="sandbox-ready") +Child-->>Parent : postMessage(type="sandbox-error", message) +Parent->>Parent : Verify e.source === iframe.contentWindow +Parent->>Parent : switch(type){case "sandbox-ready": ...} +``` + +Diagram Sources + +- [web-sandbox.tsx:262-282](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L282) +- [html-iframe-event-listener.js:1-12](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L12) +- [react-iframe-template.html:16-29](file://frontend/pro/web-sandbox/react-iframe-template.html#L16-L29) + +### Malicious Content Injection and XSS Protection + +- **Input normalization**: Paths and entry files are normalized to prevent path traversal and ambiguity. +- **Code transformation**: Babel is used to transform JS/TSX/JSX, replacing relative imports with Blob URLs and removing or transforming CSS imports, reducing the chance of directly executing untrusted scripts. +- **HTML template mode**: Inline scripts are scanned and replaced, converted to Blob URLs, and injected into the DOM, preventing direct execution of user-input scripts. +- **Error isolation**: Errors inside the iframe are reported via postMessage; the parent page only displays descriptive information without echoing raw stack traces or source code. + +Section Sources + +- [utils.ts:28-34](file://frontend/pro/web-sandbox/utils.ts#L28-L34) +- [parser.ts:176-283](file://frontend/pro/web-sandbox/parser.ts#L176-L283) +- [web-sandbox.tsx:110-179](file://frontend/pro/web-sandbox/web-sandbox.tsx#L110-L179) +- [html-iframe-event-listener.js:1-12](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L12) + +### Security-Related Third-Party Dependencies + +- **@babel/standalone**: Used for browser-side code transformation and import path replacement; a key component for secure transformation. +- **path-browserify-esm**: Used for path normalization to prevent path injection. +- **antd**: Provides notifications and loading indicators for error display and user experience. + +Section Sources + +- [package.json:8-39](file://frontend/package.json#L8-L39) +- [parser.ts:1-12](file://frontend/pro/web-sandbox/parser.ts#L1-L12) +- [utils.ts:1-8](file://frontend/pro/web-sandbox/utils.ts#L1-L8) + +## Dependency Analysis + +WebSandbox's security implementation relies on multi-module collaboration: the component layer handles control and message bridging; the parsing layer handles dependencies and code transformation; the utility layer handles path and template processing; the iframe layer handles event reporting and isolation. + +```mermaid +graph LR +WS["web-sandbox.tsx"] --> PR["parser.ts"] +WS --> UT["utils.ts"] +WS --> RT["react-iframe-template.html"] +WS --> EL["html-iframe-event-listener.js"] +PR --> BL["@babel/standalone"] +UT --> PB["path-browserify-esm"] +WS --> AN["antd (notification/loading)"] +``` + +Diagram Sources + +- [web-sandbox.tsx:1-19](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L19) +- [parser.ts:1-12](file://frontend/pro/web-sandbox/parser.ts#L1-L12) +- [utils.ts:1-8](file://frontend/pro/web-sandbox/utils.ts#L1-L8) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [package.json:8-39](file://frontend/package.json#L8-L39) + +Section Sources + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [package.json:1-59](file://frontend/package.json#L1-L59) + +## Performance and Security Trade-offs + +- **Transformation cost**: Babel transformation and Blob URL creation introduce some overhead; consider enabling caching and incremental update strategies for larger input sizes. +- **Message listening**: Listen only to messages from the iframe to avoid performance issues caused by frequent events. +- **Styles and scripts**: Prefer injecting relative CSS via Blob URLs to reduce network requests; strictly whitelist external CSS sources. + +[This section contains general recommendations with no specific section sources] + +## Troubleshooting Guide + +- **Compilation failure**: Check whether input files contain circular dependencies, syntax errors, or missing entry files; the component throws an error during the parsing phase and triggers the compile error callback. +- **Render error**: Errors inside the iframe are reported via postMessage; the parent page displays an error notification or triggers the render error callback. Enable `showRenderError` to view specific information. +- **Theme and custom events**: Confirm that the parent page correctly sets `themeMode` and the `onCustom` callback; the iframe receives theme changes via postMessage. +- **Style anomalies**: Check importmap and style injection logic; ensure style URLs are correct and accessible. + +Section Sources + +- [web-sandbox.tsx:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218) +- [web-sandbox.tsx:267-281](file://frontend/pro/web-sandbox/web-sandbox.tsx#L267-L281) +- [parser.ts:128-174](file://frontend/pro/web-sandbox/parser.ts#L128-L174) + +## Conclusion + +WebSandbox achieves least-privilege execution and effective security isolation for user-input code through browser iframe isolation, importmap and Babel transformation, Blob URL injection, and a strictly controlled postMessage event channel. Combined with path normalization and error reporting mechanisms, it significantly reduces XSS and malicious script risks while maintaining usability. + +[This section is a summary with no specific section sources] + +## Appendix: Security Configuration and Best Practices + +### Security Configuration Recommendations + +- **Restrict third-party dependency sources**: Use importmap to explicitly specify third-party library versions and domains, avoiding loading uncontrolled scripts. +- **Strengthen CSP**: Set `Content-Security-Policy` at the server or gateway layer to restrict script execution sources and inline scripts. +- **Principle of least privilege**: Only inject necessary styles and scripts; avoid exposing sensitive host interfaces to the iframe. +- **Resource whitelist**: Apply a whitelist policy for external CSS/JS, allowing only `https` or trusted domains. + +### Best Practices + +- **Input validation**: Strictly validate user-input file names and paths to prevent path traversal. +- **Error message sanitization**: Error displays should avoid exposing internal paths and source code details. +- **Incremental updates**: Enable caching and incremental transformation for large projects to improve performance and security. +- **Audit logging**: Record key compile and runtime events to facilitate tracking and auditing. + +### Vulnerability Protection Guide + +- **XSS protection**: Avoid directly concatenating user input with `innerHTML`; use Blob URLs to replace inline scripts. +- **Circular dependency detection**: Circular dependencies are detected and blocked during the parsing phase to prevent abnormal behavior. +- **Cross-site messages**: Strictly validate the source and type of postMessage messages; reject messages from unknown origins. + +Section Sources + +- [README.md (WebSandbox Docs):34-70](file://docs/components/pro/web_sandbox/README.md#L34-L70) +- [web-sandbox.tsx:110-179](file://frontend/pro/web-sandbox/web-sandbox.tsx#L110-L179) +- [parser.ts:128-174](file://frontend/pro/web-sandbox/parser.ts#L128-L174) diff --git a/.wiki/en/Pro Components/WebSandbox/WebSandbox.md b/.wiki/en/Pro Components/WebSandbox/WebSandbox.md new file mode 100644 index 00000000..dac1c1cc --- /dev/null +++ b/.wiki/en/Pro Components/WebSandbox/WebSandbox.md @@ -0,0 +1,365 @@ +# WebSandbox + + +**Files Referenced in This Document** +- [web-sandbox.tsx](file://frontend/pro/web-sandbox/web-sandbox.tsx) +- [parser.ts](file://frontend/pro/web-sandbox/parser.ts) +- [utils.ts](file://frontend/pro/web-sandbox/utils.ts) +- [react-iframe-template.html](file://frontend/pro/web-sandbox/react-iframe-template.html) +- [html-iframe-event-listener.js](file://frontend/pro/web-sandbox/html-iframe-event-listener.js) +- [web-sandbox.less](file://frontend/pro/web-sandbox/web-sandbox.less) +- [Index.svelte](file://frontend/pro/web-sandbox/Index.svelte) +- [web-sandbox-CY4X1bGf.js](file://backend/modelscope_studio/components/pro/web_sandbox/templates/component/web-sandbox-CY4X1bGf.js) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix: Usage Examples and Best Practices](#appendix-usage-examples-and-best-practices) + +## Introduction + +WebSandbox is a component for safely rendering third-party or user-provided content in a controlled environment. It supports two modes: + +- **React Mode**: Compiles, bundles, and runs code starting from a React application entry file, suitable for complex interactions and component-based scenarios. +- **HTML Mode**: Parses and injects HTML documents, inlining scripts and styles, suitable for quickly rendering static or semi-static pages. + +The component isolates execution environments through iframes, uses postMessage for parent-child window event communication, and provides comprehensive error handling and theme adaptation capabilities to ensure safe rendering without disrupting the host application. + +## Project Structure + +The frontend core resides in `frontend/pro/web-sandbox`. Backend templates are generated by the Python backend and injected at runtime. The Svelte layer handles bridging and property forwarding. + +```mermaid +graph TB +subgraph "Frontend" +A["web-sandbox.tsx
Component body and lifecycle"] +B["parser.ts
File parsing and dependency graph construction"] +C["utils.ts
Path/entry/template utilities"] +D["react-iframe-template.html
React template"] +E["html-iframe-event-listener.js
Event listener inside iframe"] +F["web-sandbox.less
Styles"] +G["Index.svelte
Svelte wrapper layer"] +end +subgraph "Backend" +H["web-sandbox-CY4X1bGf.js
Backend template and runtime"] +end +A --> B +A --> C +A --> D +A --> E +A --> F +G --> A +H --> D +H --> E +``` + +**Diagram Sources** + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [web-sandbox.less:1-24](file://frontend/pro/web-sandbox/web-sandbox.less#L1-L24) +- [Index.svelte:1-76](file://frontend/pro/web-sandbox/Index.svelte#L1-L76) +- [web-sandbox-CY4X1bGf.js:163-205](file://backend/modelscope_studio/components/pro/web_sandbox/templates/component/web-sandbox-CY4X1bGf.js#L163-L205) + +**Section Sources** + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [Index.svelte:1-76](file://frontend/pro/web-sandbox/Index.svelte#L1-L76) +- [web-sandbox-CY4X1bGf.js:163-205](file://backend/modelscope_studio/components/pro/web_sandbox/templates/component/web-sandbox-CY4X1bGf.js#L163-L205) + +## Core Components + +- **WebSandbox Main Component**: Responsible for receiving input files, building import maps, parsing/transforming files, generating iframe content, handling messages and errors, and injecting theme and event listener scripts. +- **WebSandboxParser**: Based on Babel Standalone, analyzes dependencies, performs topological sorting, replaces relative imports with Blob URLs, extracts stylesheets, and produces a runnable asset manifest. +- **Utilities**: Path normalization, entry file inference, HTML template rendering, and file content extraction. +- **Templates and Event Listeners**: React template and HTML event listener scripts, both notifying the parent window of "ready" and "error" states via postMessage. + +Key responsibilities and behaviors: + +- **Security Isolation**: iframe and parent window communicate via postMessage; styles and scripts are injected via Blob URLs to avoid cross-origin risks. +- **Error Handling**: Compile-time and runtime errors are reported separately; notification display and fallback rendering are optional. +- **Theme Adaptation**: Injects theme mode into iframe, supporting dynamic updates. +- **Event Communication**: Sends "ready" after iframe loads; runtime errors are reported via "error" events. + +**Section Sources** + +- [web-sandbox.tsx:21-55](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L55) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:20-83](file://frontend/pro/web-sandbox/utils.ts#L20-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## Architecture Overview + +The overall WebSandbox flow is divided into two phases: "Compilation & Injection" and "iframe Rendering & Communication". + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant WS as "WebSandbox (Frontend)" +participant Parser as "WebSandboxParser" +participant Iframe as "iframe (Child Window)" +participant Parent as "Parent Window" +Dev->>WS : Provide files/imports/template/value +WS->>Parser : Parse files / Build dependency graph / Transform code +Parser-->>WS : Return entryUrl/styleSheetUrls/normalizedFiles +WS->>WS : Generate iframe HTML (Blob URL) +WS->>Iframe : Set src (Blob URL) +Iframe->>Parent : postMessage("sandbox-ready") +Parent-->>WS : Listen for message (type="sandbox-ready") +WS->>WS : Trigger onCompileSuccess / close loading +Iframe->>Parent : postMessage("sandbox-error", message) +Parent-->>WS : Listen for message (type="sandbox-error") +WS->>WS : Trigger onRenderError / optional notification +``` + +**Diagram Sources** + +- [web-sandbox.tsx:94-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L94-L218) +- [web-sandbox.tsx:220-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L220-L297) +- [react-iframe-template.html:16-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L16-L40) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## Detailed Component Analysis + +### WebSandbox Main Component (React) + +- **Input props and defaults**: value, imports, template, showRenderError, showCompileError, height, className, style, onCompileError, onRenderError, onCompileSuccess, onCustom, compileErrorRender, etc. +- **Import mapping**: Selects built-in React/ReactDOM mappings based on `template`, then merges user-defined `imports`. +- **Compilation flow**: + - React mode: Parse entry file, build dependency graph, Babel transform, replace relative imports with Blob URLs, collect stylesheets, generate entry URL. + - HTML mode: Parse DOM, extract and rewrite inline scripts, inject importmap and style links, inject event listener script, generate full HTML Blob URL. +- **iframe lifecycle**: Create Blob URL → Inject theme and custom dispatch function → Listen for `sandbox-ready` and `sandbox-error` → Clean up URLs. +- **Error handling**: Compile-time errors via `onCompileError` and optional `compileErrorRender` or slot; runtime errors via `onRenderError` and notification. + +```mermaid +flowchart TD +Start(["Start"]) --> CheckValue{"Has value?"} +CheckValue -- No --> End(["End"]) +CheckValue -- Yes --> Mode{"template=react?"} +Mode -- Yes --> ParseReact["Parse entry / Build dependency graph
Babel transform / Generate Blob URL"] +Mode -- No --> ParseHTML["Parse DOM / Extract inline scripts
Inject importmap / styles / event listener"] +ParseReact --> BuildIframe["Generate iframe HTML (Blob URL)"] +ParseHTML --> BuildIframe +BuildIframe --> LoadIframe["Set iframe.src and inject theme"] +LoadIframe --> Ready{"Received sandbox-ready?"} +Ready -- Yes --> OnSuccess["Trigger onCompileSuccess / Stop loading"] +Ready -- No --> ErrorEvt{"Received sandbox-error?"} +ErrorEvt -- Yes --> OnError["Trigger onRenderError / Optional notification"] +OnSuccess --> End +OnError --> End +``` + +**Diagram Sources** + +- [web-sandbox.tsx:94-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L94-L218) +- [web-sandbox.tsx:220-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L220-L297) + +**Section Sources** + +- [web-sandbox.tsx:21-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L365) + +### WebSandboxParser + +- **File normalization**: Normalizes paths, recognizes JS/TS/JSX/TSX/CSS extensions. +- **Dependency graph construction**: Analyzes import declarations from AST, handles relative paths and directory indexes, generates adjacency list. +- **Topological sorting**: Detects circular dependencies and throws errors. +- **Code transformation**: Babel transforms React/TSX, replaces relative imports with Blob URLs, removes or retains CSS imports, generates stylesheet Blob URLs. +- **Output**: entryUrl, styleSheetUrls, normalizedFiles, cleanup (reclaims Blob URLs). + +```mermaid +flowchart TD +A["Input files/importMap/entryFilePath"] --> B["Normalize file paths/extensions"] +B --> C["Build dependency graph (with relative paths/directory indexes)"] +C --> D{"Circular dependency?"} +D -- Yes --> E["Throw error"] +D -- No --> F["Topological sort output order"] +F --> G["Babel transform / Replace imports / Handle CSS"] +G --> H["Generate Blob URL map / stylesheet URLs"] +H --> I["Return entryUrl/styleSheetUrls/cleanup"] +``` + +**Diagram Sources** + +- [parser.ts:28-314](file://frontend/pro/web-sandbox/parser.ts#L28-L314) + +**Section Sources** + +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) + +### Utility Module + +- **Path and entry**: normalizePath, getEntryFile, getFileCode, renderHtmlTemplate. +- **Default entry file sets**: Default entry file lists for React mode and HTML mode. + +**Section Sources** + +- [utils.ts:20-83](file://frontend/pro/web-sandbox/utils.ts#L20-L83) + +### Templates and Event Listeners + +- **React template**: Contains importmap, style injection, event listener script, and entry module loading. +- **HTML event listener**: Captures `error` and `DOMContentLoaded` inside the iframe, notifies the parent window via postMessage. + +**Section Sources** + +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +### Svelte Wrapper Layer and Backend Template + +- **Svelte layer**: Responsible for property forwarding, visibility control, slot and theme passing. +- **Backend template**: Generates iframe HTML templates and event listener scripts consistent with the frontend to ensure front/backend consistency. + +**Section Sources** + +- [Index.svelte:1-76](file://frontend/pro/web-sandbox/Index.svelte#L1-L76) +- [web-sandbox-CY4X1bGf.js:163-205](file://backend/modelscope_studio/components/pro/web_sandbox/templates/component/web-sandbox-CY4X1bGf.js#L163-L205) + +## Dependency Analysis + +- **Component coupling**: + - WebSandbox has direct dependencies on parser.ts, utils.ts, templates, and event listener scripts. + - The Svelte layer acts only as a bridge and does not directly participate in business logic. +- **External dependencies**: + - Babel Standalone for code transformation and AST analysis. + - Ant Design's notification/Alert for error messages. + - React/ReactDOM introduced via importmap in React mode. +- **Potential circular dependencies**: + - The parser avoids circular dependencies internally through topological sorting; if user files have circular imports, an error will be thrown during the compilation phase. + +```mermaid +graph LR +WS["web-sandbox.tsx"] --> P["parser.ts"] +WS --> U["utils.ts"] +WS --> T["react-iframe-template.html"] +WS --> L["html-iframe-event-listener.js"] +S["Index.svelte"] --> WS +B["web-sandbox-CY4X1bGf.js"] --> T +B --> L +``` + +**Diagram Sources** + +- [web-sandbox.tsx:1-20](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L20) +- [parser.ts:1-12](file://frontend/pro/web-sandbox/parser.ts#L1-L12) +- [utils.ts:1-1](file://frontend/pro/web-sandbox/utils.ts#L1-L1) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [Index.svelte:1-12](file://frontend/pro/web-sandbox/Index.svelte#L1-L12) +- [web-sandbox-CY4X1bGf.js:163-205](file://backend/modelscope_studio/components/pro/web_sandbox/templates/component/web-sandbox-CY4X1bGf.js#L163-L205) + +**Section Sources** + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [Index.svelte:1-76](file://frontend/pro/web-sandbox/Index.svelte#L1-L76) +- [web-sandbox-CY4X1bGf.js:163-205](file://backend/modelscope_studio/components/pro/web_sandbox/templates/component/web-sandbox-CY4X1bGf.js#L163-L205) + +## Performance Considerations + +- **Blob URL management**: Both the parser and the component maintain Blob URL mappings and reclaim them during cleanup to avoid memory leaks. +- **Lazy loading and async**: The Svelte wrapper uses async component loading to reduce initial render pressure. +- **Dependency graph optimization**: Topological sorting and sequential transformation reduce redundant work. +- **Style injection**: CSS is injected via Blob URLs or external links to avoid blocking main thread rendering. +- **Event listeners**: Listening starts only after the iframe is ready, reducing unnecessary communication overhead. + +[This section contains general performance recommendations with no specific file references] + +## Troubleshooting Guide + +- **Compile-time errors** + - Symptom: Component displays a compile error; `onCompileError` callback is triggered. + - Diagnosis: Check whether `imports` are correct, whether `template` and the entry file match, and whether circular dependencies exist. + - Reference: [web-sandbox.tsx:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218), [parser.ts:128-174](file://frontend/pro/web-sandbox/parser.ts#L128-L174) +- **Runtime errors** + - Symptom: iframe reports an error; parent window receives `sandbox-error`. + - Diagnosis: Check the `onRenderError` callback and notification; verify that third-party libraries are correctly referenced via importmap. + - Reference: [web-sandbox.tsx:262-282](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L282), [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- **"Ready" event not triggered** + - Symptom: `onCompileSuccess` is not triggered; loading state persists. + - Diagnosis: Verify that the template correctly injects the event listener script; check whether the Blob URL is valid. + - Reference: [react-iframe-template.html:16-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L16-L40) +- **Missing styles** + - Symptom: Page has no styles or styles appear abnormal. + - Diagnosis: Verify that `styleSheetUrls` are generated; check CSS import paths and importmap. + - Reference: [parser.ts:258-276](file://frontend/pro/web-sandbox/parser.ts#L258-L276) +- **Theme not applied** + - Symptom: Theme inside iframe is inconsistent with the host application. + - Diagnosis: Confirm that `themeMode` is passed in and the message is dispatched; check whether the theme is correctly received inside the iframe. + - Reference: [web-sandbox.tsx:244-261](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L261) + +**Section Sources** + +- [web-sandbox.tsx:203-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L297) +- [parser.ts:128-276](file://frontend/pro/web-sandbox/parser.ts#L128-L276) +- [react-iframe-template.html:16-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L16-L40) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## Conclusion + +WebSandbox achieves safe rendering of third-party or user-provided content through rigorous file parsing and transformation, secure iframe isolation, and a unified event communication mechanism. Its dual-mode (React/HTML) design balances flexibility and ease of use, and combined with comprehensive error handling and theme adaptation, it meets the needs of most scenarios requiring safe rendering. + +[This section is a summary with no specific file references] + +## Appendix: Usage Examples and Best Practices + +### Configuration Props Overview + +- `value`: A dictionary of file objects, supporting strings or objects with `is_entry` flag. +- `imports`: Custom importmap overriding the default React/ReactDOM mappings. +- `template`: `'react'` or `'html'`. +- `showRenderError` / `showCompileError`: Whether to display runtime/compile error notifications. +- `onCompileError` / `onRenderError` / `onCompileSuccess` / `onCustom`: Event callbacks. +- `compileErrorRender`: Custom compile error renderer. +- `height` / `className` / `style`: Container style controls. + +Reference: + +- [web-sandbox.tsx:21-55](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L55) + +### Security Policy and Event Handling + +- **Custom event handling**: Use `onCustom` to dispatch events from inside the iframe to the parent window, enabling loosely coupled communication. +- **Security boundary**: iframe and parent window communicate via postMessage, avoiding direct DOM access; Blob URLs isolate scripts and styles. +- **Error capture**: Errors inside the iframe are uniformly reported; the parent window can choose to display notifications or handle them silently. + +Reference: + +- [web-sandbox.tsx:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +### Usage Examples (Step-by-Step) + +- **React Mode** + - Prepare the entry file (e.g., `index.tsx`), mark it with `is_entry` in `value` or use the default entry. + - If third-party libraries are needed, provide their URLs in `imports`. + - Set `template='react'`, render the component, and listen to `onCompileSuccess` and `onRenderError`. + - Reference: [web-sandbox.tsx:94-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L94-L218), [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- **HTML Mode** + - Prepare `index.html`; inline scripts will be extracted and transformed automatically. + - Set `template='html'`; the component will automatically inject importmap, styles, and event listener scripts. + - Reference: [web-sandbox.tsx:110-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L110-L218), [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +### Best Practices + +- Prefer React mode for better type support and ecosystem compatibility. +- Add third-party libraries to `imports` to avoid cross-origin CDN script issues. +- Enable `showRenderError` in production to catch runtime issues promptly. +- Use the `compileErrorRender` slot or function to customize the error UI for better user experience. +- Remember to clean up Blob URLs to prevent memory leaks. + +[This section contains general guidelines with no specific file references] diff --git a/.wiki/en/Project Overview/Core Features.md b/.wiki/en/Project Overview/Core Features.md new file mode 100644 index 00000000..99a25f47 --- /dev/null +++ b/.wiki/en/Project Overview/Core Features.md @@ -0,0 +1,321 @@ +# Core Features + + +**Files referenced in this document** +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [frontend/package.json](file://frontend/package.json) +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [frontend/antdx/package.json](file://frontend/antdx/package.json) +- [pyproject.toml](file://pyproject.toml) +- [docs/README.md](file://docs/README.md) +- [docs/FAQ.md](file://docs/FAQ.md) +- [docs/app.py](file://docs/app.py) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) +- [docs/components/antd/config_provider/demos/basic.py](file://docs/components/antd/config_provider/demos/basic.py) +- [docs/components/base/application/demos/theme_adaptation.py](file://docs/components/base/application/demos/theme_adaptation.py) +- [docs/components/pro/web_sandbox/demos/react.py](file://docs/components/pro/web_sandbox/demos/react.py) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +ModelScope Studio is a third-party component library based on Gradio, designed to provide developers with richer UI components and stronger page layout capabilities. While maintaining good compatibility with native Gradio components, it introduces the Ant Design (Antd) and Ant Design X (Antdx) UI ecosystems, and extends with a Pro advanced component family, covering diverse needs from general interactions to AI scenarios. Its core features include: + +- Supported UI libraries: Ant Design, Ant Design X +- Component count statistics: The Antd component family includes many commonly used UI components; Antdx focuses on conversational and prompt scenarios; Pro components provide advanced capabilities such as chatbot, multimodal input, code editor, and web sandbox +- Gradio integration: Seamlessly connects with Gradio's event system, state management, queue and concurrency control +- Advantages over native Gradio: Compared to native Gradio components, ModelScope Studio focuses more on page layout optimization and component flexibility, making it suitable for building more visually appealing and maintainable user interfaces +- Development scenarios: Machine learning applications, AI interactive interfaces, multimodal experiences, visualization and demo spaces +- Internationalization and theming: Built-in multi-language mapping and theme customization, supporting light/dark modes and compact algorithm +- Performance optimization: Improves response speed through on-demand frontend bundling, template caching, and Gradio queue concurrency configuration + +## Project Structure + +The project adopts a front-end/back-end separated multi-package organization: + +- Backend Python package: Provides component exports and packaging metadata +- Frontend Svelte packages: Split by module into Antd/Antdx/Base/Pro, with each component as an independent directory and template +- Documentation and examples: Aggregate component examples and layout templates through the docs application + +```mermaid +graph TB +subgraph "Backend" +PY["Python Package
modelscope_studio"] +PY --> ANTDCOMP["antd component exports"] +PY --> ANTDXCOMP["antdx component exports"] +PY --> PROCOMP["pro component exports"] +end +subgraph "Frontend" +FE_PKG["frontend/package.json"] +ANTD_PKG["@modelscope-studio/antd"] +ANTDX_PKG["@modelscope-studio/antdx"] +FE_PKG --> ANTD_PKG +FE_PKG --> ANTDX_PKG +end +subgraph "Documentation & Examples" +DOCS["docs/app.py"] +DOCS --> DEMOS["Component examples & layout templates"] +end +PY --- FE_PKG +DOCS --- FE_PKG +``` + +Diagram Sources + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:577-590](file://docs/app.py#L577-L590) + +Section Sources + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:577-590](file://docs/app.py#L577-L590) + +## Core Components + +The core of ModelScope Studio consists of three major component families: + +- Antd component family: Covers general, layout, navigation, data entry, data display, feedback, and global configuration categories, with a rich set of components suitable for complex business scenarios +- Antdx component family: Specialized components for AI interaction, such as conversation bubbles, prompt collections, senders, thought chains, welcome messages, etc. +- Pro component family: Provides advanced capabilities such as chatbot, multimodal input, Monaco editor, web sandbox, etc. + +Section Sources + +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## Architecture Overview + +The following diagram shows the position of ModelScope Studio within the Gradio ecosystem and its interaction relationships: + +```mermaid +graph TB +GR["Gradio Application"] +MS["ModelScope Studio Component Library"] +ANTD["Ant Design Components"] +ANTCFG["ConfigProvider Global Configuration"] +ANTDX["Ant Design X Components"] +PRO["Pro Advanced Components"] +BASE["Base Components"] +GR --> MS +MS --> ANTD +MS --> ANTDX +MS --> PRO +MS --> BASE +ANTD --> ANTCFG +``` + +Diagram Sources + +- [docs/README.md:32-42](file://docs/README.md#L32-L42) +- [docs/app.py:577-590](file://docs/app.py#L577-L590) + +Section Sources + +- [docs/README.md:32-42](file://docs/README.md#L32-L42) +- [docs/app.py:577-590](file://docs/app.py#L577-L590) + +## Detailed Component Analysis + +### Antd Component Family + +The Antd component family is the main body of ModelScope Studio, covering a wide functional domain, suitable for building enterprise-level or complex interactive interfaces. Typical components include: + +- Layout: Layout, Grid, Flex, Space, Splitter +- Navigation: Anchor, Breadcrumb, Dropdown, Menu, Pagination, Steps +- Data Entry: AutoComplete, Cascader, Checkbox, ColorPicker, DatePicker, Form, Input, InputNumber, Mentions, Radio, Rate, Select, Slider, Switch, TimePicker, Transfer, TreeSelect, Upload +- Data Display: Avatar, Badge, Calendar, Card, Carousel, Collapse, Descriptions, Empty, Image, List, Popover, QRCode, Segmented, Statistic, Table, Tabs, Tag, Timeline, Tooltip, Tour, Tree +- Feedback: Alert, Drawer, Message, Modal, Notification, Popconfirm, Progress, Result, Skeleton, Spin, Watermark +- General: Button, FloatButton, Icon, Typography +- Global Configuration: ConfigProvider (theme, locale, direction) + +Component count statistics (based on backend export manifest): + +- Antd main components: approximately 120+ specific components (including sub-modules) +- Antdx specialized components: approximately 30+ components +- Pro advanced components: approximately 4 components + +Section Sources + +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [pyproject.toml:48-244](file://pyproject.toml#L48-L244) + +### Antdx Component Family + +Antdx is designed specifically for AI interaction, emphasizing the complete conversational chain of "wake—express—confirm—feedback—tool": + +- Wake: Welcome, Prompts +- Express: Attachments, Sender, Suggestion +- Confirm: ThoughtChain +- Feedback: Actions +- Tool: XProvider +- General: Bubble, Conversations + +These components, combined with ConfigProvider, theme, and internationalization, can quickly build high-quality AI conversational interfaces. + +Section Sources + +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +### Pro Component Family + +Pro components focus on advanced interaction and demo scenarios: + +- Chatbot: Conversational applications +- MultimodalInput: Multimodal input +- MonacoEditor: Code editor +- WebSandbox: Web sandbox preview + +Section Sources + +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +### Internationalization and Theme Customization + +- Internationalization: The frontend provides multi-language mapping, supporting conversion from language codes to Antd/dayjs localization +- Theme customization: ConfigProvider supports theme algorithms (light/dark, compact), primary color, and direction switching +- Examples: Documentation provides basic theme and color adjustment examples, as well as application-level theme adaptation examples + +```mermaid +flowchart TD +Start(["Enter Page"]) --> DetectLang["Detect language code"] +DetectLang --> LoadLocales["Dynamically load Antd and dayjs localization"] +LoadLocales --> ApplyTheme["Apply theme configuration light/dark/compact"] +ApplyTheme --> RenderUI["Render components"] +RenderUI --> End(["Done"]) +``` + +Diagram Sources + +- [frontend/antd/config-provider/locales.ts:12-87](file://frontend/antd/config-provider/locales.ts#L12-L87) +- [docs/components/antd/config_provider/demos/basic.py:54-74](file://docs/components/antd/config_provider/demos/basic.py#L54-L74) +- [docs/components/base/application/demos/theme_adaptation.py:6-8](file://docs/components/base/application/demos/theme_adaptation.py#L6-L8) + +Section Sources + +- [frontend/antd/config-provider/locales.ts:12-87](file://frontend/antd/config-provider/locales.ts#L12-L87) +- [docs/components/antd/config_provider/demos/basic.py:54-74](file://docs/components/antd/config_provider/demos/basic.py#L54-L74) +- [docs/components/base/application/demos/theme_adaptation.py:6-8](file://docs/components/base/application/demos/theme_adaptation.py#L6-L8) + +### Gradio Integration and Page Layout Optimization + +- Events and state: Collaborate with Gradio's event system through base components such as Application, AutoLoading, etc. +- Layout optimization: Use Flex, Grid, Layout, Space, Splitter, and other components for flexible layout +- Interaction feedback: The AutoLoading component is used to display loading feedback during interactions, avoiding blank waits caused by missing Gradio's default loading state + +```mermaid +sequenceDiagram +participant U as "User" +participant G as "Gradio Application" +participant APP as "Application" +participant AL as "AutoLoading" +participant C as "Component" +U->>G : Trigger interaction +G->>APP : Enter context +APP->>AL : Display loading feedback +AL-->>U : Show loading state +G->>C : Execute processing logic +C-->>G : Return result +G-->>U : Update interface +``` + +Diagram Sources + +- [docs/FAQ.md:7-19](file://docs/FAQ.md#L7-L19) +- [docs/app.py:577-590](file://docs/app.py#L577-L590) + +Section Sources + +- [docs/FAQ.md:7-19](file://docs/FAQ.md#L7-L19) +- [docs/app.py:577-590](file://docs/app.py#L577-L590) + +## Dependency Analysis + +- Python-side dependencies: Gradio version range constraints ensure compatibility with different versions +- Frontend dependencies: Ant Design, Ant Design X, React, Svelte, Monaco Editor, Mermaid, KaTeX, Prism, etc. +- Packaging and release: Built with hatchling; artifact list includes many template resources for on-demand frontend loading + +```mermaid +graph LR +PY["pyproject.toml Dependencies"] +FE["frontend/package.json Dependencies"] +PY --> |Constraint| GR["Gradio"] +FE --> |Component ecosystem| ANT["antd"] +FE --> |X ecosystem| ANTX["@ant-design/x"] +FE --> |Editor| MONACO["monaco-editor"] +FE --> |Visualization| MERMAID["mermaid"] +FE --> |Syntax highlighting| PRISM["prismjs"] +``` + +Diagram Sources + +- [pyproject.toml:26-26](file://pyproject.toml#L26-L26) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) + +Section Sources + +- [pyproject.toml:26-26](file://pyproject.toml#L26-L26) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) + +## Performance Considerations + +- Concurrency and queues: Example applications enable queue and concurrency limits, which helps maintain stable operation under high load +- Templates and resources: The artifact list includes many template resources; it is recommended to load on demand in production environments to reduce initial page size +- SSR note: SSR must be disabled in Hugging Face Space to avoid custom component rendering issues + +Section Sources + +- [docs/app.py:592-594](file://docs/app.py#L592-L594) +- [docs/FAQ.md:3-5](file://docs/FAQ.md#L3-L5) +- [pyproject.toml:48-244](file://pyproject.toml#L48-L244) + +## Troubleshooting Guide + +- Hugging Face Space page not displaying: Add parameter `ssr_mode=False` +- Long wait after interactions: When the AutoLoading component is not used, Gradio's default loading state may not display; it is recommended to use AutoLoading globally +- Theme/language not taking effect: Check whether the `theme` and `locale` settings of ConfigProvider are correctly passed down the component tree + +Section Sources + +- [docs/FAQ.md:3-19](file://docs/FAQ.md#L3-L19) +- [docs/components/antd/config_provider/demos/basic.py:54-74](file://docs/components/antd/config_provider/demos/basic.py#L54-L74) + +## Conclusion + +ModelScope Studio, through the Antd, Antdx, and Pro component families combined with Gradio's event and state mechanisms, provides significant enhancements in page layout, component flexibility, and AI interaction experience. Its internationalization and theme customization capabilities, complete examples and documentation, make it the ideal choice for building machine learning and AI interactive interfaces. For scenarios requiring complex layouts and rich interactions, ModelScope Studio can effectively improve development efficiency and user experience. + +## Appendix + +- Usage Scenario Examples + - Machine learning model demos: Use Layout, Grid, Form, Table, Modal, and other components to display data and results + - AI conversational interfaces: Use Antdx components like Bubble, Sender, Prompts, ThoughtChain to build natural conversation flows + - Code and visualization: Use Pro's MonacoEditor and Mermaid to implement code editing and flowchart display + - Multimodal input: Use Pro's MultimodalInput to build text/image/audio input scenarios + - Web preview: Use Pro's WebSandbox to quickly embed external pages for demo + +Section Sources + +- [docs/components/pro/web_sandbox/demos/react.py:74-97](file://docs/components/pro/web_sandbox/demos/react.py#L74-L97) +- [docs/components/antd/config_provider/demos/basic.py:54-74](file://docs/components/antd/config_provider/demos/basic.py#L54-L74) +- [docs/components/base/application/demos/theme_adaptation.py:18-30](file://docs/components/base/application/demos/theme_adaptation.py#L18-L30) diff --git a/.wiki/en/Project Overview/Project Introduction.md b/.wiki/en/Project Overview/Project Introduction.md new file mode 100644 index 00000000..b6ace8b2 --- /dev/null +++ b/.wiki/en/Project Overview/Project Introduction.md @@ -0,0 +1,441 @@ +# Project Introduction + + +**Files referenced in this document** +- [README.md](file://README.md) +- [README-zh_CN.md](file://README-zh_CN.md) +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [docs/app.py](file://docs/app.py) +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [frontend/antdx/package.json](file://frontend/antdx/package.json) +- [frontend/pro/package.json](file://frontend/pro/package.json) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +ModelScope Studio is a third-party component library based on Gradio, designed to provide developers with richer and more flexible UI-building capabilities. By integrating the Ant Design and Ant Design X (Antd/Antdx) ecosystems, along with a self-developed base and professional component system, it helps users quickly build visually appealing and maintainable interactive interfaces while retaining the ease of use of Gradio. + +- Core Value Proposition + - Stronger page layout and component flexibility: Compared to native Gradio components, ModelScope Studio focuses more on page layout and component composition, making it ideal for applications that prioritize visual and interactive experience. + - Seamless integration with the Gradio ecosystem: Can be used independently or mixed with existing Gradio components to meet interface needs of varying complexity. + - Multi-platform deployment support: Supports platforms such as ModelScope Studio and Hugging Face Space, providing a consistent development and release experience. + +- Design Philosophy + - Core principle of "component as a service," providing reusable and composable UI components. + - Simplifies complex layout and data flow management through context and slot mechanisms. + - Maintains deep compatibility with Gradio to reduce migration and learning costs. + +- Relationship with ModelScope and Gradio Ecosystems + - Leveraging Gradio's Blocks/Interface rendering and event system, ModelScope Studio exposes Antd/Antdx components and professional components as Gradio components, allowing the Python side to declaratively compose frontend components. + - On the ModelScope Studio platform and Hugging Face Space, users can directly run examples and templates to quickly validate UI effects. + +- Background and Goals + - Background: While Gradio provides an extremely simple interface entry for model applications, there is still room for improvement in complex layouts and professional interactions; the Ant Design ecosystem is mature but its direct integration with Gradio is not seamless enough. + - Goal: Build a component library with "lightweight access, powerful composition" that covers full-stack UI needs from basic layout to professional interactions, driving the engineering and standardization of model application interfaces. + +- Core Problems Solved + - High page layout complexity: Reduces nesting levels and logical complexity through layout components and slot mechanisms. + - Component reuse and consistency: A unified Antd/Antdx component system ensures cross-module consistency and maintainability. + - Multi-platform deployment consistency: Provides stable SSR/CSR configuration recommendations to avoid display anomalies on different platforms. + +- Open Source Philosophy and Community Contribution + - License: Apache-2.0, encouraging enterprise and individual use and contributions within compliance. + - Contributing: Welcome feedback via Issues/PR, supplementing documentation, improving components, or fixing defects; follow code standards and change processes. + - Releases and versioning: Manage versions and changelogs through Changesets; CI pipeline handles build and release. + +- Future Plans + - Expand component matrix: Continuously improve Antd/Antdx and professional components to cover more business scenarios. + - Optimize developer experience: Improve documentation site, example templates, and debugging toolchain. + - Platform adaptation: Enhance adaptation and best practices for ModelScope Studio, Hugging Face Space, and other platforms. + +**Section Sources** + +- [README.md:17-32](file://README.md#L17-L32) +- [README-zh_CN.md:17-32](file://README-zh_CN.md#L17-L32) + +## Project Structure + +The project adopts a front-end/back-end separated multi-package workspace structure. The backend Python package provides component registration and version information; the frontend implements each component in Svelte and integrates with the Gradio build toolchain; the documentation site dynamically loads component examples and templates through Python. + +```mermaid +graph TB +subgraph "Backend (Python)" +PY_PKG["Python Package
modelscope_studio"] +CMPTS["Component Exports
components/__init__.py"] +ANTD_ALL["Antd Component Aggregation
antd/components.py"] +VERSION["Version
version.py"] +end +subgraph "Frontend (Svelte)" +FE_ANTD["@modelscope-studio/antd
antd/*"] +FE_ANTDX["@modelscope-studio/antdx
antdx/*"] +FE_PRO["@modelscope-studio/pro
pro/*"] +end +subgraph "Documentation & Scripts" +DOCS_APP["Documentation Site Entry
docs/app.py"] +PKG_JSON["Root Package Config
package.json"] +PYPROJ["Python Build Config
pyproject.toml"] +end +PY_PKG --> CMPTS +CMPTS --> ANTD_ALL +PY_PKG --> VERSION +DOCS_APP --> FE_ANTD +DOCS_APP --> FE_ANTDX +DOCS_APP --> FE_PRO +PKG_JSON --> DOCS_APP +PYPROJ --> PY_PKG +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +**Section Sources** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +## Core Components + +ModelScope Studio's component system is divided into three major categories: + +- Base components (base): Provide layout, rendering control and context capabilities, such as Application, AutoLoading, Slot, Fragment, Each, Filter, Div, Span, Text, Markdown, etc. +- Ant Design components (antd): Cover Antd's general, layout, navigation, data entry, data display, feedback, and other categories, including a large number of sub-components and composite forms. +- Ant Design X components (antdx): A professional component collection for conversational and collaborative scenarios, such as Bubble, Conversations, Sender, ThoughtChain, Actions, etc. +- Pro components (pro): Advanced components for specific business needs, such as Chatbot, Monaco Editor, Multimodal Input, Web Sandbox, etc. + +These components are exposed on the Python side through a unified registration and export mechanism, making it easy to compose them as needed within Blocks. + +**Section Sources** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [docs/app.py:189-509](file://docs/app.py#L189-L509) + +## Architecture Overview + +ModelScope Studio's overall architecture revolves around "Python component definition + Svelte frontend implementation + Gradio rendering pipeline." On the Python side, components are injected into Blocks as Gradio components through component base classes and context mechanisms; the frontend uses Svelte to implement component UIs and packages and distributes them through Gradio's build toolchain; the documentation site dynamically loads component examples and templates, forming a closed loop of "develop—demo—publish." + +```mermaid +graph TB +subgraph "Python Layer" +MC["ModelScopeComponent Base Class
utils/dev/component.py"] +ML["ModelScopeLayoutComponent Base Class
utils/dev/component.py"] +APP_CTX["AppContext
utils/dev/component.py"] +CMPTS_PY["Component Registration
components/__init__.py"] +end +subgraph "Frontend Layer (Svelte)" +CMP_SVELTE["Component Implementation
frontend/antd/*
frontend/antdx/*
frontend/pro/*"] +end +subgraph "Runtime" +GRADIO["Gradio Rendering Pipeline"] +DOCS["Documentation Site
docs/app.py"] +end +MC --> GRADIO +ML --> GRADIO +APP_CTX --> MC +APP_CTX --> ML +CMPTS_PY --> MC +CMP_SVELTE --> GRADIO +DOCS --> CMPTS_PY +DOCS --> CMP_SVELTE +``` + +**Diagram Sources** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) + +## Detailed Component Analysis + +### Component Base Classes and Context Mechanism + +ModelScope Studio supports the component system through three base classes: + +- ModelScopeComponent: For data-type components, with value passing, event binding, rendering control, and other capabilities. +- ModelScopeLayoutComponent: For layout-type components, supporting layout markers and context switching. +- ModelScopeDataLayoutComponent: Combines data and layout characteristics for complex container components. + +These base classes unify component lifecycle, property injection, and context association, ensuring consistent component behavior within Blocks. + +```mermaid +classDiagram +class ModelScopeComponent { ++EVENTS ++skip_api ++__init__(...) ++elem_style ++as_item +} +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__(...) ++__init__(...) ++elem_style ++as_item +} +class ModelScopeDataLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__(...) ++__init__(...) ++preserved_by_key ++elem_style ++as_item +} +ModelScopeDataLayoutComponent <|-- ModelScopeComponent +ModelScopeLayoutComponent <|-- ModelScopeDataLayoutComponent +``` + +**Diagram Sources** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +**Section Sources** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +### Ant Design Component Aggregation + +Antd components are uniformly exposed through centralized export files, covering general, layout, navigation, data entry, data display, feedback, and other categories, making it easy to import and use on the Python side as needed. + +```mermaid +graph LR +ANTD_ALL["antd/components.py"] --> BUTTON["Button"] +ANTD_ALL --> INPUT["Input"] +ANTD_ALL --> FORM["Form"] +ANTD_ALL --> TABLE["Table"] +ANTD_ALL --> MODAL["Modal"] +ANTD_ALL --> LAYOUT["Layout"] +ANTD_ALL --> MENU["Menu"] +ANTD_ALL --> TREE["Tree"] +ANTD_ALL --> UPLOAD["Upload"] +ANTD_ALL --> PROGRESS["Progress"] +ANTD_ALL --> ALERT["Alert"] +ANTD_ALL --> DRAWER["Drawer"] +ANTD_ALL --> PAGINATION["Pagination"] +ANTD_ALL --> SPIN["Spin"] +ANTD_ALL --> MESSAGE["Message"] +ANTD_ALL --> NOTIFICATION["Notification"] +ANTD_ALL --> TYPGRAPHY["Typography"] +ANTD_ALL --> GRID["Grid"] +ANTD_ALL --> SPACE["Space"] +ANTD_ALL --> SPLITTER["Splitter"] +ANTD_ALL --> STATISTIC["Statistic"] +ANTD_ALL --> TOUR["Tour"] +ANTD_ALL --> WATERMARK["Watermark"] +ANTD_ALL --> QR_CODE["QRCode"] +ANTD_ALL --> CALENDAR["Calendar"] +ANTD_ALL --> CAROUSEL["Carousel"] +ANTD_ALL --> COLLAPSE["Collapse"] +ANTD_ALL --> DESCRIPTIONS["Descriptions"] +ANTD_ALL --> EMPTY["Empty"] +ANTD_ALL --> IMAGE["Image"] +ANTD_ALL --> LIST["List"] +ANTD_ALL --> POPOVER["Popover"] +ANTD_ALL --> SEGMENTED["Segmented"] +ANTD_ALL --> TIME_PICKER["TimePicker"] +ANTD_ALL --> TIMELINE["Timeline"] +ANTD_ALL --> TOOLTIP["Tooltip"] +ANTD_ALL --> TRANSFER["Transfer"] +ANTD_ALL --> TREE_SELECT["TreeSelect"] +ANTD_ALL --> SKELETON["Skeleton"] +ANTD_ALL --> SWITCH["Switch"] +ANTD_ALL --> SLIDER["Slider"] +ANTD_ALL --> SELECT["Select"] +ANTD_ALL --> RADIO["Radio"] +ANTD_ALL --> RATE["Rate"] +ANTD_ALL --> CHECKBOX["Checkbox"] +ANTD_ALL --> COLOR_PICKER["ColorPicker"] +ANTD_ALL --> DATE_PICKER["DatePicker"] +ANTD_ALL --> AUTO_COMPLETE["AutoComplete"] +ANTD_ALL --> CASCADER["Cascader"] +ANTD_ALL --> MENTIONS["Mentions"] +ANTD_ALL --> FLOAT_BUTTON["FloatButton"] +ANTD_ALL --> ICON["Icon"] +ANTD_ALL --> DIVIDER["Divider"] +ANTD_ALL --> DROPDOWN["Dropdown"] +ANTD_ALL --> BADGE["Badge"] +ANTD_ALL --> AVATAR["Avatar"] +ANTD_ALL --> RESULT["Result"] +ANTD_ALL --> POPCONFIRM["Popconfirm"] +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) + +**Section Sources** + +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) + +### Documentation Site and Example Loading + +The documentation site dynamically imports `app.py` from each component directory, aggregating component examples and descriptions to form a unified navigation and display interface; it also supports layout templates and multi-language environment switching. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Docs as "Documentation Site Entry
docs/app.py" +participant Loader as "Component/Template Loader" +participant Site as "Site Renderer" +Dev->>Docs : Launch documentation site +Docs->>Loader : Scan component and template directories +Loader-->>Docs : Return component/template metadata +Docs->>Site : Organize menu and documentation mapping +Site-->>Dev : Render unified site +``` + +**Diagram Sources** + +- [docs/app.py:19-61](file://docs/app.py#L19-L61) +- [docs/app.py:577-595](file://docs/app.py#L577-L595) + +**Section Sources** + +- [docs/app.py:19-61](file://docs/app.py#L19-L61) +- [docs/app.py:577-595](file://docs/app.py#L577-L595) + +### Conceptual Overview + +The following conceptual flowchart shows the key steps from component declaration to page rendering, helping beginners understand the overall workflow. + +```mermaid +flowchart TD +Start(["Start"]) --> Import["Import component library and components"] +Import --> Blocks["Declare layout in Blocks"] +Blocks --> Compose["Compose base/pro/Antd/Antdx components"] +Compose --> Render["Gradio rendering pipeline generates page"] +Render --> Deploy["Deploy to ModelScope Studio/Hugging Face Space"] +Deploy --> End(["End"]) +``` + +[This is a conceptual flowchart and does not correspond to specific source files, hence no diagram source] + +## Dependency Analysis + +- Runtime Dependencies + - Gradio: As the core rendering and event system, ModelScope Studio extends component capabilities on top of it. +- Build and Development Dependencies + - Gradio CLI: Provides component build and development server functionality. + - TypeScript/Svelte: Frontend component implementation and type checking. + - Prettier/ESLint/Stylelint: Code style and quality assurance. +- Release and Version Management + - Changesets: Version and changelog management. + - CI scripts: Automated build, validation, and release. + +```mermaid +graph TB +GR["Gradio(>=4.43.0)"] --> PY["Python Package
pyproject.toml"] +TS["TypeScript/Svelte"] --> FE["@modelscope-studio/* Frontend Packages"] +ESLINT["ESLint"] --> FE +STYLE["Stylelint"] --> FE +PRETTIER["Prettier"] --> FE +CHANGES["Changesets"] --> PKG["package.json Scripts"] +CI["CI Scripts"] --> PKG +PY --> FE +FE --> DOCS["Documentation Site"] +``` + +**Diagram Sources** + +- [pyproject.toml:26](file://pyproject.toml#L26) +- [package.json:8-25](file://package.json#L8-L25) + +**Section Sources** + +- [pyproject.toml:26](file://pyproject.toml#L26) +- [package.json:8-25](file://package.json#L8-L25) + +## Performance Considerations + +- Component lazy loading and on-demand imports: Prioritize importing only required components to reduce initial bundle size. +- Frontend build optimization: Leverage Gradio CLI's build capabilities and caching strategy to shorten incremental build times. +- Rendering concurrency and queues: Set reasonable concurrency and queue sizes in documentation sites and examples to avoid blocking. +- Platform differences: When using Hugging Face Space, pay attention to `ssr_mode` parameter configuration to avoid page rendering anomalies. + +[This section is general guidance and does not involve specific file analysis] + +## Troubleshooting Guide + +- Hugging Face Space page display anomalies + - Symptom: Blank page or components not rendering correctly. + - Fix: Add `ssr_mode=False` parameter in `demo.launch()`. + - Reference: [README.md:32](file://README.md#L32), [README-zh_CN.md:32](file://README-zh_CN.md#L32), [docs/app.py:594](file://docs/app.py#L594) + +- Component import path error + - Symptom: Module or component not found. + - Fix: Verify that the component namespace and import path match, e.g., `modelscope_studio.components.antd`, `modelscope_studio.components.base`, etc. + - Reference: [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) + +- Documentation site development mode + - Symptom: Local development cannot hot-reload or examples are not displayed. + - Fix: Use `gradio cc dev docs/app.py` to start the development server, and ensure the corresponding `app.py` exists in the docs directory. + - Reference: [README.md:96-100](file://README.md#L96-L100), [docs/app.py:10](file://docs/app.py#L10) + +**Section Sources** + +- [README.md:32](file://README.md#L32) +- [README-zh_CN.md:32](file://README-zh_CN.md#L32) +- [docs/app.py:594](file://docs/app.py#L594) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [README.md:96-100](file://README.md#L96-L100) +- [docs/app.py:10](file://docs/app.py#L10) + +## Conclusion + +ModelScope Studio, built on Gradio and integrating the Ant Design and Ant Design X ecosystems, has constructed a complete component system covering base, professional, and Antd/Antdx components. While maintaining Gradio's ease of use, it significantly enhances page layout and component composition capabilities, making it suitable for model application UI development from prototype to production. Through a comprehensive documentation site, version management, and platform adaptation, the project provides clear onboarding paths and stable technical support for both beginners and experienced developers. + +[This section is a summary and does not involve specific file analysis] + +## Appendix + +- Quick Start + - Installation: `pip install modelscope_studio` + - Example: Compose `ms.Application`, `antd.ConfigProvider`, `antd.DatePicker`, and other components within Blocks. + - Reference: [README.md:38-57](file://README.md#L38-L57), [README-zh_CN.md:38-57](file://README-zh_CN.md#L38-L57) + +- Version and Release + - Current version: 2.0.0 + - Release scripts: build, dev, version, ci:\*, etc. + - Reference: [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2), [package.json:8-25](file://package.json#L8-L25) + +**Section Sources** + +- [README.md:38-57](file://README.md#L38-L57) +- [README-zh_CN.md:38-57](file://README-zh_CN.md#L38-L57) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [package.json:8-25](file://package.json#L8-L25) diff --git a/.wiki/en/Project Overview/Project Overview.md b/.wiki/en/Project Overview/Project Overview.md new file mode 100644 index 00000000..f58b0a22 --- /dev/null +++ b/.wiki/en/Project Overview/Project Overview.md @@ -0,0 +1,432 @@ +# Project Overview + + +**Files referenced in this document** +- [README.md](file://README.md) +- [README-zh_CN.md](file://README-zh_CN.md) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/app_context.py](file://backend/modelscope_studio/utils/dev/app_context.py) +- [frontend/package.json](file://frontend/package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) +- [docs/README.md](file://docs/README.md) +- [docs/app.py](file://docs/app.py) +- [docs/FAQ.md](file://docs/FAQ.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +ModelScope Studio is a third-party component library based on Gradio, designed to provide developers with more customizable UI-building capabilities and richer component usage patterns. The project supports both Ant Design and Ant Design X UI ecosystems, and achieves cross-framework component bridging and rendering through a unified Python component interface and a frontend Svelte/React technology stack. + +- Core Goals + - Improve page layout and component flexibility to help build more visually appealing user interfaces + - Maintain good compatibility with native Gradio components to meet diverse interaction needs from simple to complex + - Enhance developer experience and user experience through the Application context and AutoLoading feedback mechanism + +- Key Features + - Three-tier component system: base components, Ant Design components (antd), Ant Design X components (antdx), and Pro components (pro) + - Frontend uses Vite + Svelte + React preprocessing bridge, along with a custom Vite plugin for module aliasing and externalization + - Supports multi-language site and documentation system, covering Chinese, English, and Japanese + +- Use Cases + - Quickly build data visualization and interactive demo pages + - Deploy interactive applications on Hugging Face Space or ModelScope Studio platforms + - Workflows requiring complex forms, tables, charts, and conversational interactions + +- Design Philosophy + - Uses Gradio Blocks as the host, encapsulating frontend Svelte components through Python component wrappers to achieve integrated "Python logic + customizable UI" development + - Provides unified theme, lifecycle, and loading state management through context components such as ConfigProvider, Application, and AutoLoading + +- Relationship with Ant Design / Ant Design X + - antd components map directly to the Ant Design component ecosystem, providing richer layout and interaction capabilities + - antdx components focus on conversational experiences and knowledge workflows, such as Bubble, Sender, ThoughtChain, etc. + - pro components provide professional-grade interaction capabilities, such as Chatbot, Monaco Editor, Web Sandbox, etc. + +- Technical Architecture + - Backend: Python handles component exports and version information; component registration is centralized in the components sub-package + - Frontend: Svelte component tree + React preprocessing bridge; Vite build and plugin inject global variables + - Documentation: Based on the docs site with dynamically loaded component examples, supporting multiple languages and layout templates + +- Development History and Versions + - Current version: 2.0.0 + - License: Apache-2.0 + - Dependency range: Gradio >= 4.43.0 and <= 6.8.0 + +- Usage Recommendations + - When deploying on Hugging Face Space, set `ssr_mode=False` + - Globally include AutoLoading for consistent loading feedback + - To migrate legacy components, simply wrap with `ms.Application` to continue using them + +**Section Sources** + +- [README.md:17-101](file://README.md#L17-L101) +- [README-zh_CN.md:17-101](file://README-zh_CN.md#L17-L101) +- [docs/README.md:32-75](file://docs/README.md#L32-L75) +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) + +## Project Structure + +The project uses a front-end/back-end separated, multi-package collaborative organization: + +- backend/modelscope_studio: Python backend components and packaging configuration +- frontend: Frontend components (Svelte/React) and build configuration +- docs: Documentation site and example applications +- config/scripts: Changesets, publish scripts, and Lint configuration + +```mermaid +graph TB +subgraph "Backend" +PY["Python Package
modelscope_studio"] +CMP["components sub-package
antd/antdx/base/pro"] +VER["version.py
Version"] +end +subgraph "Frontend" +FE_PKG["frontend/package.json
Dependencies & Scripts"] +FE_CFG["defineConfig.js
Vite Config"] +FE_PLG["plugin.js
Vite Plugin"] +FE_ANTD["antd/*
Svelte Components"] +FE_ANTDX["antdx/*
Svelte Components"] +FE_BASE["base/*
Svelte Components"] +FE_PRO["pro/*
Svelte Components"] +end +subgraph "Documentation" +DOCS_APP["docs/app.py
Site Entry"] +DOCS_MD["docs/README.md
Docs Description"] +DOCS_FAQ["docs/FAQ.md
FAQ"] +end +PY --> CMP +PY --> VER +FE_PKG --> FE_ANTD +FE_PKG --> FE_ANTDX +FE_PKG --> FE_BASE +FE_PKG --> FE_PRO +FE_CFG --> FE_PLG +DOCS_APP --> CMP +DOCS_APP --> DOCS_MD +DOCS_APP --> DOCS_FAQ +``` + +**Diagram Sources** + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [docs/app.py:1-200](file://docs/app.py#L1-L200) +- [docs/README.md:1-75](file://docs/README.md#L1-L75) +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) + +**Section Sources** + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:1-200](file://docs/app.py#L1-L200) + +## Core Components + +- Component Categories + - antd: Covers the full range of Ant Design component families including general, layout, navigation, data entry, data display, feedback, etc. + - antdx: Component family oriented toward conversational experience, such as Bubble, Sender, ThoughtChain, Prompts, etc. + - base: Basic layout and rendering utility components, such as Application, AutoLoading, Slot, Fragment, Each, Filter, Markdown, etc. + - pro: Professional interaction components, such as Chatbot, Monaco Editor, Web Sandbox, Multimodal Input, etc. + +- Exports and Aggregation + - The backend `components/__init__.py` centralizes exports of antd, antdx, base, and pro components, making it easy to import by namespace + - `antd/components.py` and `antdx/components.py` respectively list component classes for each sub-module, forming a unified Python API + +- Key Context Components + - Application: Application-level context used to establish the component tree and lifecycle management + - AutoLoading: Automatic loading feedback component, ensuring interactive operations have consistent loading indicators + - ConfigProvider: Theme and internationalization configuration provider, spanning the antd component tree + +- Development Base Classes + - ModelScopeComponent / ModelScopeLayoutComponent / ModelScopeDataLayoutComponent: Provide unified lifecycle, slot, and rendering control for components + +**Section Sources** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +## Architecture Overview + +The overall architecture revolves around "Python component → frontend Svelte component → Gradio rendering". The frontend maps React/antd/antdx and other dependencies to global variables via Vite plugins, reducing bundle size and improving loading efficiency. + +```mermaid +graph TB +PY_API["Python Component API
components.antd / antdx / base / pro"] +APP_CTX["Application Context
AppContext"] +AUTOLOAD["AutoLoading
Loading Feedback"] +CFG["ConfigProvider
Theme/i18n"] +subgraph "Frontend Build" +VITE["Vite Build"] +PLG["ModelScopeStudioVitePlugin
Externalization & Aliases"] +REACT["React Global Mapping"] +ANTD["antd/antdx Global Mapping"] +end +subgraph "Component Implementation" +SVELTE["Svelte Component Tree"] +UTILS["Utility Functions & Context"] +end +PY_API --> VITE +APP_CTX --> PY_API +AUTOLOAD --> PY_API +CFG --> PY_API +VITE --> PLG +PLG --> REACT +PLG --> ANTD +REACT --> SVELTE +ANTD --> SVELTE +UTILS --> SVELTE +``` + +**Diagram Sources** + +- [backend/modelscope_studio/utils/dev/app_context.py:1-25](file://backend/modelscope_studio/utils/dev/app_context.py#L1-L25) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## Detailed Component Analysis + +### Component Class Hierarchy + +The following class diagram shows the relationship between backend component base classes and their typical derived components, reflecting unified lifecycle and rendering strategies. + +```mermaid +classDiagram +class Component +class BlockContext +class ComponentMeta +class ModelScopeComponent { ++EVENTS ++skip_api ++__init__(...) +} +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__(...) ++__init__(...) +} +class ModelScopeDataLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__(...) ++__init__(...) +} +ModelScopeComponent --|> Component +ModelScopeLayoutComponent --|> BlockContext +ModelScopeLayoutComponent --|> Component +ModelScopeDataLayoutComponent --|> ModelScopeComponent +ModelScopeDataLayoutComponent --|> BlockContext +``` + +**Diagram Sources** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +**Section Sources** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +### Documentation Site and Example Loading Flow + +The documentation site dynamically scans `app.py` for each component under `docs/components`, aggregates them to generate the sidebar and documentation content, and supports layout templates and multi-language switching. + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant Docs as "docs/app.py" +participant FS as "File System" +participant Comp as "Component app.py" +participant Site as "Site Renderer" +Dev->>Docs : Launch gradio cc dev docs/app.py +Docs->>FS : Scan layout_templates and components +FS-->>Docs : Return component directory list +loop Iterate components +Docs->>Comp : Dynamically import app.py +Comp-->>Docs : Return docs dictionary +end +Docs->>Site : Render menu and documentation content +Site-->>Dev : Display component examples and descriptions +``` + +**Diagram Sources** + +- [docs/app.py:19-61](file://docs/app.py#L19-L61) + +**Section Sources** + +- [docs/app.py:19-61](file://docs/app.py#L19-L61) + +### Frontend Build and Module Externalization + +The frontend uses a custom Vite plugin to map React, antd, antdx, and other dependencies to global variables, avoiding repeated bundling. Externalization is performed during the build phase to reduce artifact size. + +```mermaid +flowchart TD +Start(["Start"]) --> ReadCfg["Read defineConfig.js"] +ReadCfg --> InitPlugin["Initialize ModelScopeStudioVitePlugin"] +InitPlugin --> Build{"Build command?"} +Build --> |Yes| ExtDeps["Collect global mapping dependencies"] +Build --> |No| Alias["Configure aliases and resolution rules"] +ExtDeps --> RollupExt["Rollup externalization"] +Alias --> Transform["Traverse AST and replace import statements"] +Transform --> Emit["Output transformed code"] +RollupExt --> Emit +Emit --> End(["End"]) +``` + +**Diagram Sources** + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:41-168](file://frontend/plugin.js#L41-L168) + +**Section Sources** + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) + +### Component Namespaces and Import Conventions + +- On the Python side, import corresponding components via `modelscope_studio.components.antd`, `antdx`, `base`, `pro` +- It is recommended to wrap the outermost layer of your application with `ms.Application` to enable context and lifecycle management +- For legacy components, they can also be used by wrapping with `ms.Application` + +**Section Sources** + +- [README.md:49-78](file://README.md#L49-L78) +- [docs/README.md:64-75](file://docs/README.md#L64-L75) + +## Dependency Analysis + +- Python Side + - Dependencies: Gradio (version range constrained) + - Optional dependencies: Build and release-related tools + - Packaging: Built with hatchling; artifact list includes many component template resources + +- Frontend Side + - Dependencies: antd, @ant-design/x, @gradio/\*, monaco-editor, svelte, react, etc. + - Build: Vite + React-SWC + Less; plugin handles externalization and alias replacement + +- Documentation and Site + - Based on `docs/app.py` dynamically loading component examples; supports multiple languages and layout templates + +```mermaid +graph LR +PY["pyproject.toml
Dependencies & Packaging"] +FE["frontend/package.json
Dependencies & Scripts"] +DOC["docs/app.py
Example Loading"] +GR["Gradio
Version Constraint"] +PY --> GR +FE --> ANTD["antd"] +FE --> REACT["react"] +FE --> SVLT["svelte"] +DOC --> PY +DOC --> FE +``` + +**Diagram Sources** + +- [pyproject.toml:26](file://pyproject.toml#L26) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [docs/app.py:19-61](file://docs/app.py#L19-L61) + +**Section Sources** + +- [pyproject.toml:9-43](file://pyproject.toml#L9-L43) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:19-61](file://docs/app.py#L19-L61) + +## Performance Considerations + +- Frontend Externalization and Aliasing + - Maps React, antd, antdx, etc. to global variables via Vite plugin, reducing repeated bundling and size + - Rollup externalization during build phase further reduces artifact size + +- Component Loading Feedback + - AutoLoading provides unified loading placeholders, improving perceived performance during interaction delays + - It is recommended to include AutoLoading at least once globally to avoid missing Gradio's default loading state + +- Documentation and Examples + - `docs/app.py` uses on-demand dynamic imports of component `app.py`, reducing initial load pressure + +**Section Sources** + +- [frontend/plugin.js:41-168](file://frontend/plugin.js#L41-L168) +- [docs/FAQ.md:7-20](file://docs/FAQ.md#L7-L20) +- [docs/app.py:19-61](file://docs/app.py#L19-L61) + +## Troubleshooting Guide + +- Hugging Face Space page not displaying or style anomalies + - Solution: Add `ssr_mode=False` parameter in `demo.launch()` + +- Slow operation response or no feedback + - Cause: Independent loading feedback mechanism of each component and waiting time caused by Gradio frontend/backend communication + - Solution: Globally include the AutoLoading component to ensure loading state is visible + +- Missing Application context warning + - Symptom: A warning is triggered when the outermost layer is not wrapped with `ms.Application` + - Solution: Wrap with `ms.Application` at the outermost layer + +**Section Sources** + +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) +- [backend/modelscope_studio/utils/dev/app_context.py:16-21](file://backend/modelscope_studio/utils/dev/app_context.py#L16-L21) +- [README.md:32](file://README.md#L32) + +## Conclusion + +ModelScope Studio, with Gradio as its core, combines the rich component ecosystems of Ant Design and Ant Design X to provide an integrated solution from basic layout to professional interactions. Through a unified Python component API, frontend Svelte/React bridging, and Vite plugin optimizations, the project strikes a balance between ease of use and performance. For beginners, it is recommended to start with base components and Application/AutoLoading; for experienced developers, exploring antdx and pro components can quickly build conversational and professional-grade interactive applications. + +## Appendix + +- Version and License + - Version: 2.0.0 + - License: Apache-2.0 + - Author: ModelScope team + +- Installation and Quick Start + - Install `modelscope_studio` via pip + - Use `modelscope_studio.components.antd` and `modelscope_studio.components.base` within Blocks + +- Development and Contributing + - Backend installation: `pip install -e '.'` + - Frontend installation: `pnpm install` + - Build: `pnpm build` + - Start documentation: `gradio cc dev docs/app.py` + +**Section Sources** + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:9-43](file://pyproject.toml#L9-L43) +- [README.md:38-101](file://README.md#L38-L101) +- [README-zh_CN.md:38-101](file://README-zh_CN.md#L38-L101) diff --git a/.wiki/en/Project Overview/Tech Stack.md b/.wiki/en/Project Overview/Tech Stack.md new file mode 100644 index 00000000..274979ce --- /dev/null +++ b/.wiki/en/Project Overview/Tech Stack.md @@ -0,0 +1,397 @@ +# Tech Stack + + +**Files referenced in this document** +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [frontend/package.json](file://frontend/package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) +- [frontend/tsconfig.json](file://frontend/tsconfig.json) +- [svelte-tsconfig.json](file://svelte-tsconfig.json) +- [docs/app.py](file://docs/app.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [config/lint-config/package.json](file://config/lint-config/package.json) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is aimed at developers and maintainers of the ModelScope Studio project. It systematically reviews and explains the project's technology stack and architecture design, with key coverage of: + +- Python backend tech stack: Gradio 6.0–6.8.0, component library organization and packaging strategy +- Frontend tech stack: Svelte 5.55.2, Ant Design 6.3.5, Ant Design X, React 19.2.4, Vite build and plugin system +- Monorepo architecture: Workspace division, package management and build process +- Development toolchain: ESLint, Stylelint, Prettier, TypeScript, Svelte checking +- Testing and release: Changeset version management, PyPI publish scripts +- Best practices: Component architecture, plugin system, build optimization and error handling + +## Project Structure + +ModelScope Studio uses a Monorepo architecture, where the root directory manages multiple sub-packages and configuration modules through the pnpm workspace. The frontend is built around Svelte, combined with the React ecosystem and Ant Design/Ant Design X component system; the backend is based on Gradio's custom component mechanism, providing rich UI components and advanced capabilities. + +```mermaid +graph TB +Root["Repository Root"] --> Frontend["Frontend Packages
frontend/"] +Root --> Backend["Python Package
backend/modelscope_studio/"] +Root --> Config["Configuration & Toolchain
config/"] +Root --> Docs["Documentation Site
docs/"] +Root --> Scripts["Scripts & Release
scripts/"] +Frontend --> Antd["Antd Component Collection
frontend/antd/"] +Frontend --> Antdx["AntdX Component Collection
frontend/antdx/"] +Frontend --> Pro["Pro Advanced Components
frontend/pro/"] +Frontend --> Base["Base Components
frontend/base/"] +Frontend --> Utils["Utilities & Aliases
frontend/utils/"] +Frontend --> Plugin["Vite Plugin
frontend/plugin.js"] +Frontend --> Define["Vite Config Factory
frontend/defineConfig.js"] +Backend --> PyPkg["Python Packaging Config
pyproject.toml"] +Backend --> Version["Version
backend/modelscope_studio/version.py"] +Backend --> Components["Component Export Entry
backend/modelscope_studio/components/antd/__init__.py"] +Backend --> DevUtil["Dev Utilities & Context
backend/modelscope_studio/utils/dev/component.py"] +Docs --> AppPy["Documentation App Entry
docs/app.py"] +Config --> Lint["Lint Config Package
config/lint-config/package.json"] +``` + +Diagram Sources + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +Section Sources + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## Core Components + +- Python Backend + - Gradio 6.0–6.8.0: The foundational framework for component runtime and page rendering, responsible for component lifecycle, events, and state management. + - Component organization: Split into antd, antdx, pro, base four namespaces by functional domain for on-demand imports and documentation generation. + - Packaging and distribution: Built with Hatchling; artifacts explicitly export each component's template resources; wheel contains only the backend package path. +- Frontend + - Svelte 5.55.2: Component compiler and runtime with smaller footprint and faster hot-reload experience. + - Ant Design 6.3.5 and Ant Design X: The former provides general UI capabilities; the latter focuses on conversational and collaborative scenarios. + - React 19.2.4: Bridges the React ecosystem through Vite plugin, enabling mixed use with Svelte and sharing global objects. + - Vite build: Uses custom plugins for externalization and alias mapping to reduce artifact size and improve loading efficiency. +- Documentation and Site + - docs/app.py: Dynamically scans components and layout templates to generate a multi-tab documentation site, supporting Chinese/English switching and theming. + +Section Sources + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## Architecture Overview + +The overall architecture consists of "frontend component layer + backend component layer + documentation & toolchain." The frontend externalizes React/AntD and other dependencies to host globals via Vite plugin; Svelte components consume them directly in the browser; the backend registers Python components as reusable modules through Gradio, and renders and demos them in the documentation site. + +```mermaid +graph TB +subgraph "Frontend" +Svelte["Svelte 5.55.2"] +Antd["Antd 6.3.5"] +Antdx["AntdX"] +React["React 19.2.4"] +Vite["Vite Build"] +Plugin["ModelScopeStudioVitePlugin"] +end +subgraph "Backend" +Gradio["Gradio 6.0–6.8.0"] +PyPkg["Python Packaging (Hatchling)"] +Components["Component Exports (antd/antdx/pro/base)"] +end +subgraph "Documentation & Tools" +DocsApp["docs/app.py"] +LintCfg["Lint Config Package"] +end +Svelte --> Antd +Svelte --> Antdx +React --> Antd +Vite --> Plugin +Plugin --> React +Plugin --> Antd +Gradio --> Components +PyPkg --> Components +DocsApp --> Gradio +DocsApp --> Components +LintCfg --> Vite +``` + +Diagram Sources + +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [config/lint-config/package.json:1-48](file://config/lint-config/package.json#L1-L48) + +## Detailed Component Analysis + +### Frontend Vite Plugin and Build Optimization + +The plugin is responsible for: + +- Externalizing React, Ant Design, AntdX, dayjs, monaco-loader, and other dependencies as `window.ms_globals.*`, avoiding repeated bundling +- Setting `define` constants at build stage to ensure consistent production environment behavior +- Simplifying import paths through alias mapping of `@utils`, `@globals`, `svelte-preprocess-react` +- Transforming import/export declarations in the `renderChunk` stage to rewrite module references as global accesses, reducing runtime overhead + +```mermaid +flowchart TD +Start(["Start Build"]) --> ReadConfig["Read Vite Config"] +ReadConfig --> SetDefine["Set define constants"] +SetDefine --> AliasMap["Configure aliases (@utils/@globals/svelte-preprocess-react)"] +AliasMap --> Externalize{"Externalization enabled?"} +Externalize --> |Yes| RollupExt["Rollup externalization config"] +Externalize --> |No| SkipExt["Skip externalization"] +RollupExt --> Transform["Transform import/export in renderChunk"] +SkipExt --> Transform +Transform --> Output(["Output optimized artifacts"]) +``` + +Diagram Sources + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:41-168](file://frontend/plugin.js#L41-L168) + +Section Sources + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) + +### Component Exports and Namespaces + +- antd: Covers the official Ant Design component system, split by module, providing full types and template resources +- antdx: Extended component collection for conversational and collaborative scenarios, such as Bubble, Conversations, Sender, etc. +- pro: Advanced business components, such as Chatbot, Monaco Editor, Web Sandbox +- base: Basic rendering and layout components, such as Application, AutoLoading, Slot, Fragment, Each, Filter, Markdown, etc. + +```mermaid +graph LR +A["antd/*"] --> ExportA["__init__.py Exports"] +B["antdx/*"] --> ExportB["components.py Exports"] +C["pro/*"] --> ExportC["Standalone Package/Templates"] +D["base/*"] --> ExportD["components.py Exports"] +ExportA --> PyPkg["pyproject.toml artifacts"] +ExportB --> PyPkg +ExportC --> PyPkg +ExportD --> PyPkg +``` + +Diagram Sources + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) + +Section Sources + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) + +### Documentation Site and Dynamic Routing + +`docs/app.py` dynamically scans components and layout templates to build a multi-tab documentation site: + +- Supports Chinese/English content switching +- Generates menu and documentation index for each component +- Renders unified entry point via Site; optimizes queue and concurrency parameters + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant App as "docs/app.py" +participant Scan as "Dynamic Scanner" +participant Site as "Site Renderer" +participant Gradio as "Gradio Runtime" +Dev->>App : Start development server +App->>Scan : Scan components and layout templates +Scan-->>App : Return component and template manifest +App->>Site : Build menu and documentation index +Site->>Gradio : Register components and pages +Gradio-->>Dev : Display documentation site +``` + +Diagram Sources + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +Section Sources + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +### Component Base Classes and Context + +The backend provides three types of component base classes for unified lifecycle, slot, and rendering control: + +- ModelScopeComponent: Standard component base class, supporting events, visibility, styles, and other properties +- ModelScopeLayoutComponent: Layout component base class, supporting BlockContext and internal layout markers +- ModelScopeDataLayoutComponent: Mixed data and layout component, inheriting component and context capabilities + +```mermaid +classDiagram +class ModelScopeComponent { ++EVENTS ++skip_api ++__init__(...) ++elem_style ++as_item +} +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++__exit__(...) ++__init__(...) ++elem_style ++as_item +} +class ModelScopeDataLayoutComponent { ++EVENTS ++SLOTS ++__exit__(...) ++__init__(...) ++preserved_by_key +} +ModelScopeDataLayoutComponent --|> ModelScopeComponent +ModelScopeDataLayoutComponent --|> BlockContext +``` + +Diagram Sources + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +Section Sources + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +## Dependency Analysis + +- Frontend dependencies + - React and Ant Design: Externalized via Vite plugin to reduce bundle size + - Svelte 5.55.2: Core compiler and runtime + - Ant Design X: Provides conversational and collaborative component ecosystem + - Monaco Editor and React ecosystem: For code editing and highlighting +- Backend dependencies + - Gradio 6.0–6.8.0: Component runtime and page rendering + - Build tools: Hatchling, Hatch-requirements-txt, Fancy-PyPI-Readme + - artifacts explicitly export each component template; wheel contains only the backend path +- Toolchain + - ESLint, Stylelint, Prettier, TypeScript, Svelte checking + - Changesets for version management and change tracking + +```mermaid +graph TB +subgraph "Frontend" +R["React 19.2.4"] +AD["Antd 6.3.5"] +AFX["@ant-design/x 2.5.0"] +SV["Svelte 5.55.2"] +ME["Monaco Editor"] +VR["Vite + Plugin"] +end +subgraph "Backend" +GR["Gradio 6.0–6.8.0"] +HN["Hatchling"] +ART["artifacts Template Exports"] +end +R --> AD +R --> AFX +SV --> AD +SV --> AFX +VR --> R +VR --> SV +GR --> ART +HN --> ART +``` + +Diagram Sources + +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) +- [frontend/plugin.js:5-20](file://frontend/plugin.js#L5-L20) + +Section Sources + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) + +## Performance Considerations + +- Externalization strategy: Externalizing React, Antd, AntdX, and other dependencies via Vite plugin significantly reduces frontend bundle size and initial load time +- Build target: ESNext module target, leveraging modern browser features to reduce transpilation costs +- Component templates: Backend accurately exports template resources via artifacts, avoiding redundant files in the wheel +- Concurrency and queues: Set queue and concurrency limits at documentation site startup to ensure demo stability + +Section Sources + +- [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) +- [docs/app.py:592-595](file://docs/app.py#L592-L595) + +## Troubleshooting Guide + +- Build failure or externalization anomalies + - Check whether the Vite plugin correctly configures externals and aliases + - Confirm that the global variable `window.ms_globals` exposes the required modules +- Component not displaying or style missing + - Verify that artifact paths and template exports match + - Ensure Gradio version is within the 6.0–6.8.0 range +- Documentation site fails to start + - Check the scanning logic and menu building in `docs/app.py` + - Confirm that the component's `app.py` exists and contains the `docs` field +- Lint or formatting errors + - Use the unified lint configuration package to ensure consistent rules + - Prioritize running formatting and type checking before ESLint/Stylelint + +Section Sources + +- [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) +- [docs/app.py:19-61](file://docs/app.py#L19-L61) +- [config/lint-config/package.json:1-48](file://config/lint-config/package.json#L1-L48) + +## Conclusion + +ModelScope Studio uses a Monorepo as its backbone, with the frontend powered by dual Svelte and React engines, and the backend based on Gradio, forming a reusable "component as a service" ecosystem. Through Vite plugin externalization and alias mapping, precise artifact exports, and a unified Lint/formatting toolchain, the project achieves balance in maintainability, performance, and developer experience. It is recommended to continuously improve component documentation and automated testing in subsequent iterations to further enhance delivery quality and team collaboration efficiency. + +## Appendix + +- Version and Meta Information + - Repository version: 2.0.0 + - Python package version: Aligned with repository version +- Key Configuration References + - Frontend workspace and dependencies: [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + - Python packaging and exports: [pyproject.toml:45-257](file://pyproject.toml#L45-L257) + - Workspace declaration: [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) + - TypeScript and Svelte configuration: [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8), [svelte-tsconfig.json:1-4](file://svelte-tsconfig.json#L1-L4) + - Documentation site entry: [docs/app.py:1-595](file://docs/app.py#L1-L595) + - Lint configuration package: [config/lint-config/package.json:1-48](file://config/lint-config/package.json#L1-L48) diff --git a/.wiki/en/Project Overview/Use Cases.md b/.wiki/en/Project Overview/Use Cases.md new file mode 100644 index 00000000..ba58f24d --- /dev/null +++ b/.wiki/en/Project Overview/Use Cases.md @@ -0,0 +1,337 @@ +# Use Cases + + +**Files Referenced in This Document** +- [README-zh_CN.md](file://README-zh_CN.md) +- [README.md](file://README.md) +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [frontend/pro/package.json](file://frontend/pro/package.json) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [frontend/pro/chatbot/Index.svelte](file://frontend/pro/chatbot/Index.svelte) +- [frontend/pro/multimodal-input/Index.svelte](file://frontend/pro/multimodal-input/Index.svelte) +- [frontend/pro/web-sandbox/Index.svelte](file://frontend/pro/web-sandbox/Index.svelte) +- [frontend/pro/monaco-editor/Index.svelte](file://frontend/pro/monaco-editor/Index.svelte) +- [docs/layout_templates/chatbot/README-zh_CN.md](file://docs/layout_templates/chatbot/README-zh_CN.md) +- [docs/layout_templates/coder_artifacts/README-zh_CN.md](file://docs/layout_templates/coder_artifacts/README-zh_CN.md) +- [docs/demos/example.py](file://docs/demos/example.py) +- [docs/README-zh_CN.md](file://docs/README-zh_CN.md) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +ModelScope Studio is a third-party component library built on Gradio, providing developers with more customizable interface-building capabilities and richer component usage patterns. It supports both the Ant Design and Ant Design X UI ecosystems, and offers Pro scenario-specific components (such as chatbot, multimodal input, code editor, web sandbox, etc.), making it ideal for rapidly building professional-grade frontends in machine learning and AI applications. + +- Compared to Gradio's native components, ModelScope Studio emphasizes page layout flexibility and component richness, making it suitable for projects that prioritize visual and interactive experiences. +- When an application requires extensive built-in data processing on the Python side, it can be combined with Gradio's native components; ModelScope Studio serves as an optimization layer to enhance frontend presentation. +- When deploying in Hugging Face Space, set `ssr_mode=False` in `demo.launch()` to avoid page rendering issues. + +Section Sources + +- [README-zh_CN.md:26-32](file://README-zh_CN.md#L26-L32) +- [README.md:26-32](file://README.md#L26-L32) + +## Project Structure + +The project adopts a frontend-backend separation with a multi-package organization: + +- Backend Python package: Provides component exports and version information, uniformly exposing component collections. +- Frontend Svelte packages: Split into sub-packages by module — antd, antdx, base, pro — corresponding to UI components, base capabilities, and Pro scenario components. +- Documentation and examples: Contains component documentation, layout templates, and demo scripts for rapid onboarding. + +```mermaid +graph TB +subgraph "Backend" +PY_PKG["Python Package
backend/modelscope_studio"] +PY_INIT["__init__.py"] +PY_VER["version.py"] +end +subgraph "Frontend" +FE_ANTD["@modelscope-studio/antd
package.json"] +FE_PRO["@modelscope-studio/pro
package.json"] +FE_BASE["base components"] +FE_ANTDX["antdx components"] +end +PY_PKG --> PY_INIT +PY_PKG --> PY_VER +PY_PKG --> FE_ANTD +PY_PKG --> FE_PRO +PY_PKG --> FE_BASE +PY_PKG --> FE_ANTDX +``` + +Diagram Sources + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) + +Section Sources + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) + +## Core Components + +- Ant Design component family: Covers a full-chain UI component set for forms, layouts, feedback, navigation, data entry, and display, meeting standard business interface needs. +- Pro scenario-specific components: Dedicated components for AI/ML applications, including chatbot, multimodal input, code editor, and web sandbox. +- Base components: Provides common capabilities such as application context, auto-loading, text/paragraph/slot, supporting complex layouts and dynamic rendering. + +Section Sources + +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [docs/README-zh_CN.md:14-26](file://docs/README-zh_CN.md#L14-L26) + +## Architecture Overview + +ModelScope Studio's frontend components are implemented in Svelte and bridge React components into the Svelte context via `@svelte-preprocess-react`, enabling seamless integration with Gradio. Pro components further encapsulate logic for sharing state with Gradio (such as theme, API prefix, root path), ensuring stability across different deployment environments. + +```mermaid +graph TB +GR["Gradio App"] +MS_APP["ms.Application
App Context"] +CFG["antd.ConfigProvider
Config Provider"] +AUTOLOAD["ms.AutoLoading
Auto Loading"] +CHAT["Pro Chatbot
chatbot"] +MM["Pro Multimodal Input
multimodal-input"] +EDIT["Pro Code Editor
monaco-editor"] +SANDBOX["Pro Web Sandbox
web-sandbox"] +GR --> MS_APP --> CFG --> AUTOLOAD +MS_APP --> CHAT +MS_APP --> MM +MS_APP --> EDIT +MS_APP --> SANDBOX +``` + +Diagram Sources + +- [docs/demos/example.py:5-10](file://docs/demos/example.py#L5-L10) +- [frontend/pro/chatbot/Index.svelte:12-88](file://frontend/pro/chatbot/Index.svelte#L12-L88) +- [frontend/pro/multimodal-input/Index.svelte:13-96](file://frontend/pro/multimodal-input/Index.svelte#L13-L96) +- [frontend/pro/monaco-editor/Index.svelte:12-98](file://frontend/pro/monaco-editor/Index.svelte#L12-L98) +- [frontend/pro/web-sandbox/Index.svelte:12-74](file://frontend/pro/web-sandbox/Index.svelte#L12-L74) + +## Detailed Component Analysis + +### Pro Chatbot + +- Use cases: AI chatbot interfaces, multi-turn conversation management, conversation history editing/retry/deletion, interruption prompts, input suggestions, attachment uploads, etc. +- Key features: Supports concurrent multi-session management, fine-grained history control, input suggestion triggers, attachment upload limits and format restrictions. +- Usage recommendations: Combine Gradio shared state and theme configuration to ensure consistent appearance and behavior across different deployment environments. + +```mermaid +sequenceDiagram +participant U as "User" +participant C as "Pro Chatbot" +participant G as "Gradio Shared State" +U->>C : Input message / trigger suggestion +C->>G : Read theme / API prefix / root path +C->>U : Display conversation / history / suggestions +U->>C : Interrupt / clear / edit / retry +C->>G : Update state and re-render +``` + +Diagram Sources + +- [frontend/pro/chatbot/Index.svelte:67-88](file://frontend/pro/chatbot/Index.svelte#L67-L88) +- [docs/layout_templates/chatbot/README-zh_CN.md:7-11](file://docs/layout_templates/chatbot/README-zh_CN.md#L7-L11) + +Section Sources + +- [frontend/pro/chatbot/Index.svelte:12-88](file://frontend/pro/chatbot/Index.svelte#L12-L88) +- [docs/layout_templates/chatbot/README-zh_CN.md:1-20](file://docs/layout_templates/chatbot/README-zh_CN.md#L1-L20) + +### Pro Multimodal Input + +- Use cases: Interfaces in AI applications that require simultaneous text and multimedia (images/files) input, such as image description, document Q&A, code generation, etc. +- Key features: Supports file uploads, paste uploads, value change callbacks, and Gradio client integration. +- Usage recommendations: Set reasonable upload count and format restrictions, and combine with backend processing to ensure security and performance. + +```mermaid +flowchart TD +Start(["Enter Component"]) --> CheckVisible{"Is Visible?"} +CheckVisible --> |No| End(["Exit"]) +CheckVisible --> |Yes| Upload["File Upload / Paste"] +Upload --> Prepare["Prepare File Data"] +Prepare --> CallAPI["Call Gradio Client Upload"] +CallAPI --> Update["Update Component Value"] +Update --> Render["Render Output"] +Render --> End +``` + +Diagram Sources + +- [frontend/pro/multimodal-input/Index.svelte:68-96](file://frontend/pro/multimodal-input/Index.svelte#L68-L96) + +Section Sources + +- [frontend/pro/multimodal-input/Index.svelte:13-96](file://frontend/pro/multimodal-input/Index.svelte#L13-L96) + +### Pro Monaco Editor + +- Use cases: AI assistant/code generation tools, online IDE previews, code comparison and diff editing. +- Key features: Supports CDN/local loader modes, theme adaptation, value change callbacks, slot extensions. +- Usage recommendations: Choose the appropriate loader mode based on the deployment environment to avoid cross-origin and resource loading issues. + +```mermaid +sequenceDiagram +participant E as "Monaco Editor" +participant L as "Loader" +participant P as "Props Handler" +participant G as "Gradio Theme" +E->>P : Get component props +P->>E : Pass style / className / ID / value +E->>L : Initialize loader (CDN/Local) +L-->>E : Loading complete +E->>G : Read theme mode +E-->>P : Trigger value change callback +``` + +Diagram Sources + +- [frontend/pro/monaco-editor/Index.svelte:61-89](file://frontend/pro/monaco-editor/Index.svelte#L61-L89) + +Section Sources + +- [frontend/pro/monaco-editor/Index.svelte:12-98](file://frontend/pro/monaco-editor/Index.svelte#L12-L98) + +### Pro Web Sandbox + +- Use cases: Online preview/debug of HTML/CSS/JS snippets, suitable for AI-assisted development and teaching demos. +- Key features: Compile error/success events, render error events, theme mode adaptation, slot extensions. +- Usage recommendations: Strictly control sandbox content and permissions to avoid executing untrusted code. + +```mermaid +flowchart TD +Enter(["Enter Sandbox"]) --> Load["Load Content"] +Load --> Compile{"Compile Successful?"} +Compile --> |No| OnError["Trigger Compile Error Event"] +Compile --> |Yes| Render["Render Output"] +Render --> Done["Complete"] +OnError --> Done +``` + +Diagram Sources + +- [frontend/pro/web-sandbox/Index.svelte:60-74](file://frontend/pro/web-sandbox/Index.svelte#L60-L74) + +Section Sources + +- [frontend/pro/web-sandbox/Index.svelte:12-74](file://frontend/pro/web-sandbox/Index.svelte#L12-L74) + +### Ant Design Component Family + +- Use cases: General business interface construction, such as form filling, list display, pagination navigation, notification reminders, etc. +- Key features: Covers a complete component matrix aligned with the UI design system, supporting internationalization and theme switching. +- Usage recommendations: Use ConfigProvider for global configuration, combined with AutoLoading to improve initial screen experience. + +Section Sources + +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [docs/demos/example.py:5-10](file://docs/demos/example.py#L5-L10) + +## Dependency Analysis + +- Version and naming: Both `@modelscope-studio/antd` and `@modelscope-studio/pro` frontend packages are labeled `2.0.0`, and the backend `version.py` also points to the same semantic version, ensuring frontend-backend consistency. +- Integration with Gradio: Components render and interact through Gradio shared state (root, api_prefix, theme), ensuring consistency across different deployment environments (including Hugging Face Space). +- Deployment notes: When deploying in Hugging Face Space, set `ssr_mode=False` in `demo.launch()` to avoid SSR-related page rendering issues. + +```mermaid +graph LR +VER["version.py
2.0.0"] +ANTDPKG["@modelscope-studio/antd
2.0.0"] +PROPkg["@modelscope-studio/pro
2.0.0"] +VER --> ANTDPKG +VER --> PROPkg +``` + +Diagram Sources + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) + +Section Sources + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) +- [README-zh_CN.md:32](file://README-zh_CN.md#L32) +- [README.md:32](file://README.md#L32) + +## Performance Considerations + +- On-demand loading and lazy loading: Pro components universally adopt `importComponent` and dynamic `import` to reduce initial bundle size and first-screen blocking. +- Theme and resources: Monaco Editor supports CDN/local loaders, which can be chosen based on network and security policies to avoid unnecessary resource downloads. +- File uploads: The multimodal input component uploads files through the Gradio client; it is recommended to limit file size and type on the frontend to reduce backend pressure. +- SSR note: Disable SSR in Hugging Face Space to avoid compatibility issues caused by server-side rendering. + +Section Sources + +- [frontend/pro/monaco-editor/Index.svelte:61-70](file://frontend/pro/monaco-editor/Index.svelte#L61-L70) +- [frontend/pro/multimodal-input/Index.svelte:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) +- [README-zh_CN.md:32](file://README-zh_CN.md#L32) +- [README.md:32](file://README.md#L32) + +## Troubleshooting Guide + +- Page not displayed or rendering abnormally: Add `ssr_mode=False` to `demo.launch()`, especially in Hugging Face Space environments. +- Component not visible: Check the component's `visible` property and parent container layout; confirm that `ms.Application` wrapping level is correct. +- Editor loading failure: Confirm the `_loader` configuration (cdn/local) and `cdn_url` are valid; avoid cross-origin and resource path issues. +- Upload failure: Check file type and count limits; confirm the Gradio client upload interface is available. + +Section Sources + +- [README-zh_CN.md:32](file://README-zh_CN.md#L32) +- [README.md:32](file://README.md#L32) +- [frontend/pro/monaco-editor/Index.svelte:61-70](file://frontend/pro/monaco-editor/Index.svelte#L61-L70) +- [frontend/pro/multimodal-input/Index.svelte:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) + +## Conclusion + +ModelScope Studio provides a highly customizable, high-performance frontend interface solution for machine learning and AI applications through Ant Design and Pro scenario-specific components. It excels in the following areas: + +- Deep integration with Gradio, simplifying the frontend development workflow for AI applications. +- Provides AI-oriented specialized components including chatbot, multimodal input, code editor, and web sandbox, covering common business scenarios. +- Supports flexible theme and internationalization configuration, adapting to multiple deployment environments. + +When to choose: + +- Need to build visually appealing, interaction-rich AI application interfaces. +- Need scenario-specific capabilities such as multimodal input, conversation management, code editing, and online preview. +- Have differentiated deployment requirements (e.g., Hugging Face Space) that require SSR control. + +When not to choose: + +- The application requires extensive built-in data processing and computation on the Python side; prefer Gradio's native components. +- Extremely sensitive to frontend performance and resource usage, and do not require complex UI or interactions. + +## Appendix + +- Quick start example: Use `ms.Application`, `antd.ConfigProvider`, and `ms.AutoLoading` to wrap components inside Blocks, then launch the demo. +- Layout templates: The chatbot and Coder Artifacts templates provide out-of-the-box scenario-specific interfaces. + +Section Sources + +- [docs/demos/example.py:5-10](file://docs/demos/example.py#L5-L10) +- [docs/layout_templates/chatbot/README-zh_CN.md:1-20](file://docs/layout_templates/chatbot/README-zh_CN.md#L1-L20) +- [docs/layout_templates/coder_artifacts/README-zh_CN.md:1-8](file://docs/layout_templates/coder_artifacts/README-zh_CN.md#L1-L8) diff --git a/.wiki/en/Project Overview/Version Info.md b/.wiki/en/Project Overview/Version Info.md new file mode 100644 index 00000000..60d2bb50 --- /dev/null +++ b/.wiki/en/Project Overview/Version Info.md @@ -0,0 +1,335 @@ +# Version Info + + +**Files Referenced in This Document** +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [CHANGELOG.md](file://CHANGELOG.md) +- [.changeset/config.json](file://.changeset/config.json) +- [.changeset/pre.json](file://.changeset/pre.json) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [scripts/create-tag-n-release.mts](file://scripts/create-tag-n-release.mts) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) +- [config/changelog/src/index.ts](file://config/changelog/src/index.ts) +- [README.md](file://README.md) +- [docs/FAQ.md](file://docs/FAQ.md) + + +## Update Summary + +**Changes** + +- Version number updated from 2.0.0-beta.0 to 2.0.0 +- Gradio dependency version requirement updated to standard syntax format +- Updated changelog to reflect features of 2.0.0 + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This document is intended for ModelScope Studio users and maintainers, systematically organizing project version information, including version history, current version status, upgrade paths, compatibility policies, long-term support and support lifecycle, known issues and security updates, how to view changelogs, and release frequency. In particular, for the major changes and migration paths in version 1.0, it provides actionable upgrade steps and best practices. + +## Project Structure + +ModelScope Studio is organized using a multi-package workspace (pnpm workspace). The core backend is published as a Python package, the frontend is built as a Svelte component library, and version and changelog generation is managed through the Changesets toolchain. The release process is automated by GitHub Actions, completing the build, uploading to PyPI, creating tags, and publishing GitHub Releases. + +```mermaid +graph TB +A["Root
package.json"] --> B["Backend Python Package
pyproject.toml"] +A --> C["Frontend Component Library
frontend/*"] +A --> D["Changeset Config
.changeset/config.json"] +D --> E["Changeset Pre-release Config
.changeset/pre.json"] +A --> F["Release Workflow
.github/workflows/publish.yaml"] +F --> G["PyPI Publish Script
scripts/publish-to-pypi.mts"] +F --> H["Tag & Release Script
scripts/create-tag-n-release.mts"] +A --> I["Changelog Generator
config/changelog/src/index.ts"] +A --> J["Changelog
CHANGELOG.md"] +``` + +**Diagram Sources** + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) +- [config/changelog/src/index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) + +**Section Sources** + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) + +## Core Components + +- **Current Version Status** + - Backend Python package version: 2.0.0 + - Frontend and workspace root package version: 2.0.0 +- **Version Number Sources** + - Backend Python package version is defined in [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) + - Root package version is defined in [package.json:1-55](file://package.json#L1-L55) + - Python package version is defined in [pyproject.toml:1-258](file://pyproject.toml#L1-L258) +- **Changelog** + - Root-level changelog at [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) + - Changeset toolchain configuration at [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) and [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) + - Changelog generator at [config/changelog/src/index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) + +**Section Sources** + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [config/changelog/src/index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) + +## Architecture Overview + +The end-to-end flow for release and version management is as follows: + +```mermaid +sequenceDiagram +participant Dev as "Developer" +participant CS as "Changesets" +participant WF as "GitHub Actions
publish.yaml" +participant PYPI as "PyPI" +participant GH as "GitHub Releases" +Dev->>CS : Submit changeset and version update +CS-->>Dev : Generate / update changelog +Dev->>WF : Push branch to trigger workflow +WF->>PYPI : Call publish script to upload package +WF->>GH : Create tag and Release +GH-->>Dev : Publish completion notification +``` + +**Diagram Sources** + +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +**Section Sources** + +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +## Detailed Component Analysis + +### Version History and Current Status + +- **Latest Stable Version** + - Current backend version: 2.0.0 + - Frontend and root package version: 2.0.0 +- **Version History and Major Milestones** + - 2.0.0: Added complete new features for Ant Design and Ant Design X + - 2.0.0-beta.0: Full migration to Gradio 6.0, Ant Design 6.0, and Ant Design X 2.0 + - 1.x series: Includes many component enhancements, Pro component introduction, i18n support, form actions, etc. + - 1.0.0: Migration from Gradio to version 5, integration of Ant Design + - 0.x series: Early versions, progressively introducing custom components and Gradio 5 migration preparation + +**Section Sources** + +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) + +### Upgrade Path and 1.0 Breaking Changes + +- **Breaking Changes in Version 1.0** + - Gradio migrated from 4.x to 5.x + - Component parameters and lifecycle adjustments, ensuring event bindings are correct + - Added AutoLoading component to optimize loading feedback +- **Upgrade Steps from Older Versions to 1.0** + - Wrap the Application component at the outermost layer of the application; keep existing component imports and usage unchanged + - If you need to continue using components from the legacy module, import them following the README examples + - If deploying on Hugging Face Space, add `ssr_mode=False` in `demo.launch()` + +```mermaid +flowchart TD +Start(["Start Upgrade"]) --> CheckLegacy["Check if using legacy components"] +CheckLegacy --> |Yes| ImportMgr["Import legacy module per README example"] +CheckLegacy --> |No| SkipMgr["Skip legacy import"] +ImportMgr --> WrapApp["Wrap ms.Application() at outermost layer"] +SkipMgr --> WrapApp +WrapApp --> HFSSR["If deploying on Hugging Face Space, set ssr_mode=False"] +HFSSR --> Test["Run tests to confirm component behavior"] +Test --> Done(["Complete"]) +``` + +**Diagram Sources** + +- [README.md:64-78](file://README.md#L64-L78) +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) + +**Section Sources** + +- [README.md:64-78](file://README.md#L64-L78) +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) + +### Version Compatibility Policy + +- **Python Compatibility** + - Python version requirement: >=3.8 + - Gradio dependency range: gradio>=6.0,<=6.8.0 (current 2.0.0) +- **Frontend-Backend Version Alignment** + - Both root package and backend Python package declare 2.0.0; it is recommended to keep them in sync +- **Browser and Runtime Environment** + - Recommended to develop and test in mainstream browsers + - SSR must be disabled when deploying on Hugging Face Space + +**Section Sources** + +- [pyproject.toml:15-26](file://pyproject.toml#L15-L26) +- [package.json:1-55](file://package.json#L1-L55) +- [README.md:34-37](file://README.md#L34-L37) +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) + +### Long-Term Support and Support Lifecycle + +- **No explicit LTS plan or support lifecycle statement is currently published** +- **Recommended to follow the root-level CHANGELOG.md and release workflows for the latest version updates and release cadence** + +**Section Sources** + +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +### Known Issues, Security Updates, and Bug Fixes + +- **Known Issues** + - Hugging Face Space enables SSR by default, which may cause custom component display issues; must be disabled manually + - Earlier versions had encoding and event binding issues, fixed in subsequent versions +- **Security Updates and Bug Fixes** + - The changelog contains many fix entries (Fixes), covering upload logic, styles, rendering, event binding, etc. + - It is recommended to upgrade to versions containing the corresponding fixes first + +**Section Sources** + +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) + +### Version Selection Recommendations + +- **Production Environment** + - Prefer stable versions (non-beta); if beta must be used, evaluate risks carefully with the changelog +- **Development and Experimentation** + - Beta versions can be chosen to experience new features, but watch for potential API changes and compatibility issues +- **Integration with the Gradio Ecosystem** + - Ensure the Gradio version meets the dependency range (gradio>=6.0,<=6.8.0) + +**Section Sources** + +- [pyproject.toml:26-26](file://pyproject.toml#L26-L26) +- [package.json:1-55](file://package.json#L1-L55) + +### Viewing Changelogs and Release Frequency + +- **Viewing the Changelog** + - The root-level CHANGELOG.md records a summary of changes for all versions + - The Changesets toolchain generates entries based on commit messages, making it easy to track PRs, commits, and contributors +- **Release Frequency** + - The release workflow is triggered on main branch pushes; the specific frequency depends on commit frequency and changeset strategy + - Changeset pre-release configuration supports pre-release management with the beta tag + +**Section Sources** + +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +## Dependency Analysis + +- **Version Consistency** + - The backend Python package version and the root package version are kept consistent (2.0.0), which facilitates publishing and rollback +- **Dependency Range** + - Gradio dependency range is strictly defined to avoid incompatibilities with higher versions +- **Release Chain** + - Changesets generates changelog → GitHub Actions triggers build and release → PyPI upload → Create tag and Release + +```mermaid +graph LR +V["Version
2.0.0"] --> P["Python Package
pyproject.toml"] +V --> R["Root Package
package.json"] +P --> PYPI["PyPI"] +R --> PYPI +PYPI --> REL["GitHub Releases"] +``` + +**Diagram Sources** + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) + +**Section Sources** + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) + +## Performance Considerations + +- **Loading Feedback** + - It is recommended to use the AutoLoading component globally to reduce blank screens or flickering during frontend-backend interaction waits +- **Rendering and Event Binding** + - Version 1.0 optimized event binding logic, reducing unnecessary re-renders after upgrading +- **Uploads and File Handling** + - Multiple versions have fixed upload logic and file retention issues; it is recommended to upgrade to versions containing the relevant fixes + +**Section Sources** + +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) + +## Troubleshooting Guide + +- **Display Issues on Hugging Face Space** + - Solution: Add `ssr_mode=False` to `demo.launch()` +- **Abnormal Upload Component Behavior** + - Recommended to upgrade to versions containing upload logic fixes +- **Event Binding and Rendering Issues** + - Version 1.0 has fixed related issues; it is recommended to upgrade to 1.0 or higher + +**Section Sources** + +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) + +## Conclusion + +ModelScope Studio current stable release is 2.0.0. The comprehensive migration to Gradio 6 and Ant Design 6 brings significant feature enhancements and stability improvements. This version adds complete new features for Ant Design and Ant Design X, further improving the component ecosystem. The key to upgrading to 1.0 is wrapping the Application component at the outermost layer of the application, and disabling SSR when necessary to adapt to Hugging Face Space. + +## Appendix + +- **Quick Reference** + - Current version: 2.0.0 + - Python compatibility: >=3.8 + - Gradio dependency: gradio>=6.0,<=6.8.0 + - Changelog: Root-level CHANGELOG.md + - Release workflow: .github/workflows/publish.yaml + +**Section Sources** + +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) +- [pyproject.toml:15-26](file://pyproject.toml#L15-L26) +- [package.json:1-55](file://package.json#L1-L55) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) diff --git a/.wiki/en/Quick Start.md b/.wiki/en/Quick Start.md new file mode 100644 index 00000000..b8362797 --- /dev/null +++ b/.wiki/en/Quick Start.md @@ -0,0 +1,433 @@ +# Quick Start + + +**Files Referenced in This Document** +- [README.md](file://README.md) +- [pyproject.toml](file://pyproject.toml) +- [docs/requirements.txt](file://docs/requirements.txt) +- [docs/demos/example.py](file://docs/demos/example.py) +- [docs/FAQ.md](file://docs/FAQ.md) +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [frontend/package.json](file://frontend/package.json) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [docs/app.py](file://docs/app.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) + + +## Update Summary + +**Changes** + +- Updated Gradio version requirement: migrated from 4.43.0+ to 6.0.0+ +- Added version constraint description and migration guidance +- Updated dependency ranges and version constraints +- Strengthened version compatibility warnings + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Notes](#performance-notes) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This guide is intended for first-time ModelScope Studio users, helping you complete installation and get up and running in the shortest time possible, and master the basic methods for importing the component library and creating basic interfaces. You will learn: + +- Installation and environment preparation (Python version, dependencies) +- Steps to run the minimal working example +- Component library import and usage patterns +- Quick resolution of common issues + +**Important Update**: ModelScope Studio 2.0.0 has migrated to the Gradio 6.0 ecosystem, supporting version ranges >=6.0.0 and <=6.8.0. + +## Project Structure + +ModelScope Studio is a third-party component library based on Gradio, providing richer page layouts and component forms. The project adopts a layered design of "backend Python package + frontend Svelte/React components": + +- Backend: Python package wrapping component interfaces and template resources +- Frontend: Svelte/React components bridging Ant Design/Ant Design X via @svelte-preprocess-react +- Documentation and examples: Displayed via docs/app.py showing components and layout templates + +```mermaid +graph TB +subgraph "Backend (Python)" +PY_API["Python API
components/__init__.py"] +PY_ANTD["antd submodule
components/antd/__init__.py"] +PY_BASE["base submodule
components/base/__init__.py"] +end +subgraph "Frontend (JS/TS)" +FE_BTN["Button Component
frontend/antd/button/button.tsx"] +FE_FORM["Form Component
frontend/antd/form/form.tsx"] +FE_PKG["Dependencies
frontend/package.json"] +end +subgraph "Docs & Examples" +DOCS_APP["Example App
docs/app.py"] +DEMO_EXAMPLE["Minimal Example
docs/demos/example.py"] +end +PY_API --> PY_ANTD +PY_API --> PY_BASE +PY_ANTD --> FE_BTN +PY_ANTD --> FE_FORM +PY_BASE --> FE_BTN +FE_PKG --> FE_BTN +FE_PKG --> FE_FORM +DOCS_APP --> PY_API +DEMO_EXAMPLE --> PY_API +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +**Section Sources** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## Core Components + +- Component library entry point: Import submodules via `modelscope_studio.components.*` + - antd: Ant Design component collection + - base: Base layout and rendering components (e.g., Application, AutoLoading, Slot, Fragment, Div, Text, Markdown, etc.) +- Key component usage patterns + - Use context containers: `ms.Application`, `antd.ConfigProvider`, `ms.AutoLoading` + - Directly nest specific components (e.g., `antd.DatePicker`) inside containers + +**Section Sources** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +## Architecture Overview + +The diagram below shows the call chain from the Python application to frontend components, and the dynamic loading mechanism of the documentation site for components. + +```mermaid +sequenceDiagram +participant Dev as "Developer Script
docs/demos/example.py" +participant Blocks as "Gradio Blocks" +participant MSApp as "ms.Application" +participant CFG as "antd.ConfigProvider" +participant Auto as "ms.AutoLoading" +participant Comp as "antd.DatePicker" +Dev->>Blocks : Create Blocks context +Blocks->>MSApp : Enter Application container +MSApp->>CFG : Enter ConfigProvider container +CFG->>Auto : Enter AutoLoading container +Auto->>Comp : Render DatePicker +Comp-->>Dev : Page displays component +``` + +**Diagram Sources** + +- [docs/demos/example.py:5-10](file://docs/demos/example.py#L5-L10) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +**Section Sources** + +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## Detailed Component Analysis + +### Component Usage Patterns and Best Practices + +- Using container composition + - It is recommended to wrap `ms.Application` at the outermost layer, then wrap `antd.ConfigProvider` and `ms.AutoLoading` inside, to get global configuration and auto-loading feedback +- Component import and instantiation + - Import required components via `modelscope_studio.components.antd` or `modelscope_studio.components.base` + - Directly instantiate components within the container scope +- Commonly used component examples + - Base components: Button, Text, Div, Markdown + - Data entry: Form, Input, DatePicker, Select + - Feedback and notifications: Message, Modal, Notification, Spin + +**Section Sources** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +### Component Class Relationships (Code Level) + +The following class diagram shows the mapping between frontend components and Ant Design, reflecting the component bridging and slot mechanism. + +```mermaid +classDiagram +class Button { ++Props : "antd Button Props" ++Slots : "icon, loading.icon" ++Behavior : "Renders Antd Button" +} +class Form { ++Props : "value, onValueChange, formAction" ++Events : "onValuesChange" ++Behavior : "Form state management and action triggers" +} +class AntdButton { ++Props : "GetProps
antd/base"] +Import --> Ctx["Enter Container
Application/ConfigProvider/AutoLoading"] +Ctx --> Render["Render Specific Component
e.g. DatePicker/Button/Form"] +Render --> Feedback["Auto-Loading Feedback
AutoLoading Display"] +Feedback --> End(["Complete"]) +``` + +**Diagram Sources** + +- [docs/demos/example.py:5-10](file://docs/demos/example.py#L5-L10) +- [docs/FAQ.md:7-19](file://docs/FAQ.md#L7-L19) + +**Section Sources** + +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) + +## Dependency Analysis + +- Python environment and version + - Python version requirement: >=3.8 + - **Gradio dependency range**: >=6.0.0 and <=6.8.0 + - **Important note**: The current example uses 5.34.1, but version 2.0.0 has migrated to the Gradio 6.0 ecosystem +- Frontend dependencies + - Ant Design 6.x, Ant Design X 2.x, React 19, Svelte 5, @gradio/\* series, etc. +- Documentation and example dependencies + - Example scripts and the documentation site use `modelscope_studio==2.0.0` + +**Important Update**: For version migration details, please refer to [Migration Guide](#migration-guide) + +```mermaid +graph LR +PyVer["Python >=3.8"] --> Install["pip install modelscope_studio"] +Install --> Gradio["Gradio 6.0 Ecosystem
(>=6.0.0, <=6.8.0)"] +Gradio --> Front["Frontend Component Runtime"] +Front --> Antd["Antd 6 / Antd X 2 Components"] +``` + +**Diagram Sources** + +- [pyproject.toml:15-26](file://pyproject.toml#L15-L26) +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-4) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) + +**Section Sources** + +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-L4) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +### Migration Guide + +**Gradio 6.0 Migration Guide** + +ModelScope Studio 2.0.0 has completed a major migration from Gradio 4.x to 6.x, involving the following key changes: + +#### Version Range Description + +- **Supported versions**: >=6.0.0 and <=6.8.0 +- **Unsupported versions**: <6.0.0 or >6.8.0 +- **Migration reason**: Gradio 6.0 introduced major architectural changes that require corresponding component adaptations + +#### Using Pre-Migration Versions + +If your project is still using Gradio versions from 4.43.0 to before 6.0.0, please use the 1.x version: + +```bash +pip install modelscope_studio~=1.0 +``` + +#### Using Post-Migration Versions + +For new projects with Gradio 6.0+, use the latest version: + +```bash +pip install modelscope_studio==2.0.0 +``` + +#### Compatibility Notes + +- **Hugging Face Space**: Still requires `ssr_mode=False` +- **Component API**: Most APIs maintain backward compatibility +- **Performance Improvements**: Gradio 6.0 provides better performance and stability + +**Section Sources** + +- [README.md:36-50](file://README.md#L36-L50) +- [pyproject.toml:26](file://pyproject.toml#L26) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) + +## Performance Notes + +- Interaction latency and loading feedback + - The component library independently provides a loading feedback mechanism; it is recommended to enable AutoLoading globally to reduce user-perceived wait times +- Concurrency and queuing + - The documentation site examples use queue and concurrency limit parameters; actual projects can adjust based on requirements + +**Section Sources** + +- [docs/FAQ.md:7-19](file://docs/FAQ.md#L7-L19) +- [docs/app.py:592-594](file://docs/app.py#L592-L594) + +## Troubleshooting Guide + +- Hugging Face Space page not displaying + - Add `ssr_mode=False` to `demo.launch()` +- Slow responses or no feedback + - Missing AutoLoading container causes no loading feedback; it is recommended to add `ms.AutoLoading` at the application top level +- **Gradio version conflict** + - Ensure Gradio version is in the range >=6.0.0 and <=6.8.0 + - If using an older version of Gradio, downgrade to modelscope_studio 1.x + - If using a newer version of Gradio, upgrade to modelscope_studio 2.0.0 + +**Section Sources** + +- [docs/FAQ.md:3-5](file://docs/FAQ.md#L3-L5) +- [docs/FAQ.md:7-19](file://docs/FAQ.md#L7-L19) +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-L4) +- [README.md:36-50](file://README.md#L36-L50) + +## Conclusion + +Through this guide, you have learned: + +- How to install and prepare the environment +- How to import the component library and create the minimal working example +- How to use the basic patterns of containers and components +- How to quickly locate and fix common issues +- **Important notes for Gradio version migration** + +It is recommended to progressively introduce more components in subsequent development (e.g., Form, Table, Modal), and combine AutoLoading to optimize user experience. Pay attention to version compatibility and ensure the Gradio version meets the currently supported range. + +## Appendix + +### Installation and Run Steps + +- Installation + - Use pip to install modelscope_studio +- Running + - Refer to the minimal example script; running it directly will start the local service + +**Section Sources** + +- [README.md:38-57](file://README.md#L38-L57) +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +### Minimal Example (Path) + +- Example script path: [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) +- Run command reference: Execute the Python file in the directory where the example script is located + +**Section Sources** + +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +### Component Import and Usage (Paths) + +- Import antd components: [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- Import base components: [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- Component library entry aggregation: [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- Python package export entry: [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) + +**Section Sources** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) + +### Documentation Site and Example Entry (Paths) + +- Documentation site entry: [docs/app.py:1-595](file://docs/app.py#L1-L595) + +**Section Sources** + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +### Version Compatibility Matrix + +| Gradio Version | ModelScope Studio Version | Support Status | +| ----------------- | ------------------------- | ---------------- | +| >=4.43.0,<6.0.0 | 1.x | ✅ Supported | +| >=6.0.0,<=6.8.0 | 2.0.0 | ✅ Supported | +| <4.43.0 or >6.8.0 | Any | ❌ Not Supported | + +> **⚠️ Note: Why Gradio >6.8.0 is not supported** +> The current version has not yet been fully tested and adapted for Gradio versions above 6.8.0. New versions of Gradio may contain changes to component APIs, boundary behaviors, and internal interfaces; use is not recommended until full coverage has been verified. If you need to use a higher version, please follow the official repository's compatibility update announcements. + +**Section Sources** + +- [README.md:36-50](file://README.md#L36-L50) +- [pyproject.toml:26](file://pyproject.toml#L26) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) diff --git a/.wiki/en/Troubleshooting.md b/.wiki/en/Troubleshooting.md new file mode 100644 index 00000000..aaaf83d6 --- /dev/null +++ b/.wiki/en/Troubleshooting.md @@ -0,0 +1,400 @@ +# Troubleshooting + + +**Files Referenced in This Document** +- [README.md](file://README.md) +- [README-zh_CN.md](file://README-zh_CN.md) +- [FAQ.md](file://docs/FAQ.md) +- [FAQ-zh_CN.md](file://docs/FAQ-zh_CN.md) +- [docs/app.py](file://docs/app.py) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [backend/modelscope_studio/components/base/auto_loading/__init__.py](file://backend/modelscope_studio/components/base/auto_loading/__init__.py) +- [frontend/base/auto-loading/useLoadingStatus.ts](file://frontend/base/auto-loading/useLoadingStatus.ts) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/process_links.py](file://backend/modelscope_studio/utils/dev/process_links.py) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx) +- [backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py) +- [frontend/svelte-preprocess-react/component/import.ts](file://frontend/svelte-preprocess-react/component/import.ts) +- [frontend/utils/tick.ts](file://frontend/utils/tick.ts) + + +## Table of Contents + +1. [Introduction](#introduction) +2. [Project Structure](#project-structure) +3. [Core Components](#core-components) +4. [Architecture Overview](#architecture-overview) +5. [Detailed Component Analysis](#detailed-component-analysis) +6. [Dependency Analysis](#dependency-analysis) +7. [Performance Considerations](#performance-considerations) +8. [Troubleshooting Guide](#troubleshooting-guide) +9. [Conclusion](#conclusion) +10. [Appendix](#appendix) + +## Introduction + +This guide is intended for developers using ModelScope Studio, focusing on systematic troubleshooting and resolution of common issues related to installation, configuration, runtime errors, and performance. Content is sourced from the official documentation, FAQs, example sites, and source code implementations in the repository, covering key paths including frontend components, backend component bridging, auto-loading feedback, error boundaries, link processing, and development and release workflows. + +## Project Structure + +ModelScope Studio is a third-party component library based on Gradio, providing the Ant Design, Ant Design X, and Pro component ecosystems. The project adopts a frontend-backend separation with a multi-package workspace organization: + +- Frontend (Svelte + React preprocessing): Located in the frontend directory, split by component, each with independent build configurations and template directories +- Backend (Python): Located in backend/modelscope_studio, providing component bridging capabilities to Gradio +- Documentation and examples: The docs directory contains example sites and component documentation +- Build and release: package.json and pyproject.toml define scripts and packaging rules; GitHub Actions handles Lint and release + +```mermaid +graph TB +subgraph "Docs & Examples" +DOCS_APP["docs/app.py"] +DOCS_FAQ["docs/FAQ.md"] +end +subgraph "Frontend" +FE_AUTOLOAD["frontend/base/auto-loading/useLoadingStatus.ts"] +FE_ERROR_BOUNDARY["frontend/antd/alert/error-boundary/alert.error-boundary.tsx"] +FE_IMPORT["frontend/svelte-preprocess-react/component/import.ts"] +FE_TICK["frontend/utils/tick.ts"] +end +subgraph "Backend" +BE_AUTOLOAD["backend/modelscope_studio/components/base/auto_loading/__init__.py"] +BE_COMPONENT["backend/modelscope_studio/utils/dev/component.py"] +BE_PROCESS_LINKS["backend/modelscope_studio/utils/dev/process_links.py"] +end +DOCS_APP --> FE_AUTOLOAD +DOCS_APP --> FE_ERROR_BOUNDARY +DOCS_APP --> BE_AUTOLOAD +DOCS_APP --> BE_COMPONENT +DOCS_APP --> BE_PROCESS_LINKS +FE_AUTOLOAD --> BE_AUTOLOAD +FE_ERROR_BOUNDARY --> BE_COMPONENT +FE_IMPORT --> BE_COMPONENT +FE_TICK --> BE_COMPONENT +``` + +**Diagram Sources** + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:1-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L1-L65) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [backend/modelscope_studio/utils/dev/process_links.py:1-61](file://backend/modelscope_studio/utils/dev/process_links.py#L1-L61) + +**Section Sources** + +- [README.md:1-101](file://README.md#L1-L101) +- [README-zh_CN.md:1-101](file://README-zh_CN.md#L1-L101) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## Core Components + +- Auto-loading feedback (AutoLoading) + - Backend component: Provides bridging and rendering control for global loading state, queue position, ETA, etc. + - Frontend Hook: `useLoadingStatus` converts Gradio's state tracking into displayable timing and ETA-formatted output +- Error Boundary (Alert.ErrorBoundary) + - Frontend: Wraps Ant Design's ErrorBoundary via `sveltify`, supporting slot injection of message and description + - Backend: Corresponding component definition, declaring `skip_api`, used only for frontend rendering +- Component Base Class and Context + - Backend: `ModelScopeComponent`/`ModelScopeLayoutComponent`, etc., unifying component lifecycle and App context validation +- Link Processing + - Backend: `process_links` converts relative links in Markdown/HTML to accessible `/file=...` resource paths + +**Section Sources** + +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:1-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L1-L65) +- [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:20-72](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L20-L72) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [backend/modelscope_studio/utils/dev/process_links.py:1-61](file://backend/modelscope_studio/utils/dev/process_links.py#L1-L61) + +## Architecture Overview + +The diagram below shows the key call chain from the example site to component rendering, including the collaboration between auto-loading feedback and error boundaries. + +```mermaid +sequenceDiagram +participant User as "User" +participant Site as "Site Rendering (docs/app.py)" +participant AutoLoading as "AutoLoading (Backend)" +participant Hook as "useLoadingStatus (Frontend)" +participant ErrorBoundary as "Alert.ErrorBoundary (Frontend)" +participant Comp as "Specific Component (e.g. Button)" +User->>Site : Visit example site +Site->>AutoLoading : Initialize global loading feedback +AutoLoading-->>Hook : Provide loading status (ETA/queue/message) +Hook-->>User : Display timing/ETA/queue info +User->>Comp : Trigger interaction +Comp-->>AutoLoading : Trigger loading +AutoLoading-->>Hook : Update status +Hook-->>User : Real-time update +Note over ErrorBoundary,Comp : If component throws an error, captured and displayed by ErrorBoundary +``` + +**Diagram Sources** + +- [docs/app.py:577-595](file://docs/app.py#L577-L595) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:1-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L1-L65) +- [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +## Detailed Component Analysis + +### Auto-Loading Feedback (AutoLoading) + +- Design highlights + - The backend component does not participate in regular API calls; it only handles rendering and state bridging + - The frontend Hook uses `requestAnimationFrame` for smooth timing, combined with ETA and queue information for formatted output +- Common issue diagnosis + - Without AutoLoading, Gradio's default loading state may not display, causing user-perceived latency + - Large queues or long-running backend tasks will cause ETA fluctuations; evaluate based on queue size and concurrency limits + +```mermaid +flowchart TD +Start(["Enter Interaction"]) --> CheckAutoLoading["Does AutoLoading Component Exist?"] +CheckAutoLoading --> |No| ShowDefault["Show Gradio Default Loading State"] +CheckAutoLoading --> |Yes| UseHook["useLoadingStatus Subscribes to State"] +UseHook --> UpdateUI["Update ETA/Timing/Queue Info"] +ShowDefault --> WaitResponse["Wait for Response"] +UpdateUI --> WaitResponse +WaitResponse --> End(["Interaction Complete"]) +``` + +**Diagram Sources** + +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:1-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L1-L65) +- [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) + +**Section Sources** + +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:1-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L1-L65) +- [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) + +### Error Boundary (Alert.ErrorBoundary) + +- Design highlights + - Frontend wraps Ant Design's ErrorBoundary via `sveltify`, supporting slot injection of `message`/`description` + - Backend component declares `skip_api`, preventing it from being treated as a regular component for API calls +- Common issue diagnosis + - Uncaught exceptions inside components will directly interrupt the UI; ensure critical areas are wrapped with ErrorBoundary + - When slot content is empty, falls back to props, ensuring error information is visible + +```mermaid +sequenceDiagram +participant FE as "Frontend Component" +participant EB as "ErrorBoundary" +participant BE as "Backend Component (declares skip_api)" +FE->>EB : Throw exception +EB-->>FE : Render message/description slot +BE-->>EB : Does not participate in API calls (skip_api) +``` + +**Diagram Sources** + +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:20-72](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L20-L72) + +**Section Sources** + +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:20-72](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L20-L72) + +### Component Base Class and Context (ModelScopeComponent/Layout) + +- Design highlights + - Uniformly inherits Gradio component metaclass and BlockContext, ensuring parent-child relationships and rendering order are correct + - Layout-type components default to `skip_api`; data-type components participate in the API flow +- Common issue diagnosis + - Not being within the Application context will trigger assertion failure + - Layout components need to sync the layout flag when exiting, to avoid rendering misalignment + +**Section Sources** + +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) + +### Link Processing (process_links) + +- Design highlights + - Converts relative links in Markdown/HTML to `/file=` cache paths for safe Gradio access +- Common issue diagnosis + - When files don't exist or paths are wrong, returns them as-is; check resource absolute paths and block cache mappings + +**Section Sources** + +- [backend/modelscope_studio/utils/dev/process_links.py:1-61](file://backend/modelscope_studio/utils/dev/process_links.py#L1-L61) + +## Dependency Analysis + +- Frontend-Backend Dependencies + - Frontend uses Svelte 5 and React preprocessing, combined with Gradio's state tracking and component bridging + - Backend depends on Gradio version ranges to ensure compatibility +- Build and Release + - Frontend scripts include build, development, formatting, Lint, etc.; backend is packaged via hatchling + - GitHub Actions handles Lint and release processes + +```mermaid +graph LR +Pkg["package.json
Frontend Scripts & Dependencies"] --> FE["Frontend Build/Dev"] +Py["pyproject.toml
Backend Packaging Config"] --> BE["Backend Packaging/Release"] +FE --> DOCS["docs/app.py Example Site"] +BE --> DOCS +Lint["lint.yaml"] --> FE +Lint --> BE +Pub["publish.yaml"] --> BE +``` + +**Diagram Sources** + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/app.py:577-595](file://docs/app.py#L577-L595) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +**Section Sources** + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +## Performance Considerations + +- Loading feedback and queuing + - Using AutoLoading and `useLoadingStatus` can improve perceived performance, but requires reasonable concurrency and queue limits +- SSR and space deployment + - SSR must be disabled in Hugging Face Space, otherwise custom components may not display correctly +- Build and caching + - Frontend build scripts and Gradio resource caching strategies affect initial load and switching performance + +**Section Sources** + +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) +- [docs/FAQ-zh_CN.md:1-20](file://docs/FAQ-zh_CN.md#L1-L20) +- [docs/app.py:592-595](file://docs/app.py#L592-L595) + +## Troubleshooting Guide + +### 1. Installation and Environment `🛠 All Versions` + +- Dependency versions + - Backend depends on Gradio version ranges; ensure compatibility with the current environment + - **Gradio 6.0+ specific**: When using modelscope_studio 2.x, ensure gradio>=6.0,<=6.8.0 +- Frontend dependencies + - Use pnpm to install dependencies and run builds; development mode is started via docs/app.py +- Common symptoms + - Components unavailable or import errors after installation; check Gradio version and Python environment first +- Resolution steps + - Confirm Gradio version meets requirements + - Clear cache and reinstall dependencies + - Validate environment using the example site + +**Section Sources** + +- [pyproject.toml:26-26](file://pyproject.toml#L26-L26) +- [package.json:8-25](file://package.json#L8-L25) +- [README.md:34-42](file://README.md#L34-L42) +- [README-zh_CN.md:34-42](file://README-zh_CN.md#L34-L42) + +### 2. Configuration Issues `🛠 All Versions` + +- SSR mode + - SSR must be disabled in Hugging Face Space, otherwise interface display is abnormal + - **Version applicability**: Gradio 6.0+ specific (this issue also existed in versions before Gradio 6.0) +- Auto-loading feedback + - If AutoLoading is not placed, Gradio's default loading state may not display; it is recommended to use AutoLoading at least once globally +- Build and development + - Development mode uses docs/app.py; production builds use frontend scripts + +**Section Sources** + +- [docs/FAQ.md:3-5](file://docs/FAQ.md#L3-L5) +- [docs/FAQ-zh_CN.md:3-5](file://docs/FAQ-zh_CN.md#L3-L5) +- [docs/FAQ.md:7-19](file://docs/FAQ.md#L7-L19) +- [docs/FAQ-zh_CN.md:7-19](file://docs/FAQ-zh_CN.md#L7-L19) +- [docs/app.py:592-595](file://docs/app.py#L592-L595) + +### 3. Runtime Errors `🛠 Gradio 6.0+ Specific` + +- Error boundaries + - Internal component exceptions are captured and displayed by ErrorBoundary with message/description; if not working, check if wrapping is correct +- Initialization and lazy loading + - Component lazy loading depends on initialization Promises; if not complete, the component may not be ready; ensure waiting for initialization to complete +- Link access + - Relative resources need to be converted to `/file=` paths via `process_links`; if resources are missing, returns as-is; check paths and cache + +**Section Sources** + +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:20-72](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L20-L72) +- [frontend/svelte-preprocess-react/component/import.ts:1-20](file://frontend/svelte-preprocess-react/component/import.ts#L1-L20) +- [backend/modelscope_studio/utils/dev/process_links.py:48-61](file://backend/modelscope_studio/utils/dev/process_links.py#L48-L61) + +### 4. Performance Issues `🛠 All Versions` + +- Loading wait and ETA fluctuations + - Large queues or long-running backend tasks cause ETA fluctuations; can be mitigated by reducing concurrency and optimizing task logic +- Timing and rendering + - `useLoadingStatus` uses `requestAnimationFrame` for real-time updates, ensuring UI fluency; avoid creating instances repeatedly in high-frequency events +- SSR and space deployment + - Disabling SSR avoids compatibility issues with custom components in SSR scenarios + +**Section Sources** + +- [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [docs/FAQ.md:7-9](file://docs/FAQ.md#L7-L9) +- [docs/FAQ-zh_CN.md:7-9](file://docs/FAQ-zh_CN.md#L7-L9) +- [docs/app.py:592-595](file://docs/app.py#L592-L595) + +### 5. Debugging Tips `🛠 All Versions` + +- Logs and state + - Use `useLoadingStatus` to output ETA, timing, and queue position, helping locate latency causes +- Component initialization + - Wait for `initializePromise` to complete before dynamically importing components, avoiding exceptions due to uninitialized state +- Links and resources + - Use `process_links` to convert relative links to `/file=` paths, ensuring resources are accessible + +**Section Sources** + +- [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [frontend/svelte-preprocess-react/component/import.ts:1-20](file://frontend/svelte-preprocess-react/component/import.ts#L1-L20) +- [backend/modelscope_studio/utils/dev/process_links.py:48-61](file://backend/modelscope_studio/utils/dev/process_links.py#L48-L61) + +### 6. Community Support and Issue Reporting `🛠 All Versions` + +- Official docs and examples + - Use the example site to validate issue reproduction and fix effectiveness +- Submitting issues + - Submit an Issue in the repository, including environment info, dependency versions, minimal reproduction, and expected behavior +- Reference scripts + - Lint and publish scripts can be used to check and validate the local environment + +**Section Sources** + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +## Conclusion + +By understanding core mechanisms such as AutoLoading, ErrorBoundary, component base classes, and link processing, developers can systematically locate and resolve installation, configuration, runtime, and performance-related issues. It is recommended to disable SSR in Hugging Face Space and enable AutoLoading globally to improve user experience; when issues arise, first check initialization, error boundaries, and resource links, and use the example site for minimal reproduction and validation. + +## Appendix + +- Key File Index + - Example site and menu: [docs/app.py:1-595](file://docs/app.py#L1-L595) + - Auto-loading feedback (backend): [backend/modelscope_studio/components/base/auto_loading/**init**.py:1-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L1-L65) + - Auto-loading feedback (frontend): [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) + - Error boundary (frontend): [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + - Error boundary (backend): [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:20-72](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L20-L72) + - Component base class: [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) + - Link processing: [backend/modelscope_studio/utils/dev/process_links.py:1-61](file://backend/modelscope_studio/utils/dev/process_links.py#L1-L61) + - Frontend scripts: [package.json:1-55](file://package.json#L1-L55) + - Backend packaging: [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + - Lint workflow: [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) + - Release workflow: [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/API \345\217\202\350\200\203.md" "b/.wiki/zh/API \345\217\202\350\200\203/API \345\217\202\350\200\203.md" new file mode 100644 index 00000000..810ad246 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/API \345\217\202\350\200\203.md" @@ -0,0 +1,514 @@ +# API 参考 + + +**本文档引用的文件** +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/table/table.tsx](file://frontend/antd/table/table.tsx) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [frontend/base/application/application.ts](file://frontend/base/application/application.ts) +- [frontend/pro/chatbot/chatbot.ts](file://frontend/pro/chatbot/chatbot.ts) +- [frontend/pro/monaco-editor/monaco-editor.ts](file://frontend/pro/monaco-editor/monaco-editor.ts) +- [frontend/pro/multimodal-input/multimodal-input.ts](file://frontend/pro/multimodal-input/multimodal-input.ts) +- [frontend/pro/web-sandbox/web-sandbox.ts](file://frontend/pro/web-sandbox/web-sandbox.ts) +- [frontend/utils/hooks/useAsyncEffect.ts](file://frontend/utils/hooks/useAsyncEffect.ts) +- [frontend/utils/hooks/useAsyncMemo.ts](file://frontend/utils/hooks/useAsyncMemo.ts) +- [frontend/utils/hooks/useDeepCompareEffect.ts](file://frontend/utils/hooks/useDeepCompareEffect.ts) +- [frontend/utils/hooks/useEvent.ts](file://frontend/utils/hooks/useEvent.ts) +- [frontend/utils/hooks/useMount.ts](file://frontend/utils/hooks/useMount.ts) +- [frontend/utils/hooks/useUnmount.ts](file://frontend/utils/hooks/useUnmount.ts) +- [frontend/utils/hooks/useUpdateEffect.ts](file://frontend/utils/hooks/useUpdateEffect.ts) +- [frontend/utils/createFunction.ts](file://frontend/utils/createFunction.ts) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/patchProps.tsx](file://frontend/utils/patchProps.tsx) +- [frontend/utils/omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) +- [frontend/utils/tick.ts](file://frontend/utils/tick.ts) +- [frontend/utils/upload.ts](file://frontend/utils/upload.ts) +- [frontend/globals/components/index.ts](file://frontend/globals/components/index.ts) +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 的完整 API 参考文档，覆盖 Python 后端组件与前端 JavaScript/Svelte 组件两大体系。Python API 提供基于 Gradio 的第三方组件库封装，前端以 Svelte 实现，二者通过 Gradio 自定义组件机制协同工作。本文档面向开发者，提供组件导入方式、类定义、方法签名、参数说明、返回值类型（Python）、组件属性与事件（JavaScript/Svelte）、生命周期钩子、公共方法、使用示例与注意事项，并补充参数验证规则、错误处理机制与版本兼容性信息。 + +## 项目结构 + +ModelScope Studio 采用前后端分离的多包结构： + +- 后端 Python 包：modelscope_studio，提供组件导出与版本信息 +- 前端 Svelte 包：多个子包按功能域划分（antd、antdx、base、pro），并提供工具函数与全局组件入口 +- 构建与发布：通过 Gradio CLI 进行自定义组件构建，支持禁用自动生成文档 + +```mermaid +graph TB +subgraph "后端 Python" +PY_PKG["modelscope_studio 包"] +PY_VERSION["版本信息"] +PY_EXPORTS["组件导出"] +end +subgraph "前端 Svelte" +FE_ANTD["antd 子包"] +FE_ANTDX["antdx 子包"] +FE_BASE["base 子包"] +FE_PRO["pro 子包"] +FE_UTILS["utils 工具集"] +FE_GLOBALS["globals 全局组件"] +end +PY_PKG --> PY_EXPORTS +PY_EXPORTS --> FE_ANTD +PY_EXPORTS --> FE_ANTDX +PY_EXPORTS --> FE_BASE +PY_EXPORTS --> FE_PRO +FE_ANTD --> FE_UTILS +FE_ANTDX --> FE_UTILS +FE_BASE --> FE_UTILS +FE_PRO --> FE_UTILS +FE_GLOBALS --> FE_UTILS +``` + +图表来源 + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [frontend/globals/components/index.ts:1-2](file://frontend/globals/components/index.ts#L1-L2) + +章节来源 + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [frontend/globals/components/index.ts:1-2](file://frontend/globals/components/index.ts#L1-L2) + +## 核心组件 + +本节概述 Python 与前端组件的导出与组织方式，帮助开发者快速定位目标组件。 + +- Python 导入与导出 + - 根包导出：从 components 模块导入所有组件，并暴露版本号 + - 组件聚合：按领域分组导出（antd、antdx、base、pro） + - antd 子包：导出大量 UI 组件别名，便于直接使用 + - antdx 子包：导出对话与内容相关组件 +- 前端组件组织 + - 每个组件通常对应一个 Svelte 文件（如 button.tsx、form.tsx、table.tsx） + - 工具函数集中于 utils，包括 hooks、渲染器、属性修补等 + - globals 提供全局组件入口，当前导出 markdown 子模块 + +章节来源 + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [frontend/globals/components/index.ts:1-2](file://frontend/globals/components/index.ts#L1-L2) + +## 架构总览 + +下图展示 Python 后端与前端组件的交互关系及数据流： + +```mermaid +graph TB +PY_API["Python API
modelscope_studio.components.*"] +GRADIO["Gradio 运行时"] +FE_COMP["前端组件
Svelte 组件树"] +UTILS["前端工具集
hooks & 渲染器"] +PY_API --> GRADIO +GRADIO --> FE_COMP +FE_COMP --> UTILS +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/table/table.tsx](file://frontend/antd/table/table.tsx) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) + +## 详细组件分析 + +### Python API 参考（概览） + +- 版本与依赖 + - 版本：2.0.0 + - 依赖：Gradio 6.0 ≤ v ≤ 6.8.0 +- 导入方式 + - from modelscope_studio import 组件名 + - 或 from modelscope_studio.components.antd import 组件名 + - 或 from modelscope_studio.components.antdx import 组件名 + - 或 from modelscope_studio.components.pro import Chatbot, MonacoEditor, MultimodalInput, WebSandbox +- 类与别名 + - antd 子包导出大量组件别名，如 Button、Form、Table 等 + - antdx 子包导出对话与内容相关组件，如 Bubble、Chatbot、Sender 等 + - pro 子包导出专业能力组件：Chatbot、MonacoEditor（含子组件 MonacoEditorDiffEditor）、MultimodalInput、WebSandbox +- 使用示例路径 + - 参考 docs/demos 下各组件示例（例如 chatbot 示例） +- 注意事项 + - 请确保 Gradio 版本满足范围要求 + - 部分组件可能需要额外的前端模板或资源（由构建系统打包） + +章节来源 + +- [pyproject.toml:26-26](file://pyproject.toml#L26-L26) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) + +### JavaScript/Svelte API 参考（概览） + +- 组件组织 + - antd：通用 UI 组件，如 Button、Form、Table 等 + - antdx：对话与内容扩展组件，如 Bubble、Sender、ThoughtChain 等 + - base：基础容器与逻辑组件，如 Application、Each、Filter 等 + - pro：专业能力组件，如 Chatbot、MonacoEditor、MultimodalInput、WebSandbox +- 属性、事件与生命周期 + - 属性：通过 props 传递，遵循 Svelte 规范 + - 事件：通过 $on/$off 或 Svelte 事件绑定 + - 生命周期：mount/unmount/update 等钩子由 hooks 提供 +- 公共方法 + - 通过 createFunction 等工具创建可调用方法 + - 上传、渲染插槽、属性修补等由 utils 提供 + +章节来源 + +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/table/table.tsx](file://frontend/antd/table/table.tsx) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [frontend/base/application/application.ts](file://frontend/base/application/application.ts) +- [frontend/pro/chatbot/chatbot.ts](file://frontend/pro/chatbot/chatbot.ts) +- [frontend/pro/monaco-editor/monaco-editor.ts](file://frontend/pro/monaco-editor/monaco-editor.ts) +- [frontend/pro/multimodal-input/multimodal-input.ts](file://frontend/pro/multimodal-input/multimodal-input.ts) +- [frontend/pro/web-sandbox/web-sandbox.ts](file://frontend/pro/web-sandbox/web-sandbox.ts) + +### 组件 A：Button（按钮） + +- Python 导入与别名 + - from modelscope_studio.components.antd import Button +- 前端组件 + - 路径：frontend/antd/button/button.tsx + - 属性：参考组件文件中的 props 定义 + - 事件：参考组件文件中的事件绑定 + - 生命周期：通过 hooks 管理（如 useMount、useUnmount） +- 使用示例 + - 参考 docs/components/antd/button 下的示例文件 +- 注意事项 + - 确保与 Gradio 的交互模式一致 + - 如需图标，请使用 Ant Design 图标 + +章节来源 + +- [backend/modelscope_studio/components/antd/**init**.py:14-14](file://backend/modelscope_studio/components/antd/__init__.py#L14-L14) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) + +### 组件 B：Form（表单） + +- Python 导入与别名 + - from modelscope_studio.components.antd import Form, FormItem, FormProvider +- 前端组件 + - 路径：frontend/antd/form/form.tsx + - 属性：参考组件文件中的 props 定义 + - 事件：参考组件文件中的事件绑定 + - 表单校验：FormItem.Rule 支持规则配置 +- 使用示例 + - 参考 docs/components/antd/form 下的示例文件 +- 注意事项 + - 表单状态与 Gradio 数据流保持同步 + - Rule 配置需符合 Ant Design 规范 + +章节来源 + +- [backend/modelscope_studio/components/antd/**init**.py:48-51](file://backend/modelscope_studio/components/antd/__init__.py#L48-L51) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) + +### 组件 C：Table（表格） + +- Python 导入与别名 + - from modelscope_studio.components.antd import Table, TableColumn, TableRowSelection +- 前端组件 + - 路径：frontend/antd/table/table.tsx + - 属性：参考组件文件中的 props 定义 + - 事件：参考组件文件中的事件绑定 + - 选择列：TableRowSelection 提供选择能力 +- 使用示例 + - 参考 docs/components/antd/table 下的示例文件 +- 注意事项 + - 列配置需与数据结构匹配 + - 选择行为需与 Gradio 输出格式一致 + +章节来源 + +- [backend/modelscope_studio/components/antd/**init**.py:116-122](file://backend/modelscope_studio/components/antd/__init__.py#L116-L122) +- [frontend/antd/table/table.tsx](file://frontend/antd/table/table.tsx) + +### 组件 D：Bubble（消息气泡） + +- Python 导入与别名 + - from modelscope_studio.components.antdx import Bubble +- 前端组件 + - 路径：frontend/antdx/bubble/bubble.tsx + - 属性：参考组件文件中的 props 定义 + - 事件：参考组件文件中的事件绑定 +- 使用示例 + - 参考 docs/components/antdx/bubble 下的示例文件 +- 注意事项 + - 消息内容与样式需与对话场景适配 + +章节来源 + +- [backend/modelscope_studio/components/antdx/**init**.py:8-13](file://backend/modelscope_studio/components/antdx/__init__.py#L8-L13) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) + +### 组件 E：Application（应用容器） + +- 前端组件 + - 路径：frontend/base/application/application.ts + - 作用：作为应用根容器，管理上下文与布局 +- 使用示例 + - 参考 docs/components/base/application 下的示例文件 +- 注意事项 + - 与其他基础组件（如 Each、Filter）配合使用 + +章节来源 + +- [frontend/base/application/application.ts](file://frontend/base/application/application.ts) + +### 组件 F：Chatbot（聊天机器人） + +- Python 导入与别名 + - from modelscope_studio.components.pro import Chatbot +- 前端组件 + - 路径：frontend/pro/chatbot/chatbot.ts + - 属性：参考组件文件中的 props 定义 + - 事件：参考组件文件中的事件绑定 +- 使用示例 + - 参考 docs/components/pro/chatbot 下的示例文件 +- 注意事项 + - 与后端模型服务对接时注意数据格式 + +章节来源 + +- [backend/modelscope_studio/components/pro/components.py:1-20](file://backend/modelscope_studio/components/pro/components.py#L1-L20) +- [frontend/pro/chatbot/chatbot.ts](file://frontend/pro/chatbot/chatbot.ts) + +### 组件 G：MonacoEditor（代码编辑器） + +- Python 导入与别名 + - from modelscope_studio.components.pro import MonacoEditor +- 前端组件 + - 路径：frontend/pro/monaco-editor/monaco-editor.ts + - 属性：参考组件文件中的 props 定义 + - 事件：参考组件文件中的事件绑定 +- 使用示例 + - 参考 docs/components/pro/monaco_editor 下的示例文件 +- 注意事项 + - 编辑器主题与语言配置需与 Gradio 交互一致 + +章节来源 + +- [backend/modelscope_studio/components/pro/components.py:1-20](file://backend/modelscope_studio/components/pro/components.py#L1-L20) +- [frontend/pro/monaco-editor/monaco-editor.ts](file://frontend/pro/monaco-editor/monaco-editor.ts) + +### 组件 H：MultimodalInput（多模态输入） + +- Python 导入与别名 + - from modelscope_studio.components.pro import MultimodalInput +- 前端组件 + - 路径：frontend/pro/multimodal-input/multimodal-input.ts + - 属性：参考组件文件中的 props 定义 + - 事件：参考组件文件中的事件绑定 +- 使用示例 + - 参考 docs/components/pro/multimodal_input 下的示例文件 +- 注意事项 + - 输入类型与后端模型接口需匹配 + +章节来源 + +- [backend/modelscope_studio/components/pro/components.py:1-20](file://backend/modelscope_studio/components/pro/components.py#L1-L20) +- [frontend/pro/multimodal-input/multimodal-input.ts](file://frontend/pro/multimodal-input/multimodal-input.ts) + +### 组件 I：WebSandbox（网页沙盒） + +- Python 导入与别名 + - from modelscope_studio.components.pro import WebSandbox +- 前端组件 + - 路径：frontend/pro/web-sandbox/web-sandbox.ts + - 属性：参考组件文件中的 props 定义 + - 事件：参考组件文件中的事件绑定 +- 使用示例 + - 参考 docs/components/pro/web_sandbox 下的示例文件 +- 注意事项 + - 安全策略与跨域限制需在部署时配置 + +章节来源 + +- [backend/modelscope_studio/components/pro/components.py:1-20](file://backend/modelscope_studio/components/pro/components.py#L1-L20) +- [frontend/pro/web-sandbox/web-sandbox.ts](file://frontend/pro/web-sandbox/web-sandbox.ts) + +### 组件 J：全局组件（Markdown） + +- 前端组件 + - 路径：frontend/globals/components/index.ts + - 当前导出 markdown 子模块 +- 使用示例 + - 参考 docs/components/base/markdown 下的示例文件 +- 注意事项 + - 全局组件需在应用入口统一注册 + +章节来源 + +- [frontend/globals/components/index.ts:1-2](file://frontend/globals/components/index.ts#L1-L2) + +## 依赖分析 + +- Python 侧 + - 依赖：Gradio 6.0 ≤ v ≤ 6.8.0 + - 版本：2.0.0 +- 前端侧 + - 构建脚本：通过 Gradio CLI 执行组件构建 + - 开发脚本：启动文档站点开发服务器 +- 工具与渲染 + - hooks：useMount、useUnmount、useUpdateEffect、useAsyncEffect、useAsyncMemo、useDeepCompareEffect、useEvent + - 渲染器：renderSlot、renderParamsSlot、renderItems + - 属性处理：patchProps、omitUndefinedProps + - 其他：createFunction、tick、upload + +```mermaid +graph TB +PY_DEPS["Python 依赖
Gradio 6.0 ≤ v ≤ 6.8.0"] +FE_SCRIPTS["前端脚本
构建/开发"] +FE_HOOKS["hooks 工具集"] +FE_RENDER["渲染器"] +FE_PATCH["属性处理"] +FE_OTHER["其他工具"] +PY_DEPS --> FE_SCRIPTS +FE_SCRIPTS --> FE_HOOKS +FE_SCRIPTS --> FE_RENDER +FE_SCRIPTS --> FE_PATCH +FE_SCRIPTS --> FE_OTHER +``` + +图表来源 + +- [pyproject.toml:26-26](file://pyproject.toml#L26-L26) +- [package.json:8-24](file://package.json#L8-L24) +- [frontend/utils/hooks/useMount.ts](file://frontend/utils/hooks/useMount.ts) +- [frontend/utils/hooks/useUnmount.ts](file://frontend/utils/hooks/useUnmount.ts) +- [frontend/utils/hooks/useUpdateEffect.ts](file://frontend/utils/hooks/useUpdateEffect.ts) +- [frontend/utils/hooks/useAsyncEffect.ts](file://frontend/utils/hooks/useAsyncEffect.ts) +- [frontend/utils/hooks/useAsyncMemo.ts](file://frontend/utils/hooks/useAsyncMemo.ts) +- [frontend/utils/hooks/useDeepCompareEffect.ts](file://frontend/utils/hooks/useDeepCompareEffect.ts) +- [frontend/utils/hooks/useEvent.ts](file://frontend/utils/hooks/useEvent.ts) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/patchProps.tsx](file://frontend/utils/patchProps.tsx) +- [frontend/utils/omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) +- [frontend/utils/createFunction.ts](file://frontend/utils/createFunction.ts) +- [frontend/utils/tick.ts](file://frontend/utils/tick.ts) +- [frontend/utils/upload.ts](file://frontend/utils/upload.ts) + +章节来源 + +- [pyproject.toml:26-26](file://pyproject.toml#L26-L26) +- [package.json:8-24](file://package.json#L8-L24) +- [frontend/utils/hooks/useMount.ts](file://frontend/utils/hooks/useMount.ts) +- [frontend/utils/hooks/useUnmount.ts](file://frontend/utils/hooks/useUnmount.ts) +- [frontend/utils/hooks/useUpdateEffect.ts](file://frontend/utils/hooks/useUpdateEffect.ts) +- [frontend/utils/hooks/useAsyncEffect.ts](file://frontend/utils/hooks/useAsyncEffect.ts) +- [frontend/utils/hooks/useAsyncMemo.ts](file://frontend/utils/hooks/useAsyncMemo.ts) +- [frontend/utils/hooks/useDeepCompareEffect.ts](file://frontend/utils/hooks/useDeepCompareEffect.ts) +- [frontend/utils/hooks/useEvent.ts](file://frontend/utils/hooks/useEvent.ts) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/patchProps.tsx](file://frontend/utils/patchProps.tsx) +- [frontend/utils/omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) +- [frontend/utils/createFunction.ts](file://frontend/utils/createFunction.ts) +- [frontend/utils/tick.ts](file://frontend/utils/tick.ts) +- [frontend/utils/upload.ts](file://frontend/utils/upload.ts) + +## 性能考虑 + +- 组件懒加载与按需引入：优先使用具体组件导入，避免一次性导入过多模块 +- 渲染优化：利用 renderItems、renderParamsSlot 等工具减少重复渲染 +- 异步处理：使用 useAsyncEffect/useAsyncMemo 处理异步副作用，避免阻塞主线程 +- 属性修补：通过 patchProps 合理合并属性，减少不必要的重渲染 +- 上传与资源：upload 工具应结合 Gradio 的上传流程，避免大文件阻塞 + +## 故障排查指南 + +- 版本不兼容 + - 症状：运行时报错或功能异常 + - 排查：确认 Gradio 版本在 6.0 ≤ v ≤ 6.8.0 范围内 +- 组件未生效 + - 症状：前端组件不显示或无响应 + - 排查：检查组件是否正确导入；确认构建产物已生成；核对 props 传入 +- 表单校验失败 + - 症状：提交时报错或无反馈 + - 排查：检查 FormItem.Rule 配置；确认字段名与数据结构一致 +- 上传异常 + - 症状：文件上传失败或进度异常 + - 排查：检查 upload 工具调用；确认后端接口与 Gradio 上传协议一致 +- 生命周期问题 + - 症状：组件卸载后仍有副作用 + - 排查：确保使用 useUnmount 注册清理逻辑；必要时使用 useUpdateEffect 监听变化 + +章节来源 + +- [pyproject.toml:26-26](file://pyproject.toml#L26-L26) +- [frontend/utils/hooks/useUnmount.ts](file://frontend/utils/hooks/useUnmount.ts) +- [frontend/utils/hooks/useUpdateEffect.ts](file://frontend/utils/hooks/useUpdateEffect.ts) +- [frontend/utils/upload.ts](file://frontend/utils/upload.ts) + +## 结论 + +本 API 参考文档梳理了 ModelScope Studio 的 Python 与前端组件体系，明确了导入方式、组件结构、属性与事件、生命周期钩子以及工具函数的使用方法。建议开发者在实际项目中遵循版本约束、按需引入组件、合理使用工具函数，并结合示例文件进行快速集成。 + +## 附录 + +- 快速索引 + - Python 组件：参考 antd 与 antdx 子包导出列表 + - 前端组件：参考各子包下的 Svelte 文件 + - 工具函数：参考 utils 目录下的 hooks 与渲染器 +- 版本与兼容性 + - Python：2.0.0 + - Gradio：6.0 ≤ v ≤ 6.8.0 +- 构建与开发 + - 构建命令：pnpm run build + - 开发命令：pnpm run dev + +章节来源 + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [pyproject.toml:26-26](file://pyproject.toml#L26-L26) +- [package.json:8-24](file://package.json#L8-L24) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/JavaScript API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/JavaScript API.md" new file mode 100644 index 00000000..52c9aaf4 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/JavaScript API.md" @@ -0,0 +1,413 @@ +# JavaScript API + + +**本文引用的文件** +- [frontend/package.json](file://frontend/package.json) +- [frontend/tsconfig.json](file://frontend/tsconfig.json) +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [frontend/antdx/package.json](file://frontend/antdx/package.json) +- [frontend/base/package.json](file://frontend/base/package.json) +- [frontend/pro/package.json](file://frontend/pro/package.json) +- [frontend/globals/components/index.ts](file://frontend/globals/components/index.ts) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/form/Index.svelte](file://frontend/antd/form/Index.svelte) +- [frontend/antd/layout/Index.svelte](file://frontend/antd/layout/Index.svelte) +- [frontend/antd/modal/Index.svelte](file://frontend/antd/modal/Index.svelte) +- [frontend/antd/table/Index.svelte](file://frontend/antd/table/Index.svelte) +- [frontend/svelte-preprocess-react/index.ts](file://frontend/svelte-preprocess-react/index.ts) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts](file://frontend/svelte-preprocess-react/sveltify.svelte.ts) +- [frontend/svelte-preprocess-react/inject.ts](file://frontend/svelte-preprocess-react/inject.ts) +- [frontend/svelte-preprocess-react/react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能与内存管理](#性能与内存管理) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：API 索引与导航](#附录api-索引与导航) + +## 简介 + +本文件为 ModelScope Studio 的 JavaScript API 参考文档，聚焦于前端层的 Svelte 组件与 React 组件桥接方案，覆盖以下要点： + +- Svelte 组件的属性定义、事件处理、生命周期与公共方法 +- 组件间通信机制（props 传递、事件冒泡、插槽系统） +- React 组件桥接实现（属性转换、事件绑定、状态同步） +- 标准实例化与配置示例（基础与复杂场景） +- 样式定制、主题配置与响应式设计支持 +- TypeScript 类型定义、接口规范与泛型使用 +- 性能优化、内存管理与最佳实践 +- 完整 API 索引与导航 + +## 项目结构 + +前端采用多包结构，按功能域拆分： + +- 基础组件库：base +- Ant Design 组件库：antd +- Ant Design 扩展组件库：antdx +- Pro 高阶组件库：pro +- 全局组件入口：globals/components + +各包均以 Svelte 5 作为核心运行时，并通过自研的 svelte-preprocess-react 桥接方案将 React 组件注入到 Svelte 中。 + +```mermaid +graph TB +subgraph "前端包" +BASE["@modelscope-studio/base"] +ANTD["@modelscope-studio/antd"] +ANTHDX["@modelscope-studio/antdx"] +PRO["@modelscope-studio/pro"] +GLOBALS["@globals/components"] +end +subgraph "桥接层" +PRE["@svelte-preprocess-react
index.ts"] +INJ["inject.ts"] +SLOT["react-slot.tsx"] +SVLT["sveltify.svelte.ts"] +end +BASE --> PRE +ANTD --> PRE +ANTHDX --> PRE +PRO --> PRE +GLOBALS --> PRE +PRE --> INJ +PRE --> SLOT +PRE --> SVLT +``` + +图表来源 + +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) +- [frontend/base/package.json:1-6](file://frontend/base/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) +- [frontend/svelte-preprocess-react/inject.ts:1-103](file://frontend/svelte-preprocess-react/inject.ts#L1-L103) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) + +章节来源 + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) + +## 核心组件 + +本节概述 Svelte 组件在桥接层中的通用模式与能力边界，便于快速定位与复用。 + +- 属性透传与过滤 + - 统一通过 getProps 获取外部传入 props，并对可见性、内部标记、元素标识等进行过滤与保留 + - 使用 processProps 将命名映射（如 fields_change → fieldsChange）与额外属性合并 +- 插槽系统 + - 通过 getSlots 收集 Svelte 插槽内容，注入 React 组件的 slots 字段 + - ReactSlot 负责将 DOM 克隆或挂载到 React 组件中，支持属性观察与事件克隆 +- 异步加载与渲染 + - importComponent 动态导入 React 组件，结合 Svelte await 片段实现异步渲染 +- 事件与状态同步 + - onValueChange、onResetFormAction 等回调用于回写父级状态 + - updateProps 用于更新可变属性（如 value） + +章节来源 + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/modal/Index.svelte:1-63](file://frontend/antd/modal/Index.svelte#L1-L63) +- [frontend/antd/table/Index.svelte:1-61](file://frontend/antd/table/Index.svelte#L1-L61) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) + +## 架构总览 + +下图展示从 Svelte 到 React 的桥接路径与关键节点： + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 组件
Index.svelte" +participant Bridge as "桥接工具
sveltify.ts" +participant Inject as "全局注入
inject.ts" +participant React as "React 组件" +participant Slot as "插槽桥接
react-slot.tsx" +Svelte->>Bridge : "importComponent + getProps + processProps" +Bridge->>Inject : "初始化共享根节点与上下文" +Bridge->>React : "创建 Portal 并挂载" +Svelte->>Slot : "getSlots() -> slots.value" +Slot-->>React : "克隆/挂载 DOM 并传播事件" +React-->>Svelte : "onValueChange 等回调触发 updateProps" +``` + +图表来源 + +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/inject.ts:1-103](file://frontend/svelte-preprocess-react/inject.ts#L1-L103) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +## 组件详解 + +### Button（按钮） + +- 属性定义 + - additional_props?: Record
基础包装"] --> B["markdown.tsx
React 组件入口"] +B --> C["utils.ts
解析/高亮/安全/Mermaid"] +B --> D["sanitize.ts
HTML 过滤"] +B --> E["markdown.less
通用样式"] +B --> F["prism.less
代码高亮主题"] +B --> G["html-tags.ts
白名单标签"] +end +subgraph "后端" +H["backend/base/markdown/__init__.py
Gradio 组件定义"] +end +A --> H +H --> B +``` + +**图表来源** + +- [frontend/base/markdown/Index.svelte:1-63](file://frontend/base/markdown/Index.svelte#L1-L63) +- [frontend/base/markdown/markdown.tsx:1-34](file://frontend/base/markdown/markdown.tsx#L1-L34) +- [frontend/globals/components/markdown/index.tsx:1-272](file://frontend/globals/components/markdown/index.tsx#L1-L272) +- [frontend/globals/components/markdown/utils.ts:1-411](file://frontend/globals/components/markdown/utils.ts#L1-L411) +- [frontend/globals/components/markdown/sanitize.ts:1-26](file://frontend/globals/components/markdown/sanitize.ts#L1-L26) +- [frontend/globals/components/markdown/markdown.less:1-140](file://frontend/globals/components/markdown/markdown.less#L1-L140) +- [frontend/globals/components/markdown/prism.less:1-185](file://frontend/globals/components/markdown/prism.less#L1-L185) +- [frontend/globals/components/markdown/html-tags.ts:1-210](file://frontend/globals/components/markdown/html-tags.ts#L1-L210) +- [backend/modelscope_studio/components/base/markdown/**init**.py:1-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L1-L174) + +**章节来源** + +- [frontend/base/markdown/Index.svelte:1-63](file://frontend/base/markdown/Index.svelte#L1-L63) +- [frontend/base/markdown/markdown.tsx:1-34](file://frontend/base/markdown/markdown.tsx#L1-L34) +- [frontend/globals/components/markdown/index.tsx:1-272](file://frontend/globals/components/markdown/index.tsx#L1-L272) +- [backend/modelscope_studio/components/base/markdown/**init**.py:1-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L1-L174) + +## 核心组件 + +- 前端 React 组件：负责 Markdown 解析、代码高亮、数学公式渲染、Mermaid 图表、HTML 安全过滤、复制按钮交互等。 +- 后端 Gradio 组件：负责参数透传、事件绑定（如 copy/change/mouse 系列）、默认值与示例数据。 + +关键职责划分： + +- 解析与渲染：Marked + marked-highlight（Prism）+ 自定义扩展（LaTeX、Mermaid） +- 安全过滤：Amuchina + 外链处理 +- 数学公式：KaTeX 按需加载与自动渲染 +- 图表：Mermaid 按需加载与错误回退 +- 样式：通用样式 + Prism 主题变量 + +**章节来源** + +- [frontend/globals/components/markdown/index.tsx:27-48](file://frontend/globals/components/markdown/index.tsx#L27-L48) +- [frontend/globals/components/markdown/utils.ts:286-344](file://frontend/globals/components/markdown/utils.ts#L286-L344) +- [backend/modelscope_studio/components/base/markdown/**init**.py:11-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L11-L174) + +## 架构总览 + +Markdown 组件从后端接收参数，经前端包装后进行解析与渲染。解析阶段可启用行尾换行、标题锚点、LaTeX 与 Mermaid 扩展；渲染阶段结合 Prism 进行代码高亮，结合 KaTeX/Mermaid 进行数学与图表渲染，并对输出 HTML 进行安全过滤。 + +```mermaid +sequenceDiagram +participant Backend as "后端组件" +participant Wrapper as "前端包装(Svelte)" +participant ReactComp as "React 组件" +participant Parser as "Marked/Prism/KaTeX/Mermaid" +participant Sanitizer as "HTML 过滤" +Backend->>Wrapper : 传递参数(value, 配置) +Wrapper->>ReactComp : 渲染组件并注入 props +ReactComp->>Parser : 初始化解析器(含扩展/高亮) +ReactComp->>Parser : 解析 Markdown +Parser-->>ReactComp : 返回 HTML 片段 +ReactComp->>Sanitizer : 可选安全过滤 +Sanitizer-->>ReactComp : 返回安全 HTML +ReactComp-->>Wrapper : 渲染最终内容 +``` + +**图表来源** + +- [frontend/base/markdown/Index.svelte:19-62](file://frontend/base/markdown/Index.svelte#L19-L62) +- [frontend/globals/components/markdown/index.tsx:86-92](file://frontend/globals/components/markdown/index.tsx#L86-L92) +- [frontend/globals/components/markdown/utils.ts:286-344](file://frontend/globals/components/markdown/utils.ts#L286-L344) +- [frontend/globals/components/markdown/sanitize.ts:12-25](file://frontend/globals/components/markdown/sanitize.ts#L12-L25) + +## 详细组件分析 + +### 属性定义与默认值 + +- value: 字符串，Markdown 内容 +- sanitizeHtml: 布尔，是否启用 HTML 安全过滤，默认开启 +- latexDelimiters: 数组，自定义 LaTeX 分隔符，包含 left/right/display 三元组 +- lineBreaks: 布尔，是否将换行符转换为
，默认开启 +- headerLinks: 布尔，是否生成标题锚点与链接图标，默认关闭 +- showCopyButton: 布尔，是否显示整体复制按钮 +- rtl: 布尔，是否启用从右到左布局 +- themeMode: 字符串，主题模式（light/dark），用于样式与 Mermaid 主题 +- rootUrl: 字符串，根路径，用于外链判断与资源定位 +- allowTags: 布尔或字符串数组，控制允许的 HTML/SVG 标签 +- onCopy: 回调，复制成功时触发 +- onChange: 回调，渲染完成时触发 +- copyButtons: 自定义复制按钮集合（通过插槽） + +默认 LaTeX 分隔符集合包含多组常见表达式（行内/块级、括号变体等）。 + +**章节来源** + +- [frontend/globals/components/markdown/index.tsx:27-48](file://frontend/globals/components/markdown/index.tsx#L27-L48) +- [frontend/globals/components/markdown/index.tsx:50-60](file://frontend/globals/components/markdown/index.tsx#L50-L60) +- [backend/modelscope_studio/components/base/markdown/**init**.py:54-141](file://backend/modelscope_studio/components/base/markdown/__init__.py#L54-L141) + +### 渲染选项与解析器配置 + +- 行尾换行：由 Marked 的 breaks 选项控制 +- 标题锚点：在启用 headerLinks 时，为标题生成 ID 并插入锚点链接图标 +- LaTeX：自定义 tokenizer 支持多组分隔符，渲染为块级容器 +- Mermaid：自定义 tokenizer 支持代码块标记为 mermaid，渲染为图表 +- 代码高亮：通过 marked-highlight 集成 Prism，按语言类名渲染 +- HTML 安全：对链接外链添加 target/rel，使用 Amuchina 白名单过滤 + +```mermaid +flowchart TD +Start(["开始"]) --> Init["初始化 Marked
启用 GFM/换行/高亮"] +Init --> Header{"启用标题锚点?"} +Header --> |是| AddHeader["注册标题扩展
生成 ID/锚点"] +Header --> |否| SkipHeader["跳过标题扩展"] +AddHeader --> Ext +SkipHeader --> Ext +Ext["注册 LaTeX/Mermaid 扩展"] --> Parse["解析 Markdown"] +Parse --> Math{"存在 LaTeX 语法?"} +Math --> |是| LoadKatex["按需加载 KaTeX 并渲染"] +Math --> |否| SkipMath["跳过数学渲染"] +LoadKatex --> Safe{"启用 HTML 过滤?"} +SkipMath --> Safe +Safe --> |是| Sanitize["外链处理/白名单过滤"] +Safe --> |否| NoSanitize["保留原 HTML"] +Sanitize --> Render["渲染结果"] +NoSanitize --> Render +Render --> End(["结束"]) +``` + +**图表来源** + +- [frontend/globals/components/markdown/utils.ts:286-344](file://frontend/globals/components/markdown/utils.ts#L286-L344) +- [frontend/globals/components/markdown/index.tsx:107-138](file://frontend/globals/components/markdown/index.tsx#L107-L138) +- [frontend/globals/components/markdown/sanitize.ts:12-25](file://frontend/globals/components/markdown/sanitize.ts#L12-L25) + +**章节来源** + +- [frontend/globals/components/markdown/utils.ts:286-344](file://frontend/globals/components/markdown/utils.ts#L286-L344) +- [frontend/globals/components/markdown/index.tsx:107-138](file://frontend/globals/components/markdown/index.tsx#L107-L138) + +### 代码高亮与语言支持 + +- 高亮库：Prism.js（marked-highlight 集成） +- 语言支持：内置加载 Python、LaTeX、Bash、JSX、TypeScript、TSX 等常用语言 +- 渲染方式：根据代码块语言动态选择 Prism 语言，未识别语言则保持原文 +- 主题：通过 prism.less 应用主题变量，深色模式下切换暗色配色 + +```mermaid +classDiagram +class Prism { ++highlight(code, lang, alias) ++languages +} +class MarkedHighlight { ++highlight(code, lang) +} +class MarkdownUtils { ++create_marked() +} +MarkdownUtils --> MarkedHighlight : "使用" +MarkedHighlight --> Prism : "调用" +``` + +**图表来源** + +- [frontend/globals/components/markdown/utils.ts:9-16](file://frontend/globals/components/markdown/utils.ts#L9-L16) +- [frontend/globals/components/markdown/utils.ts:303-310](file://frontend/globals/components/markdown/utils.ts#L303-L310) + +**章节来源** + +- [frontend/globals/components/markdown/utils.ts:9-16](file://frontend/globals/components/markdown/utils.ts#L9-L16) +- [frontend/globals/components/markdown/utils.ts:303-310](file://frontend/globals/components/markdown/utils.ts#L303-L310) + +### HTML 安全过滤与白名单 + +- 外链处理：对外部链接自动设置 target="\_blank" 与 rel="noopener noreferrer" +- 白名单过滤：基于 Amuchina 对 HTML 进行清理，仅保留标准 HTML 与 SVG 标签 +- 允许标签：支持布尔开关或显式数组，对不在白名单内的标签进行转义 + +```mermaid +flowchart TD +A["输入 HTML"] --> B["遍历节点(A/IMG 等)"] +B --> C{"是否外部链接?"} +C --> |是| D["设置 target/_blank + rel"] +C --> |否| E["保持不变"] +D --> F["Amuchina 白名单过滤"] +E --> F +F --> G["输出安全 HTML"] +``` + +**图表来源** + +- [frontend/globals/components/markdown/sanitize.ts:12-25](file://frontend/globals/components/markdown/sanitize.ts#L12-L25) +- [frontend/globals/components/markdown/html-tags.ts:206-210](file://frontend/globals/components/markdown/html-tags.ts#L206-L210) + +**章节来源** + +- [frontend/globals/components/markdown/sanitize.ts:1-26](file://frontend/globals/components/markdown/sanitize.ts#L1-L26) +- [frontend/globals/components/markdown/html-tags.ts:1-210](file://frontend/globals/components/markdown/html-tags.ts#L1-L210) + +### 样式定制与主题变量 + +- CSS 类名：组件根元素包含 ms-gr-markdown 与 md/prose 等类，便于覆盖 +- 主题变量：通过 CSS 变量控制颜色、间距、圆角、阴影等 +- 代码高亮主题：prism.less 提供明/暗两套配色，随 themeMode 切换 +- 复制按钮：绝对定位，支持自定义按钮集合（copy/copied） + +```mermaid +classDiagram +class Styles { ++ms-gr-markdown ++md ++prose ++code_wrap ++copy_code_button +} +class ThemeVars { ++--block-background-fill ++--border-color-primary ++--body-text-color ++--code-background-fill ++... +} +Styles --> ThemeVars : "使用" +``` + +**图表来源** + +- [frontend/globals/components/markdown/markdown.less:1-140](file://frontend/globals/components/markdown/markdown.less#L1-L140) +- [frontend/globals/components/markdown/prism.less:1-185](file://frontend/globals/components/markdown/prism.less#L1-L185) + +**章节来源** + +- [frontend/globals/components/markdown/markdown.less:1-140](file://frontend/globals/components/markdown/markdown.less#L1-L140) +- [frontend/globals/components/markdown/prism.less:1-185](file://frontend/globals/components/markdown/prism.less#L1-L185) + +### 使用示例 + +- 基础文本渲染：直接传入 Markdown 字符串 +- 显示复制按钮：启用 showCopyButton 或通过插槽提供自定义按钮 +- 自定义按钮：使用 Slot 注入两个按钮（如复制/已复制状态） + +参考示例脚本与文档： + +- 基础示例：[basic.py:1-10](file://docs/components/base/markdown/demos/basic.py#L1-L10) +- 自定义复制按钮：[custom_copy_buttons.py:1-21](file://docs/components/base/markdown/demos/custom_copy_buttons.py#L1-L21) +- 组件说明：[README.md:1-13](file://docs/components/base/markdown/README.md#L1-L13) + +**章节来源** + +- [docs/components/base/markdown/demos/basic.py:1-10](file://docs/components/base/markdown/demos/basic.py#L1-L10) +- [docs/components/base/markdown/demos/custom_copy_buttons.py:1-21](file://docs/components/base/markdown/demos/custom_copy_buttons.py#L1-L21) +- [docs/components/base/markdown/README.md:1-13](file://docs/components/base/markdown/README.md#L1-L13) + +## 依赖关系分析 + +- 前端依赖 + - Marked：Markdown 解析与渲染 + - marked-highlight + Prism：代码高亮 + - KaTeX：数学公式渲染（按需加载） + - Mermaid：图表渲染（按需加载） + - Amuchina：HTML 白名单过滤 + - github-slugger：标题 ID 生成 +- 后端依赖 + - Gradio 事件监听：copy/change/mouse 系列 + - 前端目录解析：resolve_frontend_dir("markdown") + +```mermaid +graph LR +A["Marked"] --> B["marked-highlight"] +B --> C["Prism"] +A --> D["LaTeX Tokenizer"] +A --> E["Mermaid Tokenizer"] +A --> F["HTML Renderer"] +F --> G["Amuchina"] +A --> H["KaTeX(按需)"] +A --> I["Mermaid(按需)"] +``` + +**图表来源** + +- [frontend/globals/components/markdown/utils.ts:6-18](file://frontend/globals/components/markdown/utils.ts#L6-L18) +- [frontend/globals/components/markdown/utils.ts:286-344](file://frontend/globals/components/markdown/utils.ts#L286-L344) + +**章节来源** + +- [frontend/globals/components/markdown/utils.ts:6-18](file://frontend/globals/components/markdown/utils.ts#L6-L18) +- [backend/modelscope_studio/components/base/markdown/**init**.py:15-46](file://backend/modelscope_studio/components/base/markdown/__init__.py#L15-L46) + +## 性能考虑 + +- 懒加载 + - KaTeX：首次出现数学公式时才加载样式与自动渲染模块 + - Mermaid：渲染前异步加载并在下一帧执行 + - Prism：在解析阶段按需高亮，避免无谓开销 +- 缓存策略 + - 已加载的 KaTeX 模块进行全局标记，避免重复导入 + - Mermaid 初始化参数固定，减少重复初始化成本 +- 渲染时机 + - 使用 requestAnimationFrame 将渲染操作推迟到浏览器空闲帧 + - 仅在内容变化时重新解析与渲染 +- 安全过滤 + - 仅在启用 sanitizeHtml 时进行过滤，避免不必要的 DOM 解析 + +**章节来源** + +- [frontend/globals/components/markdown/index.tsx:140-173](file://frontend/globals/components/markdown/index.tsx#L140-L173) +- [frontend/globals/components/markdown/utils.ts:177-223](file://frontend/globals/components/markdown/utils.ts#L177-L223) + +## 故障排查指南 + +- 复制按钮无效 + - 检查容器是否正确绑定点击事件（bind_copy_event） + - 确认 copyButtons 插槽是否正确注入 +- 数学公式不渲染 + - 确认 latexDelimiters 是否正确配置 + - 检查是否启用了 sanitizeHtml 导致脚本被移除 +- Mermaid 图表报错 + - 查看控制台错误日志 + - 确认 mermaid 代码块闭合与语法正确 + - 检查 themeMode 是否与页面主题一致 +- 外链未打开新窗口 + - 确认 rootUrl 与链接 origin 匹配 + - 检查 sanitize 流程中是否正确设置 target/rel +- 代码高亮失效 + - 确认语言标识是否在 Prism 支持列表中 + - 检查 prism.less 是否正确引入与主题变量生效 + +**章节来源** + +- [frontend/globals/components/markdown/utils.ts:346-380](file://frontend/globals/components/markdown/utils.ts#L346-L380) +- [frontend/globals/components/markdown/sanitize.ts:12-25](file://frontend/globals/components/markdown/sanitize.ts#L12-L25) +- [frontend/globals/components/markdown/utils.ts:177-223](file://frontend/globals/components/markdown/utils.ts#L177-L223) + +## 结论 + +ModelScope Studio 的 Markdown 组件在保证安全与可访问性的前提下，提供了丰富的渲染能力与灵活的定制接口。通过 Marked + Prism + KaTeX + Mermaid 的组合，满足从基础文本到复杂公式与图表的多样化需求；通过白名单过滤与外链处理确保输出安全；通过主题变量与样式类名实现一致的视觉风格与良好的可定制性。 + +## 附录 + +### 后端组件参数一览 + +- 参数名称：value、rtl、latex_delimiters、sanitize_html、line_breaks、header_links、allow_tags、show_copy_button、copy_buttons +- 事件：change、copy、click、dblclick、mousedown、mouseup、mouseover、mouseout、mousemove、scroll +- 示例：example_payload/example_value 返回简单 Markdown 字符串 + +**章节来源** + +- [backend/modelscope_studio/components/base/markdown/**init**.py:54-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L54-L174) + +### 前端组件属性一览 + +- value、sanitizeHtml、latexDelimiters、lineBreaks、headerLinks、showCopyButton、rtl、themeMode、rootUrl、allowTags、onCopy、onChange、copyButtons +- 默认 LaTeX 分隔符集合、复制按钮图标与反馈、Mermaid 错误回退 + +**章节来源** + +- [frontend/globals/components/markdown/index.tsx:27-48](file://frontend/globals/components/markdown/index.tsx#L27-L48) +- [frontend/globals/components/markdown/index.tsx:50-60](file://frontend/globals/components/markdown/index.tsx#L50-L60) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/React \347\273\204\344\273\266\346\241\245\346\216\245 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/React \347\273\204\344\273\266\346\241\245\346\216\245 API.md" new file mode 100644 index 00000000..0ccc5d62 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/React \347\273\204\344\273\266\346\241\245\346\216\245 API.md" @@ -0,0 +1,378 @@ +# React 组件桥接 API + + +**本文引用的文件** +- [frontend/svelte-preprocess-react/index.ts](file://frontend/svelte-preprocess-react/index.ts) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts](file://frontend/svelte-preprocess-react/sveltify.svelte.ts) +- [frontend/svelte-preprocess-react/inject.ts](file://frontend/svelte-preprocess-react/inject.ts) +- [frontend/svelte-preprocess-react/react-slot.tsx](file://frontend/svelte-preprocess-react/reactSlot.tsx) +- [frontend/svelte-preprocess-react/internal/types.ts](file://frontend/svelte-preprocess-react/internal/types.ts) +- [frontend/svelte-preprocess-react/react-contexts/index.ts](file://frontend/svelte-preprocess-react/react-contexts/index.ts) +- [frontend/utils/convertToCamelCase.ts](file://frontend/utils/convertToCamelCase.ts) +- [frontend/utils/createFunction.ts](file://frontend/utils/createFunction.ts) +- [frontend/utils/patchProps.tsx](file://frontend/utils/patchProps.tsx) +- [frontend/utils/hooks/useMemoizedEqualValue.ts](file://frontend/utils/hooks/useMemoizedEqualValue.ts) +- [frontend/utils/style.ts](file://frontend/utils/style.ts) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/base/text/text.tsx](file://frontend/base/text/text.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：标准用法与示例路径](#附录标准用法与示例路径) + +## 简介 + +本文件为 ModelScope Studio 的 React 组件桥接系统提供全面的 API 文档，重点覆盖以下方面： + +- React 组件到 Svelte 组件的转换机制（sveltify） +- 属性映射、事件绑定与状态同步 +- 事件处理（冒泡、委托、自定义事件） +- 生命周期钩子在 Svelte 中的对应实现 +- 属性转换规则（驼峰命名、布尔值、函数属性） +- 上下文系统（React Context 与 Svelte Context 的互操作） +- 性能优化（懒加载、缓存、内存管理） +- 错误处理与调试技巧 + +## 项目结构 + +桥接系统主要由三部分组成： + +- 注入层：初始化全局运行时环境与库桥接 +- 转换层：sveltify 将 React 组件包装为 Svelte 组件 +- 渲染层：ReactSlot 将 Svelte 插槽内容渲染为 React 元素，并支持克隆与属性注入 + +```mermaid +graph TB +Inject["注入层
inject.ts"] --> Types["类型定义
internal/types.ts"] +Inject --> ReactContexts["React 上下文
react-contexts/index.ts"] +Sveltify["转换层
sveltify.svelte.ts"] --> Bridge["桥接器
Bridge.svelte"] +Sveltify --> ReactWrapper["React 包装器
ReactWrapper.svelte"] +ReactSlot["渲染层
react-slot.tsx"] --> Portal["DOM 传送门
createPortal"] +Utils["工具集
convertToCamelCase.ts
createFunction.ts
patchProps.tsx
style.ts"] --> Sveltify +Utils --> ReactSlot +DemoBtn["示例组件
antd/button/button.tsx"] --> Sveltify +DemoForm["示例组件
antd/form/form.tsx"] --> Sveltify +DemoText["示例组件
base/text/text.tsx"] --> Sveltify +``` + +图表来源 + +- [frontend/svelte-preprocess-react/inject.ts:1-103](file://frontend/svelte-preprocess-react/inject.ts#L1-L103) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/svelte-preprocess-react/internal/types.ts:1-79](file://frontend/svelte-preprocess-react/internal/types.ts#L1-L79) +- [frontend/svelte-preprocess-react/react-contexts/index.ts:1-123](file://frontend/svelte-preprocess-react/react-contexts/index.ts#L1-L123) +- [frontend/utils/convertToCamelCase.ts:1-22](file://frontend/utils/convertToCamelCase.ts#L1-L22) +- [frontend/utils/createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/base/text/text.tsx:1-11](file://frontend/base/text/text.tsx#L1-L11) + +章节来源 + +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) +- [frontend/svelte-preprocess-react/inject.ts:1-103](file://frontend/svelte-preprocess-react/inject.ts#L1-L103) + +## 核心组件 + +- sveltify：将任意 React 组件包装为 Svelte 组件，负责属性透传、插槽映射、事件桥接与树节点构建。 +- ReactSlot：将 Svelte 插槽内容渲染为 React 元素，支持克隆 DOM、事件监听迁移、样式与类名注入。 +- 类型系统：统一事件命名、属性剔除与 Svelte/SvelteKit 类型适配。 +- 上下文系统：React Context 到 Svelte 的桥接与合并策略。 + +章节来源 + +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:27-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L27-L119) +- [frontend/svelte-preprocess-react/react-slot.tsx:8-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L8-L224) +- [frontend/svelte-preprocess-react/internal/types.ts:4-79](file://frontend/svelte-preprocess-react/internal/types.ts#L4-L79) +- [frontend/svelte-preprocess-react/react-contexts/index.ts:1-123](file://frontend/svelte-preprocess-react/react-contexts/index.ts#L1-L123) + +## 架构总览 + +下图展示从 Svelte 使用方到 React 组件的完整调用链路与数据流： + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 组件" +participant Sveltify as "sveltify 包装器" +participant Bridge as "Bridge 桥接器" +participant ReactWrapper as "ReactWrapper" +participant ReactComp as "React 组件" +participant DOM as "DOM 传送门" +Svelte->>Sveltify : 传入 props 与插槽 +Sveltify->>Bridge : 创建/更新树节点 +Bridge->>ReactWrapper : 渲染 ReactWrapper +ReactWrapper->>ReactComp : 传递 props/事件/插槽 +ReactComp-->>DOM : 通过 createPortal 渲染到目标容器 +DOM-->>Svelte : 插槽内容可见 +``` + +图表来源 + +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:40-104](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L40-L104) +- [frontend/svelte-preprocess-react/react-slot.tsx:109-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L224) + +## 详细组件分析 + +### sveltify 函数与转换机制 + +- 功能概述 + - 将 React 组件包装为 Svelte 组件，自动处理属性透传、插槽映射、事件桥接与树形渲染。 + - 支持可选的忽略渲染选项（ignore）以控制节点是否参与渲染。 +- 关键点 + - 初始化共享根节点与桥接容器，确保 React 根挂载在文档头部。 + - 为每个 Svelte 实例生成唯一 key，并建立父子节点关系。 + - 通过 Bridge 与 ReactWrapper 协作完成渲染与更新。 + - 提供 Promise 化返回，等待全局初始化完成后才可使用。 +- 参数与返回 + - 第一个参数：React 组件类型（可带通用插槽声明）。 + - 第二个参数：可选配置对象，当前支持 ignore 字段。 + - 返回：Sveltified 类型的 Svelte 组件（Promise 或已初始化版本）。 + +```mermaid +flowchart TD +Start(["调用 sveltify"]) --> InitRoot["初始化共享根节点与桥接容器"] +InitRoot --> BuildNode["构建树节点
设置 key/ignore/reactComponent"] +BuildNode --> AttachParent["附加到父节点
加入 nodes 并触发 rerender"] +AttachParent --> Render["调用 Bridge 渲染"] +Render --> Done(["返回 Sveltified 组件"]) +``` + +图表来源 + +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:40-104](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L40-L104) + +章节来源 + +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:27-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L27-L119) +- [frontend/svelte-preprocess-react/index.ts:6-8](file://frontend/svelte-preprocess-react/index.ts#L6-L8) + +### ReactSlot 插槽渲染与事件处理 + +- 功能概述 + - 将 Svelte 插槽内容渲染为 React 元素，支持克隆 DOM、迁移事件监听器、注入样式与类名。 + - 可选择观察属性变化，以适配动态渲染场景（如表格列渲染）。 +- 关键点 + - 克隆策略：遍历子节点，复制文本节点与元素节点；对 React 元素进行深度克隆并迁移内部注册的副作用。 + - 事件迁移：读取元素上的事件监听列表，重新绑定到克隆节点上。 + - 属性注入：支持 className 与 style 的注入，并将 React 样式对象转换为内联样式。 + - 观察器：使用防抖的 MutationObserver 监听插槽变化，确保动态内容及时反映。 +- 参数 + - slot：插槽对应的 HTMLElement。 + - clone：是否克隆 DOM（默认 false）。 + - className/style：注入的类名与样式对象。 + - observeAttributes：是否观察属性变化（默认 false）。 + +```mermaid +flowchart TD +Enter(["ReactSlot 渲染"]) --> CheckSlot{"slot 是否存在？"} +CheckSlot --> |否| Exit["退出"] +CheckSlot --> |是| CloneMode{"clone 为真？"} +CloneMode --> |是| Clone["克隆 DOM 树
迁移事件监听器"] +CloneMode --> |否| Mount["直接挂载到容器"] +Clone --> Observe{"开启观察器？"} +Observe --> |是| Debounce["防抖后重渲染"] +Observe --> |否| MountProps["注入 className/style 并挂载"] +Debounce --> Render["重新克隆并渲染"] +Render --> MountProps +MountProps --> Cleanup["卸载时清理 DOM 与观察器"] +Cleanup --> Exit +``` + +图表来源 + +- [frontend/svelte-preprocess-react/react-slot.tsx:16-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L16-L224) + +章节来源 + +- [frontend/svelte-preprocess-react/react-slot.tsx:8-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L8-L224) + +### 类型系统与事件映射 + +- 事件命名与映射 + - React 侧事件属性以大写开头（如 onClick），Svelte 侧事件处理器以 on 前缀（如 onClick 对应 on-click）。 + - 类型工具将 React 事件属性映射为 Svelte 事件处理器签名。 +- 属性剔除 + - 将 React 事件属性从普通属性中剔除，避免传递给 Svelte 组件导致冲突。 +- Svelte Props 适配 + - children 属性被适配为 Svelte 的 Snippet 类型，以支持插槽与片段。 + +章节来源 + +- [frontend/svelte-preprocess-react/internal/types.ts:4-79](file://frontend/svelte-preprocess-react/internal/types.ts#L4-L79) + +### 上下文系统（React Context 与 Svelte 的互操作） + +- React Context + - 提供 IconFont、FormItem、AutoComplete、Suggestion、SuggestionOpen 等上下文，用于组件间共享状态与回调。 +- Svelte 侧桥接 + - 通过 ContextPropsContext 在 ReactSlot 内部读取上下文值，支持强制克隆与参数变更检测。 + - 支持上下文合并策略，避免重复 Provider 导致的状态丢失。 +- 使用建议 + - 在需要动态渲染或克隆 DOM 的场景下，结合 forceClone 与 observeAttributes 提升稳定性。 + +章节来源 + +- [frontend/svelte-preprocess-react/react-contexts/index.ts:1-123](file://frontend/svelte-preprocess-react/react-contexts/index.ts#L1-L123) + +### 属性转换规则与工具 + +- 驼峰命名转换 + - 将下划线风格的键转换为小驼峰或大驼峰，便于与 React 属性保持一致。 +- 布尔值处理 + - 通过工具函数将布尔值正确映射到 React 属性。 +- 函数属性绑定 + - 支持字符串形式的函数定义，自动解析为可执行函数，便于从外部传入回调逻辑。 +- 插槽属性补丁 + - 对 key 等特殊属性进行内部转存与恢复，避免与 Svelte 内部机制冲突。 + +章节来源 + +- [frontend/utils/convertToCamelCase.ts:1-22](file://frontend/utils/convertToCamelCase.ts#L1-L22) +- [frontend/utils/createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) + +### 事件处理机制 + +- 事件冒泡与委托 + - ReactSlot 在克隆过程中迁移事件监听器，确保克隆后的元素仍能响应事件。 +- 自定义事件 + - 通过 ContextPropsContext 与 useFunction 钩子，将自定义回调以稳定函数形式注入 React 组件。 +- 样式与单位 + - 将 React 样式对象转换为内联样式字符串或对象，自动添加像素单位（无单位属性除外）。 + +章节来源 + +- [frontend/svelte-preprocess-react/react-slot.tsx:67-96](file://frontend/svelte-preprocess-react/react-slot.tsx#L67-L96) +- [frontend/utils/hooks/useMemoizedEqualValue.ts:1-15](file://frontend/utils/hooks/useMemoizedEqualValue.ts#L1-L15) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) + +### 生命周期钩子在 Svelte 中的对应实现 + +- 初始化 + - 通过全局初始化 Promise 确保运行时环境就绪后再进行渲染。 +- 更新 + - 每次节点变更触发 rerender，Bridge 重新渲染 ReactWrapper 与子树。 +- 销毁 + - 清理 DOM 节点与观察器，释放资源。 + +章节来源 + +- [frontend/svelte-preprocess-react/inject.ts:95-103](file://frontend/svelte-preprocess-react/inject.ts#L95-L103) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:75-82](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L75-L82) +- [frontend/svelte-preprocess-react/react-slot.tsx:204-212](file://frontend/svelte-preprocess-react/react-slot.tsx#L204-L212) + +## 依赖关系分析 + +- 运行时依赖 + - React、ReactDOM、@ant-design/cssinjs、@ant-design/icons、@ant-design/x、dayjs 等库通过全局注入提供。 +- 工具依赖 + - lodash-es 提供 isEqual、debounce、noop 等工具。 +- 组件依赖 + - sveltify 依赖 Bridge 与 ReactWrapper 完成渲染；ReactSlot 依赖 createPortal 与样式工具。 + +```mermaid +graph LR +Inject["inject.ts"] --> Libs["全局库注入"] +Sveltify["sveltify.svelte.ts"] --> Bridge["Bridge.svelte"] +Sveltify --> ReactWrapper["ReactWrapper.svelte"] +ReactSlot["react-slot.tsx"] --> Portal["createPortal"] +Utils["工具集"] --> Sveltify +Utils --> ReactSlot +``` + +图表来源 + +- [frontend/svelte-preprocess-react/inject.ts:20-85](file://frontend/svelte-preprocess-react/inject.ts#L20-L85) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-7](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L7) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-6](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L6) + +章节来源 + +- [frontend/svelte-preprocess-react/inject.ts:1-103](file://frontend/svelte-preprocess-react/inject.ts#L1-L103) + +## 性能考虑 + +- 懒加载与延迟初始化 + - 通过全局初始化 Promise 与共享根节点，避免重复挂载与多次初始化。 +- 缓存与去重 + - 使用 useMemoizedEqualValue 与 ContextPropsContext 的变更检测，减少不必要的重渲染。 +- 内存管理 + - 卸载时断开 MutationObserver、移除 DOM 节点与桥接容器，防止内存泄漏。 +- 渲染优化 + - ReactSlot 的克隆与观察采用防抖策略，降低频繁变更带来的性能压力。 + +章节来源 + +- [frontend/svelte-preprocess-react/react-slot.tsx:180-198](file://frontend/svelte-preprocess-react/react-slot.tsx#L180-L198) +- [frontend/utils/hooks/useMemoizedEqualValue.ts:1-15](file://frontend/utils/hooks/useMemoizedEqualValue.ts#L1-L15) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:67-82](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L67-L82) + +## 故障排查指南 + +- 插槽不显示 + - 检查 slot 是否存在且未被销毁；确认 clone 模式与 observeAttributes 设置。 +- 事件失效 + - 确认事件监听是否随克隆迁移；检查事件监听器是否被覆盖或移除。 +- 样式异常 + - 检查样式对象是否正确转换为内联样式；确认单位是否符合预期。 +- 性能问题 + - 合理使用 forceClone 与防抖观察器；避免频繁变更导致的重渲染。 +- 上下文冲突 + - 使用 ContextPropsProvider 的合并策略与参数变更检测，避免重复 Provider 导致的状态丢失。 + +章节来源 + +- [frontend/svelte-preprocess-react/react-slot.tsx:156-212](file://frontend/svelte-preprocess-react/react-slot.tsx#L156-L212) +- [frontend/utils/style.ts:39-77](file://frontend/utils/style.ts#L39-L77) +- [frontend/svelte-preprocess-react/react-contexts/index.ts:67-123](file://frontend/svelte-preprocess-react/react-contexts/index.ts#L67-L123) + +## 结论 + +ModelScope Studio 的 React 组件桥接系统通过 sveltify 与 ReactSlot 实现了 React 与 Svelte 的无缝协作。其设计强调： + +- 明确的类型约束与事件映射 +- 稳健的插槽渲染与事件迁移 +- 可扩展的上下文系统与性能优化策略 +- 清晰的生命周期管理与资源回收 + +该体系为复杂前端应用提供了统一的组件桥接方案，既保证了开发体验，也兼顾了运行时性能与稳定性。 + +## 附录：标准用法与示例路径 + +- 简单组件桥接 + - 示例：基础文本组件桥接 + - 路径：[frontend/base/text/text.tsx:1-11](file://frontend/base/text/text.tsx#L1-L11) +- 复杂组件桥接（含插槽与事件） + - 示例：按钮组件桥接（图标与加载态插槽） + - 路径：[frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- 表单组件桥接（含状态同步与动作分发） + - 示例：表单组件桥接（值同步、动作重置、事件转发） + - 路径：[frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- sveltify 使用要点 + - 路径：[frontend/svelte-preprocess-react/sveltify.svelte.ts:27-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L27-L119) +- ReactSlot 使用要点 + - 路径：[frontend/svelte-preprocess-react/react-slot.tsx:8-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L8-L224) +- 类型与事件映射 + - 路径：[frontend/svelte-preprocess-react/internal/types.ts:4-79](file://frontend/svelte-preprocess-react/internal/types.ts#L4-L79) +- 上下文系统 + - 路径：[frontend/svelte-preprocess-react/react-contexts/index.ts:1-123](file://frontend/svelte-preprocess-react/react-contexts/index.ts#L1-L123) +- 属性转换与函数绑定 + - 路径：[frontend/utils/convertToCamelCase.ts:1-22](file://frontend/utils/convertToCamelCase.ts#L1-L22) + - 路径：[frontend/utils/createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) + - 路径：[frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- 样式工具 + - 路径：[frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..405ae278 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API.md" @@ -0,0 +1,436 @@ +# Ant Design X 组件 API + + +**本文引用的文件** +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/components/pro/__init__.py](file://backend/modelscope_studio/components/pro/__init__.py) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [frontend/antdx/conversations/conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [frontend/antdx/sender/sender.tsx](file://frontend/antdx/sender/sender.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 中基于 Ant Design X 的 Svelte 组件 API 参考文档，覆盖以下组件族： + +- 通用组件：来自 Ant Design（antd）的常用 UI 组件封装 +- 唤醒组件：用于引导用户交互、提示或触发流程的组件 +- 表达组件：用于内容展示、富文本、对话气泡等表达类组件 +- 确认组件：用于二次确认、弹窗确认等交互组件 +- 反馈组件：用于消息、通知、进度、结果等反馈类组件 +- 工具组件：用于表单、布局、工具栏、上下文等辅助能力 + +文档重点记录各组件的属性定义、事件处理函数、插槽系统、状态管理与消息传递、对话流程控制机制，并给出面向 AI/ML 场景的使用模式与最佳实践。 + +## 项目结构 + +ModelScope Studio 的前端采用 Svelte + Ant Design X 的组合，通过统一的适配层将 React 组件桥接到 Svelte 生态中。后端 Python 层负责导出组件集合，便于在应用中按需引入。 + +```mermaid +graph TB +subgraph "后端组件导出" +A_init["backend/modelscope_studio/components/__init__.py"] +A_antd_init["backend/modelscope_studio/components/antd/__init__.py"] +A_antdx_init["backend/modelscope_studio/components/antdx/__init__.py"] +A_base_init["backend/modelscope_studio/components/base/__init__.py"] +A_pro_init["backend/modelscope_studio/components/pro/__init__.py"] +end +subgraph "前端适配层" +F_button["frontend/antd/button/button.tsx"] +F_form["frontend/antd/form/form.tsx"] +F_actions["frontend/antdx/actions/actions.tsx"] +F_bubble["frontend/antdx/bubble/bubble.tsx"] +F_conversations["frontend/antdx/conversations/conversations.tsx"] +F_sender["frontend/antdx/sender/sender.tsx"] +end +A_init --> A_antd_init +A_init --> A_antdx_init +A_init --> A_base_init +A_init --> A_pro_init +A_antd_init --> F_button +A_antd_init --> F_form +A_antdx_init --> F_actions +A_antdx_init --> F_bubble +A_antdx_init --> F_conversations +A_antdx_init --> F_sender +``` + +**图示来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +**章节来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) + +## 核心组件 + +本节概述各组件族的关键职责与典型用法，便于快速定位与选型。 + +- 通用组件（Antd） + - 职责：提供基础 UI 能力，如按钮、输入框、表单、布局、消息、通知等 + - 典型组件：Button、Form、Input、Modal、Message、Notification 等 + - 特性：通过适配器将 Ant Design 的 React 组件桥接为 Svelte 组件，支持插槽与函数式属性 + +- 唤醒组件（AntdX） + - 职责：引导用户进行下一步操作，如动作菜单、提示、技能开关等 + - 典型组件：Actions、Sender、Suggestion、Welcome 等 + - 特性：支持复杂插槽、上下文注入、事件透传与值变更联动 + +- 表达组件（AntdX） + - 职责：用于内容表达与对话呈现，如气泡、思维链、文件卡片、附件等 + - 典型组件：Bubble、ThoughtChain、FileCard、Attachments、Prompts 等 + - 特性：支持渲染函数、可编辑配置、头尾部与额外区域插槽 + +- 确认组件（AntdX） + - 职责：用于二次确认、弹窗确认等交互 + - 典型组件：Popconfirm、Modal（静态）、Tour 等 + - 特性：与 AntdX 的交互语义一致，保持一致的插槽与事件模型 + +- 反馈组件（AntdX） + - 职责：消息、通知、进度、结果等反馈 + - 典型组件：Message、Notification、Progress、Result 等 + - 特性：支持插槽化渲染、函数式回调、状态驱动更新 + +- 工具组件（AntdX） + - 职责：表单、布局、上下文、应用容器等辅助能力 + - 典型组件：Form、Layout、XProvider、Markdown、Slot 等 + - 特性：提供上下文、渲染工具函数与插槽系统 + +**章节来源** + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +## 架构总览 + +下图展示了从后端组件导出到前端适配层再到具体组件的映射关系，以及插槽与函数式属性的处理路径。 + +```mermaid +graph TB +subgraph "后端导出" +B1["antd/__init__.py
导出 Button/Form 等"] +B2["antdx/__init__.py
导出 Actions/Bubble 等"] +B3["base/__init__.py
导出 Application/Slot 等"] +B4["pro/__init__.py
导出 Chatbot/Monaco 等"] +end +subgraph "前端适配" +F1["sveltify
桥接 React 组件"] +F2["插槽系统
ReactSlot/renderParamsSlot"] +F3["函数式属性
useFunction/createFunction"] +F4["上下文与菜单项
withItemsContextProvider/useItems"] +end +subgraph "组件实例" +C1["Button"] +C2["Form"] +C3["Actions"] +C4["Bubble"] +C5["Conversations"] +C6["Sender"] +end +B1 --> F1 --> C1 +B1 --> F1 --> C2 +B2 --> F1 --> C3 +B2 --> F1 --> C4 +B2 --> F1 --> C5 +B2 --> F1 --> C6 +F1 --> F2 +F1 --> F3 +F1 --> F4 +``` + +**图示来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +## 组件详解 + +### 通用组件 API（Antd） + +#### Button（按钮） + +- 作用：将 Ant Design 的 Button 桥接为 Svelte 组件，支持插槽与加载态图标插槽 +- 关键点 + - 插槽：icon、loading.icon + - 值绑定：支持 value 与 children 的智能选择 + - 加载态：loading 支持传入对象并可指定延迟 +- 使用要点 + - 当存在插槽时优先使用插槽渲染，否则回退到属性值 + - 通过 useTargets 处理 children 的目标节点 + +**章节来源** + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) + +#### Form（表单） + +- 作用：将 Ant Design 的 Form 桥接为 Svelte 组件，提供受控值与动作同步 +- 关键点 + - 受控值：value 与 onValueChange + - 动作同步：formAction（reset/submit/validate）与 onResetFormAction + - 插槽：requiredMark + - 回调：onValuesChange +- 使用要点 + - 通过 useEffect 根据 formAction 执行重置/提交/校验 + - 将外部 value 同步到内部 form 实例 + +**章节来源** + +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) + +### 唤醒组件 API（AntdX） + +#### Actions（动作菜单） + +- 作用：将 AntdX 的 Actions 桥接为 Svelte 组件，支持菜单项与下拉渲染插槽 +- 关键点 + - 插槽：dropdownProps.menu.items、dropdownProps.menu.expandIcon、dropdownProps.menu.overflowedIndicator、dropdownProps.dropdownRender、dropdownProps.popupRender + - 上下文：与菜单项上下文集成，支持 items/default 插槽 + - 渲染：renderItems、renderParamsSlot、createFunction +- 使用要点 + - 优先使用插槽中的 items，否则回退到属性 items + - 对下拉渲染与菜单项进行条件性替换 + +**章节来源** + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) + +#### Sender（发送器） + +- 作用：AntdX Sender 的 Svelte 适配，支持上传、粘贴文件、建议上下文、插槽化头部/尾部等 +- 关键点 + - 插槽：suffix、header、prefix、footer、skill.\* 系列 + - 事件：onSubmit（在建议未打开时触发）、onChange、onPasteFile + - 值变更：onValueChange 与 useValueChange + - 上传：upload 函数返回文件数据数组 +- 使用要点 + - 在粘贴文件时调用 upload 并回传路径 + - 通过 slotConfig 格式化结果与自定义渲染 + +**章节来源** + +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +### 表达组件 API（AntdX） + +#### Bubble（气泡） + +- 作用：AntdX Bubble 的 Svelte 适配，支持头/体/脚/额外区域与可编辑配置 +- 关键点 + - 插槽：avatar、editable.okText、editable.cancelText、content、footer、header、extra、loadingRender、contentRender + - 函数：typing、contentRender、header/footer/avatar/extra、editable +- 使用要点 + - 支持布尔 editable 或对象配置；当插槽存在时优先使用插槽 + - 通过 useFunction 将属性转换为函数式渲染 + +**章节来源** + +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) + +#### Conversations（会话列表） + +- 作用：AntdX Conversations 的 Svelte 适配，支持分组、菜单、插槽化标签等 +- 关键点 + - 插槽：menu.trigger、menu.expandIcon、menu.overflowedIndicator、groupable.label + - 上下文：菜单项上下文与会话项上下文 + - 渲染：renderItems、patchMenuEvents（事件透传） +- 使用要点 + - 支持字符串或对象形式的 menu 配置；当无 items 时自动回退 + - 通过 classNames 注入样式类名 + +**章节来源** + +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) + +### 确认组件 API（AntdX） + +- Popconfirm：二次确认弹窗，支持插槽化标题与描述 +- Modal（静态）：静态模态框，适合固定内容展示 +- Tour：引导漫游，支持步骤与插槽化渲染 + +[本节为概念性说明，不直接分析具体文件] + +### 反馈组件 API（AntdX） + +- Message：消息提示，支持插槽化内容与函数式渲染 +- Notification：通知提醒，支持插槽化渲染与关闭回调 +- Progress：进度条，支持插槽化格式化 +- Result：结果页，支持插槽化操作区 + +[本节为概念性说明，不直接分析具体文件] + +### 工具组件 API（AntdX） + +- Form：见“通用组件”小节 +- Layout：布局容器，支持 Content/Footer/Header/Sider +- XProvider：上下文提供者，为 AntdX 组件提供全局配置 +- Markdown：Markdown 渲染组件 +- Slot：插槽容器，用于动态内容挂载 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +## 依赖关系分析 + +```mermaid +graph TB +subgraph "后端导出" +A["components/__init__.py"] +A_antd["antd/__init__.py"] +A_antdx["antdx/__init__.py"] +A_base["base/__init__.py"] +A_pro["pro/__init__.py"] +end +subgraph "前端适配" +U_render["renderItems/renderParamsSlot"] +U_func["useFunction/createFunction"] +U_slot["ReactSlot"] +U_ctx["withItemsContextProvider/useItems"] +end +subgraph "组件" +C_btn["Button"] +C_form["Form"] +C_act["Actions"] +C_bub["Bubble"] +C_conv["Conversations"] +C_snd["Sender"] +end +A --> A_antd --> C_btn +A --> A_antd --> C_form +A --> A_antdx --> C_act +A --> A_antdx --> C_bub +A --> A_antdx --> C_conv +A --> A_antdx --> C_snd +C_btn -.-> U_render +C_form -.-> U_func +C_act -.-> U_render +C_act -.-> U_ctx +C_bub -.-> U_func +C_bub -.-> U_slot +C_conv -.-> U_render +C_conv -.-> U_ctx +C_snd -.-> U_func +C_snd -.-> U_slot +``` + +**图示来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +**章节来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +## 性能考量 + +- 插槽与函数式属性的懒渲染 + - 仅在插槽存在时才渲染对应内容，避免不必要的计算 + - 使用 useMemo 包裹菜单与渲染逻辑，减少重复渲染 +- 受控值与动作同步 + - 通过 useEffect 根据 formAction 触发 reset/submit/validate，避免频繁重绘 + - 使用 useValueChange 管理输入值变更，降低上游抖动 +- 事件透传与防抖 + - 在菜单事件中对 onClick 进行 DOM 事件冒泡阻止，避免意外触发 + - 对函数式属性使用 useMemoizedFn 缓存回调 + +[本节为通用指导，不直接分析具体文件] + +## 故障排查指南 + +- 插槽未生效 + - 检查插槽键名是否与组件约定一致（如 menu.items、dropdownRender 等） + - 确认插槽是否被 children 隐藏或未正确传递 +- 值未同步 + - 对于 Form：确认 value 是否正确传入且 onValueChange 是否被触发 + - 对于 Sender：确认 onValueChange 与 useValueChange 的绑定 +- 下拉菜单不显示 + - 检查 dropdownProps 与 menu.items 是否正确设置 + - 确认 withItemsContextProvider 是否包裹组件 +- 上传失败 + - 确认 upload 函数返回值包含 path 字段 + - 检查 onPasteFile 的回传路径是否正确 + +**章节来源** + +- [frontend/antd/form/form.tsx:32-53](file://frontend/antd/form/form.tsx#L32-L53) +- [frontend/antdx/sender/sender.tsx:135-138](file://frontend/antdx/sender/sender.tsx#L135-L138) +- [frontend/antdx/actions/actions.tsx:39-96](file://frontend/antdx/actions/actions.tsx#L39-L96) + +## 结论 + +本文档梳理了 ModelScope Studio 中 Ant Design X Svelte 组件的 API 与使用模式，重点覆盖了插槽系统、函数式属性、上下文与菜单项集成、值变更与动作同步等关键机制。结合 AI/ML 场景，推荐优先使用 Sender、Bubble、Conversations、Actions 等组件构建对话与表达流程，并通过插槽与函数式属性实现高度定制化的内容渲染与交互行为。 + +## 附录 + +### 组件实例化与配置（AI/ML 场景建议） + +- 对话流程 + - 使用 Sender 作为输入入口，配置 upload 以支持多模态输入 + - 使用 Bubble 渲染回复内容，必要时启用 editable 以支持二次编辑 + - 使用 Conversations 管理会话列表，配合 menu 与 groupable 实现分组与操作 +- 表单与验证 + - 使用 Form 提供受控值与动作同步，结合 reset/submit/validate 控制流程 +- 动作与引导 + - 使用 Actions 提供上下文菜单与引导项，结合插槽实现自定义渲染 + +[本节为概念性说明，不直接分析具体文件] diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\345\217\215\351\246\210\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\345\217\215\351\246\210\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..5b35e256 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\345\217\215\351\246\210\347\273\204\344\273\266 API.md" @@ -0,0 +1,395 @@ +# 反馈组件 API + + +**本文引用的文件** +- [frontend/antd/notification/notification.tsx](file://frontend/antd/notification/notification.tsx) +- [frontend/antd/notification/Index.svelte](file://frontend/antd/notification/Index.svelte) +- [frontend/antdx/notification/notification.tsx](file://frontend/antdx/notification/notification.tsx) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [frontend/antdx/actions/feedback/actions.feedback.tsx](file://frontend/antdx/actions/feedback/actions.feedback.tsx) +- [frontend/antdx/actions/action-item/actions.action-item.tsx](file://frontend/antdx/actions/action-item/actions.action-item.tsx) +- [frontend/antdx/actions/item/actions.item.tsx](file://frontend/antdx/actions/item/actions.item.tsx) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 中 Ant Design X 的反馈组件 API 参考文档，聚焦两类反馈能力： + +- Actions 操作列表组件：用于在对话或工作流中提供可点击的操作项集合，并支持下拉菜单、子项、图标等扩展。 +- Notification 通知组件：用于全局提示消息与浏览器原生通知权限管理，覆盖 Ant Design 与 Ant Design X 两套实现。 + +文档将从接口定义、数据结构、事件与状态管理、用户交互机制、类型规范与最佳实践等方面进行系统阐述，并给出面向 AI 应用的典型使用场景与配置建议。 + +## 项目结构 + +反馈组件主要分布在以下路径： + +- 前端 Ant Design 实现：frontend/antd/notification +- 前端 Ant Design X 实现：frontend/antdx/notification 与 frontend/antdx/actions +- 通用工具：frontend/utils 下的 items 上下文与渲染工具 + +```mermaid +graph TB +subgraph "Ant Design 实现" +A1["antd/notification/notification.tsx"] +A2["antd/notification/Index.svelte"] +end +subgraph "Ant Design X 实现" +B1["antdx/notification/notification.tsx"] +B2["antdx/actions/actions.tsx"] +B3["antdx/actions/context.ts"] +B4["antdx/actions/feedback/actions.feedback.tsx"] +B5["antdx/actions/action-item/actions.action-item.tsx"] +B6["antdx/actions/item/actions.item.tsx"] +end +subgraph "通用工具" +C1["utils/createItemsContext.tsx"] +C2["utils/renderItems.tsx"] +C3["utils/renderParamsSlot.tsx"] +C4["utils/renderSlot.tsx"] +end +A2 --> A1 +B2 --> B3 +B2 --> C1 +B2 --> C2 +B2 --> C3 +B2 --> C4 +B4 --> B2 +B5 --> B3 +B6 --> B2 +``` + +图表来源 + +- [frontend/antd/notification/notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [frontend/antd/notification/Index.svelte:56-79](file://frontend/antd/notification/Index.svelte#L56-L79) +- [frontend/antdx/notification/notification.tsx:1-51](file://frontend/antdx/notification/notification.tsx#L1-L51) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:1-16](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L1-L16) +- [frontend/antdx/actions/action-item/actions.action-item.tsx:1-23](file://frontend/antdx/actions/action-item/actions.action-item.tsx#L1-L23) +- [frontend/antdx/actions/item/actions.item.tsx:1-34](file://frontend/antdx/actions/item/actions.item.tsx#L1-L34) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) + +章节来源 + +- [frontend/antd/notification/notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [frontend/antd/notification/Index.svelte:56-79](file://frontend/antd/notification/Index.svelte#L56-L79) +- [frontend/antdx/notification/notification.tsx:1-51](file://frontend/antdx/notification/notification.tsx#L1-L51) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:1-16](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L1-L16) +- [frontend/antdx/actions/action-item/actions.action-item.tsx:1-23](file://frontend/antdx/actions/action-item/actions.action-item.tsx#L1-L23) +- [frontend/antdx/actions/item/actions.item.tsx:1-34](file://frontend/antdx/actions/item/actions.item.tsx#L1-L34) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) + +## 核心组件 + +- Actions 操作列表组件 + - 负责渲染一组可交互的操作项，支持下拉菜单、子项、图标插槽与菜单项上下文注入。 + - 提供 Actions.Feedback 子组件以适配特定反馈场景。 +- Notification 通知组件 + - Ant Design 版本：基于 antd.notification.useNotification，支持可见性控制与插槽渲染。 + - Ant Design X 版本：基于 @ant-design/x/notification，内置浏览器通知权限请求与按 tag 关闭能力。 + +章节来源 + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:1-16](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L1-L16) +- [frontend/antd/notification/notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [frontend/antdx/notification/notification.tsx:1-51](file://frontend/antdx/notification/notification.tsx#L1-L51) + +## 架构总览 + +反馈组件的运行时架构由“组件桥接层 + 通知/动作库 + 渲染管线”构成： + +- 组件桥接层：通过 sveltify 将 Svelte 组件包装为 React 组件，统一对外暴露属性与插槽。 +- 通知/动作库：分别对接 antd 与 @ant-design/x 的通知与动作能力。 +- 渲染管线：利用 createItemsContext 与 renderItems 等工具，将插槽中的 DOM 节点转换为 React 组件树，支持参数化插槽与克隆策略。 + +```mermaid +sequenceDiagram +participant UI as "调用方" +participant Actions as "Actions 组件" +participant ItemsCtx as "ItemsContext" +participant Renderer as "渲染管线" +participant XActions as "@ant-design/x Actions" +UI->>Actions : 传入 items/dropdownProps/slots +Actions->>ItemsCtx : 注入上下文并收集插槽项 +Actions->>Renderer : 解析插槽为 React 组件 +Renderer-->>Actions : 返回可渲染的 items +Actions->>XActions : 渲染为 Ant Design X 动作列表 +XActions-->>UI : 用户交互回调onClick 等 +``` + +图表来源 + +- [frontend/antdx/actions/actions.tsx:17-120](file://frontend/antdx/actions/actions.tsx#L17-L120) +- [frontend/utils/createItemsContext.tsx:97-274](file://frontend/utils/createItemsContext.tsx#L97-L274) +- [frontend/utils/renderItems.tsx:8-114](file://frontend/utils/renderItems.tsx#L8-L114) + +## 详细组件分析 + +### Actions 操作列表组件 API + +- 组件名称：Actions +- 外观形态：Ant Design X 的 Actions 组件，支持下拉菜单与多级子项。 +- 关键属性（部分）： + - items：操作项数组，支持默认插槽与子项插槽。 + - dropdownProps：透传给下拉菜单的配置，包括 dropdownRender、popupRender、menu 等。 + - slots：插槽映射，支持 menu.expandIcon、menu.overflowedIndicator、menu.items 等。 +- 插槽与上下文： + - 使用 createItemsContext 维护“default”与“items”等插槽项集合。 + - 通过 ItemHandler 将子节点写入上下文，支持 itemProps、itemChildren 等动态计算。 +- 渲染流程： + - 合并外部 items 与插槽解析结果，生成最终的菜单项。 + - 对 dropdownRender/popupRender 与菜单项进行参数化插槽渲染。 +- 典型子组件： + - Actions.Feedback：直接转发 @ant-design/x 的 Actions.Feedback。 + - Actions.Item：封装默认图标与运行中图标的插槽。 + - ActionsActionItem：作为 ItemHandler 的便捷包装，限定允许的插槽键。 + +```mermaid +classDiagram +class Actions { ++props : ActionsProps ++slots : Record ++dropdownProps ++items +} +class ActionsItem { ++props : ActionsItemProps ++slots : defaultIcon, runningIcon +} +class ActionsFeedback { ++props : ActionsFeedbackProps +} +class ItemsContext { ++items : Record ++setItem() ++useItems() +} +class ItemHandler { ++itemIndex ++itemSlotKey ++allowedSlots ++itemChildrenKey +} +Actions --> ItemsContext : "收集/读取" +Actions --> ItemHandler : "子项注入" +ActionsItem --> Actions : "作为子项" +ActionsFeedback --> Actions : "子组件" +``` + +图表来源 + +- [frontend/antdx/actions/actions.tsx:17-120](file://frontend/antdx/actions/actions.tsx#L17-L120) +- [frontend/antdx/actions/item/actions.item.tsx:6-34](file://frontend/antdx/actions/item/actions.item.tsx#L6-L34) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:5-16](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L5-L16) +- [frontend/antdx/actions/context.ts:3-4](file://frontend/antdx/actions/context.ts#L3-L4) +- [frontend/antdx/actions/action-item/actions.action-item.tsx:7-20](file://frontend/antdx/actions/action-item/actions.action-item.tsx#L7-L20) + +章节来源 + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:1-16](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L1-L16) +- [frontend/antdx/actions/action-item/actions.action-item.tsx:1-23](file://frontend/antdx/actions/action-item/actions.action-item.tsx#L1-L23) +- [frontend/antdx/actions/item/actions.item.tsx:1-34](file://frontend/antdx/actions/item/actions.item.tsx#L1-L34) +- [frontend/utils/createItemsContext.tsx:20-95](file://frontend/utils/createItemsContext.tsx#L20-L95) +- [frontend/utils/renderItems.tsx:8-114](file://frontend/utils/renderItems.tsx#L8-L114) +- [frontend/utils/renderParamsSlot.tsx:5-51](file://frontend/utils/renderParamsSlot.tsx#L5-L51) +- [frontend/utils/renderSlot.tsx:13-29](file://frontend/utils/renderSlot.tsx#L13-L29) + +### Notification 通知组件 API + +- Ant Design 版本（antd/notification） + - 属性要点： + - visible：是否显示通知。 + - onVisible：关闭时回调，用于同步 visible 状态。 + - notificationKey：唯一标识，用于 destroy/open。 + - 支持插槽：btn、actions、closeIcon、description、icon、message。 + - 行为机制： + - visible 为真时调用 open；否则 destroy。 + - onClose 回调中先触发 onVisible(false)，再执行用户自定义 onClose。 +- Ant Design X 版本（@ant-design/x/notification） + - 属性要点： + - visible：是否显示通知。 + - onVisible：关闭时回调。 + - onPermission：浏览器通知权限变化回调。 + - tag：通知标签，用于按 tag 关闭。 + - 行为机制： + - 首次显示前若未授权则请求权限，仅在 granted 时 open。 + - visible 为真时 open，否则 close(tag)。 + - 组件卸载时自动关闭对应 tag 的通知。 + +```mermaid +sequenceDiagram +participant Caller as "调用方" +participant ANTD as "antd Notification" +participant XNOTI as "X Notification" +Caller->>ANTD : 设置 visible=true, 传入 message/description 等 +ANTD->>ANTD : useNotification 初始化 +ANTD->>ANTD : open({ key, message, description, ... }) +ANTD-->>Caller : onClose 回调触发 onVisible(false) +Caller->>XNOTI : 设置 visible=true, 传入 tag/message +XNOTI->>XNOTI : useNotification 获取 permission +alt 未授权 +XNOTI->>XNOTI : requestPermission() +end +XNOTI->>XNOTI : open({ tag, message, onClose }) +XNOTI-->>Caller : onClose 回调触发 onVisible(false) +``` + +图表来源 + +- [frontend/antd/notification/notification.tsx:38-95](file://frontend/antd/notification/notification.tsx#L38-L95) +- [frontend/antdx/notification/notification.tsx:17-46](file://frontend/antdx/notification/notification.tsx#L17-L46) + +章节来源 + +- [frontend/antd/notification/notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [frontend/antd/notification/Index.svelte:56-79](file://frontend/antd/notification/Index.svelte#L56-L79) +- [frontend/antdx/notification/notification.tsx:1-51](file://frontend/antdx/notification/notification.tsx#L1-L51) + +## 依赖关系分析 + +- Actions 与渲染工具链 + - Actions 依赖 createItemsContext 维护插槽项集合。 + - 通过 renderItems 将插槽项转换为 React 组件树，支持 children 键与 itemPropsTransformer。 + - renderParamsSlot 与 renderSlot 支持带参插槽与克隆策略。 +- Actions 与菜单上下文 + - 与 antd/menu 的上下文配合，优先使用菜单上下文提供的 dropdownProps.menu.items。 +- Notification 与权限 + - X 版本内置权限请求与回调，避免重复请求。 + - ANTD 版本不涉及浏览器权限，仅本地通知。 + +```mermaid +graph LR +Actions["Actions"] --> Ctx["createItemsContext"] +Actions --> RItems["renderItems"] +Actions --> RPSlot["renderParamsSlot"] +Actions --> RSlot["renderSlot"] +Actions --> MenuCtx["antd/menu context"] +XNoti["X Notification"] --> Perm["requestPermission/onPermission"] +ANoti["antd Notification"] --> Local["本地通知"] +``` + +图表来源 + +- [frontend/antdx/actions/actions.tsx:10-15](file://frontend/antdx/actions/actions.tsx#L10-L15) +- [frontend/utils/createItemsContext.tsx:97-274](file://frontend/utils/createItemsContext.tsx#L97-L274) +- [frontend/utils/renderItems.tsx:8-114](file://frontend/utils/renderItems.tsx#L8-L114) +- [frontend/utils/renderParamsSlot.tsx:5-51](file://frontend/utils/renderParamsSlot.tsx#L5-L51) +- [frontend/utils/renderSlot.tsx:13-29](file://frontend/utils/renderSlot.tsx#L13-L29) +- [frontend/antdx/notification/notification.tsx:13-19](file://frontend/antdx/notification/notification.tsx#L13-L19) + +章节来源 + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/antdx/notification/notification.tsx:1-51](file://frontend/antdx/notification/notification.tsx#L1-L51) + +## 性能考量 + +- 插槽渲染优化 + - 使用 useMemo 包裹 dropdownProps 的修改，减少无效重渲染。 + - renderItems 支持 clone/forceClone 控制，避免不必要的 React 节点重建。 +- 通知生命周期 + - ANTD：visible 切换时 destroy 对应 key，卸载时也销毁，避免内存泄漏。 + - X：visible=false 或卸载时按 tag 关闭，确保资源回收。 +- 权限请求去抖 + - X 版本在首次打开前检查权限，避免重复请求。 + +章节来源 + +- [frontend/antdx/actions/actions.tsx:39-96](file://frontend/antdx/actions/actions.tsx#L39-L96) +- [frontend/antd/notification/notification.tsx:74-95](file://frontend/antd/notification/notification.tsx#L74-L95) +- [frontend/antdx/notification/notification.tsx:17-46](file://frontend/antdx/notification/notification.tsx#L17-L46) + +## 故障排查指南 + +- Actions 无法显示子项 + - 检查插槽键是否正确：default 与 subItems 是否匹配 ItemHandler 的 itemChildrenKey。 + - 确认 allowedSlots 与 itemChildren 的返回值逻辑一致。 +- 插槽未生效 + - 确认 slots 中的元素已正确传递到 ItemHandler 或 Actions 的 slots。 + - 若使用参数化插槽，确认 renderParamsSlot 的 targets 与 withParams 配置。 +- 通知未显示 + - ANTD：确认 visible 为 true 且 notificationKey 唯一；onClose 中是否调用了 onVisible(false)。 + - X：确认浏览器通知权限为 granted；tag 是否正确传入；onClose 中是否调用了 onVisible(false)。 +- 性能问题 + - 检查 dropdownProps 是否频繁变更；尽量复用对象引用或使用 useMemo。 + - 减少不必要的 clone，仅在必要时开启 forceClone。 + +章节来源 + +- [frontend/antdx/actions/action-item/actions.action-item.tsx:11-19](file://frontend/antdx/actions/action-item/actions.action-item.tsx#L11-L19) +- [frontend/antdx/actions/context.ts:3-4](file://frontend/antdx/actions/context.ts#L3-L4) +- [frontend/utils/renderParamsSlot.tsx:23-49](file://frontend/utils/renderParamsSlot.tsx#L23-L49) +- [frontend/antd/notification/notification.tsx:38-95](file://frontend/antd/notification/notification.tsx#L38-L95) +- [frontend/antdx/notification/notification.tsx:17-46](file://frontend/antdx/notification/notification.tsx#L17-L46) + +## 结论 + +- Actions 通过插槽与上下文机制，将复杂 UI 结构转化为可组合、可扩展的操作列表，适合在 AI 应用中承载多步骤任务、多轮对话中的操作反馈。 +- Notification 在 ANTD 与 X 两端提供了统一的可见性与生命周期管理，X 版本额外支持浏览器通知权限，满足更丰富的用户反馈需求。 +- 建议在实际应用中结合业务语义选择合适的实现版本，并遵循插槽与上下文的最佳实践，以获得稳定与高性能的反馈体验。 + +## 附录 + +### 类型与接口要点（概要） + +- Actions + - ActionsProps：来自 @ant-design/x，包含 items、dropdownProps 等。 + - ActionsItemProps：Actions.Item 的属性集合。 + - ActionsFeedbackProps：Actions.Feedback 的属性集合。 +- Notification + - ANTD：ArgsProps 与 NotificationConfig，支持 visible、onVisible、插槽等。 + - X：XNotificationOpenArgs，支持 visible、onVisible、onPermission、tag 等。 + +章节来源 + +- [frontend/antdx/actions/actions.tsx:3-8](file://frontend/antdx/actions/actions.tsx#L3-L8) +- [frontend/antd/notification/notification.tsx:8-16](file://frontend/antd/notification/notification.tsx#L8-L16) +- [frontend/antdx/notification/notification.tsx:6-11](file://frontend/antdx/notification/notification.tsx#L6-L11) + +### 使用场景与最佳实践（建议） + +- AI 应用中的操作反馈 + - 使用 Actions.Feedback 快速挂载反馈类操作。 + - 使用 Actions.Item 自定义图标与文案，结合插槽实现动态文案与状态指示。 + - 对于多级菜单，使用 subItems 与 allowedSlots 管理层级结构。 +- 通知时机控制 + - ANTD：通过 visible 精准控制显示/隐藏；对关键错误或成功状态使用短时通知。 + - X：在需要系统级提醒时启用，注意权限请求只在首次触发，避免频繁打扰。 +- 状态同步 + - onClose 中统一设置 onVisible(false)，保证 UI 与状态一致。 + - 对批量关闭，使用 tag 或 key 进行精准定位。 diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\345\224\244\351\206\222\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\345\224\244\351\206\222\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..77e4ba4a --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\345\224\244\351\206\222\347\273\204\344\273\266 API.md" @@ -0,0 +1,348 @@ +# 唤醒组件 API + + +**本文引用的文件** +- [backend/modelscope_studio/components/antdx/welcome/__init__.py](file://backend/modelscope_studio/components/antdx/welcome/__init__.py) +- [backend/modelscope_studio/components/antdx/prompts/__init__.py](file://backend/modelscope_studio/components/antdx/prompts/__init__.py) +- [frontend/antdx/welcome/Index.svelte](file://frontend/antdx/welcome/Index.svelte) +- [frontend/antdx/welcome/welcome.tsx](file://frontend/antdx/welcome/welcome.tsx) +- [frontend/antdx/prompts/Index.svelte](file://frontend/antdx/prompts/Index.svelte) +- [frontend/antdx/prompts/prompts.tsx](file://frontend/antdx/prompts/prompts.tsx) +- [frontend/antdx/prompts/context.ts](file://frontend/antdx/prompts/context.ts) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 的 Ant Design X 唤醒组件 API 参考文档，聚焦以下两个组件： + +- 欢迎组件（AntdXWelcome）：用于在应用首次加载或特定场景下展示欢迎信息，支持标题、描述、图标、额外内容等插槽化配置。 +- 提示集组件（AntdXPrompts）：用于展示一组可点击的提示词卡片，支持标题、垂直布局、渐入动画、换行等配置，并提供项点击事件回调。 + +文档将从系统架构、组件关系、数据流、处理逻辑、集成点、错误处理与性能特性等方面进行深入解析，并提供生命周期钩子、事件处理、状态管理机制以及 TypeScript 类型定义与接口规范，帮助开发者在 AI 应用中实现流畅的首次体验与提示引导。 + +## 项目结构 + +ModelScope Studio 的前端采用 Svelte + Ant Design X 组件体系，后端通过 Python 组件桥接前端组件。唤醒与提示集组件分别位于 antdx 模块中，后端组件负责属性传递与事件绑定，前端组件负责渲染与交互。 + +```mermaid +graph TB +subgraph "后端" +B_Welcome["AntdXWelcome
Python 组件"] +B_Prompts["AntdXPrompts
Python 组件"] +end +subgraph "前端" +F_Welcome["welcome/Index.svelte
渲染器"] +F_Welcome_TSX["welcome/welcome.tsx
组件实现"] +F_Prompts["prompts/Index.svelte
渲染器"] +F_Prompts_TSX["prompts/prompts.tsx
组件实现"] +F_Prompts_Context["prompts/context.ts
上下文"] +end +B_Welcome --> F_Welcome +F_Welcome --> F_Welcome_TSX +B_Prompts --> F_Prompts +F_Prompts --> F_Prompts_TSX +F_Prompts_TSX --> F_Prompts_Context +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) +- [frontend/antdx/welcome/Index.svelte:1-72](file://frontend/antdx/welcome/Index.svelte#L1-L72) +- [frontend/antdx/welcome/welcome.tsx](file://frontend/antdx/welcome/welcome.tsx) +- [frontend/antdx/prompts/Index.svelte:1-71](file://frontend/antdx/prompts/Index.svelte#L1-L71) +- [frontend/antdx/prompts/prompts.tsx](file://frontend/antdx/prompts/prompts.tsx) +- [frontend/antdx/prompts/context.ts](file://frontend/antdx/prompts/context.ts) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:1-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:1-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L1-L88) +- [frontend/antdx/welcome/Index.svelte:1-72](file://frontend/antdx/welcome/Index.svelte#L1-L72) +- [frontend/antdx/prompts/Index.svelte:1-71](file://frontend/antdx/prompts/Index.svelte#L1-L71) + +## 核心组件 + +本节概述两个组件的关键职责与能力边界： + +- 欢迎组件（AntdXWelcome） + - 职责：展示欢迎信息，支持多插槽（标题、描述、图标、额外内容），可选样式与变体。 + - 关键点：不暴露标准 API（skip_api 为真），通过插槽与静态资源路径注入实现。 +- 提示集组件（AntdXPrompts） + - 职责：展示一组提示词卡片，支持标题、垂直布局、渐入动画、换行等；提供项点击事件回调。 + - 关键点：内部嵌套项组件，事件绑定通过 EventListener 配置。 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) + +## 架构总览 + +下图展示了从后端组件到前端渲染器再到具体组件实现的调用链路，以及事件绑定与插槽传递机制。 + +```mermaid +sequenceDiagram +participant Py as "Python 后端组件" +participant Svelte as "Svelte 渲染器" +participant TSX as "TSX 组件实现" +Py->>Py : "初始化组件属性与事件" +Py->>Svelte : "传递 props 与可见性控制" +Svelte->>TSX : "动态导入并渲染组件" +TSX-->>Svelte : "渲染完成，等待插槽内容" +Svelte-->>Py : "事件回调绑定如 item_click" +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:55-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L55-L73) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:70-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L70-L88) +- [frontend/antdx/welcome/Index.svelte:10-72](file://frontend/antdx/welcome/Index.svelte#L10-L72) +- [frontend/antdx/prompts/Index.svelte:10-71](file://frontend/antdx/prompts/Index.svelte#L10-L71) + +## 详细组件分析 + +### 欢迎组件（AntdXWelcome） + +- 组件定位：用于首次体验或引导场景，承载标题、描述、图标与额外内容等。 +- 插槽支持：extra、icon、description、title。 +- 属性与行为： + - 支持额外属性 additional_props、样式 styles/class_names、根类名 root_class_name。 + - 图标参数 icon 会经由静态资源服务处理（serve_static_file）。 + - 不暴露标准 API（skip_api 为真），适合通过插槽与静态资源组合使用。 +- 生命周期与钩子： + - preprocess/postprocess/example_payload/example_value 均返回空值，表明该组件不参与常规数据流转换。 +- 典型使用场景： + - 应用启动后的欢迎页、新用户引导、功能入口提示等。 + +```mermaid +classDiagram +class AntdXWelcome { ++EVENTS : list ++SLOTS : list ++additional_props : dict|None ++extra : str|None ++icon : str|None ++styles : dict|str|None ++class_names : dict|str|None ++description : str|None ++variant : "filled"| "borderless"| None ++title : str|None ++root_class_name : str|None ++skip_api() : bool ++preprocess(payload) : None ++postprocess(value) : None ++example_payload() : None ++example_value() : None +} +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) +- [frontend/antdx/welcome/Index.svelte:1-72](file://frontend/antdx/welcome/Index.svelte#L1-L72) +- [frontend/antdx/welcome/welcome.tsx](file://frontend/antdx/welcome/welcome.tsx) + +### 提示集组件（AntdXPrompts） + +- 组件定位：展示一组提示词卡片，支持标题、垂直布局、渐入动画、换行等。 +- 内部结构： + - 内嵌项组件：AntdXPrompts.Item。 + - 事件：item_click（点击提示项时触发）。 +- 属性与行为： + - items：提示项列表（字典数组）。 + - 样式与布局：prefix_cls、vertical、fade_in、fade_in_left、wrap。 + - 支持 additional_props、styles、class_names、root_class_name。 + - 不暴露标准 API（skip_api 为真）。 +- 事件处理： + - 通过 EventListener("item_click") 将点击事件映射到内部状态更新（bind_itemClick_event）。 + +```mermaid +classDiagram +class AntdXPrompts { ++Item : AntdXPromptsItem ++EVENTS : list ++SLOTS : list ++items : list[dict]|None ++prefix_cls : str|None ++title : str|None ++vertical : bool|None ++fade_in : bool|None ++fade_in_left : bool|None ++wrap : bool|None ++styles : dict|str|None ++class_names : dict|str|None ++root_class_name : str|None ++skip_api() : bool ++preprocess(payload) : None ++postprocess(value) : None ++example_payload() : Any ++example_value() : Any +} +class AntdXPromptsItem { ++... 项级属性与行为 ... +} +AntdXPrompts --> AntdXPromptsItem : "包含" +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) +- [frontend/antdx/prompts/Index.svelte:1-71](file://frontend/antdx/prompts/Index.svelte#L1-L71) +- [frontend/antdx/prompts/prompts.tsx](file://frontend/antdx/prompts/prompts.tsx) +- [frontend/antdx/prompts/context.ts](file://frontend/antdx/prompts/context.ts) + +### 组件渲染与事件绑定流程 + +以下序列图展示了后端组件如何通过前端渲染器绑定事件并渲染组件。 + +```mermaid +sequenceDiagram +participant Backend as "后端组件" +participant Renderer as "Svelte 渲染器" +participant Frontend as "TSX 组件" +Backend->>Renderer : "传递组件属性与事件配置" +Renderer->>Frontend : "动态导入并渲染" +Frontend-->>Renderer : "注册事件监听如 item_click" +Renderer-->>Backend : "事件回调生效" +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-23](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L23) +- [frontend/antdx/prompts/Index.svelte:10-71](file://frontend/antdx/prompts/Index.svelte#L10-L71) + +## 依赖关系分析 + +- 组件基类与工具： + - 所有组件继承自 ModelScopeLayoutComponent，统一处理可见性、元素 ID/类、样式与渲染开关。 + - 前端目录解析通过 resolve_frontend_dir 完成，确保 Python 后端与 Svelte 前端正确映射。 +- 组件间耦合： + - 欢迎组件与提示集组件均为独立 UI 组件，彼此无直接依赖。 + - 提示集组件内部项组件与上下文存在交互，但对外仍以整体组件形式暴露。 + +```mermaid +graph LR +Base["ModelScopeLayoutComponent
组件基类"] --> Welcome["AntdXWelcome"] +Base --> Prompts["AntdXPrompts"] +Resolve["resolve_frontend_dir
前端目录解析"] --> Welcome +Resolve --> Prompts +``` + +**图表来源** + +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:55-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L55-L55) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:70-70](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L70-L70) + +**章节来源** + +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:55-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L55-L55) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:70-70](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L70-L70) + +## 性能考虑 + +- 渲染策略 + - 组件均通过动态导入方式渲染，避免首屏阻塞，提升初始加载性能。 +- 事件绑定 + - 事件仅在需要时绑定，且通过内部状态更新减少不必要的重渲染。 +- 资源处理 + - 图标等静态资源通过 serve_static_file 处理，建议缓存与预加载以优化用户体验。 + +[本节为通用指导，无需列出具体文件来源] + +## 故障排除指南 + +- 组件未显示 + - 检查 visible、elem_id、elem_classes、elem_style 是否正确设置。 + - 确认渲染开关 render 为真。 +- 插槽内容不生效 + - 确认插槽名称与组件支持的 SLOTS 列表一致（欢迎组件：extra、icon、description、title；提示集组件：title、items）。 +- 事件未触发 + - 确认事件监听器已正确配置（提示集组件的 item_click）。 +- 图标或静态资源无法加载 + - 确认 icon 路径有效，且 serve_static_file 正常工作。 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:14-15](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L14-L15) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:25-26](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L25-L26) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-23](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L23) + +## 结论 + +AntdXWelcome 与 AntdXPrompts 在 ModelScope Studio 中分别承担“欢迎引导”与“提示引导”的核心职责。前者通过插槽与静态资源实现灵活的欢迎页展示，后者通过项点击事件与布局配置提供高效的提示词引导。二者均采用动态渲染与事件绑定机制，具备良好的扩展性与可维护性。结合本文档提供的类型定义、接口规范与最佳实践，开发者可在 AI 应用中快速构建一致、流畅的首次体验与提示引导流程。 + +[本节为总结性内容，无需列出具体文件来源] + +## 附录 + +### TypeScript 类型定义与接口规范 + +- 欢迎组件（AntdXWelcome） + - 支持属性：additional_props、extra、icon、styles、class_names、description、variant、title、root_class_name、as_item、visible、elem_id、elem_classes、elem_style、render。 + - 插槽：extra、icon、description、title。 + - 事件：无。 + - 生命周期钩子：preprocess/postprocess/example_payload/example_value 返回空值。 +- 提示集组件（AntdXPrompts） + - 支持属性：items、prefix_cls、title、vertical、fade_in、fade_in_left、wrap、styles、class_names、root_class_name、additional_props、as_item、visible、elem_id、elem_classes、elem_style、render。 + - 插槽：title、items。 + - 事件：item_click（点击提示项时触发）。 + - 生命周期钩子：preprocess/postprocess/example_payload/example_value 返回空值。 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:17-54](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L17-L54) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:14-15](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L14-L15) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:61-69](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L61-L69) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:28-68](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L28-L68) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:25-26](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L25-L26) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:76-87](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L76-L87) + +### 与对话系统的集成方式 + +- 提示集组件可作为对话输入前的引导层，用户点击提示项后，由上层业务逻辑将提示内容注入到对话输入框或直接发起对话请求。 +- 欢迎组件可作为对话会话的入口提示，结合上下文状态决定是否展示。 + +[本节为概念性说明，无需列出具体文件来源] + +### 最佳实践 + +- 欢迎组件 + - 使用插槽组织标题、描述与图标，保持视觉层次清晰。 + - 对于多语言场景，建议通过外部文案管理模块传入 title 与 description。 +- 提示集组件 + - 合理设置 vertical、fade_in、fade_in_left、wrap，以适配不同屏幕尺寸与交互节奏。 + - 为每个提示项提供明确的语义标签，便于无障碍访问与 SEO。 +- 事件处理 + - 在 item_click 回调中执行最小必要操作（如将提示内容写入输入框），避免阻塞 UI。 +- 状态管理 + - 将提示集的可见性与当前会话状态解耦，允许在不同页面或视图中复用。 + +[本节为通用指导，无需列出具体文件来源] diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\345\267\245\345\205\267\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\345\267\245\345\205\267\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..e4c6467f --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\345\267\245\345\205\267\347\273\204\344\273\266 API.md" @@ -0,0 +1,377 @@ +# 工具组件 API + + +**本文引用的文件** +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antdx/code-highlighter/code-highlighter.tsx](file://frontend/antdx/code-highlighter/code-highlighter.tsx) +- [frontend/antdx/file-card/file-card.tsx](file://frontend/antdx/file-card/file-card.tsx) +- [frontend/antdx/file-card/base.tsx](file://frontend/antdx/file-card/base.tsx) +- [frontend/antdx/folder/folder.tsx](file://frontend/antdx/folder/folder.tsx) +- [frontend/antdx/folder/context.ts](file://frontend/antdx/folder/context.ts) +- [frontend/antdx/mermaid/mermaid.tsx](file://frontend/antdx/mermaid/mermaid.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [docs/components/antdx/x_provider/README.md](file://docs/components/antdx/x_provider/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向 ModelScope Studio 的 Ant Design X 工具组件 API，聚焦以下组件的完整接口与使用方法： + +- XProvider 全局配置组件（基于 antd 的 ConfigProvider 扩展） +- CodeHighlighter 代码高亮组件 +- FileCard 文件卡片组件 +- Folder 文件夹组件 +- Mermaid 流程图组件 + +文档覆盖全局配置方式、代码高亮语言与主题支持、文件管理交互、流程图绘制与动作集成，以及与 Gradio 生态的集成方式。同时提供类型定义要点、上下文提供与状态管理机制、性能优化与扩展最佳实践。 + +## 项目结构 + +围绕工具组件的关键目录与文件如下： + +- 前端组件实现位于 frontend/antdx 与 frontend/antd 下，分别对应 Ant Design X 组件与 antd 配置层 +- 每个组件均通过 sveltify 包装为可在 Svelte 中使用的 React 组件，并通过 slots 与参数桥接 +- 组件间共享上下文通过 createItemsContext 提供，用于树节点、目录图标与动作项等 + +```mermaid +graph TB +subgraph "Antd 配置层" +CP["ConfigProvider
frontend/antd/config-provider/config-provider.tsx"] +end +subgraph "Ant Design X 工具组件" +CH["CodeHighlighter
frontend/antdx/code-highlighter/code-highlighter.tsx"] +FC["FileCard
frontend/antdx/file-card/file-card.tsx"] +FCB["BaseFileCard
frontend/antdx/file-card/base.tsx"] +FD["Folder
frontend/antdx/folder/folder.tsx"] +FDCtx["Folder 上下文
frontend/antdx/folder/context.ts"] +MM["Mermaid
frontend/antdx/mermaid/mermaid.tsx"] +ActCtx["动作上下文
frontend/antdx/actions/context.ts"] +end +CP --> CH +CP --> FC +FC --> FCB +CP --> FD +FD --> FDCtx +CP --> MM +MM --> ActCtx +``` + +图表来源 + +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:1-54](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L1-L54) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) +- [frontend/antdx/folder/folder.tsx:1-123](file://frontend/antdx/folder/folder.tsx#L1-L123) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) + +章节来源 + +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:1-54](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L1-L54) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) +- [frontend/antdx/folder/folder.tsx:1-123](file://frontend/antdx/folder/folder.tsx#L1-L123) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) + +## 核心组件 + +本节概述各组件职责与关键能力： + +- XProvider：在 Gradio Blocks 场景中替代 antd 的 ConfigProvider，统一提供 Ant Design X 组件的全局配置（主题、区域化、弹出容器等），并兼容 slots 注入 +- CodeHighlighter：封装 @ant-design/x 的代码高亮组件，支持自定义 header 插槽与明暗主题下的语法高亮样式 +- FileCard：文件卡片组件，支持图片占位符、预览遮罩、关闭图标、工具栏渲染、指示器与描述文本的插槽化配置 +- Folder：文件夹树组件，支持树节点数据、目录图标映射、空态渲染、标题与预览渲染的插槽化注入，并可接入文件内容服务 +- Mermaid：流程图组件，支持主题切换、高亮样式、动作项上下文注入与自定义动作 + +章节来源 + +- [docs/components/antdx/x_provider/README.md:1-19](file://docs/components/antdx/x_provider/README.md#L1-L19) +- [frontend/antd/config-provider/config-provider.tsx:51-151](file://frontend/antd/config-provider/config-provider.tsx#L51-L151) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:29-51](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L29-L51) +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/folder/folder.tsx:16-120](file://frontend/antdx/folder/folder.tsx#L16-L120) +- [frontend/antdx/mermaid/mermaid.tsx:33-84](file://frontend/antdx/mermaid/mermaid.tsx#L33-L84) + +## 架构总览 + +XProvider 作为顶层配置容器，向下为各工具组件提供统一的主题、区域化与弹出容器策略；工具组件通过 slots 与参数桥接，结合上下文提供者实现灵活的插槽化与动态渲染。 + +```mermaid +sequenceDiagram +participant App as "应用" +participant XProv as "XProvider(ConfigProvider)" +participant Comp as "工具组件" +participant Slots as "插槽系统" +App->>XProv : "包裹应用并传入配置" +XProv->>Comp : "提供主题/区域化/容器策略" +Comp->>Slots : "读取插槽(如 header、mask、previewRender)" +Slots-->>Comp : "返回 React 节点" +Comp-->>App : "渲染最终 UI" +``` + +图表来源 + +- [frontend/antd/config-provider/config-provider.tsx:108-149](file://frontend/antd/config-provider/config-provider.tsx#L108-L149) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:35-49](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L35-L49) +- [frontend/antdx/file-card/file-card.tsx:46-123](file://frontend/antdx/file-card/file-card.tsx#L46-L123) +- [frontend/antdx/folder/folder.tsx:48-116](file://frontend/antdx/folder/folder.tsx#L48-L116) +- [frontend/antdx/mermaid/mermaid.tsx:47-81](file://frontend/antdx/mermaid/mermaid.tsx#L47-L81) + +## 组件详解 + +### XProvider 全局配置组件 + +- 角色定位：替代 antd 的 ConfigProvider，为 @ant-design/x 组件提供统一的全局配置 +- 关键能力 + - 主题模式：支持 themeMode 控制暗色/紧凑算法 + - 区域化：自动根据浏览器语言解析并加载对应 antd/dayjs 本地化资源 + - 弹出容器：支持 getPopupContainer/getTargetContainer 函数注入 + - 插槽化：通过 combinePropsAndSlots 将 slots 注入到组件属性中 + - 自定义渲染：renderEmpty 支持 slot 或函数两种形式 +- 使用建议 + - 在 Gradio Blocks 中以 antdx.XProvider 替代 antd.ConfigProvider + - 通过 themeMode 切换明暗主题，避免重复 key 导致的重渲染问题 + - 合理设置 getPopupContainer，确保浮层渲染在正确容器内 + +章节来源 + +- [docs/components/antdx/x_provider/README.md:1-19](file://docs/components/antdx/x_provider/README.md#L1-L19) +- [frontend/antd/config-provider/config-provider.tsx:51-151](file://frontend/antd/config-provider/config-provider.tsx#L51-L151) + +### CodeHighlighter 代码高亮组件 + +- 角色定位：对代码进行语法高亮渲染，支持 header 插槽与明暗主题样式 +- 关键能力 + - 语言支持：依赖 react-syntax-highlighter 的 Prism 风格，可直接渲染多种语言 + - 明暗主题：根据 themeMode 切换 materialDark/materialLight 样式，统一去除代码块外边距 + - 插槽化：支持 header 插槽注入自定义头部 + - 值绑定：value 属性或子节点内容均可作为代码输入 +- 使用建议 + - 在 AI 应用中，优先使用明暗一致的主题风格，保证阅读体验 + - 通过 header 插槽添加复制、下载等操作按钮 + +章节来源 + +- [frontend/antdx/code-highlighter/code-highlighter.tsx:29-51](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L29-L51) + +### FileCard 文件卡片组件 + +- 角色定位：展示文件信息，支持图片占位、预览遮罩、工具栏、指示器与描述文本的插槽化配置 +- 关键能力 + - 图片处理：支持占位符、预览容器、关闭图标、工具栏与图片渲染的插槽化 + - 加载状态：spinProps 支持 size、icon、description、indicator 插槽 + - 描述与图标：description、icon 插槽可自定义展示内容 + - 资源解析：通过 BaseFileCard 的 resolveFileSrc 解析相对路径与 FileData +- 使用建议 + - 对于远程图片，确保 rootUrl 与 apiPrefix 正确拼接可访问 URL + - 预览功能按需开启，避免不必要的 DOM 渲染 + +```mermaid +flowchart TD +Start(["进入 FileCard"]) --> CheckImg["检查 imageProps.preview 是否启用"] +CheckImg --> |启用| BuildPreview["构建预览配置(含插槽)"] +CheckImg --> |禁用| NoPreview["禁用预览"] +BuildPreview --> ResolveSrc["解析 src 为可访问 URL"] +NoPreview --> ResolveSrc +ResolveSrc --> Render["渲染 BaseFileCard"] +Render --> End(["完成"]) +``` + +图表来源 + +- [frontend/antdx/file-card/file-card.tsx:34-123](file://frontend/antdx/file-card/file-card.tsx#L34-L123) +- [frontend/antdx/file-card/base.tsx:15-41](file://frontend/antdx/file-card/base.tsx#L15-L41) + +章节来源 + +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/file-card/base.tsx:9-41](file://frontend/antdx/file-card/base.tsx#L9-L41) + +### Folder 文件夹组件 + +- 角色定位：文件夹树组件，支持树节点数据、目录图标映射、空态与标题渲染、预览渲染与文件内容服务 +- 关键能力 + - 树节点上下文：通过 withTreeNodeItemsContextProvider 提供 treeData/default 两套数据源 + - 目录图标上下文：通过 withDirectoryIconItemsContextProvider 提供扩展名到图标的映射 + - 预览服务：fileContentService 可注入加载文件内容的回调 + - 插槽化：emptyRender、directoryTitle、previewTitle、previewRender 均支持插槽 +- 使用建议 + - treeData 为空时回退至默认节点列表，确保首次渲染稳定 + - 目录图标映射通过插槽收集后转换为字典，便于快速匹配 + +```mermaid +sequenceDiagram +participant FD as "Folder" +participant Ctx as "上下文提供者" +participant XFD as "@ant-design/x Folder" +participant FS as "文件内容服务" +FD->>Ctx : "读取树节点与目录图标" +FD->>FD : "合并 treeData/default" +FD->>FD : "构建目录图标映射" +FD->>XFD : "传入 treeData、directoryIcons、emptyRender..." +alt 存在 fileContentService +FD->>FS : "调用 onLoadFileContent(filePath)" +FS-->>FD : "返回文件内容" +end +XFD-->>FD : "渲染树与预览" +``` + +图表来源 + +- [frontend/antdx/folder/folder.tsx:24-120](file://frontend/antdx/folder/folder.tsx#L24-L120) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) + +章节来源 + +- [frontend/antdx/folder/folder.tsx:16-120](file://frontend/antdx/folder/folder.tsx#L16-L120) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) + +### Mermaid 流程图组件 + +- 角色定位：流程图绘制组件，支持主题切换、高亮样式与动作项上下文 +- 关键能力 + - 主题与高亮：根据 themeMode 切换 dark/base 主题，并应用 Prism 风格 + - 动作上下文：通过 withActionItemsContextProvider 注入自定义动作项 + - 插槽化：header 与 actions.customActions 支持插槽 + - 配置合并：config 中的 theme 将被 themeMode 覆盖 +- 使用建议 + - 在 AI 应用中，将复制、下载、全屏等动作通过 actions.customActions 注入 + - 保持主题一致性，避免明暗切换导致的视觉割裂 + +章节来源 + +- [frontend/antdx/mermaid/mermaid.tsx:33-84](file://frontend/antdx/mermaid/mermaid.tsx#L33-L84) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) + +## 依赖关系分析 + +- 组件耦合 + - FileCard 依赖 BaseFileCard 进行资源解析，降低重复逻辑 + - Folder 通过上下文提供者注入树节点与目录图标，解耦外部数据源 + - Mermaid 通过动作上下文提供者注入自定义动作，增强可扩展性 +- 外部依赖 + - react-syntax-highlighter：提供 Prism 风格的高亮样式 + - @ant-design/x：提供底层组件能力（CodeHighlighter、Folder、Mermaid、FileCard 等） + - antd：ConfigProvider 的扩展与主题算法 +- 循环依赖 + - 当前结构未发现循环依赖，上下文提供者通过 createItemsContext 抽象，避免直接互相引用 + +```mermaid +graph LR +CH["CodeHighlighter"] --> XCH["@ant-design/x CodeHighlighter"] +FC["FileCard"] --> FCB["BaseFileCard"] +FCB --> XFC["@ant-design/x FileCard"] +FD["Folder"] --> XFD["@ant-design/x Folder"] +FD --> FDCtx["Folder 上下文"] +MM["Mermaid"] --> XMM["@ant-design/x Mermaid"] +MM --> ActCtx["动作上下文"] +CP["ConfigProvider(XProvider)"] --> CH +CP --> FC +CP --> FD +CP --> MM +``` + +图表来源 + +- [frontend/antdx/code-highlighter/code-highlighter.tsx:1-54](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L1-L54) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) +- [frontend/antdx/folder/folder.tsx:1-123](file://frontend/antdx/folder/folder.tsx#L1-L123) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) + +章节来源 + +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/folder/folder.tsx:16-120](file://frontend/antdx/folder/folder.tsx#L16-L120) +- [frontend/antdx/mermaid/mermaid.tsx:33-84](file://frontend/antdx/mermaid/mermaid.tsx#L33-L84) +- [frontend/antd/config-provider/config-provider.tsx:51-151](file://frontend/antd/config-provider/config-provider.tsx#L51-L151) + +## 性能考量 + +- 渲染策略 + - 合理使用 useMemo 缓存 treeData、directoryIcons、actions.customActions 等计算结果，避免重复渲染 + - 预览容器与工具栏仅在需要时启用，减少 DOM 结构复杂度 +- 主题切换 + - themeMode 变更时，通过明暗算法组合与样式对象复用，避免频繁重建样式 +- 插槽渲染 + - 使用 renderParamsSlot 与 renderItems 时，尽量传递 clone: true，确保插槽节点独立更新 +- 资源解析 + - BaseFileCard 的 resolveFileSrc 仅在 src/rootUrl/apiPrefix 变化时重新计算，避免不必要的 URL 拼接 + +[本节为通用指导，无需列出具体文件来源] + +## 故障排查指南 + +- 区域化不生效 + - 检查 locale 参数格式是否符合预期，确认 locales 映射存在对应语言包 + - 确认 dayjs.locale 已被正确设置 +- 弹出层位置异常 + - 检查 getPopupContainer/getTargetContainer 返回的容器是否可见且层级正确 +- 预览不可用 + - 确认 imageProps.preview 未被显式设为 false，且插槽 mask/closeIcon/toolbarRender/imageRender 至少有一个可用 +- 文件无法访问 + - 确认 resolveFileSrc 的 rootUrl 与 apiPrefix 拼接正确，必要时使用 FileData.url 字段 +- 动作项不显示 + - 确认通过 withActionItemsContextProvider 注入的动作项已正确收集并传递给 actions.customActions + +章节来源 + +- [frontend/antd/config-provider/config-provider.tsx:96-105](file://frontend/antd/config-provider/config-provider.tsx#L96-L105) +- [frontend/antdx/file-card/file-card.tsx:34-123](file://frontend/antdx/file-card/file-card.tsx#L34-L123) +- [frontend/antdx/file-card/base.tsx:15-41](file://frontend/antdx/file-card/base.tsx#L15-L41) +- [frontend/antdx/mermaid/mermaid.tsx:40-84](file://frontend/antdx/mermaid/mermaid.tsx#L40-L84) + +## 结论 + +本文档系统梳理了 ModelScope Studio 中 Ant Design X 工具组件的 API 与使用方式，重点覆盖 XProvider 全局配置、CodeHighlighter、FileCard、Folder、Mermaid 的接口要点与最佳实践。通过插槽化与上下文提供者，组件在 Gradio 生态中实现了高度可定制与可扩展的能力，适用于 AI 应用中的工具集成与内容展示场景。 + +[本节为总结性内容，无需列出具体文件来源] + +## 附录 + +### 组件 API 速查表 + +- XProvider + - 主要属性：themeMode、locale、getPopupContainer、getTargetContainer、renderEmpty、component、className、style、id + - 插槽：无（通过参数与函数注入） +- CodeHighlighter + - 主要属性：value、themeMode、highlightProps、header + - 插槽：header +- FileCard + - 主要属性：rootUrl、apiPrefix、src、imageProps、spinProps、description、icon、mask + - 插槽：imageProps.placeholder、imageProps.preview.mask、imageProps.preview.closeIcon、imageProps.preview.toolbarRender、imageProps.preview.imageRender、description、icon、mask、spinProps.icon、spinProps.description、spinProps.indicator +- Folder + - 主要属性：treeData、directoryIcons、emptyRender、directoryTitle、previewTitle、previewRender、fileContentService + - 插槽：emptyRender、previewRender、directoryTitle、previewTitle +- Mermaid + - 主要属性：value、themeMode、config、actions、header + - 插槽：header、actions.customActions + +章节来源 + +- [frontend/antd/config-provider/config-provider.tsx:51-151](file://frontend/antd/config-provider/config-provider.tsx#L51-L151) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:29-51](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L29-L51) +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/folder/folder.tsx:16-120](file://frontend/antdx/folder/folder.tsx#L16-L120) +- [frontend/antdx/mermaid/mermaid.tsx:33-84](file://frontend/antdx/mermaid/mermaid.tsx#L33-L84) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\347\241\256\350\256\244\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\347\241\256\350\256\244\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..0afb63dd --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\347\241\256\350\256\244\347\273\204\344\273\266 API.md" @@ -0,0 +1,331 @@ +# 确认组件 API + + +**本文引用的文件** +- [thought_chain/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py) +- [think/__init__.py](file://backend/modelscope_studio/components/antdx/think/__init__.py) +- [thought-chain.tsx](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [think.tsx](file://frontend/antdx/think/think.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 的 Ant Design X 确认组件 API 参考文档，聚焦 ThoughtChain 思考链组件与 Think 思维组件的完整接口与行为说明。内容涵盖： + +- 组件的属性、事件与插槽定义 +- 思考过程的可视化展示与节点管理机制 +- 确认流程的控制与状态管理 +- 与 AI 推理过程和决策展示场景的集成建议 +- TypeScript 类型与接口规范 +- 最佳实践与常见问题排查 + +## 项目结构 + +Ant Design X 组件在后端通过 Python 组件包装，在前端通过 Svelte/React 混合桥接至 @ant-design/x 的原生实现。核心文件组织如下： + +- 后端 Python 包装：位于 backend/modelscope_studio/components/antdx 下，分别提供 ThoughtChain 与 Think 的 Python 组件类 +- 前端实现：位于 frontend/antdx 下，分别提供 thought-chain 与 think 的 TSX 实现 + +```mermaid +graph TB +subgraph "后端" +PY_TC["AntdXThoughtChain
Python 组件"] +PY_TH["AntdXThink
Python 组件"] +end +subgraph "前端" +FE_TC["ThoughtChain
TSX 实现"] +FE_TH["Think
TSX 实现"] +end +subgraph "第三方库" +ADX["@ant-design/x
原生组件库"] +end +PY_TC --> FE_TC +PY_TH --> FE_TH +FE_TC --> ADX +FE_TH --> ADX +``` + +图表来源 + +- [thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +章节来源 + +- [thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +## 核心组件 + +本节概述两个核心组件的职责与能力边界： + +- ThoughtChain（思考链）：用于以树形/列表形式可视化展示推理或决策过程的节点序列，支持展开/折叠、连线样式与节点集合管理 +- Think（思维）：用于封装单个思维单元，支持标题、图标、加载态与可展开状态，并提供插槽扩展点 + +章节来源 + +- [thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) + +## 架构总览 + +下图展示了从后端 Python 组件到前端 TSX 实现再到 @ant-design/x 原生组件的调用链路。 + +```mermaid +sequenceDiagram +participant PyTC as "后端 : AntdXThoughtChain" +participant PyTH as "后端 : AntdXThink" +participant FETC as "前端 : ThoughtChain" +participant FETH as "前端 : Think" +participant ADX as "@ant-design/x" +PyTC->>FETC : 渲染 ThoughtChain 组件 +FETC->>ADX : 使用 XThoughtChain 渲染 +PyTH->>FETH : 渲染 Think 组件 +FETH->>ADX : 使用 XThink 渲染 +``` + +图表来源 + +- [thought_chain/**init**.py:68-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L68-L86) +- [think/**init**.py:61-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L61-L79) +- [thought-chain.tsx:11-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L43) +- [think.tsx:6-24](file://frontend/antdx/think/think.tsx#L6-L24) + +## 详细组件分析 + +### ThoughtChain（思考链）组件 + +- 组件定位：用于呈现“思考链”式的数据流或决策序列，支持节点集合(items)、展开键(expanded_keys)、默认展开键(default_expanded_keys)、连线样式(line)等 +- 插槽：支持 items 插槽，用于注入节点集合 +- 事件：expand 事件，当展开键变化时触发回调 +- 属性要点： + - expanded_keys / default_expanded_keys：控制节点展开状态 + - items：节点数据集合，可由插槽或属性传入 + - line：连线样式，支持布尔值与特定字符串枚举 + - prefix_cls / styles / class_names / root_class_name：样式与类名定制 + - 其他通用属性：visible、elem_id、elem_classes、elem_style、render 等 + +```mermaid +classDiagram +class AntdXThoughtChain { ++expanded_keys : list[str] | None ++default_expanded_keys : list[str] | None ++items : list[dict] | None ++line : bool | "solid" | "dashed" | "dotted" | None ++prefix_cls : str | None ++additional_props : dict | None ++styles : dict | str | None ++class_names : dict | str | None ++root_class_name : str | None ++EVENTS : ["expand"] ++SLOTS : ["items"] ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +``` + +图表来源 + +- [thought_chain/**init**.py:30-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L30-L86) + +章节来源 + +- [thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [thought-chain.tsx:11-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L43) + +### Think（思维）组件 + +- 组件定位：用于封装单个思维单元，支持标题(title)、图标(icon)、加载态(loading)、默认展开(default_expanded)、当前展开(expanded)、闪烁(blink)等 +- 插槽：支持 loading、icon、title 三个插槽，允许自定义渲染 +- 事件：expand 事件，用于展开状态变更通知 +- 属性要点： + - icon / title / loading：基础展示属性 + - default_expanded / expanded：展开状态控制 + - blink：视觉提示 + - 其他通用属性：visible、elem_id、elem_classes、elem_style、render 等 + +```mermaid +classDiagram +class AntdXThink { ++additional_props : dict | None ++icon : str | None ++styles : dict | str | None ++class_names : dict | str | None ++loading : str | bool | None ++title : str | None ++root_class_name : str | None ++default_expanded : bool | None ++expanded : bool | None ++blink : bool | None ++EVENTS : ["expand"] ++SLOTS : ["loading","icon","title"] ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +``` + +图表来源 + +- [think/**init**.py:21-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L21-L79) + +章节来源 + +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [think.tsx:6-24](file://frontend/antdx/think/think.tsx#L6-L24) + +### 前端实现与插槽机制 + +- ThoughtChain 前端实现通过上下文读取插槽 items/default，并在必要时克隆节点以避免副作用；最终将解析后的 items 传递给 @ant-design/x 的 XThoughtChain +- Think 前端实现通过 ReactSlot 将 slots.loading/icon/title 注入到 @ant-design/x 的 XThink 中，若未提供插槽则回退到属性值 + +```mermaid +flowchart TD +Start(["进入 ThoughtChain 渲染"]) --> ReadSlot["读取插槽 items/default"] +ReadSlot --> HasItems{"插槽 items 是否存在且非空？"} +HasItems -- 是 --> UseItems["使用插槽 items"] +HasItems -- 否 --> UseDefault["使用插槽 default"] +UseItems --> Clone["可选：克隆节点"] +UseDefault --> Clone +Clone --> RenderADX["渲染 XThoughtChain 并传入 items"] +RenderADX --> End(["完成"]) +``` + +图表来源 + +- [thought-chain.tsx:14-39](file://frontend/antdx/thought-chain/thought-chain.tsx#L14-L39) + +章节来源 + +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [think.tsx:6-24](file://frontend/antdx/think/think.tsx#L6-L24) + +## 依赖关系分析 + +- 后端 Python 组件仅负责声明属性、事件、插槽与前端目录映射，不直接处理业务逻辑 +- 前端 TSX 组件负责： + - 解析插槽与属性，合并为 @ant-design/x 所需的 props + - 通过 sveltify 桥接到 React 生态 +- 第三方库 @ant-design/x 提供实际的 UI 行为与样式 + +```mermaid +graph LR +PY["后端 Python 组件"] --> FE["前端 TSX 组件"] +FE --> ADX["@ant-design/x"] +``` + +图表来源 + +- [thought_chain/**init**.py:68-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L68-L86) +- [think/**init**.py:61-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L61-L79) +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +章节来源 + +- [thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +## 性能考虑 + +- 节点克隆：前端在需要时对插槽节点进行克隆，避免共享引用导致的副作用，但会增加内存与计算开销。建议在节点数量较大时谨慎使用 +- 插槽解析：优先使用 items 插槽，其次回退到 default 插槽，减少不必要的属性传递 +- 展开状态：合理设置 expanded_keys/default_expanded_keys，避免一次性展开过多节点造成渲染压力 +- 加载态：Think 组件的 loading 插槽/属性应按需启用，避免冗余的动画与 DOM 结构 + +## 故障排查指南 + +- 插槽未生效 + - 检查是否正确使用 items/default 插槽；确认插槽名称大小写与顺序 + - 若使用属性 items，请确保类型与 @ant-design/x 的期望一致 +- 展开事件无效 + - 确认已绑定 expand 事件；检查回调中是否更新了 bind_expand_event 或相关状态 +- 加载态与插槽冲突 + - 当提供 loading 插槽时，插槽优先于属性；若未提供插槽，将回退到属性值 +- 样式与类名 + - 如需覆盖样式，优先使用 styles/class_names/root_class_name；注意与第三方库默认样式的冲突 + +章节来源 + +- [thought-chain.tsx:14-39](file://frontend/antdx/thought-chain/thought-chain.tsx#L14-L39) +- [think.tsx:10-17](file://frontend/antdx/think/think.tsx#L10-L17) +- [thought_chain/**init**.py:20-25](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L20-L25) +- [think/**init**.py:12-16](file://backend/modelscope_studio/components/antdx/think/__init__.py#L12-L16) + +## 结论 + +- ThoughtChain 与 Think 组件通过清晰的属性、事件与插槽设计，为 AI 推理与决策过程的可视化提供了稳定的基础 +- 建议在大规模节点场景下优化插槽使用与展开策略，结合加载态与样式定制提升用户体验 +- 通过 expand 事件与展开状态控制，可实现交互式确认流程与逐步展示 + +## 附录 + +### API 规范与类型定义（基于源码） + +- AntdXThoughtChain + - 属性 + - expanded_keys: 列表，节点展开键 + - default_expanded_keys: 列表，初始展开键 + - items: 列表，节点数据 + - line: 布尔或特定字符串，连线样式 + - prefix_cls: 字符串，前缀类名 + - additional_props/styles/class_names/root_class_name: 样式与类名定制 + - visible/elem_id/elem_classes/elem_style/render: 通用属性 + - 事件 + - expand：展开键变化回调 + - 插槽 + - items：节点集合 +- AntdXThink + - 属性 + - icon/title/loading: 图标、标题、加载态 + - default_expanded/expanded: 默认/当前展开状态 + - blink: 闪烁效果 + - styles/class_names/root_class_name: 样式与类名定制 + - visible/elem_id/elem_classes/elem_style/render: 通用属性 + - 事件 + - expand：展开状态变更回调 + - 插槽 + - loading/icon/title：对应属性的插槽替代 + +章节来源 + +- [thought_chain/**init**.py:30-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L30-L86) +- [think/**init**.py:21-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L21-L79) + +### 集成与最佳实践 + +- 推理过程可视化 + - 使用 ThoughtChain 展示多步推理/决策序列；每个 Think 代表一个思维单元 + - 通过 expand 控制逐步展示，结合 loading 插槽表示正在思考 +- 用户理解优化 + - 合理使用 line 连线样式与 prefix_cls，增强层级感 + - 在 Think 中使用 icon/title 明确角色与意图；必要时使用 blink 提示关注 +- 状态管理与流程控制 + - 通过 expanded_keys/default_expanded_keys 管理节点展开；通过 expand 事件驱动后续步骤 + - 对于长链路，建议分页/分段加载，避免一次性渲染过多节点 diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\350\241\250\350\276\276\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\350\241\250\350\276\276\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..b90b0b0d --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\350\241\250\350\276\276\347\273\204\344\273\266 API.md" @@ -0,0 +1,344 @@ +# 表达组件 API + + +**本文引用的文件** +- [frontend/antdx/attachments/Index.svelte](file://frontend/antdx/attachments/Index.svelte) +- [frontend/antdx/attachments/attachments.tsx](file://frontend/antdx/attachments/attachments.tsx) +- [frontend/antdx/sender/Index.svelte](file://frontend/antdx/sender/Index.svelte) +- [frontend/antdx/sender/sender.tsx](file://frontend/antdx/sender/sender.tsx) +- [frontend/antdx/suggestion/Index.svelte](file://frontend/antdx/suggestion/Index.svelte) +- [frontend/antdx/suggestion/suggestion.tsx](file://frontend/antdx/suggestion/suggestion.tsx) +- [frontend/antdx/suggestion/context.ts](file://frontend/antdx/suggestion/context.ts) +- [frontend/antdx/file-card/base.tsx](file://frontend/antdx/file-card/base.tsx) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/utils/hooks/useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [docs/components/antdx/attachments/README.md](file://docs/components/antdx/attachments/README.md) +- [docs/components/antdx/sender/README.md](file://docs/components/antdx/sender/README.md) +- [docs/components/antdx/suggestion/README.md](file://docs/components/antdx/suggestion/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 中 Ant Design X 表达组件的 API 参考文档，聚焦以下三个组件： + +- 附件组件：用于多模态输入中的文件/图片等附件展示与上传 +- 发送器组件：用于聊天消息输入、快捷指令触发与粘贴上传 +- 快捷指令组件：用于在输入框中提供可选择的快捷建议项 + +文档覆盖组件的属性接口、事件回调、数据绑定、状态同步、TypeScript 类型定义、与聊天系统的集成方式，以及多模态数据处理与用户输入优化的最佳实践。 + +## 项目结构 + +- 组件以 Svelte 包装层（Index.svelte）+ React 实现层（\*.tsx）的方式组织，通过 svelte-preprocess-react 将 Ant Design X 的 React 组件桥接为 Svelte 组件。 +- 附件组件支持自定义占位图、预览容器、图标渲染、列表项渲染等插槽扩展；发送器组件支持前缀/后缀/页眉/页脚插槽、技能面板、粘贴上传；快捷指令组件支持动态项渲染与键盘触发控制。 + +```mermaid +graph TB +subgraph "Svelte 包装层" +A_Index["attachments/Index.svelte"] +B_Index["sender/Index.svelte"] +C_Index["suggestion/Index.svelte"] +end +subgraph "React 实现层" +A_Impl["attachments.tsx"] +B_Impl["sender.tsx"] +C_Impl["suggestion.tsx"] +end +A_Index --> A_Impl +B_Index --> B_Impl +C_Index --> C_Impl +``` + +图表来源 + +- [frontend/antdx/attachments/Index.svelte:1-98](file://frontend/antdx/attachments/Index.svelte#L1-L98) +- [frontend/antdx/sender/Index.svelte:1-102](file://frontend/antdx/sender/Index.svelte#L1-L102) +- [frontend/antdx/suggestion/Index.svelte:1-75](file://frontend/antdx/suggestion/Index.svelte#L1-L75) +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) +- [frontend/antdx/suggestion/suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) + +章节来源 + +- [frontend/antdx/attachments/Index.svelte:1-98](file://frontend/antdx/attachments/Index.svelte#L1-L98) +- [frontend/antdx/sender/Index.svelte:1-102](file://frontend/antdx/sender/Index.svelte#L1-L102) +- [frontend/antdx/suggestion/Index.svelte:1-75](file://frontend/antdx/suggestion/Index.svelte#L1-L75) + +## 核心组件 + +- 附件组件（Attachments） + - 职责：展示与管理附件列表，支持拖拽/点击上传、限制数量、占位图与预览配置、自定义渲染与图标插槽。 + - 关键属性：items、maxCount、placeholder、imageProps、showUploadList、beforeUpload、customRequest、isImageUrl、itemRender、iconRender、getDropContainer、progress、onChange/onValueChange、upload。 + - 数据流：接收 items 并维护本地 fileList，onChange/onValueChange 同步外部值，upload 回调负责文件上传并回填 uid。 +- 发送器组件（Sender） + - 职责：聊天输入框，支持文本输入、粘贴上传、快捷指令面板、前后缀与页眉页脚插槽、提交拦截与联动。 + - 关键属性：value、onValueChange、onChange、onSubmit、suffix/header/prefix/footer、skill、slotConfig、onPasteFile、upload。 + - 数据流：使用 useValueChange 同步外部 value，拦截提交时若快捷指令打开则不触发 onSubmit，粘贴文件时通过 upload 获取文件路径数组。 +- 快捷指令组件（Suggestion） + - 职责：在输入框内提供可选建议项，支持动态 items 渲染、插槽扩展、键盘触发控制、弹出容器配置。 + - 关键属性：items、open、onOpenChange、getPopupContainer、shouldTrigger、children 插槽。 + - 数据流：内部维护 open 状态，合并 slots 与 props 的 items，通过 SuggestionOpenContext 与子树共享状态。 + +章节来源 + +- [frontend/antdx/attachments/attachments.tsx:36-410](file://frontend/antdx/attachments/attachments.tsx#L36-L410) +- [frontend/antdx/sender/sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) +- [frontend/antdx/suggestion/suggestion.tsx:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) + +## 架构总览 + +下图展示了三组件在 Svelte 与 React 层之间的桥接关系与数据流向。 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 包装层" +participant ReactImpl as "React 实现层" +participant Gradio as "Gradio 客户端" +Svelte->>ReactImpl : 传递 props/插槽/回调 +ReactImpl->>ReactImpl : useFunction/useValueChange 处理函数与值同步 +ReactImpl->>Gradio : 上传文件upload 回调 +Gradio-->>ReactImpl : 返回 FileData 列表 +ReactImpl-->>Svelte : 触发 onValueChange/onChange +Svelte-->>Svelte : updateProps 更新 value +``` + +图表来源 + +- [frontend/antdx/attachments/Index.svelte:77-92](file://frontend/antdx/attachments/Index.svelte#L77-L92) +- [frontend/antdx/sender/Index.svelte:71-78](file://frontend/antdx/sender/Index.svelte#L71-L78) +- [frontend/antdx/attachments/attachments.tsx:329-348](file://frontend/antdx/attachments/attachments.tsx#L329-L348) +- [frontend/antdx/sender/sender.tsx:135-138](file://frontend/antdx/sender/sender.tsx#L135-L138) + +## 详细组件分析 + +### 附件组件（Attachments） + +- 类型与接口 + - 导出类型：基于 @ant-design/x 的 AttachmentsProps，额外声明 onValueChange、onChange、upload、items 等。 + - 支持的插槽键：showUploadList.extra、showUploadList.previewIcon、showUploadList.removeIcon、showUploadList.downloadIcon、iconRender、itemRender、placeholder、placeholder.title、placeholder.description、placeholder.icon、imageProps.placeholder、imageProps.preview.mask、imageProps.preview.closeIcon、imageProps.preview.toolbarRender、imageProps.preview.imageRender。 +- 上传流程 + - 在 onChange 中区分新增/删除：新增时先执行 beforeUpload，再调用 upload 获取 FileData，合并到 fileList，最后触发 onValueChange。 + - 删除时若未处于上传中，则触发 onRemove 并更新值。 +- 配置要点 + - maxCount 控制单/多文件上传策略。 + - imageProps.preview 支持自定义 mask/closeIcon/toolbarRender/imageRender，或完全禁用预览。 + - placeholder 支持对象化配置与插槽组合。 + - showUploadList 支持对象化配置与插槽组合，分别注入 downloadIcon/removeIcon/previewIcon/extra。 +- 事件与状态 + - onValueChange：返回 FileData[]，用于外部绑定 value。 + - onChange：返回字符串路径数组，便于下游按路径处理。 + - upload：Promise<(FileData|null)[]>，需保留原始文件 uid 以便后续匹配。 + +```mermaid +flowchart TD +Start(["开始"]) --> Change["监听 onChange 事件"] +Change --> IsRemove{"是否为删除操作？"} +IsRemove --> |是| RemoveLogic["触发 onRemove
更新 fileList
触发 onValueChange/onChange"] +IsRemove --> |否| AddLogic["执行 beforeUpload
检查 maxCount 与上传状态
调用 upload 获取 FileData
合并到 fileList
触发 onValueChange/onChange"] +RemoveLogic --> End(["结束"]) +AddLogic --> End +``` + +图表来源 + +- [frontend/antdx/attachments/attachments.tsx:275-354](file://frontend/antdx/attachments/attachments.tsx#L275-L354) + +章节来源 + +- [frontend/antdx/attachments/attachments.tsx:36-410](file://frontend/antdx/attachments/attachments.tsx#L36-L410) +- [frontend/antdx/attachments/Index.svelte:72-92](file://frontend/antdx/attachments/Index.svelte#L72-L92) + +### 发送器组件（Sender） + +- 类型与接口 + - 导出类型：基于 @ant-design/x 的 SenderProps，额外声明 onValueChange、upload、onPasteFile 等。 + - 插槽键：suffix、header、prefix、footer、skill.title、skill.toolTip.title、skill.closable.closeIcon。 + - slotConfig：支持 formatResult/customRender 函数化包装。 +- 提交流程 + - onSubmit 会被拦截：当快捷指令打开时阻止提交，避免误触。 + - onChange 会同步内部 value，并触发外部 onChange。 +- 粘贴上传 + - onPasteFile：读取剪贴板文件，调用 upload 获取 FileData 数组，回传路径数组给 onPasteFile。 +- 事件与状态 + - onValueChange：外部 value 变更时，通过 useValueChange 同步内部状态。 + - onChange：实时变更通知。 + - upload：Promise
useFunction/useValueChange"] +Svelte --> Impl["React 实现层"] +Impl --> ADX["@ant-design/x 组件"] +Impl --> Utils["BaseFileCard/上传工具"] +Hooks --> Impl +``` + +图表来源 + +- [frontend/antdx/attachments/Index.svelte:28-56](file://frontend/antdx/attachments/Index.svelte#L28-L56) +- [frontend/antdx/sender/Index.svelte:35-66](file://frontend/antdx/sender/Index.svelte#L35-L66) +- [frontend/antdx/suggestion/Index.svelte:26-54](file://frontend/antdx/suggestion/Index.svelte#L26-L54) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/hooks/useValueChange.ts:9-29](file://frontend/utils/hooks/useValueChange.ts#L9-L29) +- [frontend/antdx/file-card/base.tsx:15-41](file://frontend/antdx/file-card/base.tsx#L15-L41) + +章节来源 + +- [frontend/antdx/attachments/Index.svelte:28-56](file://frontend/antdx/attachments/Index.svelte#L28-L56) +- [frontend/antdx/sender/Index.svelte:35-66](file://frontend/antdx/sender/Index.svelte#L35-L66) +- [frontend/antdx/suggestion/Index.svelte:26-54](file://frontend/antdx/suggestion/Index.svelte#L26-L54) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/hooks/useValueChange.ts:9-29](file://frontend/utils/hooks/useValueChange.ts#L9-L29) +- [frontend/antdx/file-card/base.tsx:15-41](file://frontend/antdx/file-card/base.tsx#L15-L41) + +## 性能考量 + +- 插槽与函数化 + - 使用 useFunction 包装 props 与插槽，减少不必要的重渲染。 + - 对复杂计算（如 items 渲染）使用 useMemo 与 useMemoizedEqualValue 缓存结果。 +- 上传状态 + - 附件组件在上传期间设置 uploading 状态，避免并发上传与误删。 + - 通过 maxCount 与临时 fileList 避免超量上传与 UI 抖动。 +- 值同步 + - useValueChange 仅在外部 value 变化时更新内部状态，避免循环更新。 + +章节来源 + +- [frontend/antdx/attachments/attachments.tsx:122-132](file://frontend/antdx/attachments/attachments.tsx#L122-L132) +- [frontend/antdx/attachments/attachments.tsx:304-312](file://frontend/antdx/attachments/attachments.tsx#L304-L312) +- [frontend/antdx/sender/sender.tsx:68-72](file://frontend/antdx/sender/sender.tsx#L68-L72) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/hooks/useValueChange.ts:9-29](file://frontend/utils/hooks/useValueChange.ts#L9-L29) + +## 故障排查指南 + +- 附件上传失败 + - 检查 upload 回调是否正确返回 FileData[]，并保留 uid 与原文件对应。 + - 确认 Gradio 客户端上传路径与 rootUrl/apiPrefix 配置一致。 +- 快捷指令不触发 + - 确认 shouldTrigger 是否被设置，且与输入框的 onKeyDown/onTrigger 协同工作。 + - 检查 open 状态是否被外部覆盖，或 SuggestionOpenContext 是否正确传递。 +- 发送器提交被拦截 + - 若快捷指令面板打开，onSubmit 会被拦截；关闭面板或等待其关闭后再提交。 +- 预览与图标不显示 + - 检查 imageProps.preview 与 showUploadList 的插槽键是否正确配置。 + - 确保插槽内容已正确渲染，必要时使用 ReactSlot 包裹。 + +章节来源 + +- [frontend/antdx/attachments/attachments.tsx:329-348](file://frontend/antdx/attachments/attachments.tsx#L329-L348) +- [frontend/antdx/suggestion/suggestion.tsx:135-140](file://frontend/antdx/suggestion/suggestion.tsx#L135-L140) +- [frontend/antdx/sender/sender.tsx:126-130](file://frontend/antdx/sender/sender.tsx#L126-L130) + +## 结论 + +- 附件组件提供了完善的多模态上传能力与灵活的插槽扩展，适合在聊天场景中承载图片/文件等多媒体输入。 +- 发送器组件将输入、粘贴上传与快捷指令面板整合，具备良好的交互一致性与可控性。 +- 快捷指令组件通过上下文与插槽系统实现高度可定制的建议体验，适配多种触发与渲染需求。 +- 建议在实际应用中结合 Gradio 客户端与 BaseFileCard 统一处理文件路径，确保跨模块的一致性与可维护性。 + +## 附录 + +- 示例与文档入口 + - 附件组件示例：见文档目录中的 demo 标签 + - 发送器组件示例：见文档目录中的 demo 标签 + - 快捷指令组件示例：见文档目录中的 demo 标签 + +章节来源 + +- [docs/components/antdx/attachments/README.md:1-9](file://docs/components/antdx/attachments/README.md#L1-L9) +- [docs/components/antdx/sender/README.md:1-10](file://docs/components/antdx/sender/README.md#L1-L10) +- [docs/components/antdx/suggestion/README.md:1-10](file://docs/components/antdx/suggestion/README.md#L1-L10) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\351\200\232\347\224\250\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\351\200\232\347\224\250\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..8842acd3 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design X \347\273\204\344\273\266 API/\351\200\232\347\224\250\347\273\204\344\273\266 API.md" @@ -0,0 +1,518 @@ +# 通用组件 API + + +**本文引用的文件** +- [bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [prompts.tsx](file://frontend/antdx/prompts/prompts.tsx) +- [suggestion.tsx](file://frontend/antdx/suggestion/suggestion.tsx) +- [sender.tsx](file://frontend/antdx/sender/sender.tsx) +- [context.ts（建议项上下文）](file://frontend/antdx/suggestion/context.ts) +- [context.ts（会话项上下文）](file://frontend/antdx/conversations/context.ts) +- [context.ts（提示项上下文）](file://frontend/antdx/prompts/context.ts) +- [renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [createFunction.ts](file://frontend/utils/createFunction.ts) +- [patchSlots.ts](file://frontend/utils/patchSlots.ts) +- [useMemoizedEqualValue.ts](file://frontend/utils/hooks/useMemoizedEqualValue.ts) +- [react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) +- [react-contexts.ts](file://frontend/svelte-preprocess-react/react-contexts.ts) +- [sveltify.svelte.ts](file://frontend/svelte-preprocess-react/sveltify.svelte.ts) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 的 Ant Design X 通用组件 API 参考文档，聚焦以下核心通用组件的完整接口说明与使用指南： + +- Bubble：对话气泡组件，支持头像、内容、底部栏、额外操作等插槽与渲染函数 +- Conversations：对话列表/分组管理，支持菜单、分组标签、溢出指示器等扩展 +- Prompts：提示词卡片集合，支持标题插槽与动态项渲染 +- Suggestion：快捷指令/建议输入，支持弹层容器、触发策略、子项插槽补丁 +- Sender：发送器，支持粘贴上传、技能面板、前缀/后缀/页眉/页脚插槽 + +文档覆盖属性定义、事件处理、插槽系统、状态管理、消息传递与对话流程控制机制，并给出面向 AI 聊天与对话场景的实例化与配置示例路径、TypeScript 类型与与 Ant Design 组件的集成方式，以及性能优化与最佳实践。 + +## 项目结构 + +Ant Design X 通用组件位于前端目录的 antdx 子模块中，采用“Svelte 包装 + React 组件桥接”的架构：通过 svelte-preprocess-react 将 @ant-design/x 的 React 组件以 Svelte 方式使用，同时提供统一的插槽系统与上下文注入能力。 + +```mermaid +graph TB +subgraph "Ant Design X 通用组件" +B["Bubble
气泡组件"] +C["Conversations
会话列表/分组"] +P["Prompts
提示词卡片"] +S["Suggestion
快捷指令/建议"] +SD["Sender
发送器"] +end +subgraph "工具与上下文" +U1["renderItems.tsx
渲染项工具"] +U2["renderParamsSlot.tsx
带参插槽渲染"] +U3["useFunction.ts
函数包装钩子"] +U4["useValueChange.ts
值变更钩子"] +U5["createFunction.ts
函数工厂"] +U6["patchSlots.ts
插槽补丁"] +U7["react-slot.tsx
React 插槽"] +U8["react-contexts.ts
React 上下文"] +U9["sveltify.svelte.ts
Svelte 包装"] +end +B --> U1 +B --> U2 +B --> U3 +B --> U7 +C --> U1 +C --> U2 +C --> U3 +C --> U8 +P --> U1 +P --> U2 +S --> U1 +S --> U2 +S --> U3 +S --> U6 +SD --> U1 +SD --> U2 +SD --> U3 +SD --> U4 +SD --> U5 +SD --> U7 +SD --> U8 +``` + +图表来源 + +- [bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) +- [sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) +- [renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [createFunction.ts](file://frontend/utils/createFunction.ts) +- [patchSlots.ts](file://frontend/utils/patchSlots.ts) +- [react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) +- [react-contexts.ts](file://frontend/svelte-preprocess-react/react-contexts.ts) +- [sveltify.svelte.ts](file://frontend/svelte-preprocess-react/sveltify.svelte.ts) + +章节来源 + +- [bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) +- [sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +## 核心组件 + +本节概述四个核心通用组件的职责与典型用法，便于快速定位到具体实现与示例路径。 + +- Bubble（对话气泡） + - 支持头像、内容、页眉、页脚、额外操作、可编辑文案、加载与内容自定义渲染 + - 插槽键名：avatar、content、header、footer、extra、editable.okText、editable.cancelText、loadingRender、contentRender + - 典型场景：用户/系统消息展示、可编辑回复、异步加载态 + +- Conversations（会话管理） + - 支持会话项列表、分组、菜单、溢出指示器、展开图标、触发器等 + - 插槽键名：menu.items、menu.trigger、menu.expandIcon、menu.overflowedIndicator、groupable.label + - 典型场景：历史会话浏览、分组折叠、右键菜单操作 + +- Prompts（提示集） + - 支持提示词卡片标题插槽与动态项渲染 + - 插槽键名：title + - 典型场景：聊天引导、快捷提示、模板化输入 + +- Suggestion（快捷指令） + - 支持建议项列表、子项插槽补丁、弹层容器、打开状态、键盘触发策略 + - 插槽键名：children + - 典型场景：@提及、/命令、快捷建议 + +- Sender（发送器） + - 支持粘贴上传、技能面板、前缀/后缀/页眉/页脚插槽、值变更与提交拦截 + - 插槽键名：suffix、header、prefix、footer、skill.title、skill.toolTip.title、skill.closable.closeIcon + - 典型场景：文本输入、文件粘贴上传、技能开关 + +章节来源 + +- [bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) +- [conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) +- [prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) +- [suggestion.tsx:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) +- [sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) + +## 架构总览 + +下图展示了通用组件与工具库之间的调用关系与数据流，体现“插槽解析 → 函数包装 → 渲染项生成 → React 组件桥接”的整体流程。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Comp as "Svelte 包装组件" +participant Utils as "工具库" +participant X as "@ant-design/x 组件" +Dev->>Comp : 传入属性与插槽 +Comp->>Utils : 解析插槽/函数包装/值变更 +Utils-->>Comp : 返回渲染结果/函数句柄 +Comp->>X : 透传属性并桥接 React 组件 +X-->>Dev : 渲染 UI 并触发回调 +``` + +图表来源 + +- [bubble.tsx:27-115](file://frontend/antdx/bubble/bubble.tsx#L27-L115) +- [conversations.tsx:72-171](file://frontend/antdx/conversations/conversations.tsx#L72-L171) +- [prompts.tsx:16-37](file://frontend/antdx/prompts/prompts.tsx#L16-L37) +- [suggestion.tsx:77-159](file://frontend/antdx/suggestion/suggestion.tsx#L77-L159) +- [sender.tsx:35-169](file://frontend/antdx/sender/sender.tsx#L35-L169) +- [renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [createFunction.ts](file://frontend/utils/createFunction.ts) +- [patchSlots.ts](file://frontend/utils/patchSlots.ts) +- [react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) + +## 详细组件分析 + +### Bubble 组件 API + +- 组件职责 + - 将 @ant-design/x 的 Bubble 以 Svelte 形式封装，提供插槽与函数包装能力 + - 支持可编辑文案、加载与内容自定义渲染、头像/页眉/页脚/额外操作等插槽 +- 关键属性与插槽 + - 属性：继承自 BubbleProps，支持 editable、typing、content、avatar、extra、footer、header、loadingRender、contentRender 等 + - 插槽：avatar、content、header、footer、extra、editable.okText、editable.cancelText、loadingRender、contentRender +- 事件与状态 + - 通过 useFunction 包装回调，确保响应式更新；editable 支持布尔或配置对象 +- 使用要点 + - 当 editable 配置存在或插槽存在时启用编辑态；loadingRender/contentRender 支持带参插槽 +- 示例路径 + - [Bubble 实现:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) + +```mermaid +classDiagram +class Bubble { ++props : BubbleProps ++slots : 插槽集合 ++useFunction() ++ReactSlot ++renderParamsSlot() +} +class XBubble { ++继承自 @ant-design/x +} +Bubble --> XBubble : "桥接" +``` + +图表来源 + +- [bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) + +章节来源 + +- [bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) + +### Conversations 组件 API + +- 组件职责 + - 将 @ant-design/x 的 Conversations 以 Svelte 形式封装，提供菜单与分组能力 +- 关键属性与插槽 + - 属性：继承自 ConversationsProps，支持 items、menu、groupable、classNames 等 + - 插槽：menu.items、menu.trigger、menu.expandIcon、menu.overflowedIndicator、groupable.label +- 事件与状态 + - 通过 useFunction 包装 menu 回调；对菜单事件进行包裹以传递当前会话上下文 + - 分组标签支持插槽与函数配置 +- 使用要点 + - menu 支持字符串或对象；当未提供 items 时可从上下文注入 + - classNames.item 注入样式类名以增强一致性 +- 示例路径 + - [Conversations 实现:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Conv as "Conversations" +participant Ctx as "上下文/插槽" +participant XConv as "X Conversations" +Dev->>Conv : 传入 items/menu/groupable +Conv->>Ctx : 读取插槽/上下文 items +Conv->>Conv : useFunction 包装菜单回调 +Conv->>XConv : 透传属性并渲染 +XConv-->>Dev : 渲染会话列表/分组 +``` + +图表来源 + +- [conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) +- [context.ts（会话项上下文）:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) + +章节来源 + +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [context.ts（会话项上下文）:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) + +### Prompts 组件 API + +- 组件职责 + - 将 @ant-design/x 的 Prompts 以 Svelte 形式封装，提供标题插槽与动态项渲染 +- 关键属性与插槽 + - 属性：继承自 PromptsProps，支持 items、title 等 + - 插槽：title +- 事件与状态 + - 通过 renderItems 动态生成项列表；优先使用插槽 items/default +- 使用要点 + - 适合用于“快捷提示”“模板化输入”等场景 +- 示例路径 + - [Prompts 实现:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) + +```mermaid +flowchart TD +Start(["开始"]) --> Read["读取插槽 items/default"] +Read --> HasItems{"是否有 items?"} +HasItems --> |是| Render["renderItems 渲染"] +HasItems --> |否| UseProps["使用 props.items"] +Render --> SetTitle["设置 title 插槽"] +UseProps --> SetTitle +SetTitle --> End(["结束"]) +``` + +图表来源 + +- [prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) +- [context.ts（提示项上下文）:1-7](file://frontend/antdx/prompts/context.ts#L1-L7) + +章节来源 + +- [prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [context.ts（提示项上下文）:1-7](file://frontend/antdx/prompts/context.ts#L1-L7) + +### Suggestion 组件 API + +- 组件职责 + - 将 @ant-design/x 的 Suggestion 以 Svelte 形式封装，提供建议项插槽补丁、弹层容器、打开状态与键盘触发策略 +- 关键属性与插槽 + - 属性：继承自 SuggestionProps，新增 children 插槽与 shouldTrigger 回调 + - 插槽：children +- 事件与状态 + - 通过 SuggestionOpenContext 与 useSuggestionOpenContext 控制/感知打开状态 + - 通过 patchSlots 对建议项的 icon/label/extra/children 进行插槽补丁 + - 通过 useMemoizedEqualValue 优化渲染开销 +- 使用要点 + - 支持在 children 渲染函数中注入上下文，实现 onTrigger/onKeyDown 的定制 + - 支持受控/非受控 open 状态切换 +- 示例路径 + - [Suggestion 实现:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Sug as "Suggestion" +participant Ctx as "SuggestionContext/SuggestionOpenContext" +participant Patch as "patchSlots" +participant XSug as "X Suggestion" +Dev->>Sug : 传入 items/children/shouldTrigger +Sug->>Patch : 补丁建议项插槽 +Sug->>Ctx : Provider 注入上下文 +Sug->>XSug : 透传属性并渲染 +XSug-->>Dev : 弹层与建议项 +``` + +图表来源 + +- [suggestion.tsx:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) +- [context.ts（建议项上下文）:1-7](file://frontend/antdx/suggestion/context.ts#L1-L7) +- [react-contexts.ts](file://frontend/svelte-preprocess-react/react-contexts.ts) + +章节来源 + +- [suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) +- [context.ts（建议项上下文）:1-7](file://frontend/antdx/suggestion/context.ts#L1-L7) + +### Sender 组件 API + +- 组件职责 + - 将 @ant-design/x 的 Sender 以 Svelte 形式封装，提供粘贴上传、技能面板、插槽与值变更钩子 +- 关键属性与插槽 + - 属性：继承自 SenderProps，新增 upload、onPasteFile、onValueChange 等 + - 插槽：suffix、header、prefix、footer、skill.title、skill.toolTip.title、skill.closable.closeIcon +- 事件与状态 + - 通过 useValueChange 管理受控/非受控 value + - 通过 useSuggestionOpenContext 在 Suggestion 打开时拦截提交 + - 通过 createFunction/formatResult/customRender 定制 slotConfig +- 使用要点 + - 粘贴文件时调用 upload 并回填路径数组 + - 技能面板支持 tooltip/closable 的插槽与配置组合 +- 示例路径 + - [Sender 实现:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) + +```mermaid +flowchart TD +A["onPasteFile 触发"] --> B["调用 upload(files)"] +B --> C["回填路径数组到 onPasteFile"] +D["onSubmit 触发"] --> E{"Suggestion 是否打开?"} +E --> |是| F["拦截提交"] +E --> |否| G["正常提交"] +H["onChange 触发"] --> I["useValueChange 更新 value"] +``` + +图表来源 + +- [sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) + +章节来源 + +- [sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +## 依赖关系分析 + +通用组件与工具库之间存在清晰的依赖关系：组件通过上下文与插槽系统消费工具库能力，最终桥接到 @ant-design/x 的 React 组件。 + +```mermaid +graph LR +subgraph "组件" +B["Bubble"] +C["Conversations"] +P["Prompts"] +S["Suggestion"] +SD["Sender"] +end +subgraph "工具" +R1["renderItems"] +R2["renderParamsSlot"] +H1["useFunction"] +H2["useValueChange"] +H3["useMemoizedEqualValue"] +F1["createFunction"] +F2["patchSlots"] +RS["ReactSlot"] +RC["ReactContexts"] +end +B --> R1 +B --> R2 +B --> H1 +B --> RS +C --> R1 +C --> R2 +C --> H1 +C --> RC +P --> R1 +P --> R2 +S --> R1 +S --> R2 +S --> H1 +S --> F2 +S --> H3 +SD --> R1 +SD --> R2 +SD --> H1 +SD --> H2 +SD --> F1 +SD --> RS +SD --> RC +``` + +图表来源 + +- [bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) +- [sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) +- [renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [createFunction.ts](file://frontend/utils/createFunction.ts) +- [patchSlots.ts](file://frontend/utils/patchSlots.ts) +- [react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) +- [react-contexts.ts](file://frontend/svelte-preprocess-react/react-contexts.ts) + +章节来源 + +- [bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) +- [sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +## 性能考量 + +- 插槽与函数包装 + - 使用 useMemoizedEqualValue 与 useMemo 降低渲染抖动与重复计算 + - 通过 useFunction 包装回调，避免每次渲染产生新函数导致的子组件重渲染 +- 渲染项与插槽 + - renderItems 与 renderParamsSlot 仅在必要时执行，减少不必要的克隆与渲染 + - patchSlots 仅对建议项进行按需补丁，避免全量替换 +- 值变更与事件拦截 + - useValueChange 统一 value 管理，避免外部状态不一致 + - Sender 在 Suggestion 打开时拦截提交，减少无效请求 +- 最佳实践 + - 合理拆分插槽与函数，避免在插槽中执行重型逻辑 + - 对高频更新的数据使用稳定引用，结合 useMemo/useCallback + - 在 Conversations/Prompts 中尽量复用已解析的 items，减少重复渲染 + +[本节为通用性能指导，无需特定文件来源] + +## 故障排查指南 + +- 插槽未生效 + - 检查插槽键名是否与组件声明一致（如 bubble 的 editable.okText、conversations 的 menu.items 等） + - 确认插槽内容是否被正确包裹于 ReactSlot 或 renderParamsSlot +- 事件未触发 + - 确认 useFunction 包装的回调是否正确传递至底层组件 + - 对于 Conversations 的菜单事件，检查 patchMenuEvents 是否正确包裹原事件 +- 建议项插槽不显示 + - 确认 patchSlots 已对 icon/label/extra/children 进行补丁 + - 检查 Suggestion 的 children 渲染函数是否返回了正确的节点 +- Sender 提交被拦截 + - 确认 SuggestionOpenContext 的状态是否为 true + - 检查 shouldTrigger 是否在键盘事件中正确触发 +- 值未更新 + - 确认 useValueChange 的 onValueChange 是否被调用 + - 检查 props.value 与内部状态同步逻辑 + +章节来源 + +- [bubble.tsx:27-115](file://frontend/antdx/bubble/bubble.tsx#L27-L115) +- [conversations.tsx:35-122](file://frontend/antdx/conversations/conversations.tsx#L35-L122) +- [suggestion.tsx:100-159](file://frontend/antdx/suggestion/suggestion.tsx#L100-L159) +- [sender.tsx:126-138](file://frontend/antdx/sender/sender.tsx#L126-L138) + +## 结论 + +ModelScope Studio 的 Ant Design X 通用组件通过统一的插槽系统与函数包装机制，实现了与 @ant-design/x 组件的无缝桥接。Bubble、Conversations、Prompts、Suggestion、Sender 在 AI 聊天与对话场景中提供了强大的可扩展性与易用性。遵循本文档的属性定义、事件处理、插槽系统与状态管理建议，可高效构建高质量的对话界面与交互流程。 + +[本节为总结性内容，无需特定文件来源] + +## 附录 + +- TypeScript 类型与接口 + - 组件均基于 @ant-design/x 的对应 Props 类型进行扩展或裁剪，确保类型安全 + - 插槽与函数包装通过泛型与工具函数保障类型推断 +- 与 Ant Design 组件的集成 + - 通过 svelte-preprocess-react 的 sveltify 与 ReactSlot 实现 Svelte 到 React 的桥接 + - 通过 createFunction/useFunction 等工具实现属性与回调的函数化封装 +- 示例路径索引 + - Bubble：[bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) + - Conversations：[conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) + - Prompts：[prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) + - Suggestion：[suggestion.tsx:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) + - Sender：[sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) + +[本节为补充信息，无需特定文件来源] diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..d4e506a3 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API.md" @@ -0,0 +1,479 @@ +# Ant Design 组件 API + + +**本文引用的文件** +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/form/Index.svelte](file://frontend/antd/form/Index.svelte) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/layout/Index.svelte](file://frontend/antd/layout/Index.svelte) +- [frontend/antd/layout/layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) +- [frontend/antd/table/table.tsx](file://frontend/antd/table/table.tsx) +- [frontend/antd/select/select.tsx](file://frontend/antd/select/select.tsx) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [frontend/antd/grid/context.ts](file://frontend/antd/grid/context.ts) +- [frontend/antd/table/context.ts](file://frontend/antd/table/context.ts) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 中基于 Ant Design Svelte 的组件 API 参考文档。目标是系统性梳理 Ant Design 组件在前端层的封装方式，覆盖通用组件、布局组件、导航组件、数据录入组件、数据展示组件、反馈组件等类别，明确每个组件的属性定义、事件处理、插槽系统、样式定制、状态管理与数据绑定机制，并给出与原生 Ant Design 组件的对应关系及 TypeScript 类型规范。同时提供实例化与配置的参考路径，以及性能优化与最佳实践建议。 + +## 项目结构 + +ModelScope Studio 的 Ant Design Svelte 组件采用“Svelte 外壳 + React 组件桥接”的架构：Svelte 层负责属性透传、插槽与可见性控制；React 层通过 sveltify 将 Ant Design 组件桥接到 Svelte 生态中。工具层提供统一的函数包装、插槽渲染与上下文注入能力。 + +```mermaid +graph TB +subgraph "Svelte 外壳层" +IDX_BTN["button/Index.svelte"] +IDX_FORM["form/Index.svelte"] +IDX_LAYOUT["layout/Index.svelte"] +end +subgraph "React 桥接层" +BTN_TSX["button/button.tsx"] +FORM_TSX["form/form.tsx"] +LAYOUT_BASE["layout/layout.base.tsx"] +TABLE_TSX["table/table.tsx"] +SELECT_TSX["select/select.tsx"] +end +subgraph "工具与上下文" +USE_FN["utils/hooks/useFunction.ts"] +RENDER_ITEMS["utils/renderItems.tsx"] +RENDER_SLOT["utils/renderParamsSlot.tsx"] +GRID_CTX["antd/grid/context.ts"] +TABLE_CTX["antd/table/context.ts"] +end +IDX_BTN --> BTN_TSX +IDX_FORM --> FORM_TSX +IDX_LAYOUT --> LAYOUT_BASE +TABLE_TSX --> TABLE_CTX +SELECT_TSX --> GRID_CTX +BTN_TSX --> USE_FN +FORM_TSX --> USE_FN +TABLE_TSX --> USE_FN +SELECT_TSX --> USE_FN +TABLE_TSX --> RENDER_ITEMS +SELECT_TSX --> RENDER_ITEMS +TABLE_TSX --> RENDER_SLOT +SELECT_TSX --> RENDER_SLOT +``` + +图表来源 + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [frontend/antd/table/context.ts:1-29](file://frontend/antd/table/context.ts#L1-L29) + +章节来源 + +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) + +## 核心组件 + +本节概述各组件层的职责与典型用法要点： + +- 通用组件：如 Button，负责属性透传、插槽（图标、加载态图标）与可见性控制。 +- 表单组件：如 Form，负责表单值双向绑定、动作触发（重置/提交/校验）、回调合并。 +- 布局组件：如 Layout，通过 Base 组件按需选择 Header/Footer/Content/Layout 并注入样式类名。 +- 数据展示组件：如 Table，支持列、展开、行选择、分页、粘性头部、汇总、标题/页脚插槽等复杂场景。 +- 选择器组件：如 Select，支持选项列表、过滤、下拉/弹窗渲染、标签/标签项渲染等插槽。 + +章节来源 + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) + +## 架构总览 + +Svelte 外壳通过 getProps/processProps/importComponent 等机制收集并转换属性，再由 sveltify 包装的 React 组件承载实际 UI 逻辑。插槽系统通过 ReactSlot 与 renderItems/renderParamsSlot 实现参数化渲染与上下文注入。 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 外壳(Index.svelte)" +participant Utils as "工具(useFunction/renderItems/renderParamsSlot)" +participant Bridge as "sveltify 包装的 React 组件" +participant AntD as "Ant Design 组件" +Svelte->>Utils : "使用 useFunction 包装回调/函数型属性" +Svelte->>Utils : "使用 renderItems 渲染子项/插槽" +Svelte->>Utils : "使用 renderParamsSlot 渲染带参插槽" +Svelte->>Bridge : "导入并等待组件加载(importComponent)" +Bridge->>AntD : "透传 props/事件/插槽" +AntD-->>Bridge : "返回渲染结果" +Bridge-->>Svelte : "输出最终 UI" +``` + +图表来源 + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +## 详细组件分析 + +### Button 组件 + +- 属性定义 + - 通用属性：继承 Ant Design Button 的全部属性。 + - 插槽：icon、loading.icon。 + - 元信息：elem_id、elem_classes、elem_style、visible 控制可见性与样式。 + - 链接行为：href_target 映射到 target。 +- 事件处理 + - 通过 Ant Design Button 的 onClick 等事件透传。 +- 插槽系统 + - 支持以插槽形式传入图标或加载态图标，内部通过 ReactSlot 渲染。 +- 样式定制 + - 通过 elem_classes、elem_style 注入类名与内联样式。 +- 状态管理与数据绑定 + - 无双向绑定；可通过外部更新 props 控制显示/隐藏。 +- TypeScript 类型 + - 使用 Ant Design Button 的 GetProps 类型别名进行约束。 +- 对应关系 + - React 组件：Ant Design Button。 +- 示例参考路径 + - [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + - [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) + +```mermaid +sequenceDiagram +participant UI as "调用方" +participant Shell as "button/Index.svelte" +participant Btn as "button/button.tsx" +participant AntBtn as "Ant Design Button" +UI->>Shell : "传入属性与插槽" +Shell->>Btn : "processProps 后透传" +Btn->>AntBtn : "渲染 Button 并注入插槽" +AntBtn-->>UI : "触发事件/显示内容" +``` + +图表来源 + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) + +章节来源 + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) + +### Form 组件 + +- 属性定义 + - value：表单初始值或受控值。 + - formAction：'reset' | 'submit' | 'validate' | null，用于触发动作。 + - 回调：onValueChange、onResetFormAction。 + - 其他：requiredMark、feedbackIcons、as_item、visible 等。 +- 事件处理 + - onValuesChange 合并 onValueChange，实现值变更通知。 + - 动作执行：根据 formAction 调用 form.resetFields/form.submit/form.validateFields。 +- 插槽系统 + - requiredMark 可通过插槽渲染。 +- 样式与可见性 + - elem_id、elem_classes、elem_style、visible 控制外观与显示。 +- 状态管理与数据绑定 + - 双向绑定：onValueChange 更新外部 value；外部 value 变更时同步回表单。 + - 动作解耦：onResetFormAction 在动作完成后重置 formAction。 +- TypeScript 类型 + - FormProps 扩展 Ant Design Form 的 GetProps，并声明 value、onValueChange、formAction 等。 +- 对应关系 + - React 组件：Ant Design Form。 +- 示例参考路径 + - [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) + - [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) + +```mermaid +sequenceDiagram +participant UI as "调用方" +participant Shell as "form/Index.svelte" +participant Form as "form/form.tsx" +participant AntForm as "Ant Design Form" +UI->>Shell : "设置 value/formAction" +Shell->>Form : "透传属性与回调" +Form->>AntForm : "创建并操作 Form 实例" +AntForm-->>Form : "onValuesChange/value 变更" +Form-->>Shell : "onValueChange(value)" +Shell-->>UI : "updateProps({ value })" +UI->>Shell : "formAction='reset'/'submit'/'validate'" +Shell->>Form : "触发动作" +Form-->>Shell : "onResetFormAction()" +``` + +图表来源 + +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) + +章节来源 + +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) + +### Layout 组件 + +- 属性定义 + - component：'header' | 'footer' | 'content' | 'layout'，决定渲染的具体 Ant Design 组件。 + - 其他：className、id、style 等透传。 +- 插槽系统 + - 通过 Base 组件接收 children 并渲染。 +- 样式定制 + - Base 会为不同 component 注入不同的类名前缀，便于主题化。 +- 对应关系 + - React 组件：Ant Design Layout 及其 Content/Header/Footer。 +- 示例参考路径 + - [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) + - [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +```mermaid +flowchart TD +Start(["开始"]) --> Choose["根据 component 选择具体组件"] +Choose --> |header| Header["Ant Design Layout.Header"] +Choose --> |footer| Footer["Ant Design Layout.Footer"] +Choose --> |content| Content["Ant Design Layout.Content"] +Choose --> |layout| Layout["Ant Design Layout"] +Header --> Render["渲染并注入类名"] +Footer --> Render +Content --> Render +Layout --> Render +Render --> End(["结束"]) +``` + +图表来源 + +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +章节来源 + +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +### Table 组件 + +- 属性定义 + - columns：列定义，支持默认列与扩展列常量。 + - rowSelection、expandable：行选择与可展开配置，支持插槽注入。 + - pagination：分页配置，支持插槽注入跳转按钮与页码渲染。 + - loading：支持 tip 与 indicator 插槽。 + - sticky、showSorterTooltip、footer、title、summary 等。 +- 插槽系统 + - 通过 withColumnItemsContextProvider/withRowSelectionItemsContextProvider/withExpandableItemsContextProvider 注入列、行选择与展开项。 + - renderItems 渲染列与子项；renderParamsSlot 渲染带参插槽（如分页按钮、页码渲染、排序提示等）。 +- 函数型属性 + - useFunction 包装 getPopupContainer、rowClassName、rowKey、summary、footer 等函数型属性。 +- 性能注意 + - 列与行选择等配置通过 useMemo 优化渲染。 +- 对应关系 + - React 组件：Ant Design Table。 +- 示例参考路径 + - [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) + - [frontend/antd/table/context.ts:1-29](file://frontend/antd/table/context.ts#L1-L29) + - [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + - [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +```mermaid +sequenceDiagram +participant UI as "调用方" +participant Shell as "table/Index.svelte" +participant Table as "table/table.tsx" +participant Ctx as "上下文(列/行选择/展开)" +participant AntTable as "Ant Design Table" +UI->>Shell : "传入 columns/rowSelection/expandable/pagination 等" +Shell->>Table : "processProps 与 slots" +Table->>Ctx : "读取列/行选择/展开项" +Table->>AntTable : "渲染并注入插槽/函数型属性" +AntTable-->>Table : "事件/渲染结果" +Table-->>Shell : "输出最终 UI" +``` + +图表来源 + +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/table/context.ts:1-29](file://frontend/antd/table/context.ts#L1-L29) + +章节来源 + +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/table/context.ts:1-29](file://frontend/antd/table/context.ts#L1-L29) + +### Select 组件 + +- 属性定义 + - options：选项列表，支持通过插槽注入。 + - onChange/onValueChange：值变更回调。 + - filterOption/filterSort：过滤与排序函数。 + - dropdownRender/popupRender/optionRender/tagRender/labelRender：插槽化渲染。 + - allowClear.prefix/removeIcon/suffixIcon/notFoundContent/menuItemSelectedIcon：插槽化图标与文案。 +- 插槽系统 + - withItemsContextProvider 注入 options/default 子项；renderItems 渲染选项。 + - renderParamsSlot 渲染带参插槽（如 maxTagPlaceholder）。 +- 函数型属性 + - useFunction 包装 getPopupContainer、dropdownRender、popupRender、optionRender、tagRender、labelRender、filterOption、filterSort。 +- 对应关系 + - React 组件：Ant Design Select。 +- 示例参考路径 + - [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) + - [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) + - [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + - [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +```mermaid +flowchart TD +Start(["开始"]) --> Options["解析 options/default 插槽项"] +Options --> RenderOpts["renderItems 渲染选项"] +RenderOpts --> Hooks["useFunction 包装函数型属性"] +Hooks --> Slots["插槽化图标/文案/渲染器"] +Slots --> AntSelect["渲染 Ant Design Select"] +AntSelect --> End(["结束"]) +``` + +图表来源 + +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) + +章节来源 + +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) + +## 依赖分析 + +- 组件间依赖 + - Button/Form/Layout/Table/Select 均依赖 sveltify 将 Ant Design 组件桥接至 Svelte。 + - 插槽与上下文依赖 renderItems/renderParamsSlot 与 createItemsContext。 + - 函数型属性依赖 useFunction 包装为可执行函数。 +- 外部依赖 + - Ant Design：作为 React 组件库，提供 UI 基础能力。 + - 工具库：classnames、lodash-es 等辅助样式与对象处理。 +- 循环依赖 + - 未发现直接循环依赖；上下文注入通过独立模块导出。 + +```mermaid +graph LR +Svelte["Svelte 外壳"] --> Sveltify["sveltify 包装"] +Sveltify --> AntD["Ant Design 组件"] +Svelte --> Utils["工具函数"] +Utils --> RenderItems["renderItems"] +Utils --> RenderSlot["renderParamsSlot"] +Utils --> UseFunction["useFunction"] +Svelte --> Ctx["上下文(createItemsContext)"] +``` + +图表来源 + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +章节来源 + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +## 性能考虑 + +- 函数型属性包装 + - 使用 useFunction 将传入的字符串/函数包装为可执行函数，避免每次渲染重新创建闭包。 +- 插槽与上下文 + - renderItems 与 renderParamsSlot 支持克隆与参数化渲染，减少重复渲染开销。 +- 计算缓存 + - Table/Select 中大量使用 useMemo 缓存计算结果（如列、行键、容器函数等）。 +- 异步加载 + - Svelte 外壳通过 importComponent 异步加载 React 组件，降低首屏压力。 +- 最佳实践 + - 尽量使用插槽而非内联 JSX，提升复用性与可维护性。 + - 对高频变化的 props 使用 $derived 或 useMemo 包装，避免不必要的重渲染。 + - 合理拆分组件，避免单个组件承担过多职责。 + +## 故障排查指南 + +- 插槽不生效 + - 检查插槽键是否正确（如 'loading.icon'、'pagination.showQuickJumper.goButton'），确保传递的是 HTMLElement 或带 withParams 的对象。 + - 确认 renderParamsSlot/renderItems 的 forceClone 与 clone 设置。 +- 函数型属性无效 + - 确保传入字符串表达式被 useFunction 正确包装；必要时传入 plainText=true。 +- 表单动作未触发 + - 确认 formAction 值为 'reset' | 'submit' | 'validate' | null，并在动作后重置 formAction。 +- 样式异常 + - 检查 elem_classes、elem_style 是否正确注入；Layout 组件需确保 component 参数匹配实际布局元素。 + +章节来源 + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +## 结论 + +ModelScope Studio 的 Ant Design Svelte 组件通过清晰的分层设计与强大的插槽/上下文系统，实现了对 Ant Design 组件的高保真封装。开发者可以以最小成本在 Svelte 中使用 Ant Design 的丰富能力，同时保持良好的可维护性与性能表现。建议在复杂场景中优先使用插槽与上下文，配合函数型属性包装与 useMemo 缓存，获得更优的开发体验与运行效率。 + +## 附录 + +- 组件清单（按模块分类） + - 通用组件：Button、Icon、Spin、Space、Typography 等。 + - 布局组件：Layout（Header/Footer/Content/Layout）、Grid（Row/Col）等。 + - 导航组件：Anchor、Breadcrumb、Dropdown、Menu、Pagination、Steps、Tabs、Tour 等。 + - 数据录入组件：AutoComplete、Cascader、Checkbox、ColorPicker、DatePicker、Mentions、Radio、Rate、Select、Slider、Switch、TimePicker、TreeSelect、Upload、Input/InputNumber/TextArea/Search/Password/OTP 等。 + - 数据展示组件：Avatar、Badge、Calendar、Card/Card.Grid/Card.Meta、Carousel、Descriptions、Divider、Empty、Image/Image.PreviewGroup、List/List.Item/List.Item.Meta、Masonry/Masonry.Item、Result、Statistical/Countdown/Timer、Table/Table.Column/Table.ColumnGroup/Table.Expandable/Table.RowSelection 等。 + - 反馈组件：Alert、Drawer、FloatButton/BackTop/Group、Modal/Static、Message、Notification、Popconfirm、Popover、Progress、QRCode、Result、Tour、Tooltip、Tour/Step、Tour/Step 等。 +- 与原生 Ant Design 的对应关系 + - 每个 Svelte 组件均通过 sveltify 包装对应的 Ant Design React 组件，属性与事件保持一致。 +- TypeScript 类型规范 + - 组件类型均基于 Ant Design 的 GetProps 类型别名扩展，确保类型安全。 +- 示例参考路径 + - 通用组件：[frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + - 表单组件：[frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) + - 布局组件：[frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) + - 数据展示组件：[frontend/antd/table/table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) + - 选择器组件：[frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\345\205\266\344\273\226\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\345\205\266\344\273\226\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..bc3fc9cd --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\345\205\266\344\273\226\347\273\204\344\273\266 API.md" @@ -0,0 +1,278 @@ +# 其他组件 API + + +**本文引用的文件** +- [frontend/antd/affix/Index.svelte](file://frontend/antd/affix/Index.svelte) +- [frontend/antd/affix/affix.tsx](file://frontend/antd/affix/affix.tsx) +- [frontend/antd/affix/package.json](file://frontend/antd/affix/package.json) +- [frontend/antd/config-provider/Index.svelte](file://frontend/antd/config-provider/Index.svelte) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) +- [frontend/antd/config-provider/package.json](file://frontend/antd/config-provider/package.json) +- [docs/components/antd/affix/README.md](file://docs/components/antd/affix/README.md) +- [docs/components/antd/config_provider/README.md](file://docs/components/antd/config_provider/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向 ModelScope Studio 的 Ant Design 特殊功能组件，系统性梳理 Affix（固定定位）与 ConfigProvider（全局配置）两大组件的 API、类型定义、上下文提供、主题与国际化机制、以及在组件系统中的集成方式。文档同时给出标准使用流程、典型场景与最佳实践，帮助开发者快速理解与正确使用。 + +## 项目结构 + +- 组件以 Svelte 包形式组织，每个组件目录包含： + - Index.svelte：Gradio/Svelte 包装层，负责属性透传、插槽渲染、可见性控制与延迟加载。 + - 组件实现文件（如 affix.tsx、config-provider.tsx）：基于 @svelte-preprocess-react 将 React 组件桥接为 Svelte 可用形态，并扩展必要的类型与行为。 + - package.json：导出入口，支持 Gradio 与默认两种模式。 +- 文档位于 docs/components/antd 下，提供示例与说明。 + +```mermaid +graph TB +subgraph "Ant Design 组件" +A["affix/Index.svelte"] +B["affix/affix.tsx"] +C["config-provider/Index.svelte"] +D["config-provider/config-provider.tsx"] +E["config-provider/locales.ts"] +end +A --> B +C --> D +D --> E +``` + +图表来源 + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) + +章节来源 + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/antd/affix/package.json:1-15](file://frontend/antd/affix/package.json#L1-L15) +- [frontend/antd/config-provider/package.json:1-15](file://frontend/antd/config-provider/package.json#L1-L15) +- [docs/components/antd/affix/README.md:1-9](file://docs/components/antd/affix/README.md#L1-L9) +- [docs/components/antd/config_provider/README.md:1-8](file://docs/components/antd/config_provider/README.md#L1-L8) + +## 核心组件 + +- Affix（固定定位） + - 职责：将子元素固定到视口或容器边界，常用于侧栏、回到顶部按钮等场景。 + - 关键点：通过 target 函数动态确定滚动容器；支持 visible 控制渲染；支持额外属性透传与插槽渲染。 +- ConfigProvider（全局配置） + - 职责：为 Ant Design 组件提供统一的全局配置，包括主题、语言、弹窗容器、空状态渲染等。 + - 关键点：支持主题算法开关（暗色/紧凑）、国际化语言切换、样式注入与容器函数回调；可作为上下文根节点使用。 + +章节来源 + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) + +## 架构总览 + +下图展示从 Svelte 包装层到 React 组件的调用链路，以及 ConfigProvider 的主题与国际化处理流程。 + +```mermaid +sequenceDiagram +participant UI as "页面/应用" +participant Wrap as "Svelte 包装层(Index.svelte)" +participant Impl as "组件实现(.tsx)" +participant AD as "Ant Design 组件库" +participant CSS as "样式注入(StyleProvider)" +UI->>Wrap : 渲染组件并传入属性/插槽 +Wrap->>Impl : 延迟导入并透传属性 +Impl->>AD : 实例化目标组件(如 Affix/ConfigProvider) +Impl->>CSS : 注入样式前缀与哈希策略 +AD-->>UI : 渲染结果 +``` + +图表来源 + +- [frontend/antd/affix/Index.svelte:55-68](file://frontend/antd/affix/Index.svelte#L55-L68) +- [frontend/antd/affix/affix.tsx:6-11](file://frontend/antd/affix/affix.tsx#L6-L11) +- [frontend/antd/config-provider/Index.svelte:54-71](file://frontend/antd/config-provider/Index.svelte#L54-L71) +- [frontend/antd/config-provider/config-provider.tsx:108-149](file://frontend/antd/config-provider/config-provider.tsx#L108-L149) + +## 详细组件分析 + +### Affix 固定定位组件 + +- 组件职责 + - 将子内容固定在视口或指定容器边界，随滚动变化显示/隐藏。 +- 属性与行为 + - 支持 target 容器函数，用于动态选择滚动容器。 + - 支持 visible 控制是否渲染。 + - 支持额外属性透传与插槽渲染。 +- 使用场景 + - 侧边工具栏、回到顶部按钮、悬浮操作区等。 +- 类型与实现要点 + - 通过 @svelte-preprocess-react 的 sveltify 将 Ant Design 的 Affix 桥接为 Svelte 组件。 + - target 通过 useFunction 包装，确保响应式更新。 +- 示例与文档 + - 文档提供基础与“容器滚动”两个示例，便于快速上手。 + +```mermaid +sequenceDiagram +participant P as "父组件" +participant W as "affix/Index.svelte" +participant T as "affix.tsx(Antd Affix)" +participant R as "React/Antd" +P->>W : 传入属性(含 target/visible/插槽) +W->>T : processProps 后透传 +T->>R : 使用 useFunction 包装 target 并渲染 +R-->>P : 固定定位后的 DOM 结果 +``` + +图表来源 + +- [frontend/antd/affix/Index.svelte:23-49](file://frontend/antd/affix/Index.svelte#L23-L49) +- [frontend/antd/affix/affix.tsx:6-11](file://frontend/antd/affix/affix.tsx#L6-L11) + +章节来源 + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [docs/components/antd/affix/README.md:1-9](file://docs/components/antd/affix/README.md#L1-L9) + +### ConfigProvider 全局配置组件 + +- 组件职责 + - 提供统一的全局配置，覆盖主题、语言、弹窗容器、空状态渲染等。 +- 主题与算法 + - theme.algorithm 支持自动识别：暗色/紧凑算法可按 themeMode 或显式配置启用。 +- 国际化 + - locale 支持多语言映射，根据浏览器语言或显式传入进行切换；同时设置 dayjs 的本地化。 +- 插槽与属性组合 + - 支持将插槽转换为属性树，实现复杂配置项的声明式传递。 +- 上下文与容器 + - 通过 setConfigType 标记为 antd 上下文，影响共享主题等行为。 + - 支持 getPopupContainer/getTargetContainer 自定义弹窗与挂载容器。 + +```mermaid +flowchart TD +Start(["进入 ConfigProvider"]) --> Locale["解析 locale
加载对应 Antd 与 dayjs 语言包"] +Locale --> Theme["合并 theme.algorithm
根据 themeMode 与 props 生成最终算法数组"] +Theme --> Slots["将插槽转换为属性树
支持 renderEmpty 等插槽函数化"] +Slots --> Style["注入样式前缀与哈希策略"] +Style --> Render["渲染子树"] +Render --> End(["完成"]) +``` + +图表来源 + +- [frontend/antd/config-provider/config-provider.tsx:85-105](file://frontend/antd/config-provider/config-provider.tsx#L85-L105) +- [frontend/antd/config-provider/config-provider.tsx:127-143](file://frontend/antd/config-provider/config-provider.tsx#L127-L143) +- [frontend/antd/config-provider/config-provider.tsx:29-49](file://frontend/antd/config-provider/config-provider.tsx#L29-L49) +- [frontend/antd/config-provider/locales.ts:15-27](file://frontend/antd/config-provider/locales.ts#L15-L27) + +章节来源 + +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [docs/components/antd/config_provider/README.md:1-8](file://docs/components/antd/config_provider/README.md#L1-L8) + +## 依赖分析 + +- 组件导出 + - 两者均通过 package.json 的 exports 字段提供 Gradio 与默认两种入口，便于在不同运行环境中使用。 +- 运行时依赖 + - ConfigProvider 依赖 antd 的 ConfigProvider、主题算法与样式注入；同时依赖 dayjs 与 locales 映射。 + - Affix 依赖 antd 的 Affix 与 useFunction 工具以包装回调函数。 +- 包装层耦合 + - 两组件均采用延迟导入与属性透传，降低初始加载压力，提升渲染可控性。 + +```mermaid +graph LR +PkgA["@modelscope-studio/antd-affix/package.json"] --> IA["affix/Index.svelte"] +PkgB["@modelscope-studio/antd-config-provider/package.json"] --> IC["config-provider/Index.svelte"] +IA --> TA["affix.tsx"] +IC --> TC["config-provider.tsx"] +TC --> L["locales.ts"] +``` + +图表来源 + +- [frontend/antd/affix/package.json:1-15](file://frontend/antd/affix/package.json#L1-L15) +- [frontend/antd/config-provider/package.json:1-15](file://frontend/antd/config-provider/package.json#L1-L15) +- [frontend/antd/affix/Index.svelte:10-13](file://frontend/antd/affix/Index.svelte#L10-L13) +- [frontend/antd/config-provider/Index.svelte:11-13](file://frontend/antd/config-provider/Index.svelte#L11-L13) + +章节来源 + +- [frontend/antd/affix/package.json:1-15](file://frontend/antd/affix/package.json#L1-L15) +- [frontend/antd/config-provider/package.json:1-15](file://frontend/antd/config-provider/package.json#L1-L15) + +## 性能考虑 + +- 延迟加载 + - 通过 importComponent 与 {#await} 模式按需加载组件实现，避免首屏阻塞。 +- 属性透传与派生计算 + - 使用 processProps 与 $derived 避免不必要的重渲染，仅在必要属性变化时更新。 +- 样式注入策略 + - 使用 StyleProvider 并设置高优先级哈希，减少样式冲突与重绘成本。 +- 回调函数包装 + - 使用 useFunction 包装 target/getPopupContainer 等回调，确保函数引用稳定，减少无效更新。 + +## 故障排查指南 + +- 固定定位不生效 + - 检查 target 是否返回正确的滚动容器；确认 visible 为 true 且容器存在滚动条。 + - 参考路径：[frontend/antd/affix/Index.svelte:47-49](file://frontend/antd/affix/Index.svelte#L47-L49)、[frontend/antd/affix/affix.tsx:7-10](file://frontend/antd/affix/affix.tsx#L7-L10) +- 弹窗/浮层位置异常 + - 检查 getPopupContainer 返回值是否指向正确容器；确认 ConfigProvider 的 getTargetContainer 设置。 + - 参考路径：[frontend/antd/config-provider/config-provider.tsx:93-95](file://frontend/antd/config-provider/config-provider.tsx#L93-L95) +- 主题未切换或算法未生效 + - 确认 themeMode 与 theme.algorithm 的组合；注意算法数组由多个算法函数组成。 + - 参考路径：[frontend/antd/config-provider/config-provider.tsx:88-91](file://frontend/antd/config-provider/config-provider.tsx#L88-L91)、[frontend/antd/config-provider/config-provider.tsx:127-143](file://frontend/antd/config-provider/config-provider.tsx#L127-L143) +- 国际化语言未生效 + - 检查 locale 参数格式与 locales 映射；确认 dayjs 语言已同步设置。 + - 参考路径：[frontend/antd/config-provider/config-provider.tsx:85-105](file://frontend/antd/config-provider/config-provider.tsx#L85-L105)、[frontend/antd/config-provider/locales.ts:15-27](file://frontend/antd/config-provider/locales.ts#L15-L27) + +章节来源 + +- [frontend/antd/affix/Index.svelte:47-49](file://frontend/antd/affix/Index.svelte#L47-L49) +- [frontend/antd/affix/affix.tsx:7-10](file://frontend/antd/affix/affix.tsx#L7-L10) +- [frontend/antd/config-provider/config-provider.tsx:85-105](file://frontend/antd/config-provider/config-provider.tsx#L85-L105) +- [frontend/antd/config-provider/config-provider.tsx:88-91](file://frontend/antd/config-provider/config-provider.tsx#L88-L91) +- [frontend/antd/config-provider/config-provider.tsx:127-143](file://frontend/antd/config-provider/config-provider.tsx#L127-L143) +- [frontend/antd/config-provider/locales.ts:15-27](file://frontend/antd/config-provider/locales.ts#L15-L27) + +## 结论 + +- Affix 与 ConfigProvider 在 ModelScope Studio 中通过统一的 Svelte 包装层与 @svelte-preprocess-react 桥接，实现了与 Ant Design 组件库的无缝集成。 +- ConfigProvider 提供了强大的全局配置能力，涵盖主题、国际化与容器策略；Affix 则专注于固定定位场景，具备良好的可配置性与性能表现。 +- 建议在应用根部放置 ConfigProvider 以统一风格与语言；对需要固定定位的区域使用 Affix，并合理设置 target 与 visible。 + +## 附录 + +- 示例与演示 + - Affix 示例：基础、容器滚动 + - ConfigProvider 示例：基础 +- 参考文档 + - Ant Design 官方 Affix 与 ConfigProvider 文档链接见各组件 README + +章节来源 + +- [docs/components/antd/affix/README.md:1-9](file://docs/components/antd/affix/README.md#L1-L9) +- [docs/components/antd/config_provider/README.md:1-8](file://docs/components/antd/config_provider/README.md#L1-L8) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\345\217\215\351\246\210\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\345\217\215\351\246\210\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..8c32043a --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\345\217\215\351\246\210\347\273\204\344\273\266 API.md" @@ -0,0 +1,383 @@ +# 反馈组件 API + + +**本文引用的文件** +- [frontend/antd/alert/alert.tsx](file://frontend/antd/alert/alert.tsx) +- [frontend/antd/drawer/drawer.tsx](file://frontend/antd/drawer/drawer.tsx) +- [frontend/antd/message/message.tsx](file://frontend/antd/message/message.tsx) +- [frontend/antd/modal/modal.tsx](file://frontend/antd/modal/modal.tsx) +- [frontend/antd/notification/notification.tsx](file://frontend/antd/notification/notification.tsx) +- [frontend/antd/popconfirm/popconfirm.tsx](file://frontend/antd/popconfirm/popconfirm.tsx) +- [frontend/antd/progress/progress.tsx](file://frontend/antd/progress/progress.tsx) +- [frontend/antd/result/result.tsx](file://frontend/antd/result/result.tsx) +- [frontend/antd/skeleton/skeleton.tsx](file://frontend/antd/skeleton/skeleton.tsx) +- [frontend/antd/spin/spin.tsx](file://frontend/antd/spin/spin.tsx) +- [frontend/antd/watermark/watermark.tsx](file://frontend/antd/watermark/watermark.tsx) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [docs/components/antd/alert/README.md](file://docs/components/antd/alert/README.md) +- [docs/components/antd/drawer/README.md](file://docs/components/antd/drawer/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 中基于 Ant Design 的反馈类组件 API 参考文档，覆盖以下组件：Alert（警告提示）、Drawer（抽屉面板）、Message（全局消息）、Modal（对话框）、Notification（通知提醒）、Popconfirm（气泡确认）、Progress（进度条）、Result（结果页）、Skeleton（骨架屏）、Spin（加载中）、Watermark（水印）。内容包括： + +- 属性定义与类型约束 +- 状态管理与生命周期 +- 动画与交互逻辑 +- 标准实例化与配置示例路径 +- 事件回调与异步处理 +- 无障碍与用户体验设计原则 + +## 项目结构 + +反馈组件在前端以 Svelte 包装器形式桥接 Ant Design React 组件，并通过后端 Python 模块统一导出，便于在应用中按需引入。 + +```mermaid +graph TB +subgraph "前端" +A1["alert.tsx"] +A2["drawer.tsx"] +A3["message.tsx"] +A4["modal.tsx"] +A5["notification.tsx"] +A6["popconfirm.tsx"] +A7["progress.tsx"] +A8["result.tsx"] +A9["skeleton.tsx"] +A10["spin.tsx"] +A11["watermark.tsx"] +end +subgraph "后端" +B1["__init__.py"] +B2["components.py"] +end +A1 --> B1 +A2 --> B1 +A3 --> B1 +A4 --> B1 +A5 --> B1 +A6 --> B1 +A7 --> B1 +A8 --> B1 +A9 --> B1 +A10 --> B1 +A11 --> B1 +B1 --> B2 +``` + +图表来源 + +- [frontend/antd/alert/alert.tsx:1-46](file://frontend/antd/alert/alert.tsx#L1-L46) +- [frontend/antd/drawer/drawer.tsx:1-60](file://frontend/antd/drawer/drawer.tsx#L1-L60) +- [frontend/antd/message/message.tsx:1-79](file://frontend/antd/message/message.tsx#L1-L79) +- [frontend/antd/modal/modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) +- [frontend/antd/notification/notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [frontend/antd/popconfirm/popconfirm.tsx:1-65](file://frontend/antd/popconfirm/popconfirm.tsx#L1-L65) +- [frontend/antd/progress/progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [frontend/antd/result/result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- [frontend/antd/watermark/watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +章节来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +## 核心组件 + +- Alert：用于展示需要用户关注的警告信息，支持描述、图标、可关闭、操作按钮等插槽扩展。 +- Drawer：从屏幕边缘滑出的抽屉面板，支持标题、页脚、额外操作、渲染钩子等。 +- Message：全局提示消息，支持可见性控制、自定义内容与图标、销毁与打开。 +- Modal：模态对话框，支持标题、页脚、按钮图标、渲染钩子、容器挂载等。 +- Notification：全局通知提醒，支持位置、动作、关闭图标、描述、消息等。 +- Popconfirm：气泡确认，支持确认/取消文案与图标、弹层容器。 +- Progress：进度条，支持格式化与取整函数。 +- Result：结果页，支持标题、副标题、图标、额外操作等。 +- Skeleton：骨架屏占位。 +- Spin：加载中，支持提示文本与指示器插槽。 +- Watermark：水印。 + +章节来源 + +- [frontend/antd/alert/alert.tsx:1-46](file://frontend/antd/alert/alert.tsx#L1-L46) +- [frontend/antd/drawer/drawer.tsx:1-60](file://frontend/antd/drawer/drawer.tsx#L1-L60) +- [frontend/antd/message/message.tsx:1-79](file://frontend/antd/message/message.tsx#L1-L79) +- [frontend/antd/modal/modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) +- [frontend/antd/notification/notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [frontend/antd/popconfirm/popconfirm.tsx:1-65](file://frontend/antd/popconfirm/popconfirm.tsx#L1-L65) +- [frontend/antd/progress/progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [frontend/antd/result/result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- [frontend/antd/watermark/watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) + +## 架构总览 + +反馈组件采用“Svelte 包装器 + Ant Design React 组件 + 后端统一导出”的分层架构： + +- 前端层：每个组件以 sveltify 包装 Ant Design 组件，支持 slots 插槽与函数回调转换。 +- 交互层：通过 useFunction/useTargets 等工具实现回调与子节点的桥接。 +- 导出层：Python 模块集中导出各组件，便于在应用中统一引用。 + +```mermaid +sequenceDiagram +participant App as "应用" +participant Wrapper as "Svelte 包装器" +participant AD as "Ant Design 组件" +participant Util as "工具钩子" +App->>Wrapper : 传入 props 与 slots +Wrapper->>Util : useFunction()/useTargets() +Util-->>Wrapper : 转换后的回调/目标节点 +Wrapper->>AD : 渲染并传递 props/slots +AD-->>App : 触发事件回调/状态变化 +``` + +图表来源 + +- [frontend/antd/alert/alert.tsx:12-43](file://frontend/antd/alert/alert.tsx#L12-L43) +- [frontend/antd/drawer/drawer.tsx:24-57](file://frontend/antd/drawer/drawer.tsx#L24-L57) +- [frontend/antd/message/message.tsx:18-76](file://frontend/antd/message/message.tsx#L18-L76) +- [frontend/antd/modal/modal.tsx:22-104](file://frontend/antd/modal/modal.tsx#L22-L104) +- [frontend/antd/notification/notification.tsx:17-103](file://frontend/antd/notification/notification.tsx#L17-L103) + +## 详细组件分析 + +### Alert（警告提示） + +- 关键能力 + - 支持 message、description、icon、action、closable.closeIcon 等插槽 + - afterClose 回调通过 useFunction 转换 +- 生命周期 + - 组件挂载后根据 props 渲染；关闭后触发 afterClose +- 交互与动画 + - 由 Ant Design 内置动画与过渡控制 +- 示例路径 + - [docs/components/antd/alert/README.md:1-8](file://docs/components/antd/alert/README.md#L1-L8) + +章节来源 + +- [frontend/antd/alert/alert.tsx:7-43](file://frontend/antd/alert/alert.tsx#L7-L43) + +### Drawer（抽屉面板） + +- 关键能力 + - 支持 title、footer、extra、closeIcon、closable.closeIcon、drawerRender 等插槽 + - afterOpenChange、getContainer、drawerRender 通过 useFunction/renderParamsSlot 处理 +- 生命周期 + - 打开/关闭状态变更时触发 afterOpenChange +- 交互与动画 + - Ant Design 抽屉滑入滑出动画 +- 示例路径 + - [docs/components/antd/drawer/README.md:1-9](file://docs/components/antd/drawer/README.md#L1-L9) + +章节来源 + +- [frontend/antd/drawer/drawer.tsx:8-57](file://frontend/antd/drawer/drawer.tsx#L8-L57) + +### Message（全局消息） + +- 关键能力 + - 通过 message.useMessage 获取 API + - 支持 visible 控制显示/隐藏，onVisible 回调 + - content、icon 插槽支持自定义 + - getContainer 函数化处理 +- 生命周期 + - visible=true 时 open，visible=false 或卸载时 destroy +- 异步与事件 + - onClose 同时触发 onVisible(false) 与原 onClose +- 示例路径 + - 参见各组件 README 的 demo 示例 + +章节来源 + +- [frontend/antd/message/message.tsx:9-76](file://frontend/antd/message/message.tsx#L9-L76) + +### Modal（对话框） + +- 关键能力 + - 支持 okText、okButtonProps.icon、cancelText、cancelButtonProps.icon、footer、title、modalRender、closable.closeIcon、closeIcon 等 + - afterOpenChange、afterClose、getContainer、footer、modalRender 通过 useFunction/renderParamsSlot 处理 +- 生命周期 + - 打开/关闭状态变更触发 afterOpenChange/afterClose +- 交互与动画 + - Ant Design 对话框开合动画与遮罩层行为 + +章节来源 + +- [frontend/antd/modal/modal.tsx:8-104](file://frontend/antd/modal/modal.tsx#L8-L104) + +### Notification（通知提醒） + +- 关键能力 + - 通过 notification.useNotification 获取 API + - 支持 visible 控制显示/隐藏，onVisible 回调 + - 支持 btn、actions、closeIcon、description、icon、message 插槽 + - 位置参数：top、bottom、rtl、stack +- 生命周期 + - visible=true 时 open，visible=false 或卸载时 destroy +- 异步与事件 + - onClose 同时触发 onVisible(false) 与原 onClose + +章节来源 + +- [frontend/antd/notification/notification.tsx:8-103](file://frontend/antd/notification/notification.tsx#L8-L103) + +### Popconfirm（气泡确认） + +- 关键能力 + - 支持 okText、okButtonProps.icon、cancelText、cancelButtonProps.icon、title、description + - afterOpenChange、getPopupContainer 通过 useFunction 处理 +- 生命周期 + - 弹层打开/关闭时触发 afterOpenChange +- 交互与动画 + - Ant Design 气泡确认弹层行为 + +章节来源 + +- [frontend/antd/popconfirm/popconfirm.tsx:7-62](file://frontend/antd/popconfirm/popconfirm.tsx#L7-L62) + +### Progress（进度条） + +- 关键能力 + - 支持 format、rounding 函数化处理 +- 性能与复杂度 + - 纯展示组件，无复杂计算 + +章节来源 + +- [frontend/antd/progress/progress.tsx:5-21](file://frontend/antd/progress/progress.tsx#L5-L21) + +### Result（结果页） + +- 关键能力 + - 支持 title、subTitle、icon、extra 插槽 + - 使用 useTargets 管理子节点渲染策略 +- 生命周期 + - 有插槽时渲染子节点，否则隐藏默认 children + +章节来源 + +- [frontend/antd/result/result.tsx:7-30](file://frontend/antd/result/result.tsx#L7-L30) + +### Skeleton（骨架屏） + +- 关键能力 + - 直接包装 Ant Design Skeleton +- 使用建议 + - 用于数据加载前的占位展示 + +章节来源 + +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) + +### Spin（加载中） + +- 关键能力 + - 支持 tip、indicator 插槽 + - 使用 useTargets 控制子节点显示/隐藏 +- 生命周期 + - 无插槽时显示 children，有插槽时隐藏 children 并交由 Spin 渲染 + +章节来源 + +- [frontend/antd/spin/spin.tsx:7-35](file://frontend/antd/spin/spin.tsx#L7-L35) + +### Watermark（水印） + +- 关键能力 + - 直接包装 Ant Design Watermark +- 使用建议 + - 用于内容保护与版权标识 + +章节来源 + +- [frontend/antd/watermark/watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) + +## 依赖关系分析 + +- 统一导出 + - 后端模块集中导出各组件，便于应用侧统一导入与别名管理 +- 组件间耦合 + - 各组件相对独立，主要通过 Ant Design 生态与通用工具钩子协作 + +```mermaid +graph LR +Init["__init__.py"] --> Comp["components.py"] +Init --> |导出| C1["Alert"] +Init --> |导出| C2["Drawer"] +Init --> |导出| C3["Message"] +Init --> |导出| C4["Modal"] +Init --> |导出| C5["Notification"] +Init --> |导出| C6["Popconfirm"] +Init --> |导出| C7["Progress"] +Init --> |导出| C8["Result"] +Init --> |导出| C9["Skeleton"] +Init --> |导出| C10["Spin"] +Init --> |导出| C11["Watermark"] +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +章节来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +## 性能考量 + +- 插槽与函数转换 + - 使用 useFunction 将回调函数桥接到 React 环境，避免重复创建导致的重渲染 +- 条件渲染 + - Result/Spin 通过 useTargets 精准控制子节点渲染，减少不必要的 DOM 结构 +- 销毁与清理 + - Message/Notification 在卸载或 visible=false 时主动 destroy，避免内存泄漏与重复提示 + +## 故障排查指南 + +- 插槽未生效 + - 确认插槽名称与组件定义一致（如 closable.closeIcon、okButtonProps.icon 等） +- 回调不触发 + - 检查是否通过 useFunction 包装回调，确保函数签名与 Ant Design 期望一致 +- 容器挂载问题 + - getContainer 支持字符串选择器或函数，若传入字符串则内部会转为函数处理 +- 通知/消息未消失 + - 确保 visible=false 或组件卸载时触发 destroy；检查 onClose 回调链路 + +章节来源 + +- [frontend/antd/alert/alert.tsx:12-43](file://frontend/antd/alert/alert.tsx#L12-L43) +- [frontend/antd/drawer/drawer.tsx:24-57](file://frontend/antd/drawer/drawer.tsx#L24-L57) +- [frontend/antd/message/message.tsx:35-68](file://frontend/antd/message/message.tsx#L35-L68) +- [frontend/antd/notification/notification.tsx:38-95](file://frontend/antd/notification/notification.tsx#L38-L95) + +## 结论 + +ModelScope Studio 的反馈组件通过统一的 Svelte 包装器与工具钩子，实现了对 Ant Design 组件的灵活扩展与一致化使用体验。开发者可通过插槽与函数化回调快速定制交互与视觉表现，同时借助后端统一导出简化模块管理。建议在实际业务中结合加载策略、可见性控制与无障碍要求，合理使用各反馈组件以提升用户体验。 + +## 附录 + +- 示例与演示 + - 参考各组件 README 的 demo 示例进行快速上手 + - [docs/components/antd/alert/README.md:1-8](file://docs/components/antd/alert/README.md#L1-L8) + - [docs/components/antd/drawer/README.md:1-9](file://docs/components/antd/drawer/README.md#L1-L9) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\345\257\274\350\210\252\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\345\257\274\350\210\252\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..7a2eea8b --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\345\257\274\350\210\252\347\273\204\344\273\266 API.md" @@ -0,0 +1,462 @@ +# 导航组件 API + + +**本文引用的文件** +- [frontend/antd/anchor/Index.svelte](file://frontend/antd/anchor/Index.svelte) +- [frontend/antd/anchor/anchor.tsx](file://frontend/antd/anchor/anchor.tsx) +- [frontend/antd/anchor/context.ts](file://frontend/antd/anchor/context.ts) +- [frontend/antd/breadcrumb/Index.svelte](file://frontend/antd/breadcrumb/Index.svelte) +- [frontend/antd/breadcrumb/breadcrumb.tsx](file://frontend/antd/breadcrumb/breadcrumb.tsx) +- [frontend/antd/breadcrumb/context.ts](file://frontend/antd/breadcrumb/context.ts) +- [frontend/antd/breadcrumb/item/Index.svelte](file://frontend/antd/breadcrumb/item/Index.svelte) +- [frontend/antd/dropdown/Index.svelte](file://frontend/antd/dropdown/Index.svelte) +- [frontend/antd/dropdown/dropdown.tsx](file://frontend/antd/dropdown/dropdown.tsx) +- [frontend/antd/menu/Index.svelte](file://frontend/antd/menu/Index.svelte) +- [frontend/antd/menu/menu.tsx](file://frontend/antd/menu/menu.tsx) +- [frontend/antd/menu/context.ts](file://frontend/antd/menu/context.ts) +- [frontend/antd/menu/item/Index.svelte](file://frontend/antd/menu/item/Index.svelte) +- [frontend/antd/pagination/Index.svelte](file://frontend/antd/pagination/Index.svelte) +- [frontend/antd/pagination/pagination.tsx](file://frontend/antd/pagination/pagination.tsx) +- [frontend/antd/steps/Index.svelte](file://frontend/antd/steps/Index.svelte) +- [frontend/antd/steps/steps.tsx](file://frontend/antd/steps/steps.tsx) +- [frontend/antd/steps/context.ts](file://frontend/antd/steps/context.ts) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 中基于 Ant Design 的导航类组件 API 参考文档，覆盖以下组件：Anchor（锚点）、Breadcrumb（面包屑）、Dropdown（下拉菜单）、Menu（菜单）、Pagination（分页）、Steps（步骤条）。文档从架构设计、数据流、处理逻辑、类型定义、事件绑定、路由集成、权限控制与动态加载等方面进行系统性梳理，并提供可复用的使用范式与最佳实践。 + +## 项目结构 + +导航组件在前端采用统一的“Svelte 包装层 + React 组件桥接”的模式： + +- Svelte 层负责属性透传、可见性控制、样式注入、插槽渲染与延迟加载。 +- React 层通过 sveltify 将 Ant Design 原生组件桥接到 Svelte 生态，同时提供插槽渲染、函数钩子与上下文注入能力。 + +```mermaid +graph TB +subgraph "Svelte 包装层" +A_Index["anchor/Index.svelte"] +B_Index["breadcrumb/Index.svelte"] +C_Index["dropdown/Index.svelte"] +D_Index["menu/Index.svelte"] +E_Index["pagination/Index.svelte"] +F_Index["steps/Index.svelte"] +end +subgraph "React 桥接层" +A_Core["anchor.tsx"] +B_Core["breadcrumb.tsx"] +C_Core["dropdown.tsx"] +D_Core["menu.tsx"] +E_Core["pagination.tsx"] +F_Core["steps.tsx"] +end +A_Index --> A_Core +B_Index --> B_Core +C_Index --> C_Core +D_Index --> D_Core +E_Index --> E_Core +F_Index --> F_Core +``` + +图表来源 + +- [frontend/antd/anchor/Index.svelte:1-66](file://frontend/antd/anchor/Index.svelte#L1-L66) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/dropdown/Index.svelte:1-70](file://frontend/antd/dropdown/Index.svelte#L1-L70) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/Index.svelte:1-75](file://frontend/antd/menu/Index.svelte#L1-L75) +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/pagination/Index.svelte:1-68](file://frontend/antd/pagination/Index.svelte#L1-L68) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [frontend/antd/steps/Index.svelte:1-63](file://frontend/antd/steps/Index.svelte#L1-L63) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) + +章节来源 + +- [frontend/antd/anchor/Index.svelte:1-66](file://frontend/antd/anchor/Index.svelte#L1-L66) +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/dropdown/Index.svelte:1-70](file://frontend/antd/dropdown/Index.svelte#L1-L70) +- [frontend/antd/menu/Index.svelte:1-75](file://frontend/antd/menu/Index.svelte#L1-L75) +- [frontend/antd/pagination/Index.svelte:1-68](file://frontend/antd/pagination/Index.svelte#L1-L68) +- [frontend/antd/steps/Index.svelte:1-63](file://frontend/antd/steps/Index.svelte#L1-L63) + +## 核心组件 + +本节概述六个导航组件的职责与通用特性： + +- Anchor：用于页面内锚点跳转与滚动定位，支持容器选择与当前锚点回调。 +- Breadcrumb：展示当前页面在层级结构中的位置，支持自定义分隔符、项渲染与下拉图标。 +- Dropdown：包裹触发元素并渲染下拉菜单，支持自定义弹出渲染与菜单项注入。 +- Menu：侧边或顶部导航菜单，支持主题、展开图标、溢出指示器与选择/展开事件。 +- Pagination：数据分页控件，支持快速跳转按钮与页码渲染自定义。 +- Steps：步骤流程指示器，支持步骤项列表与进度点自定义渲染。 + +章节来源 + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) + +## 架构总览 + +组件桥接采用“延迟加载 + 插槽渲染 + 函数钩子”的统一模式： + +- 属性透传：包装层将 visible、elem_id、elem_classes、elem_style、\_internal、as_item 等通用属性透传给 React 组件。 +- 插槽渲染：通过 ReactSlot 与 renderParamsSlot 支持 slot 名称映射与参数化渲染。 +- 动态注入：通过 withItemsContextProvider 注入 items 列表，支持默认插槽与显式 items 参数。 +- 事件绑定：onOpenChange、onSelect、onDeselect、onChange 等事件通过 useFunction 钩子确保响应式更新。 + +```mermaid +sequenceDiagram +participant S as "Svelte 包装层(Index.svelte)" +participant P as "属性处理器(processProps)" +participant R as "React 组件(sveltify)" +participant C as "上下文/插槽(Items/Slots)" +S->>P : 解析组件属性与附加属性 +P-->>S : 返回标准化属性集 +S->>R : 渲染 Antd 组件并传递属性 +R->>C : 读取 items 上下文与 slots +C-->>R : 提供 items 列表与插槽函数 +R-->>S : 触发事件回调(onChange/onSelect等) +S-->>S : 通过 Gradio/路由回调处理结果 +``` + +图表来源 + +- [frontend/antd/anchor/Index.svelte:22-44](file://frontend/antd/anchor/Index.svelte#L22-L44) +- [frontend/antd/anchor/anchor.tsx:10-43](file://frontend/antd/anchor/anchor.tsx#L10-L43) +- [frontend/antd/breadcrumb/breadcrumb.tsx:15-63](file://frontend/antd/breadcrumb/breadcrumb.tsx#L15-L63) +- [frontend/antd/dropdown/dropdown.tsx:26-108](file://frontend/antd/dropdown/dropdown.tsx#L26-L108) +- [frontend/antd/menu/menu.tsx:18-92](file://frontend/antd/menu/menu.tsx#L18-L92) +- [frontend/antd/pagination/pagination.tsx:14-52](file://frontend/antd/pagination/pagination.tsx#L14-L52) +- [frontend/antd/steps/steps.tsx:16-49](file://frontend/antd/steps/steps.tsx#L16-L49) + +## 详细组件分析 + +### Anchor（锚点） + +- 职责：提供页面内锚点导航，支持容器选择与当前锚点回调。 +- 关键属性与行为 + - 容器选择：getContainer 用于指定滚动容器。 + - 当前锚点：getCurrentAnchor 用于获取当前激活锚点。 + - items 注入：通过上下文注入 items，支持默认插槽与显式 items。 +- 事件与状态 + - 无显式事件回调；通过回调函数实现滚动定位与高亮同步。 +- 使用要点 + - 在长页面中配合锚点项使用，确保容器正确设置。 + - 通过插槽渲染自定义锚点标题。 + +```mermaid +flowchart TD +Start(["进入 Anchor"]) --> Items["解析 items 上下文"] +Items --> Render["渲染 Antd Anchor"] +Render --> Events{"滚动/点击事件"} +Events --> |定位| SetActive["设置当前锚点"] +Events --> |切换| Callback["执行回调函数"] +SetActive --> End(["完成"]) +Callback --> End +``` + +图表来源 + +- [frontend/antd/anchor/anchor.tsx:10-43](file://frontend/antd/anchor/anchor.tsx#L10-L43) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) + +章节来源 + +- [frontend/antd/anchor/Index.svelte:1-66](file://frontend/antd/anchor/Index.svelte#L1-L66) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) + +### Breadcrumb（面包屑） + +- 职责：显示当前页面在层级结构中的路径，支持自定义分隔符、项渲染与下拉图标。 +- 关键属性与行为 + - 分隔符：separator 支持插槽与函数。 + - 项渲染：itemRender 支持插槽与函数。 + - 下拉图标：dropdownIcon 支持插槽。 + - items 注入：支持 default 与 items 插槽。 +- 事件与状态 + - 通过 props 与 slots 控制渲染；无直接事件回调。 +- 使用要点 + - 结合路由系统生成层级结构，必要时使用 itemRender 自定义链接样式。 + +```mermaid +sequenceDiagram +participant B as "Breadcrumb" +participant S as "Slots" +participant I as "Items 上下文" +B->>I : 读取 items/default +B->>S : 渲染 separator/itemRender/dropdownIcon +B-->>B : 渲染 Antd Breadcrumb +``` + +图表来源 + +- [frontend/antd/breadcrumb/breadcrumb.tsx:15-63](file://frontend/antd/breadcrumb/breadcrumb.tsx#L15-L63) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) + +章节来源 + +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) +- [frontend/antd/breadcrumb/item/Index.svelte:1-72](file://frontend/antd/breadcrumb/item/Index.svelte#L1-L72) + +### Dropdown（下拉菜单） + +- 职责：包裹触发元素并渲染下拉菜单，支持自定义弹出渲染与菜单项注入。 +- 关键属性与行为 + - 弹出容器：getPopupContainer。 + - 下拉渲染：dropdownRender、popupRender 支持插槽与函数。 + - 菜单扩展图标：menu.expandIcon 支持插槽。 + - 溢出指示器：menu.overflowedIndicator 支持插槽。 + - 菜单项注入：通过菜单上下文注入 items。 +- 事件与状态 + - 通过 props 与 slots 控制渲染；无直接事件回调。 +- 使用要点 + - 将触发元素置于组件内部，避免样式被遮挡。 + - 通过插槽实现复杂下拉面板布局。 + +```mermaid +classDiagram +class Dropdown { ++props : GetProps ++slots : dropdownRender,popupRender,menu.expandIcon,menu.overflowedIndicator ++getPopupContainer() ++render() +} +class MenuItems { ++items : ItemType[] ++expandIcon() ++overflowedIndicator() +} +Dropdown --> MenuItems : "注入菜单项" +``` + +图表来源 + +- [frontend/antd/dropdown/dropdown.tsx:15-108](file://frontend/antd/dropdown/dropdown.tsx#L15-L108) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) + +章节来源 + +- [frontend/antd/dropdown/Index.svelte:1-70](file://frontend/antd/dropdown/Index.svelte#L1-L70) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) + +### Menu（菜单） + +- 职责：侧边或顶部导航菜单，支持主题、展开图标、溢出指示器与选择/展开事件。 +- 关键属性与行为 + - 主题：theme 支持外部传入。 + - 展开图标：expandIcon 支持插槽。 + - 溢出指示器：overflowedIndicator 支持插槽。 + - 弹出渲染：popupRender 支持插槽。 + - 事件：onOpenChange、onSelect、onDeselect。 + - items 注入：支持 default 与 items 插槽。 +- 事件与状态 + - 通过 onOpenChange、onSelect、onDeselect 实现状态管理与路由联动。 +- 使用要点 + - 与路由库结合时，onSelect 中处理路由跳转与选中态同步。 + +```mermaid +sequenceDiagram +participant M as "Menu" +participant E as "事件回调" +participant R as "路由/Gradio" +M->>E : onSelect/onDeselect/onOpenChange +E->>R : 更新路由/状态 +R-->>M : 同步选中态/展开态 +``` + +图表来源 + +- [frontend/antd/menu/menu.tsx:18-92](file://frontend/antd/menu/menu.tsx#L18-L92) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) + +章节来源 + +- [frontend/antd/menu/Index.svelte:1-75](file://frontend/antd/menu/Index.svelte#L1-L75) +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [frontend/antd/menu/item/Index.svelte:1-84](file://frontend/antd/menu/item/Index.svelte#L1-L84) + +### Pagination（分页） + +- 职责：数据分页控件，支持快速跳转按钮与页码渲染自定义。 +- 关键属性与行为 + - 快速跳转：showQuickJumper 支持插槽 goButton。 + - 总数显示：showTotal 支持函数。 + - 页码渲染：itemRender 支持插槽与函数。 + - 事件：onChange(page, pageSize)。 +- 事件与状态 + - onChange 中处理分页逻辑与数据刷新。 +- 使用要点 + - 与后端分页接口对接时，注意 page/pageSize 的转换与边界处理。 + +```mermaid +flowchart TD +Start(["用户操作"]) --> Jump["点击页码/快速跳转"] +Jump --> Call["调用 onChange(page,pageSize)"] +Call --> Fetch["请求新页数据"] +Fetch --> Update["更新列表与总数"] +Update --> End(["完成"]) +``` + +图表来源 + +- [frontend/antd/pagination/pagination.tsx:14-52](file://frontend/antd/pagination/pagination.tsx#L14-L52) + +章节来源 + +- [frontend/antd/pagination/Index.svelte:1-68](file://frontend/antd/pagination/Index.svelte#L1-L68) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) + +### Steps（步骤条） + +- 职责：步骤流程指示器，支持步骤项列表与进度点自定义渲染。 +- 关键属性与行为 + - 步骤项：items 注入，支持 default 与 items 插槽。 + - 进度点：progressDot 支持插槽与函数。 + - 事件：通过回调函数实现步骤切换。 +- 事件与状态 + - 无直接事件回调；通过函数钩子实现步骤状态管理。 +- 使用要点 + - 与表单向导结合时，根据当前步骤控制下一步可用性。 + +```mermaid +sequenceDiagram +participant S as "Steps" +participant P as "progressDot 插槽" +participant I as "items 上下文" +S->>I : 读取 items/default +S->>P : 渲染进度点 +S-->>S : 渲染 Antd Steps +``` + +图表来源 + +- [frontend/antd/steps/steps.tsx:16-49](file://frontend/antd/steps/steps.tsx#L16-L49) +- [frontend/antd/steps/context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) + +章节来源 + +- [frontend/antd/steps/Index.svelte:1-63](file://frontend/antd/steps/Index.svelte#L1-L63) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/steps/context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) + +## 依赖关系分析 + +- 组件间耦合 + - Dropdown 依赖 Menu 的上下文注入，实现菜单项的统一管理。 + - 所有带 items 的组件均依赖 createItemsContext 提供的上下文与渲染工具。 +- 外部依赖 + - Ant Design 原生组件作为渲染基础。 + - @svelte-preprocess-react 提供 sveltify、ReactSlot、renderItems、renderParamsSlot 等工具。 +- 潜在循环依赖 + - 通过上下文注入避免直接循环导入；各组件独立维护自身上下文。 + +```mermaid +graph LR +Ctx["createItemsContext"] --> A["Anchor Items"] +Ctx --> B["Breadcrumb Items"] +Ctx --> M["Menu Items"] +Ctx --> S["Steps Items"] +D["Dropdown"] --> M +A --> Antd["Antd Anchor"] +B --> Antd2["Antd Breadcrumb"] +D --> Antd3["Antd Dropdown"] +M --> Antd4["Antd Menu"] +P["Pagination"] --> Antd5["Antd Pagination"] +S --> Antd6["Antd Steps"] +``` + +图表来源 + +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [frontend/antd/steps/context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) +- [frontend/antd/dropdown/dropdown.tsx:10-13](file://frontend/antd/dropdown/dropdown.tsx#L10-L13) + +章节来源 + +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [frontend/antd/steps/context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) +- [frontend/antd/dropdown/dropdown.tsx:10-13](file://frontend/antd/dropdown/dropdown.tsx#L10-L13) + +## 性能考量 + +- 延迟加载：Svelte 包装层对 React 组件采用延迟加载，减少首屏负担。 +- 计算缓存：React 层使用 useMemo 对 items 进行稳定化处理，避免不必要的重渲染。 +- 插槽克隆：插槽渲染默认启用克隆以保证独立性，但需注意克隆成本。 +- 事件钩子：useFunction 钩子确保回调函数稳定，避免因函数引用变化导致的重渲染。 + +## 故障排查指南 + +- 事件未触发 + - 检查是否正确传入 onOpenChange/onSelect/onDeselect/onChange 等回调。 + - 确认回调函数通过 useFunction 钩子包裹。 +- 插槽不生效 + - 确认插槽名称与映射一致（如 menu.expandIcon、itemRender 等）。 + - 检查插槽是否启用克隆（clone: true）。 +- items 不显示 + - 确认已通过上下文注入 items 或显式传入 items。 + - 检查默认插槽与 items 插槽的优先级与命名。 +- 样式冲突 + - 检查 elem_id/elem_classes 是否与全局样式冲突。 + - 确认组件样式类名前缀 ms-gr-antd-\* 未被覆盖。 + +章节来源 + +- [frontend/antd/anchor/anchor.tsx:10-43](file://frontend/antd/anchor/anchor.tsx#L10-L43) +- [frontend/antd/breadcrumb/breadcrumb.tsx:15-63](file://frontend/antd/breadcrumb/breadcrumb.tsx#L15-L63) +- [frontend/antd/dropdown/dropdown.tsx:26-108](file://frontend/antd/dropdown/dropdown.tsx#L26-L108) +- [frontend/antd/menu/menu.tsx:18-92](file://frontend/antd/menu/menu.tsx#L18-L92) +- [frontend/antd/pagination/pagination.tsx:14-52](file://frontend/antd/pagination/pagination.tsx#L14-L52) +- [frontend/antd/steps/steps.tsx:16-49](file://frontend/antd/steps/steps.tsx#L16-L49) + +## 结论 + +ModelScope Studio 的导航组件通过统一的 Svelte 包装层与 React 桥接层，实现了 Ant Design 组件在前端生态中的无缝集成。其设计强调： + +- 易用性：统一的属性透传与插槽映射。 +- 可扩展性：上下文注入与函数钩子提升灵活性。 +- 可维护性：清晰的职责划分与依赖关系。 + +建议在实际项目中结合路由系统与权限体系，将事件回调与状态管理规范化，以获得更佳的用户体验与开发效率。 + +## 附录 + +- 路由集成建议 + - Menu/Pagination/Steps 的回调中统一处理路由跳转与状态同步。 + - Anchor 与 Steps 的回调中统一处理滚动定位与高亮同步。 +- 权限控制建议 + - 在 items 注入阶段过滤不可见项，或在渲染层根据权限条件隐藏。 +- 动态加载建议 + - 使用延迟加载与 useMemo 缓存策略，避免频繁重新渲染。 +- 无障碍访问建议 + - 为可点击项提供键盘可达性与屏幕阅读器友好的标签。 + - 为步骤条与分页控件提供明确的 ARIA 属性与状态提示。 diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\345\270\203\345\261\200\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\345\270\203\345\261\200\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..6dfd2c91 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\345\270\203\345\261\200\347\273\204\344\273\266 API.md" @@ -0,0 +1,398 @@ +# 布局组件 API + + +**本文引用的文件** +- [divider.tsx](file://frontend/antd/divider/divider.tsx) +- [flex.tsx](file://frontend/antd/flex/flex.tsx) +- [grid/context.ts](file://frontend/antd/grid/context.ts) +- [grid/row/row.tsx](file://frontend/antd/grid/row/row.tsx) +- [grid/col/col.tsx](file://frontend/antd/grid/col/col.tsx) +- [layout/layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) +- [layout/Base.svelte](file://frontend/antd/layout/Base.svelte) +- [layout.sider/layout.sider.tsx](file://frontend/antd/layout/sider/layout.sider.tsx) +- [space/space.tsx](file://frontend/antd/space/space.tsx) +- [splitter/splitter.tsx](file://frontend/antd/splitter/splitter.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 中基于 Ant Design 的布局组件 API 参考文档，覆盖 Divider、Flex、Grid（Row/Col）、Layout（Header/Footer/Sider/Content）以及 Space、Splitter 组件。内容包括： + +- 每个组件的属性定义与类型来源 +- 布局算法与嵌套规则 +- 响应式行为与尺寸计算要点 +- 与 CSS Grid/Flexbox 的对应关系 +- 标准使用路径与最佳实践 +- 性能优化与移动端适配建议 + +## 项目结构 + +这些布局组件通过统一的 Svelte 预处理桥接方案，将 Ant Design 的 React 组件以 Svelte 组件形式暴露给前端应用。核心模式如下： + +- 使用 sveltify 将 Ant Design 组件包装为 Svelte 组件 +- 通过上下文与 Slot 机制实现子项收集与渲染 +- 通过 Base 组件按需选择具体 Ant Design 子组件（如 Header/Footer/Content/Layout） + +```mermaid +graph TB +subgraph "Antd 包装层" +D["Divider
divider.tsx"] +F["Flex
flex.tsx"] +G["Grid.Row/Col
row.tsx / col.tsx"] +L["Layout.Base
layout.base.tsx"] +S["Space
space.tsx"] +SP["Splitter
splitter.tsx"] +end +subgraph "上下文与插槽" +Ctx["Grid 上下文
grid/context.ts"] +Slots["ReactSlot / useTargets
空间渲染"] +end +D --> |"sveltify"| AntD_D["antd.Divider"] +F --> |"sveltify"| AntD_F["antd.Flex"] +G --> |"useItems 上下文"| Ctx +G --> |"ReactSlot"| Slots +L --> |"动态选择组件"| AntD_L["antd.Layout.*"] +S --> |"ReactSlot / useTargets"| Slots +SP --> |"withItemsContextProvider"| Ctx +SP --> |"ReactSlot"| Slots +``` + +图表来源 + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) + +章节来源 + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) + +## 核心组件 + +- Divider：用于分隔线，支持传入子节点作为自定义内容或空内容。 +- Flex：弹性布局容器，直接透传 Ant Design Flex 属性。 +- Grid：Row/Col 组合实现栅格系统；Col 通过上下文注册到 Row。 +- Layout：Base 组件根据 component 属性动态映射到 Header/Footer/Content/Layout。 +- Space：在 Ant Design Space 基础上增强插槽渲染与分隔符插槽。 +- Splitter：分割面板容器，通过上下文收集 Panel 子项并渲染。 + +章节来源 + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) + +## 架构总览 + +以下图展示布局组件如何通过上下文与 Slot 机制组织子项，并最终渲染为 Ant Design 组件树。 + +```mermaid +sequenceDiagram +participant App as "应用" +participant Row as "Grid.Row
row.tsx" +participant Ctx as "Grid 上下文
context.ts" +participant Col as "Grid.Col
col.tsx" +participant Base as "Layout.Base
layout.base.tsx" +App->>Row : 渲染 Row 并提供 children +Row->>Ctx : withItemsContextProvider 注册 default 列表 +Col->>Ctx : ItemHandler 注册列项 +Row->>Row : useItems 获取 default 列表 +Row->>App : 渲染 ARow + ACol*ReactSlot 渲染 +App->>Base : 渲染 Base 并指定 component +Base->>Base : 根据 component 选择 ALayout.Header/Footer/Content/Layout +Base-->>App : 返回 Ant Design 组件 +``` + +图表来源 + +- [grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) +- [layout/layout.base.tsx:13-37](file://frontend/antd/layout/layout.base.tsx#L13-L37) + +## 详细组件分析 + +### Divider（分隔线） + +- 功能：提供水平或垂直分隔线，可选自定义子节点（如图标、文本）。 +- 关键点： + - 当存在子节点时，将子节点传递给 Ant Design Divider；否则渲染空分隔线。 + - 类型来自 Ant Design Divider Props。 +- 典型用法路径 + - [divider.tsx:5-12](file://frontend/antd/divider/divider.tsx#L5-L12) + +章节来源 + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) + +### Flex（弹性布局） + +- 功能：Ant Design Flex 容器，支持主轴、交叉轴对齐、换行等布局属性。 +- 关键点： + - 直接透传 Ant Design Flex Props。 + - 适合复杂弹性布局场景。 +- 典型用法路径 + - [flex.tsx:4-8](file://frontend/antd/flex/flex.tsx#L4-L8) + +章节来源 + +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) + +### Grid（栅格系统） + +- Row/Col 组合 + - Row：通过上下文收集 Col 子项，渲染为 Ant Design Row，并将 Col 内容通过 Slot 渲染。 + - Col：通过 ItemHandler 注册到 Row 的上下文中。 +- 上下文 + - 提供 withItemsContextProvider、useItems、ItemHandler，用于收集与分发子项。 +- 响应式与嵌套 + - 支持响应式断点参数（由 Ant Design Row/Col Props 控制），Col 可嵌套在 Row 内。 +- 典型用法路径 + - [grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) + - [grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) + - [grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) + +```mermaid +classDiagram +class GridContext { ++withItemsContextProvider(slots) ++useItems() ++ItemHandler +} +class Row { ++props : RowProps ++children : Col* ++render() : ARow + ACol* +} +class Col { ++props : ColProps ++register() : ItemHandler +} +Row --> GridContext : "注册/消费 default 列表" +Col --> GridContext : "注册到 default 列表" +``` + +图表来源 + +- [grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) +- [grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) + +章节来源 + +- [grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) + +### Layout（布局容器） + +- Base 组件 + - 根据 component 属性动态映射到 Header/Footer/Content/Layout。 + - 支持额外类名与样式透传。 +- Sider 子组件 + - 通过独立文件导出，配合 Layout 使用侧边栏。 +- 典型用法路径 + - [layout/layout.base.tsx:13-37](file://frontend/antd/layout/layout.base.tsx#L13-L37) + - [layout/Base.svelte:53-67](file://frontend/antd/layout/Base.svelte#L53-L67) + - [layout.sider/layout.sider.tsx](file://frontend/antd/layout/sider/layout.sider.tsx) + +```mermaid +sequenceDiagram +participant Svelte as "Base.svelte" +participant Base as "layout.base.tsx" +participant AD as "antd.Layout.*" +Svelte->>Base : 传入 component 与 props +Base->>Base : 根据 component 选择 Header/Footer/Content/Layout +Base->>AD : 渲染对应组件并透传 props +AD-->>Svelte : 返回 DOM +``` + +图表来源 + +- [layout/Base.svelte:53-67](file://frontend/antd/layout/Base.svelte#L53-L67) +- [layout/layout.base.tsx:13-37](file://frontend/antd/layout/layout.base.tsx#L13-L37) + +章节来源 + +- [layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [layout.sider/layout.sider.tsx](file://frontend/antd/layout/sider/layout.sider.tsx) + +### Space（间距） + +- 功能：在元素之间插入间距，支持自定义分隔符插槽。 +- 关键点： + - 使用 useTargets 解析 children，隐藏真实 DOM，通过 Ant Design Space 渲染。 + - 支持 split 插槽，允许自定义分隔符。 +- 典型用法路径 + - [space/space.tsx:7-26](file://frontend/antd/space/space.tsx#L7-L26) + +```mermaid +flowchart TD +Start(["开始"]) --> Parse["解析 children 为目标列表"] +Parse --> Hide["隐藏真实 DOM"] +Hide --> Render["渲染 Ant Design Space"] +Render --> Split{"是否提供 split 插槽?"} +Split --> |是| UseSplit["使用 split 插槽"] +Split --> |否| UseProp["使用 props.split"] +UseSplit --> Done(["结束"]) +UseProp --> Done +``` + +图表来源 + +- [space/space.tsx:8-26](file://frontend/antd/space/space.tsx#L8-L26) + +章节来源 + +- [space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) + +### Splitter（分割面板） + +- 功能：将区域分割为多个可拖拽调整大小的面板。 +- 关键点： + - 通过 withItemsContextProvider 收集默认插槽中的 Panel 子项。 + - 使用 ReactSlot 渲染每个 Panel 的内容。 +- 典型用法路径 + - [splitter/splitter.tsx:7-35](file://frontend/antd/splitter/splitter.tsx#L7-L35) + +```mermaid +sequenceDiagram +participant App as "应用" +participant Splitter as "Splitter
splitter.tsx" +participant Ctx as "上下文
context.ts" +participant Panel as "Panel" +App->>Splitter : 渲染 Splitter 并提供 children +Splitter->>Ctx : withItemsContextProvider 注册 default 面板列表 +Splitter->>Splitter : useItems 获取 default 面板 +Splitter->>Panel : 逐个渲染 Panel 并注入内容 +Panel-->>App : 返回可拖拽面板 +``` + +图表来源 + +- [splitter/splitter.tsx:7-35](file://frontend/antd/splitter/splitter.tsx#L7-L35) +- [grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) + +章节来源 + +- [splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) + +## 依赖分析 + +- 组件间耦合 + - Grid.Row/Col 依赖 Grid 上下文进行子项收集与分发。 + - Space/Splitter 依赖通用 Slot 机制与目标解析工具。 + - Layout.Base 通过动态选择组件实现多形态布局。 +- 外部依赖 + - Ant Design 组件库（Divider、Flex、Grid、Layout、Space、Splitter）。 + - Svelte 预处理工具链（sveltify、ReactSlot、useTargets）。 + - 样式工具（classnames）用于条件类名拼接。 + +```mermaid +graph LR +Row["Grid.Row"] --> Ctx["Grid 上下文"] +Col["Grid.Col"] --> Ctx +Space["Space"] --> Slot["ReactSlot / useTargets"] +Splitter["Splitter"] --> Ctx +Splitter --> Slot +LayoutBase["Layout.Base"] --> AD["antd.Layout.*"] +``` + +图表来源 + +- [grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) +- [grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) +- [space/space.tsx:8-26](file://frontend/antd/space/space.tsx#L8-L26) +- [splitter/splitter.tsx:7-35](file://frontend/antd/splitter/splitter.tsx#L7-L35) +- [layout/layout.base.tsx:13-37](file://frontend/antd/layout/layout.base.tsx#L13-L37) + +章节来源 + +- [grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +## 性能考虑 + +- 虚拟化与懒加载 + - 对于长列表或大量子项的 Grid/Space/Splitter，优先采用虚拟化或分页策略减少一次性渲染开销。 +- Slot 渲染优化 + - Space 通过隐藏真实 DOM 并仅渲染 Ant Design Space，避免重复渲染与样式抖动。 +- 条件渲染 + - Layout.Base 根据 component 动态选择组件，避免不必要的 DOM 结构。 +- 响应式断点 + - Grid 使用 Ant Design 断点参数，合理设置响应式阈值，避免频繁重排。 +- 移动端适配 + - 在小屏设备上优先使用 Flex 或 Space 的紧凑模式，减少固定宽度布局带来的溢出问题。 + - Splitter 在移动端建议限制最小面板尺寸并禁用拖拽以提升交互稳定性。 + +## 故障排查指南 + +- Grid 子项未显示 + - 检查 Row 是否正确包裹 Col，且 Col 已通过 ItemHandler 注册到上下文。 + - 确认 Row 的 children 中包含 Col，且 Col 的 el 有效。 +- Space 分隔符不生效 + - 确认已提供 split 插槽或 props.split，且插槽内容可被 ReactSlot 正确渲染。 +- Splitter 面板为空 + - 确认 Panel 已在默认插槽中注册，且 Panel 的 el 有效。 +- Layout 样式异常 + - 检查 Base 组件传入的 component 是否与预期一致，确认类名拼接逻辑未被覆盖。 + +章节来源 + +- [grid/row/row.tsx:12-29](file://frontend/antd/grid/row/row.tsx#L12-L29) +- [grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) +- [space/space.tsx:13-22](file://frontend/antd/space/space.tsx#L13-L22) +- [splitter/splitter.tsx:9-31](file://frontend/antd/splitter/splitter.tsx#L9-L31) +- [layout/layout.base.tsx:31-35](file://frontend/antd/layout/layout.base.tsx#L31-L35) + +## 结论 + +ModelScope Studio 的布局组件通过统一的 Svelte 预处理桥接方案，将 Ant Design 的布局能力以更易用的方式呈现。Grid、Layout、Space、Splitter 等组件在保持与 Ant Design API 一致的同时，增强了插槽与上下文能力，便于复杂布局场景的组合与复用。遵循本文档的属性定义、嵌套规则与性能建议，可在桌面与移动端获得稳定高效的布局体验。 + +## 附录 + +- 与 CSS Grid/Flexbox 的对应关系 + - Grid.Row/Col 对应 CSS Grid 的行/列划分；Flex 对应 CSS Flexbox 的弹性布局。 + - Space 对应 Flex 的间距分配；Splitter 对应可拖拽的区域分割。 +- 常见布局场景 + - 栅格系统：Row + Col 组合，按断点控制列宽与换行。 + - 弹性布局：Flex 容器内放置多个子元素，控制主轴与交叉轴对齐。 + - 分割面板：Splitter 内放置多个 Panel，支持拖拽调整大小。 + - 页面布局：Layout.Base 按需选择 Header/Footer/Content/Sider 组合。 diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..508faee9 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266 API.md" @@ -0,0 +1,578 @@ +# 数据展示组件 API + + +**本文引用的文件** +- [avatar.tsx](file://frontend/antd/avatar/avatar.tsx) +- [badge.tsx](file://frontend/antd/badge/badge.tsx) +- [calendar.tsx](file://frontend/antd/calendar/calendar.tsx) +- [card.tsx](file://frontend/antd/card/card.tsx) +- [carousel.tsx](file://frontend/antd/carousel/carousel.tsx) +- [collapse.tsx](file://frontend/antd/collapse/collapse.tsx) +- [descriptions.tsx](file://frontend/antd/descriptions/descriptions.tsx) +- [empty.tsx](file://frontend/antd/empty/empty.tsx) +- [image.tsx](file://frontend/antd/image/image.tsx) +- [list.tsx](file://frontend/antd/list/list.tsx) +- [popover.tsx](file://frontend/antd/popover/popover.tsx) +- [qr-code.tsx](file://frontend/antd/qr-code/qr-code.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [statistic.tsx](file://frontend/antd/statistic/statistic.tsx) +- [table.tsx](file://frontend/antd/table/table.tsx) +- [tabs.tsx](file://frontend/antd/tabs/tabs.tsx) +- [tag.tsx](file://frontend/antd/tag/tag.tsx) +- [timeline.tsx](file://frontend/antd/timeline/timeline.tsx) +- [tooltip.tsx](file://frontend/antd/tooltip/tooltip.tsx) +- [tour.tsx](file://frontend/antd/tour/tour.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详细分析](#组件详细分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 中基于 Ant Design 的数据展示类组件 API 参考文档，覆盖 Avatar、Badge、Calendar、Card、Carousel、Collapse、Descriptions、Empty、Image、List、Popover、QRCode、Segmented、Statistic、Table、Tabs、Tag、Timeline、Tooltip、Tour、Tree 等组件。内容包括： + +- 属性定义与数据格式要求 +- 显示逻辑与交互行为 +- 标准实例化与配置示例（以路径形式给出） +- 数据绑定、虚拟滚动、懒加载与性能优化机制 +- TypeScript 类型定义要点、数据转换与与图表库集成思路 +- 视觉设计原则与用户体验优化建议 + +## 项目结构 + +这些组件均位于前端目录下的 antd 子模块中，采用统一的封装模式：通过 sveltify 将 Ant Design 组件桥接到 Svelte 生态，并使用 slots 与 renderParamsSlot 实现灵活的内容插槽与函数参数渲染。 + +```mermaid +graph TB +subgraph "Ant Design 组件层" +AD_Avatar["Avatar"] +AD_Badge["Badge"] +AD_Calendar["Calendar"] +AD_Card["Card"] +AD_Carousel["Carousel"] +AD_Collapse["Collapse"] +AD_Descriptions["Descriptions"] +AD_Empty["Empty"] +AD_Image["Image"] +AD_List["List"] +AD_Popover["Popover"] +AD_QRCode["QRCode"] +AD_Segmented["Segmented"] +AD_Statistic["Statistic"] +AD_Table["Table"] +AD_Tabs["Tabs"] +AD_Tag["Tag"] +AD_Timeline["Timeline"] +AD_Tooltip["Tooltip"] +AD_Tour["Tour"] +AD_Tree["Tree"] +end +subgraph "封装层sveltify" +S_Avatar["avatar.tsx"] +S_Badge["badge.tsx"] +S_Calendar["calendar.tsx"] +S_Card["card.tsx"] +S_Carousel["carousel.tsx"] +S_Collapse["collapse.tsx"] +S_Descriptions["descriptions.tsx"] +S_Empty["empty.tsx"] +S_Image["image.tsx"] +S_List["list.tsx"] +S_Popover["popover.tsx"] +S_QRCode["qr-code.tsx"] +S_Segmented["segmented.tsx"] +S_Statistic["statistic.tsx"] +S_Table["table.tsx"] +S_Tabs["tabs.tsx"] +S_Tag["tag.tsx"] +S_Timeline["timeline.tsx"] +S_Tooltip["tooltip.tsx"] +S_Tour["tour.tsx"] +S_Tree["tree.tsx"] +end +S_Avatar --> AD_Avatar +S_Badge --> AD_Badge +S_Calendar --> AD_Calendar +S_Card --> AD_Card +S_Carousel --> AD_Carousel +S_Collapse --> AD_Collapse +S_Descriptions --> AD_Descriptions +S_Empty --> AD_Empty +S_Image --> AD_Image +S_List --> AD_List +S_Popover --> AD_Popover +S_QRCode --> AD_QRCode +S_Segmented --> AD_Segmented +S_Statistic --> AD_Statistic +S_Table --> AD_Table +S_Tabs --> AD_Tabs +S_Tag --> AD_Tag +S_Timeline --> AD_Timeline +S_Tooltip --> AD_Tooltip +S_Tour --> AD_Tour +S_Tree --> AD_Tree +``` + +图表来源 + +- [avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) +- [calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) +- [carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) +- [image.tsx:1-89](file://frontend/antd/image/image.tsx#L1-L89) +- [list.tsx:1-36](file://frontend/antd/list/list.tsx#L1-L36) +- [popover.tsx:1-37](file://frontend/antd/popover/popover.tsx#L1-L37) +- [qr-code.tsx:1-200](file://frontend/antd/qr-code/qr-code.tsx#L1-L200) +- [segmented.tsx:1-47](file://frontend/antd/segmented/segmented.tsx#L1-L47) +- [statistic.tsx:1-34](file://frontend/antd/statistic/statistic.tsx#L1-L34) +- [table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [tabs.tsx:1-121](file://frontend/antd/tabs/tabs.tsx#L1-L121) +- [tag.tsx:1-200](file://frontend/antd/tag/tag.tsx#L1-L200) +- [timeline.tsx:1-200](file://frontend/antd/timeline/timeline.tsx#L1-L200) +- [tooltip.tsx:1-200](file://frontend/antd/tooltip/tooltip.tsx#L1-L200) +- [tour.tsx:1-200](file://frontend/antd/tour/tour.tsx#L1-L200) +- [tree.tsx:1-200](file://frontend/antd/tree/tree.tsx#L1-L200) + +章节来源 + +- [avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) +- [calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) +- [carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) +- [image.tsx:1-89](file://frontend/antd/image/image.tsx#L1-L89) +- [list.tsx:1-36](file://frontend/antd/list/list.tsx#L1-L36) +- [popover.tsx:1-37](file://frontend/antd/popover/popover.tsx#L1-L37) +- [segmented.tsx:1-47](file://frontend/antd/segmented/segmented.tsx#L1-L47) +- [statistic.tsx:1-34](file://frontend/antd/statistic/statistic.tsx#L1-L34) +- [table.tsx:1-279](file://frontend/antd/table/table.tsx#L1-L279) +- [tabs.tsx:1-121](file://frontend/antd/tabs/tabs.tsx#L1-L121) + +## 核心组件 + +本节概述各组件的职责与通用封装策略： + +- 统一使用 sveltify 包装 Ant Design 组件，支持 slots 插槽与 renderParamsSlot 渲染函数参数。 +- 大多数组件支持 children 透传与多种具名插槽（如 title、extra、footer、header、content、image、description、placeholder、mask、toolbarRender、imageRender、tabBarExtraContent、tabProps.\* 等），用于灵活定制外观与行为。 +- 部分组件对事件回调进行包装，确保在 Svelte 环境下正确执行。 + +章节来源 + +- [avatar.tsx:6-25](file://frontend/antd/avatar/avatar.tsx#L6-L25) +- [badge.tsx:6-18](file://frontend/antd/badge/badge.tsx#L6-L18) +- [card.tsx:37-146](file://frontend/antd/card/card.tsx#L37-L146) +- [carousel.tsx:8-28](file://frontend/antd/carousel/carousel.tsx#L8-L28) +- [collapse.tsx:11-49](file://frontend/antd/collapse/collapse.tsx#L11-L49) +- [descriptions.tsx:10-37](file://frontend/antd/descriptions/descriptions.tsx#L10-L37) +- [empty.tsx:6-49](file://frontend/antd/empty/empty.tsx#L6-L49) +- [image.tsx:15-85](file://frontend/antd/image/image.tsx#L15-L85) +- [list.tsx:8-33](file://frontend/antd/list/list.tsx#L8-L33) +- [popover.tsx:7-34](file://frontend/antd/popover/popover.tsx#L7-L34) +- [segmented.tsx:10-43](file://frontend/antd/segmented/segmented.tsx#L10-L43) +- [statistic.tsx:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) +- [table.tsx:28-275](file://frontend/antd/table/table.tsx#L28-L275) +- [tabs.tsx:12-117](file://frontend/antd/tabs/tabs.tsx#L12-L117) + +## 架构总览 + +以下序列图展示了组件封装到渲染的关键流程：Svelte 通过 sveltify 将 props 与 slots 转换为 Ant Design 组件的 props；对于函数型参数，使用 useFunction 或 createFunction 包装；对于复杂配置对象，使用 omitUndefinedProps 合并并注入 slots。 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 组件" +participant Sveltify as "sveltify 封装" +participant AntD as "Ant Design 组件" +participant Utils as "工具函数
useFunction/createFunction/renderParamsSlot" +Svelte->>Sveltify : 传递 props 与 slots +Sveltify->>Utils : 包装函数参数/合并配置 +Utils-->>Sveltify : 返回可执行函数或配置对象 +Sveltify->>AntD : 渲染并传入 props +AntD-->>Svelte : 触发回调/返回渲染结果 +``` + +图表来源 + +- [table.tsx:76-134](file://frontend/antd/table/table.tsx#L76-L134) +- [card.tsx:40-49](file://frontend/antd/card/card.tsx#L40-L49) +- [image.tsx:32-34](file://frontend/antd/image/image.tsx#L32-L34) +- [popover.tsx:10-12](file://frontend/antd/popover/popover.tsx#L10-L12) + +## 组件详细分析 + +### Avatar（头像） + +- 作用：展示用户头像或图标，支持插槽 icon 与 src。 +- 关键点： + - 支持 slots.icon 与 slots.src；若存在插槽则优先使用插槽内容，否则回退到 props。 + - 通过 ReactSlot 渲染插槽。 +- 常见用法路径示例： + - [头像基础用法:6-25](file://frontend/antd/avatar/avatar.tsx#L6-L25) + +章节来源 + +- [avatar.tsx:6-25](file://frontend/antd/avatar/avatar.tsx#L6-L25) + +### Badge（徽标数） + +- 作用：在头像、按钮等元素上展示徽标数或文本。 +- 关键点： + - 支持 slots.count 与 slots.text，动态渲染徽标内容。 +- 常见用法路径示例： + - [徽标计数与文本:6-18](file://frontend/antd/badge/badge.tsx#L6-L18) + +章节来源 + +- [badge.tsx:6-18](file://frontend/antd/badge/badge.tsx#L6-L18) + +### Calendar（日历） + +- 作用：日期选择与日程展示。 +- 关键点： + - 对 value/defaultValue/validRange 进行 dayjs 格式化处理。 + - onChange/onPanelChange/onSelect 回调统一转换为秒级时间戳。 + - 支持 slots.cellRender/fullCellRender/headerRender 函数插槽。 +- 常见用法路径示例： + - [日历日期格式与回调:17-98](file://frontend/antd/calendar/calendar.tsx#L17-L98) + +章节来源 + +- [calendar.tsx:17-98](file://frontend/antd/calendar/calendar.tsx#L17-L98) + +### Card（卡片） + +- 作用：容器组件，支持标题、额外操作、封面、动作区与标签页。 +- 关键点： + - 支持 slots.title/extra/cover/tabBarExtraContent/left/right 等。 + - actions 通过 useTargets 自动收集子节点。 + - tabList 通过 renderItems 从上下文解析。 + - tabProps.indicator.size、more.icon、tabProps.renderTabBar、tabProps.tabBarExtraContent.\* 等均可插槽化。 +- 常见用法路径示例： + - [卡片带标签页与动作区:37-146](file://frontend/antd/card/card.tsx#L37-L146) + +章节来源 + +- [card.tsx:37-146](file://frontend/antd/card/card.tsx#L37-L146) + +### Carousel（走马灯） + +- 作用：轮播展示多张图片或内容。 +- 关键点： + - 使用 useTargets 提取子节点作为轮播项。 + - afterChange/beforeChange 通过 useFunction 包装。 +- 常见用法路径示例： + - [轮播图项渲染:8-28](file://frontend/antd/carousel/carousel.tsx#L8-L28) + +章节来源 + +- [carousel.tsx:8-28](file://frontend/antd/carousel/carousel.tsx#L8-L28) + +### Collapse（折叠面板） + +- 作用：分组折叠/展开内容。 +- 关键点： + - 支持 slots.expandIcon 函数插槽。 + - items 通过 renderItems 从上下文解析，支持 label/extra/children 结构。 +- 常见用法路径示例： + - [折叠面板项与展开图标:11-49](file://frontend/antd/collapse/collapse.tsx#L11-L49) + +章节来源 + +- [collapse.tsx:11-49](file://frontend/antd/collapse/collapse.tsx#L11-L49) + +### Descriptions（描述列表） + +- 作用：键值对形式展示信息。 +- 关键点： + - 支持 slots.title/extra；items 通过 renderItems 解析，字段为 label/children。 +- 常见用法路径示例： + - [描述列表项渲染:10-37](file://frontend/antd/descriptions/descriptions.tsx#L10-L37) + +章节来源 + +- [descriptions.tsx:10-37](file://frontend/antd/descriptions/descriptions.tsx#L10-L37) + +### Empty（空状态） + +- 作用：无数据时的占位提示。 +- 关键点： + - 支持 slots.description/image；image 支持默认常量映射。 + - styles 支持函数式返回样式对象。 +- 常见用法路径示例： + - [空状态自定义图像与描述:6-49](file://frontend/antd/empty/empty.tsx#L6-L49) + +章节来源 + +- [empty.tsx:6-49](file://frontend/antd/empty/empty.tsx#L6-L49) + +### Image（图片） + +- 作用：图片展示与预览。 +- 关键点： + - 支持 slots.placeholder、preview.mask、preview.closeIcon、preview.toolbarRender、preview.imageRender。 + - preview 通过 getConfig/omitUndefinedProps 合并配置；getContainer/toolbarRender/imageRender 通过 useFunction 包装。 +- 常见用法路径示例： + - [图片预览与工具栏渲染:15-85](file://frontend/antd/image/image.tsx#L15-L85) + +章节来源 + +- [image.tsx:15-85](file://frontend/antd/image/image.tsx#L15-L85) + +### List（列表） + +- 作用：长列表展示与加载更多。 +- 关键点： + - 支持 slots.footer/header/loadMore/renderItem；renderItem 通过 renderParamsSlot 渲染，强制克隆。 +- 常见用法路径示例： + - [列表头部尾部与加载更多:8-33](file://frontend/antd/list/list.tsx#L8-L33) + +章节来源 + +- [list.tsx:8-33](file://frontend/antd/list/list.tsx#L8-L33) + +### Popover（气泡卡片） + +- 作用：悬浮气泡展示标题与内容。 +- 关键点： + - 支持 slots.title/content；title/content 通过 ReactSlot 克隆。 + - afterOpenChange/getPopupContainer 通过 useFunction 包装。 +- 常见用法路径示例： + - [气泡卡片标题与内容:7-34](file://frontend/antd/popover/popover.tsx#L7-L34) + +章节来源 + +- [popover.tsx:7-34](file://frontend/antd/popover/popover.tsx#L7-L34) + +### QRCode（二维码） + +- 作用：生成与展示二维码。 +- 常见用法路径示例： + - [二维码组件:1-200](file://frontend/antd/qr-code/qr-code.tsx#L1-L200) + +章节来源 + +- [qr-code.tsx:1-200](file://frontend/antd/qr-code/qr-code.tsx#L1-L200) + +### Segmented（分段控制器） + +- 作用：在多个选项中进行切换。 +- 关键点： + - 支持 options/default 从上下文解析；onChange 通过 onValueChange 暴露选中值。 +- 常见用法路径示例： + - [分段控制器选项渲染:10-43](file://frontend/antd/segmented/segmented.tsx#L10-L43) + +章节来源 + +- [segmented.tsx:10-43](file://frontend/antd/segmented/segmented.tsx#L10-L43) + +### Statistic（统计数值） + +- 作用：展示数值与单位、前缀、后缀。 +- 关键点： + - 支持 slots.prefix/suffix/title/formatter；formatter 通过 renderParamsSlot 渲染。 +- 常见用法路径示例： + - [统计数值格式化:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) + +章节来源 + +- [statistic.tsx:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) + +### Table（表格） + +- 作用：数据表格展示与交互。 +- 关键点： + - 支持 columns、rowSelection、expandable、sticky、pagination、loading、footer、title、summary、showSorterTooltip 等复杂配置。 + - 通过多层 with\*ContextProvider 注入列、展开、行选择上下文。 + - 使用 renderItems 与 renderParamsSlot 动态解析 items 与函数参数；使用 createFunction/omitUndefinedProps 包装与合并配置。 +- 常见用法路径示例： + - [表格列与分页插槽:28-275](file://frontend/antd/table/table.tsx#L28-L275) + +章节来源 + +- [table.tsx:28-275](file://frontend/antd/table/table.tsx#L28-L275) + +### Tabs（标签页） + +- 作用：标签页容器与切换。 +- 关键点： + - 支持 slots.addIcon/removeIcon/renderTabBar/tabBarExtraContent/left/right/more.icon。 + - indicator.size、more.getPopupContainer、renderTabBar 通过 useFunction 包装；items 通过 renderItems 解析。 +- 常见用法路径示例： + - [标签页与额外内容:12-117](file://frontend/antd/tabs/tabs.tsx#L12-L117) + +章节来源 + +- [tabs.tsx:12-117](file://frontend/antd/tabs/tabs.tsx#L12-L117) + +### Tag（标签） + +- 作用：标记与分类。 +- 常见用法路径示例： + - [标签组件:1-200](file://frontend/antd/tag/tag.tsx#L1-L200) + +章节来源 + +- [tag.tsx:1-200](file://frontend/antd/tag/tag.tsx#L1-L200) + +### Timeline（时间轴） + +- 作用：按时间顺序展示事件。 +- 常见用法路径示例： + - [时间轴组件:1-200](file://frontend/antd/timeline/timeline.tsx#L1-L200) + +章节来源 + +- [timeline.tsx:1-200](file://frontend/antd/timeline/timeline.tsx#L1-L200) + +### Tooltip（文字提示） + +- 作用：简短提示信息。 +- 常见用法路径示例： + - [文字提示组件:1-200](file://frontend/antd/tooltip/tooltip.tsx#L1-L200) + +章节来源 + +- [tooltip.tsx:1-200](file://frontend/antd/tooltip/tooltip.tsx#L1-L200) + +### Tour（向导） + +- 作用：引导式教程。 +- 常见用法路径示例： + - [向导组件:1-200](file://frontend/antd/tour/tour.tsx#L1-L200) + +章节来源 + +- [tour.tsx:1-200](file://frontend/antd/tour/tour.tsx#L1-L200) + +### Tree（树形控件） + +- 作用：层级数据展示与选择。 +- 常见用法路径示例： + - [树形控件:1-200](file://frontend/antd/tree/tree.tsx#L1-L200) + +章节来源 + +- [tree.tsx:1-200](file://frontend/antd/tree/tree.tsx#L1-L200) + +## 依赖关系分析 + +- 组件间耦合： + - Card 与 Tabs 存在上下文共享（Card 内嵌 Tabs 时复用 tabList 上下文）。 + - Table 通过多处 context provider 注入列、展开、行选择等上下文。 + - 多数组件共享 renderItems、renderParamsSlot、useFunction、omitUndefinedProps 等工具。 +- 外部依赖： + - Ant Design 组件库与 dayjs（日历组件）。 + - lodash-es（Empty 组件中的类型判断）。 + +```mermaid +graph LR +RenderItems["renderItems"] +RenderParam["renderParamsSlot"] +UseFunc["useFunction"] +OmitUndef["omitUndefinedProps"] +Card["card.tsx"] --> RenderItems +Card --> UseFunc +Tabs["tabs.tsx"] --> RenderItems +Tabs --> UseFunc +Collapse["collapse.tsx"] --> RenderItems +Collapse --> UseFunc +Descriptions["descriptions.tsx"] --> RenderItems +Table["table.tsx"] --> RenderItems +Table --> RenderParam +Table --> UseFunc +Table --> OmitUndef +Image["image.tsx"] --> UseFunc +Image --> OmitUndef +Popover["popover.tsx"] --> UseFunc +Statistic["statistic.tsx"] --> UseFunc +Segmented["segmented.tsx"] --> RenderItems +Calendar["calendar.tsx"] --> UseFunc +``` + +图表来源 + +- [card.tsx:10-14](file://frontend/antd/card/card.tsx#L10-L14) +- [tabs.tsx:6-10](file://frontend/antd/tabs/tabs.tsx#L6-L10) +- [collapse.tsx:4-8](file://frontend/antd/collapse/collapse.tsx#L4-L8) +- [descriptions.tsx:4-7](file://frontend/antd/descriptions/descriptions.tsx#L4-L7) +- [table.tsx:7-18](file://frontend/antd/table/table.tsx#L7-L18) +- [image.tsx:3-6](file://frontend/antd/image/image.tsx#L3-L6) +- [popover.tsx:4-5](file://frontend/antd/popover/popover.tsx#L4-L5) +- [statistic.tsx:4-6](file://frontend/antd/statistic/statistic.tsx#L4-L6) +- [segmented.tsx:3-6](file://frontend/antd/segmented/segmented.tsx#L3-L6) +- [calendar.tsx:3-4](file://frontend/antd/calendar/calendar.tsx#L3-L4) + +章节来源 + +- [card.tsx:10-14](file://frontend/antd/card/card.tsx#L10-L14) +- [tabs.tsx:6-10](file://frontend/antd/tabs/tabs.tsx#L6-L10) +- [table.tsx:7-18](file://frontend/antd/table/table.tsx#L7-L18) + +## 性能考量 + +- 虚拟滚动与懒加载 + - 列表类组件（List、Table）可通过外部配置启用虚拟滚动与懒加载，减少 DOM 数量与重排开销。 + - 建议在大数据集场景下开启虚拟化与分页加载。 +- 渲染优化 + - 使用 useMemo 缓存计算结果（如 Table 的 columns、rowSelection、expandable）。 + - 合理拆分插槽渲染，避免不必要的重复渲染。 +- 事件与函数包装 + - 使用 useFunction/createFunction 包装回调，确保在 Svelte 生命周期内稳定执行，避免闭包陷阱。 +- 图片与预览 + - Image 组件支持 placeholder 与 preview 工具栏自定义，合理设置尺寸与懒加载策略，降低首屏压力。 + +## 故障排查指南 + +- 插槽未生效 + - 确认插槽名称是否正确（如 preview.mask、tabProps.renderTabBar、loading.tip 等）。 + - 检查是否遗漏 slots.\* 与 props 的组合使用。 +- 回调不触发 + - 确保回调通过 useFunction 包装；检查事件命名与参数签名。 +- 时间格式问题（日历） + - Calendar 组件内部将时间统一转换为秒级时间戳，请确认传入值类型与范围。 +- 表格列与展开配置 + - 当 columns 为空时，组件会尝试从上下文解析；请确认上下文已正确提供 default/items。 +- 样式覆盖 + - Empty 的 styles 支持函数式返回，注意返回对象结构与 key 名称。 + +章节来源 + +- [image.tsx:32-34](file://frontend/antd/image/image.tsx#L32-L34) +- [popover.tsx:10-12](file://frontend/antd/popover/popover.tsx#L10-L12) +- [calendar.tsx:85-94](file://frontend/antd/calendar/calendar.tsx#L85-L94) +- [table.tsx:67-75](file://frontend/antd/table/table.tsx#L67-L75) +- [empty.tsx:34-45](file://frontend/antd/empty/empty.tsx#L34-L45) + +## 结论 + +ModelScope Studio 的数据展示组件通过统一的 sveltify 封装，实现了与 Ant Design 的无缝对接，并提供了强大的插槽与函数参数扩展能力。借助上下文解析与工具函数，开发者可以快速构建卡片布局、轮播图、折叠面板、描述列表、图片预览、表格展示、标签云等常见数据展示场景。建议在实际项目中结合虚拟滚动、懒加载与样式优化策略，进一步提升性能与用户体验。 + +## 附录 + +- TypeScript 类型定义要点 + - 大多数组件通过 GetProps
导出各 AntD 组件"] +end +subgraph "前端封装层" +F_FORM["form/form.tsx"] +F_AUTO["auto-complete/auto-complete.tsx"] +F_CASCADE["cascader/cascader.tsx"] +F_CHECK["checkbox/checkbox.tsx"] +F_COLOR["color-picker/color-picker.tsx"] +F_DATE["date-picker/date-picker.tsx"] +F_INPUT["input/input.tsx"] +F_NUM["input-number/input-number.tsx"] +F_MENTIONS["mentions/mentions.tsx"] +F_RADIO["radio/radio.tsx"] +F_RATE["rate/rate.tsx"] +F_SELECT["select/select.tsx"] +F_SLIDER["slider/slider.tsx"] +F_SWITCH["switch/switch.tsx"] +F_TIME["time-picker/time-picker.tsx"] +F_TRANS["transfer/transfer.tsx"] +F_TSELECT["tree-select/tree-select.tsx"] +end +PY --> F_FORM +PY --> F_AUTO +PY --> F_CASCADE +PY --> F_CHECK +PY --> F_COLOR +PY --> F_DATE +PY --> F_INPUT +PY --> F_NUM +PY --> F_MENTIONS +PY --> F_RADIO +PY --> F_RATE +PY --> F_SELECT +PY --> F_SLIDER +PY --> F_SWITCH +PY --> F_TIME +PY --> F_TRANS +PY --> F_TSELECT +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/auto-complete/auto-complete.tsx:1-151](file://frontend/antd/auto-complete/auto-complete.tsx#L1-L151) +- [frontend/antd/cascader/cascader.tsx:1-207](file://frontend/antd/cascader/cascader.tsx#L1-L207) +- [frontend/antd/checkbox/checkbox.tsx:1-22](file://frontend/antd/checkbox/checkbox.tsx#L1-L22) +- [frontend/antd/color-picker/color-picker.tsx:1-106](file://frontend/antd/color-picker/color-picker.tsx#L1-L106) +- [frontend/antd/date-picker/date-picker.tsx:1-234](file://frontend/antd/date-picker/date-picker.tsx#L1-L234) +- [frontend/antd/input/input.tsx:1-119](file://frontend/antd/input/input.tsx#L1-L119) +- [frontend/antd/input-number/input-number.tsx:1-92](file://frontend/antd/input-number/input-number.tsx#L1-L92) +- [frontend/antd/mentions/mentions.tsx:1-80](file://frontend/antd/mentions/mentions.tsx#L1-L80) +- [frontend/antd/radio/radio.tsx:1-32](file://frontend/antd/radio/radio.tsx#L1-L32) +- [frontend/antd/rate/rate.tsx:1-45](file://frontend/antd/rate/rate.tsx#L1-L45) +- [frontend/antd/select/select.tsx:1-181](file://frontend/antd/select/select.tsx#L1-L181) +- [frontend/antd/slider/slider.tsx:1-97](file://frontend/antd/slider/slider.tsx#L1-L97) +- [frontend/antd/switch/switch.tsx:1-42](file://frontend/antd/switch/switch.tsx#L1-L42) +- [frontend/antd/time-picker/time-picker.tsx:1-201](file://frontend/antd/time-picker/time-picker.tsx#L1-L201) +- [frontend/antd/transfer/transfer.tsx:1-112](file://frontend/antd/transfer/transfer.tsx#L1-L112) +- [frontend/antd/tree-select/tree-select.tsx:1-163](file://frontend/antd/tree-select/tree-select.tsx#L1-L163) + +章节来源 + +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +## 核心组件 + +本节概述所有数据录入组件的通用模式与关键接口： + +- 值绑定：均支持 value 与 onValueChange，用于受控/非受控切换与双向绑定 +- 插槽系统：大量组件支持 slots（如 allowClear.clearIcon、prefix、suffix、popupRender 等），用于自定义渲染 +- 函数式属性：部分属性支持传入函数（如 formatter、parser、disabledDate 等），通过 useFunction 包装 +- 选项/树数据：Select、Cascader、TreeSelect、AutoComplete、Mentions 等支持通过 children 或 options/treeData 渲染项 +- 表单集成：Form 提供全局表单状态管理、重置、提交、校验动作与 requiredMark/feedbackIcons 支持 + +章节来源 + +- [frontend/antd/form/form.tsx:8-76](file://frontend/antd/form/form.tsx#L8-L76) +- [frontend/antd/select/select.tsx:11-178](file://frontend/antd/select/select.tsx#L11-L178) +- [frontend/antd/cascader/cascader.tsx:19-204](file://frontend/antd/cascader/cascader.tsx#L19-L204) +- [frontend/antd/tree-select/tree-select.tsx:14-161](file://frontend/antd/tree-select/tree-select.tsx#L14-L161) +- [frontend/antd/auto-complete/auto-complete.tsx:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) +- [frontend/antd/mentions/mentions.tsx:11-77](file://frontend/antd/mentions/mentions.tsx#L11-L77) + +## 架构总览 + +下图展示数据录入组件的通用调用链：前端组件通过 onValueChange 回调向上游传递值；Form 组件负责表单级动作（reset/submit/validate）与全局 requiredMark/feedbackIcons；部分组件内部对值进行格式化（如日期时间组件）。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant C as "数据录入组件" +participant F as "Form 组件" +participant B as "后端服务" +U->>C : 输入/选择/更改 +C->>C : 触发 onChange/onValueChange +C-->>F : onValueChange(value) +F->>F : setFieldsValue / submit / validate +F-->>B : 提交表单数据 +B-->>F : 返回结果/错误 +F-->>U : 显示反馈/错误提示 +``` + +图表来源 + +- [frontend/antd/form/form.tsx:27-76](file://frontend/antd/form/form.tsx#L27-L76) +- [frontend/antd/date-picker/date-picker.tsx:162-170](file://frontend/antd/date-picker/date-picker.tsx#L162-L170) +- [frontend/antd/time-picker/time-picker.tsx:131-143](file://frontend/antd/time-picker/time-picker.tsx#L131-L143) + +## 组件详细分析 + +### Form（表单容器） + +- 职责：封装 AntD Form，提供 value、onValueChange、formAction（reset/submit/validate）、requiredMark、feedbackIcons 等能力 +- 关键点： + - 通过 AForm.useForm 创建表单实例 + - formAction 变化时执行 reset/submit/validate + - onValuesChange 同步上游值并触发 onValueChange +- 典型用法路径 + - [表单容器实现:15-76](file://frontend/antd/form/form.tsx#L15-L76) + +章节来源 + +- [frontend/antd/form/form.tsx:8-76](file://frontend/antd/form/form.tsx#L8-L76) + +### AutoComplete（自动完成） + +- 能力：支持 options 列表、过滤、弹窗渲染、清空图标、无数据占位等 +- 关键点： + - 使用 useValueChange 实现受控 value + - 支持 slots：allowClear.clearIcon、dropdownRender、popupRender、notFoundContent + - 支持 filterOption 函数与 getPopupContainer +- 典型用法路径 + - [自动完成组件:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) + +章节来源 + +- [frontend/antd/auto-complete/auto-complete.tsx:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) + +### Cascader（级联选择） + +- 能力：多级联动选择，支持动态加载、搜索、标签渲染、下拉面板自定义 +- 关键点： + - 支持 options 与 children 两种数据源 + - showSearch 支持对象配置与 slots['showSearch.render'] + - 支持 onLoadData 动态加载 +- 典型用法路径 + - [级联选择组件:19-204](file://frontend/antd/cascader/cascader.tsx#L19-L204) + +章节来源 + +- [frontend/antd/cascader/cascader.tsx:19-204](file://frontend/antd/cascader/cascader.tsx#L19-L204) + +### Checkbox（复选框） + +- 能力：布尔值选择，支持 onValueChange +- 关键点： + - onChange 中透传原生事件并触发 onValueChange(value) +- 典型用法路径 + - [复选框组件:4-19](file://frontend/antd/checkbox/checkbox.tsx#L4-L19) + +章节来源 + +- [frontend/antd/checkbox/checkbox.tsx:4-19](file://frontend/antd/checkbox/checkbox.tsx#L4-L19) + +### ColorPicker（颜色选择器） + +- 能力：支持单色/渐变色，预设颜色，多种输出格式（rgb/hex/hsb） +- 关键点： + - onChange 内部根据是否渐变返回不同格式数组或单一字符串 + - 支持 presets 插槽与 panelRender/showText 自定义 +- 典型用法路径 + - [颜色选择器组件:11-103](file://frontend/antd/color-picker/color-picker.tsx#L11-L103) + +章节来源 + +- [frontend/antd/color-picker/color-picker.tsx:11-103](file://frontend/antd/color-picker/color-picker.tsx#L11-L103) + +### DatePicker（日期选择） + +- 能力：单日/范围选择、时间选择、预设快捷项、禁用日期/时间、单元格/面板自定义 +- 关键点： + - 内部将输入值格式化为 dayjs 并在 onChange/onPanelChange 输出秒级时间戳 + - 支持 showTime 对象中的 defaultValue 格式化 + - 支持 presets、cellRender、panelRender、renderExtraFooter 等 slots +- 典型用法路径 + - [日期选择组件:40-231](file://frontend/antd/date-picker/date-picker.tsx#L40-L231) + +章节来源 + +- [frontend/antd/date-picker/date-picker.tsx:40-231](file://frontend/antd/date-picker/date-picker.tsx#L40-L231) + +### Input（文本输入） + +- 能力：基础文本输入，支持前后缀、计数器、清空图标、插槽扩展 +- 关键点： + - useValueChange 实现受控 value + - 支持 showCount.formatter 插槽与 count 系列函数 + - 支持 addonBefore/After、prefix/suffix、allowClear.clearIcon +- 典型用法路径 + - [文本输入组件:10-116](file://frontend/antd/input/input.tsx#L10-L116) + +章节来源 + +- [frontend/antd/input/input.tsx:10-116](file://frontend/antd/input/input.tsx#L10-L116) + +### InputNumber（数值输入） + +- 能力：数值输入，支持步进按钮自定义、前缀/后缀、formatter/parser +- 关键点： + - useValueChange 实现受控 value + - 支持 controls.upIcon/downIcon 插槽与 addonBefore/After、prefix/suffix +- 典型用法路径 + - [数值输入组件:7-91](file://frontend/antd/input-number/input-number.tsx#L7-L91) + +章节来源 + +- [frontend/antd/input-number/input-number.tsx:7-91](file://frontend/antd/input-number/input-number.tsx#L7-L91) + +### Mentions（提及） + +- 能力：@ 提及功能，支持选项列表、过滤、弹窗渲染 +- 关键点： + - useValueChange 实现受控 value + - 支持 options、filterOption、validateSearch、getPopupContainer +- 典型用法路径 + - [提及组件:11-77](file://frontend/antd/mentions/mentions.tsx#L11-L77) + +章节来源 + +- [frontend/antd/mentions/mentions.tsx:11-77](file://frontend/antd/mentions/mentions.tsx#L11-L77) + +### Radio（单选框） + +- 能力：单选选择，支持 onValueChange +- 关键点： + - onChange 中透传原生事件并触发 onValueChange(value) + - 注入主题 token 以适配样式变量 +- 典型用法路径 + - [单选框组件:6-29](file://frontend/antd/radio/radio.tsx#L6-L29) + +章节来源 + +- [frontend/antd/radio/radio.tsx:6-29](file://frontend/antd/radio/radio.tsx#L6-L29) + +### Rate（评分） + +- 能力：星级评分，支持自定义字符 +- 关键点： + - 支持 character 插槽与函数式配置 + - onChange 触发 onValueChange +- 典型用法路径 + - [评分组件:6-42](file://frontend/antd/rate/rate.tsx#L6-L42) + +章节来源 + +- [frontend/antd/rate/rate.tsx:6-42](file://frontend/antd/rate/rate.tsx#L6-L42) + +### Select（选择器） + +- 能力：单选/多选，支持标签渲染、下拉面板自定义、过滤排序 +- 关键点： + - 支持 options 与 children 两种数据源 + - 支持 allowClear.clearIcon、prefix/removeIcon/suffixIcon、notFoundContent、menuItemSelectedIcon + - 支持 dropdownRender/popupRender/optionRender/tagRender/labelRender + - 支持 filterOption/filterSort +- 典型用法路径 + - [选择器组件:11-178](file://frontend/antd/select/select.tsx#L11-L178) + +章节来源 + +- [frontend/antd/select/select.tsx:11-178](file://frontend/antd/select/select.tsx#L11-L178) + +### Slider（滑块） + +- 能力：单/双滑块，支持刻度标记、工具提示格式化 +- 关键点： + - marks 通过 children 渲染，支持 label 子插槽 + - tooltip 支持 formatter 插槽与函数 +- 典型用法路径 + - [滑块组件:37-94](file://frontend/antd/slider/slider.tsx#L37-L94) + +章节来源 + +- [frontend/antd/slider/slider.tsx:37-94](file://frontend/antd/slider/slider.tsx#L37-L94) + +### Switch（开关） + +- 能力：布尔开关，支持自定义文案插槽 +- 关键点： + - 支持 checkedChildren/unCheckedChildren 插槽 + - onChange 触发 onValueChange +- 典型用法路径 + - [开关组件:6-39](file://frontend/antd/switch/switch.tsx#L6-L39) + +章节来源 + +- [frontend/antd/switch/switch.tsx:6-39](file://frontend/antd/switch/switch.tsx#L6-L39) + +### TimePicker（时间选择） + +- 能力：时间选择、范围选择、面板自定义、禁用时间 +- 关键点： + - 内部将输入值格式化为 dayjs 并在 onChange/onPanelChange/onCalendarChange 输出秒级时间戳 + - 支持 cellRender、panelRender、renderExtraFooter 等 slots +- 典型用法路径 + - [时间选择组件:37-198](file://frontend/antd/time-picker/time-picker.tsx#L37-L198) + +章节来源 + +- [frontend/antd/time-picker/time-picker.tsx:37-198](file://frontend/antd/time-picker/time-picker.tsx#L37-L198) + +### Transfer（穿梭框） + +- 能力：左右列表互转，支持标题、全选标签、操作按钮、渲染与过滤 +- 关键点： + - onChange 返回 targetKeys + - 支持 titles/selectAllLabels/actions 插槽 + - 支持 render/footer/locale.notFoundContent +- 典型用法路径 + - [穿梭框组件:9-110](file://frontend/antd/transfer/transfer.tsx#L9-L110) + +章节来源 + +- [frontend/antd/transfer/transfer.tsx:9-110](file://frontend/antd/transfer/transfer.tsx#L9-L110) + +### TreeSelect（树选择） + +- 能力：树形结构选择，支持动态加载、过滤、标签渲染、下拉面板自定义 +- 关键点： + - 支持 treeData 与 children 两种数据源 + - 支持 dropdownRender/popupRender/tagRender/treeTitleRender + - 支持 allowClear.clearIcon、prefix/suffix、switcherIcon、maxTagPlaceholder、notFoundContent + - onLoadData 通过包装函数接入 +- 典型用法路径 + - [树选择组件:14-161](file://frontend/antd/tree-select/tree-select.tsx#L14-L161) + +章节来源 + +- [frontend/antd/tree-select/tree-select.tsx:14-161](file://frontend/antd/tree-select/tree-select.tsx#L14-L161) + +### Upload（文件上传，待完善） + +- 当前仓库未提供 Upload 的前端封装实现，无法给出 API 详情与示例路径 +- 建议参考 Ant Design 官方 Upload 组件并在前端层按现有封装模式添加 onValueChange 与插槽支持 + +[本节不涉及具体文件分析，故无章节来源] + +## 依赖关系分析 + +- 组件间耦合：多数组件通过统一的 sveltify 包装与 hooks（useValueChange、useFunction、renderItems、renderParamsSlot）解耦 +- 外部依赖：Ant Design React 组件库、dayjs（日期时间格式化）、React Slot/Svelte Preprocess（插槽系统） +- 表单集成：Form 组件集中管理表单状态与动作，其他组件通过 onValueChange 与其协作 + +```mermaid +graph LR +A["AntD React 组件库"] --> B["sveltify 包装"] +B --> C["各数据录入组件"] +C --> D["hooks: useValueChange/useFunction"] +C --> E["renderItems/renderParamsSlot"] +F["Form 组件"] --> C +``` + +图表来源 + +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/input/input.tsx:3-42](file://frontend/antd/input/input.tsx#L3-L42) +- [frontend/antd/select/select.tsx:49-56](file://frontend/antd/select/select.tsx#L49-L56) + +章节来源 + +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/input/input.tsx:3-42](file://frontend/antd/input/input.tsx#L3-L42) +- [frontend/antd/select/select.tsx:49-56](file://frontend/antd/select/select.tsx#L49-L56) + +## 性能考量 + +- 受控与非受控：优先使用受控组件（value + onValueChange），避免重复渲染与状态漂移 +- 插槽与函数：尽量将复杂插槽逻辑外置为函数，减少不必要的重新渲染 +- 选项渲染：Select/Cascader/TreeSelect/mentions 等组件建议传入静态 options，避免每次渲染生成新数组 +- 日期时间：DatePicker/TimePicker 内部对 dayjs 进行格式化，避免在父组件中重复转换 +- 滑块与评分：Rate/Slider 的自定义字符/标签应保持轻量，避免重型 DOM 结构 + +[本节为通用指导，不直接分析具体文件] + +## 故障排查指南 + +- 表单动作无效 + - 确认 Form 的 formAction 设置为 reset/submit/validate，并在完成操作后重置该值 + - 参考路径：[表单动作处理:32-45](file://frontend/antd/form/form.tsx#L32-L45) +- 值未更新 + - 确保 onValueChange 已正确设置并触发 + - 参考路径：[输入组件值变更:49-54](file://frontend/antd/input/input.tsx#L49-L54) +- 日期时间格式异常 + - DatePicker/TimePicker 输出为秒级时间戳，确保后端按需转换 + - 参考路径：[日期格式化:26-38](file://frontend/antd/date-picker/date-picker.tsx#L26-L38) +- 选项不显示或过滤失效 + - 检查 options 是否传入，或 children 渲染是否正确 + - 参考路径：[Select 选项渲染:64-77](file://frontend/antd/select/select.tsx#L64-L77) +- 颜色格式不一致 + - ColorPicker 支持 rgb/hex/hsb 输出，确认 value_format 配置 + - 参考路径：[颜色格式化:71-95](file://frontend/antd/color-picker/color-picker.tsx#L71-L95) + +章节来源 + +- [frontend/antd/form/form.tsx:32-45](file://frontend/antd/form/form.tsx#L32-L45) +- [frontend/antd/input/input.tsx:49-54](file://frontend/antd/input/input.tsx#L49-L54) +- [frontend/antd/date-picker/date-picker.tsx:26-38](file://frontend/antd/date-picker/date-picker.tsx#L26-L38) +- [frontend/antd/select/select.tsx:64-77](file://frontend/antd/select/select.tsx#L64-L77) +- [frontend/antd/color-picker/color-picker.tsx:71-95](file://frontend/antd/color-picker/color-picker.tsx#L71-L95) + +## 结论 + +ModelScope Studio 的数据录入组件通过统一的封装模式实现了与 Ant Design 的无缝对接，提供了丰富的插槽与函数式属性，满足多样化的业务需求。建议在实际使用中遵循受控组件原则、合理利用插槽与函数、注意日期时间与颜色格式的转换，并结合 Form 组件实现完整的表单交互闭环。 + +[本节为总结性内容，不直接分析具体文件] + +## 附录 + +### 组件 API 概览（按主题分类） + +- 文本输入 + - Input：支持 value、onValueChange、addonBefore/After、prefix/suffix、allowClear.clearIcon、showCount.formatter + - 参考路径：[文本输入组件:10-116](file://frontend/antd/input/input.tsx#L10-L116) + - InputNumber：支持 value、onValueChange、formatter、parser、controls.upIcon/downIcon、addonBefore/After、prefix/suffix + - 参考路径：[数值输入组件:7-91](file://frontend/antd/input-number/input-number.tsx#L7-L91) + - AutoComplete：支持 value、onValueChange、options、filterOption、dropdownRender、popupRender、allowClear.clearIcon、notFoundContent + - 参考路径：[自动完成组件:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) + - Mentions：支持 value、onValueChange、options、filterOption、validateSearch、getPopupContainer、notFoundContent + - 参考路径：[提及组件:11-77](file://frontend/antd/mentions/mentions.tsx#L11-L77) + +- 选择器 + - Select：支持 value、onValueChange、options、filterOption、filterSort、allowClear.clearIcon、prefix/removeIcon/suffixIcon、notFoundContent、menuItemSelectedIcon、dropdownRender/popupRender/optionRender/tagRender/labelRender + - 参考路径：[选择器组件:11-178](file://frontend/antd/select/select.tsx#L11-L178) + - Cascader：支持 value、onValueChange、options、showSearch、loadData、displayRender/tagRender/optionRender、dropdownRender/popupRender、allowClear.clearIcon、prefix/suffixIcon、expandIcon、removeIcon、notFoundContent、maxTagPlaceholder + - 参考路径：[级联选择组件:19-204](file://frontend/antd/cascader/cascader.tsx#L19-L204) + - TreeSelect：支持 value、onValueChange、treeData、filterTreeNode、loadData、dropdownRender/popupRender/tagRender/treeTitleRender、allowClear.clearIcon、prefix/suffix、switcherIcon、notFoundContent、maxTagPlaceholder + - 参考路径：[树选择组件:14-161](file://frontend/antd/tree-select/tree-select.tsx#L14-L161) + +- 日期与时间 + - DatePicker：支持 value、onChange/onPanelChange、pickerValue/defaultPickerValue、showTime、disabledDate/disabledTime、cellRender/panelRender、presets、renderExtraFooter、prevIcon/nextIcon/suffixIcon/superNextIcon/superPrevIcon、allowClear.clearIcon + - 参考路径：[日期选择组件:40-231](file://frontend/antd/date-picker/date-picker.tsx#L40-L231) + - TimePicker：支持 value、onChange/onPanelChange/onCalendarChange、pickerValue/defaultPickerValue、disabledDate/disabledTime、cellRender/panelRender、renderExtraFooter、prevIcon/nextIcon/suffixIcon/superNextIcon/superPrevIcon、allowClear.clearIcon + - 参考路径：[时间选择组件:37-198](file://frontend/antd/time-picker/time-picker.tsx#L37-L198) + +- 交互与评分 + - Checkbox：支持 value、onValueChange、onChange + - 参考路径：[复选框组件:4-19](file://frontend/antd/checkbox/checkbox.tsx#L4-L19) + - Radio：支持 value、onValueChange、onChange、主题 token 注入 + - 参考路径：[单选框组件:6-29](file://frontend/antd/radio/radio.tsx#L6-L29) + - Rate：支持 value、onValueChange、onChange、character 插槽/函数 + - 参考路径：[评分组件:6-42](file://frontend/antd/rate/rate.tsx#L6-L42) + - Switch：支持 value、onChange、checkedChildren/unCheckedChildren 插槽 + - 参考路径：[开关组件:6-39](file://frontend/antd/switch/switch.tsx#L6-L39) + - Slider：支持 value、onChange、marks（children 渲染）、tooltip.formatter 插槽 + - 参考路径：[滑块组件:37-94](file://frontend/antd/slider/slider.tsx#L37-L94) + +- 颜色与表单 + - ColorPicker：支持 value、onValueChange、onChange、value_format（rgb/hex/hsb）、presets、panelRender、showText + - 参考路径：[颜色选择器组件:11-103](file://frontend/antd/color-picker/color-picker.tsx#L11-L103) + - Form：支持 value、onValueChange、formAction（reset/submit/validate）、requiredMark、feedbackIcons + - 参考路径：[表单组件:8-76](file://frontend/antd/form/form.tsx#L8-L76) + +- 穿梭框 + - Transfer：支持 value（targetKeys）、onChange、titles/selectAllLabels/actions 插槽、render/footer/locale.notFoundContent、selectionsIcon + - 参考路径：[穿梭框组件:9-110](file://frontend/antd/transfer/transfer.tsx#L9-L110) + +[本节为概览性汇总，不直接分析具体文件] diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\351\200\232\347\224\250\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\351\200\232\347\224\250\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..1e8e5c1e --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Ant Design \347\273\204\344\273\266 API/\351\200\232\347\224\250\347\273\204\344\273\266 API.md" @@ -0,0 +1,442 @@ +# 通用组件 API + + +**本文引用的文件** +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/float-button/float-button.tsx](file://frontend/antd/float-button/float-button.tsx) +- [frontend/antd/float-button/Index.svelte](file://frontend/antd/float-button/Index.svelte) +- [frontend/antd/icon/icon.tsx](file://frontend/antd/icon/icon.tsx) +- [frontend/antd/icon/Index.svelte](file://frontend/antd/icon/Index.svelte) +- [frontend/antd/typography/typography.base.tsx](file://frontend/antd/typography/typography.base.tsx) +- [frontend/antd/typography/Base.svelte](file://frontend/antd/typography/Base.svelte) +- [frontend/antd/typography/title/Index.svelte](file://frontend/antd/typography/title/Index.svelte) +- [frontend/antd/typography/paragraph/Index.svelte](file://frontend/antd/typography/paragraph/Index.svelte) +- [frontend/antd/typography/text/Index.svelte](file://frontend/antd/typography/text/Index.svelte) +- [frontend/antd/typography/link/Index.svelte](file://frontend/antd/typography/link/Index.svelte) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 中基于 Ant Design 的通用组件 API 参考文档，覆盖 Button、FloatButton、Icon、Typography 等组件。内容包括： + +- 属性定义与事件处理 +- 插槽（slots）与样式定制 +- 使用场景与最佳实践 +- TypeScript 类型与与原生 Ant Design 对应关系 +- 响应式设计、无障碍与性能优化建议 + +## 项目结构 + +这些组件采用“Svelte 入口 + React 包装”的统一模式：Svelte 入口负责属性透传、类名与可见性控制；React 包装负责对接 Ant Design 组件，实现插槽渲染与复杂交互。 + +```mermaid +graph TB +subgraph "按钮 Button" +B_Index["button/Index.svelte"] +B_Impl["button/button.tsx"] +end +subgraph "悬浮按钮 FloatButton" +F_Index["float-button/Index.svelte"] +F_Impl["float-button/float-button.tsx"] +end +subgraph "图标 Icon" +I_Index["icon/Index.svelte"] +I_Impl["icon/icon.tsx"] +end +subgraph "排版 Typography" +T_Base["typography/Base.svelte"] +T_Impl["typography/typography.base.tsx"] +T_Title["typography/title/Index.svelte"] +T_Para["typography/paragraph/Index.svelte"] +T_Text["typography/text/Index.svelte"] +T_Link["typography/link/Index.svelte"] +end +B_Index --> B_Impl +F_Index --> F_Impl +I_Index --> I_Impl +T_Title --> T_Base --> T_Impl +T_Para --> T_Base +T_Text --> T_Base +T_Link --> T_Base +``` + +图表来源 + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/float-button/Index.svelte:1-70](file://frontend/antd/float-button/Index.svelte#L1-L70) +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) +- [frontend/antd/icon/icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [frontend/antd/typography/Base.svelte:1-85](file://frontend/antd/typography/Base.svelte#L1-L85) +- [frontend/antd/typography/typography.base.tsx:1-170](file://frontend/antd/typography/typography.base.tsx#L1-L170) +- [frontend/antd/typography/title/Index.svelte:1-12](file://frontend/antd/typography/title/Index.svelte#L1-L12) +- [frontend/antd/typography/paragraph/Index.svelte:1-12](file://frontend/antd/typography/paragraph/Index.svelte#L1-L12) +- [frontend/antd/typography/text/Index.svelte:1-12](file://frontend/antd/typography/text/Index.svelte#L1-L12) +- [frontend/antd/typography/link/Index.svelte:1-12](file://frontend/antd/typography/link/Index.svelte#L1-L12) + +章节来源 + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/float-button/Index.svelte:1-70](file://frontend/antd/float-button/Index.svelte#L1-L70) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) +- [frontend/antd/typography/Base.svelte:1-85](file://frontend/antd/typography/Base.svelte#L1-L85) + +## 核心组件 + +- Button：对齐 Ant Design Button，支持 icon、loading.icon 插槽，以及 value 与 children 的优先级逻辑。 +- FloatButton：对齐 Ant Design FloatButton，支持 icon、description、tooltip、badge.count 插槽，以及 tooltip 配置函数桥接。 +- Icon：支持内置 Ant Design 图标与 IconFont，支持自定义 component 插槽。 +- Typography：统一的排版基座，支持 title、paragraph、text、link 四种形态，支持 copyable、editable、ellipsis 的插槽化配置。 + +章节来源 + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/icon/icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [frontend/antd/typography/typography.base.tsx:1-170](file://frontend/antd/typography/typography.base.tsx#L1-L170) + +## 架构总览 + +组件统一通过 Svelte 入口完成： + +- 属性透传与额外属性合并 +- 可见性控制与类名拼接 +- 插槽上下文注入 +- 懒加载与异步组件渲染 + +React 包装层完成： + +- 与 Ant Design 组件对接 +- 插槽到 ReactSlot 的映射 +- 复杂配置对象（如 tooltip、ellipsis）的条件渲染与函数桥接 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 入口(Index.svelte)" +participant Loader as "importComponent" +participant ReactImpl as "React 包装(button.tsx/float-button.tsx/icon.tsx/typography.base.tsx)" +participant AntD as "Ant Design 组件" +Svelte->>Loader : 动态导入组件模块 +Loader-->>Svelte : 返回可渲染组件 +Svelte->>ReactImpl : 传递 props + slots + value +ReactImpl->>AntD : 渲染并注入插槽/配置 +AntD-->>ReactImpl : 渲染结果 +ReactImpl-->>Svelte : 渲染结果 +``` + +图表来源 + +- [frontend/antd/button/Index.svelte:10-73](file://frontend/antd/button/Index.svelte#L10-L73) +- [frontend/antd/button/button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) +- [frontend/antd/float-button/Index.svelte:10-69](file://frontend/antd/float-button/Index.svelte#L10-L69) +- [frontend/antd/float-button/float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) +- [frontend/antd/icon/Index.svelte:10-66](file://frontend/antd/icon/Index.svelte#L10-L66) +- [frontend/antd/icon/icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- [frontend/antd/typography/Base.svelte:11-83](file://frontend/antd/typography/Base.svelte#L11-L83) +- [frontend/antd/typography/typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) + +## 组件详解 + +### Button（按钮） + +- 能力概览 + - 支持 Ant Design Button 的全部属性与事件 + - 插槽：icon、loading.icon + - 内容优先级：当存在子节点时优先渲染子节点，否则回退到 value +- 关键行为 + - 将 slots.icon 注入到 Ant Design Button 的 icon + - 将 slots.loading.icon 注入到 loading.icon，并保留 loading.delay（若为对象） +- 使用场景 + - 基础按钮、带图标的按钮、加载中的按钮 +- 示例（路径） + - 基本用法：[frontend/antd/button/Index.svelte:59-73](file://frontend/antd/button/Index.svelte#L59-L73) + - 插槽图标：[frontend/antd/button/button.tsx:18-30](file://frontend/antd/button/button.tsx#L18-L30) +- 类型与原生对应 + - 通过 sveltify 包装 Ant Design Button 的 GetProps 类型，保持一致的属性签名 +- 样式与无障碍 + - 通过 elem_classes/elem_id/elem_style 控制样式与 ID；无障碍由 Ant Design 提供 +- 性能 + - 子节点检测与条件渲染，避免不必要的 DOM 更新 + +```mermaid +flowchart TD +Start(["进入 Button 渲染"]) --> HasChildren{"是否存在子节点？"} +HasChildren --> |是| RenderChild["渲染子节点"] +HasChildren --> |否| RenderValue["渲染 value"] +RenderChild --> InjectIcon["注入 slots.icon 到 AntD Button"] +RenderValue --> InjectIcon +InjectIcon --> LoadingCfg{"是否配置 loading.icon？"} +LoadingCfg --> |是| MergeLoading["合并 loading 与 loading.icon.delay"] +LoadingCfg --> |否| PassThrough["直接透传 loading"] +MergeLoading --> End(["完成"]) +PassThrough --> End +``` + +图表来源 + +- [frontend/antd/button/button.tsx:11-36](file://frontend/antd/button/button.tsx#L11-L36) + +章节来源 + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +### FloatButton（悬浮按钮） + +- 能力概览 + - 支持 Ant Design FloatButton 的全部属性与事件 + - 插槽：icon、description、tooltip、tooltip.title、badge.count + - tooltip 支持对象配置，内部将 afterOpenChange、getPopupContainer 等函数桥接到 useFunction +- 关键行为 + - 当存在 slots.tooltip 或 tooltip 为对象时启用 tooltip 配置 + - 将 slots.icon/description/badge.count 映射到对应属性 +- 使用场景 + - 返回顶部、悬浮操作面板、带描述与徽标的悬浮入口 +- 示例（路径） + - 基本用法：[frontend/antd/float-button/Index.svelte:56-69](file://frontend/antd/float-button/Index.svelte#L56-L69) + - 插槽与 tooltip 配置：[frontend/antd/float-button/float-button.tsx:19-72](file://frontend/antd/float-button/float-button.tsx#L19-L72) +- 类型与原生对应 + - 通过 sveltify 包装 Ant Design FloatButton 的 GetProps 类型，并扩展 id 字段 +- 样式与无障碍 + - 通过 elem_classes/elem_id/elem_style 控制样式与 ID；无障碍由 Ant Design 提供 +- 性能 + - 条件渲染 tooltip 与插槽，减少不必要开销 + +```mermaid +sequenceDiagram +participant S as "Svelte 入口" +participant R as "React 包装" +participant T as "tooltip 配置" +participant A as "AntD FloatButton" +S->>R : 传递 props + slots +R->>T : 检查 tooltip 是否为对象或存在 slots.tooltip.title +alt 启用 tooltip +T-->>R : 合并配置并桥接函数 +else 不启用 +T-->>R : 直接透传 tooltip +end +R->>A : 渲染并注入 icon/description/badge/count +A-->>R : 渲染结果 +``` + +图表来源 + +- [frontend/antd/float-button/float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) +- [frontend/antd/float-button/Index.svelte:1-70](file://frontend/antd/float-button/Index.svelte#L1-L70) + +章节来源 + +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/float-button/Index.svelte:1-70](file://frontend/antd/float-button/Index.svelte#L1-L70) + +### Icon（图标） + +- 能力概览 + - 支持 Ant Design 内置图标名称映射 + - 支持 IconFontProvider 提供的字体图标 + - 插槽：component（用于自定义 SVG 组件） +- 关键行为 + - 若提供 slots.component，则以 Ant Design IconWrapper 渲染自定义组件 + - 否则根据 value 查找内置图标或使用 IconFont.type +- 使用场景 + - 文本内嵌图标、按钮图标、自定义矢量图标 +- 示例（路径） + - 基本用法：[frontend/antd/icon/Index.svelte:52-66](file://frontend/antd/icon/Index.svelte#L52-L66) + - 自定义组件与 IconFont：[frontend/antd/icon/icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- 类型与原生对应 + - 通过 sveltify 包装 Ant Design Icons 的 GetProps 类型，并扩展 value 字段 +- 样式与无障碍 + - 通过 elem_classes/elem_id/elem_style 控制样式与 ID；无障碍由 Ant Design 提供 +- 性能 + - useMemo 缓存自定义组件，避免重复创建 + +```mermaid +flowchart TD +Start(["进入 Icon 渲染"]) --> HasCustom{"是否存在 slots.component？"} +HasCustom --> |是| WrapCustom["以 Ant Design IconWrapper 包裹自定义组件"] +HasCustom --> |否| LookupIcon{"value 是否为内置图标名？"} +LookupIcon --> |是| RenderBuiltin["渲染内置图标"] +LookupIcon --> |否| UseIconFont{"是否存在 IconFont 上下文？"} +UseIconFont --> |是| RenderIconFont["使用 IconFont(type=value)"] +UseIconFont --> |否| Noop["不渲染"] +WrapCustom --> End(["完成"]) +RenderBuiltin --> End +RenderIconFont --> End +Noop --> End +``` + +图表来源 + +- [frontend/antd/icon/icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) + +章节来源 + +- [frontend/antd/icon/icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) + +### Typography（排版） + +- 能力概览 + - 统一基座：title、paragraph、text、link 四种形态 + - 支持 copyable、editable、ellipsis 的插槽化配置 + - 插槽：copyable.icon、copyable.tooltips、editable.icon、editable.tooltip、editable.enterIcon、ellipsis.symbol、ellipsis.tooltip、ellipsis.tooltip.title +- 关键行为 + - 根据 component 选择对应 Ant Design Typography 组件 + - 条件注入 copyable、editable、ellipsis 配置 + - ellipsis 在 link 组件上启用条件不同 +- 使用场景 + - 标题、段落、文本、链接的统一排版与交互 +- 示例（路径） + - 基本用法：[frontend/antd/typography/Base.svelte:65-84](file://frontend/antd/typography/Base.svelte#L65-L84) + - 子组件别名：[frontend/antd/typography/title/Index.svelte:9-11](file://frontend/antd/typography/title/Index.svelte#L9-L11) + - 插槽与配置合并：[frontend/antd/typography/typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) +- 类型与原生对应 + - 通过 sveltify 包装 Ant Design Typography 的多种类型，并扩展 component 与 value 字段 +- 样式与无障碍 + - 通过 elem_classes/elem_id/elem_style 控制样式与 ID；无障碍由 Ant Design 提供 +- 性能 + - 条件渲染与插槽目标收集，减少不必要开销 + +```mermaid +sequenceDiagram +participant S as "Base.svelte" +participant R as "typography.base.tsx" +participant T as "Typography 组件" +participant C as "copyable/editable/ellipsis" +S->>R : 传递 component/value + slots +R->>R : 解析 copyable/editable/ellipsis 配置 +alt 支持对应能力 +R->>C : 注入 slots.icon/tooltip/symbol/... 并合并配置 +else 不支持 +R->>C : 不注入，保持 undefined +end +R->>T : 渲染对应 Typography 组件 +T-->>R : 渲染结果 +``` + +图表来源 + +- [frontend/antd/typography/Base.svelte:11-83](file://frontend/antd/typography/Base.svelte#L11-L83) +- [frontend/antd/typography/typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) + +章节来源 + +- [frontend/antd/typography/typography.base.tsx:1-170](file://frontend/antd/typography/typography.base.tsx#L1-L170) +- [frontend/antd/typography/Base.svelte:1-85](file://frontend/antd/typography/Base.svelte#L1-L85) +- [frontend/antd/typography/title/Index.svelte:1-12](file://frontend/antd/typography/title/Index.svelte#L1-L12) +- [frontend/antd/typography/paragraph/Index.svelte:1-12](file://frontend/antd/typography/paragraph/Index.svelte#L1-L12) +- [frontend/antd/typography/text/Index.svelte:1-12](file://frontend/antd/typography/text/Index.svelte#L1-L12) +- [frontend/antd/typography/link/Index.svelte:1-12](file://frontend/antd/typography/link/Index.svelte#L1-L12) + +## 依赖关系分析 + +- 组件间耦合 + - Typography 的四个子组件仅作为 Base 的别名，降低重复与耦合 + - Button/FloatButton/Icon 的入口与实现分离，便于维护与扩展 +- 外部依赖 + - Ant Design 组件库（Button、FloatButton、Typography、Icon 等） + - @svelte-preprocess-react（sveltify、ReactSlot、useFunction 等） + - 工具函数：useTargets、useSlotsChildren、omitUndefinedProps、renderParamsSlot 等 +- 潜在循环依赖 + - 未发现直接循环依赖；各组件按入口 → 实现 → Ant Design 的单向依赖 + +```mermaid +graph LR +S_Button["button/Index.svelte"] --> R_Button["button/button.tsx"] +S_Float["float-button/Index.svelte"] --> R_Float["float-button/float-button.tsx"] +S_Icon["icon/Index.svelte"] --> R_Icon["icon/icon.tsx"] +S_TBase["typography/Base.svelte"] --> R_TBase["typography/typography.base.tsx"] +R_TBase --> AntD["Ant Design 组件"] +R_Button --> AntD +R_Float --> AntD +R_Icon --> AntD +``` + +图表来源 + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/float-button/Index.svelte:1-70](file://frontend/antd/float-button/Index.svelte#L1-L70) +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) +- [frontend/antd/icon/icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [frontend/antd/typography/Base.svelte:1-85](file://frontend/antd/typography/Base.svelte#L1-L85) +- [frontend/antd/typography/typography.base.tsx:1-170](file://frontend/antd/typography/typography.base.tsx#L1-L170) + +章节来源 + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/float-button/Index.svelte:1-70](file://frontend/antd/float-button/Index.svelte#L1-L70) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) +- [frontend/antd/typography/Base.svelte:1-85](file://frontend/antd/typography/Base.svelte#L1-L85) + +## 性能考量 + +- 按需渲染 + - 通过条件判断与 slots 检测，仅在需要时注入配置与插槽，减少渲染成本 +- 函数桥接 + - tooltip 等配置中的回调通过 useFunction 桥接，避免每次渲染创建新函数 +- 计算缓存 + - Icon 使用 useMemo 缓存自定义组件，避免重复创建 +- 异步加载 + - 通过 importComponent 懒加载，降低首屏压力 + +## 故障排查指南 + +- 插槽未生效 + - 确认插槽名称与组件支持列表一致（如 Button 的 icon、loading.icon；FloatButton 的 icon/description/tooltip/badge.count；Typography 的 copyable._、editable._、ellipsis.\*） +- Tooltip 回调无效 + - 确认 tooltip 为对象时，相关回调已通过 useFunction 桥接 +- 自定义图标不显示 + - 确认 value 为有效图标名或 IconFont 上下文可用 +- ellipsis 在 link 上不生效 + - 确认 ellipsis 配置存在或插槽已提供 +- 可见性问题 + - 确认 visible 属性正确传递至入口组件 + +章节来源 + +- [frontend/antd/button/button.tsx:11-36](file://frontend/antd/button/button.tsx#L11-L36) +- [frontend/antd/float-button/float-button.tsx:19-72](file://frontend/antd/float-button/float-button.tsx#L19-L72) +- [frontend/antd/icon/icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- [frontend/antd/typography/typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) +- [frontend/antd/button/Index.svelte:59-73](file://frontend/antd/button/Index.svelte#L59-L73) +- [frontend/antd/float-button/Index.svelte:56-69](file://frontend/antd/float-button/Index.svelte#L56-L69) +- [frontend/antd/icon/Index.svelte:52-66](file://frontend/antd/icon/Index.svelte#L52-L66) +- [frontend/antd/typography/Base.svelte:65-84](file://frontend/antd/typography/Base.svelte#L65-L84) + +## 结论 + +上述组件通过统一的 Svelte + React 包装模式，实现了与 Ant Design 的深度对齐与灵活扩展。借助插槽系统与工具函数，开发者可以在保持类型安全的同时，实现丰富的交互与样式定制。建议在实际项目中遵循本文档的属性与插槽约定，结合性能与无障碍建议，获得更稳定与可维护的用户体验。 + +## 附录 + +- 属性与插槽对照（摘要） + - Button + - 属性：继承 Ant Design Button 所有属性 + - 插槽：icon、loading.icon + - FloatButton + - 属性：继承 Ant Design FloatButton 所有属性 + - 插槽：icon、description、tooltip、tooltip.title、badge.count + - Icon + - 属性：value（字符串），继承 Ant Design Icon 所有属性 + - 插槽：component（自定义 SVG 组件） + - Typography + - 属性：component（'title'|'paragraph'|'text'|'link'），value（字符串） + - 插槽：copyable.icon、copyable.tooltips；editable.icon、editable.tooltip、editable.enterIcon；ellipsis.symbol、ellipsis.tooltip、ellipsis.tooltip.title diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Svelte \347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Svelte \347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..9094548d --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/Svelte \347\273\204\344\273\266 API.md" @@ -0,0 +1,415 @@ +# Svelte 组件 API + + +**本文引用的文件** +- [frontend/package.json](file://frontend/package.json) +- [frontend/tsconfig.json](file://frontend/tsconfig.json) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/form/Index.svelte](file://frontend/antd/form/Index.svelte) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/layout/Index.svelte](file://frontend/antd/layout/Index.svelte) +- [frontend/antd/modal/Index.svelte](file://frontend/antd/modal/Index.svelte) +- [frontend/antd/table/Index.svelte](file://frontend/antd/table/Index.svelte) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/createFunction.ts](file://frontend/utils/createFunction.ts) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能与最佳实践](#性能与最佳实践) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 前端 Svelte 组件 API 参考文档，聚焦于基于 Ant Design（Antd）生态的 Svelte 组件封装体系。文档覆盖以下方面： + +- 组件属性定义：props 接口、默认值与类型约束 +- 事件系统：用户交互事件、状态变更事件与自定义事件 +- 插槽系统：默认插槽、具名插槽与作用域插槽的使用 +- 生命周期与渲染：组件实例化、异步加载与条件渲染 +- 组件间通信：父子、兄弟与跨层级通信模式 +- 样式定制：CSS 类名、主题变量与内联样式 +- TypeScript 类型：接口规范、泛型使用与类型推导 +- 性能优化：按需加载、派生计算与事件节流建议 + +## 项目结构 + +前端采用多包组织方式，核心组件位于 frontend/antd 与 frontend/antdx，通过 Svelte 5 与 React 组件桥接方案实现 Antd 组件在 Svelte 中的使用。 + +```mermaid +graph TB +subgraph "前端包" +A["frontend/package.json"] +B["frontend/tsconfig.json"] +end +subgraph "Antd 组件层" +BTN["antd/button/Index.svelte"] +BTN_TS["antd/button/button.tsx"] +FORM["antd/form/Index.svelte"] +FORM_TS["antd/form/form.tsx"] +LYT["antd/layout/Index.svelte"] +MODAL["antd/modal/Index.svelte"] +TAB["antd/table/Index.svelte"] +end +subgraph "通用工具" +RS["utils/renderSlot.tsx"] +CF["utils/createFunction.ts"] +end +A --> BTN +A --> FORM +A --> LYT +A --> MODAL +A --> TAB +BTN --> BTN_TS +FORM --> FORM_TS +BTN_TS --> RS +FORM_TS --> RS +BTN_TS --> CF +FORM_TS --> CF +``` + +**图表来源** + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/modal/Index.svelte:1-63](file://frontend/antd/modal/Index.svelte#L1-L63) +- [frontend/antd/table/Index.svelte:1-61](file://frontend/antd/table/Index.svelte#L1-L61) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) + +**章节来源** + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) + +## 核心组件 + +本节概述主要组件的职责与共性特征： + +- 按钮（Button）：封装 Antd Button，支持图标与加载态插槽，具备可见性控制与类名拼接。 +- 表单（Form）：封装 Antd Form，提供值同步、动作触发（重置/提交/校验）、必填标记与反馈图标插槽。 +- 布局（Layout）：基础布局容器，透传 children 与组件标识。 +- 模态框（Modal）：封装 Antd Modal，支持可见性控制与插槽。 +- 表格（Table）：封装 Antd Table，支持可见性控制与插槽。 + +**章节来源** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/modal/Index.svelte:1-63](file://frontend/antd/modal/Index.svelte#L1-L63) +- [frontend/antd/table/Index.svelte:1-61](file://frontend/antd/table/Index.svelte#L1-L61) + +## 架构总览 + +组件采用“Svelte 层 + React 封装层 + 工具函数”的三层架构： + +- Svelte 层：负责属性收集、插槽解析、条件渲染与异步加载。 +- React 封装层：使用 sveltify 将 Antd 组件桥接为 Svelte 可用的组件，并处理插槽与回调。 +- 工具函数：提供插槽渲染、函数字符串转函数等能力。 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 组件层(Index.svelte)" +participant Utils as "工具(renderSlot.tsx/createFunction.ts)" +participant ReactComp as "React 封装层(button.tsx/form.tsx)" +participant Antd as "Antd 组件" +Svelte->>Svelte : 收集 props 与插槽 +Svelte->>ReactComp : 异步导入并传递 props +ReactComp->>Utils : 渲染插槽/函数包装 +ReactComp->>Antd : 渲染 Antd 组件 +Antd-->>ReactComp : 回调事件 +ReactComp-->>Svelte : 触发更新/动作 +``` + +**图表来源** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) + +## 组件详解 + +### 按钮（Button） + +- 职责：将 Antd Button 暴露为 Svelte 组件，支持图标与加载态插槽；根据可见性条件渲染；拼接样式类名。 +- 关键属性（props） + - additional_props?: Record
包信息"] +C["@modelscope-studio/pro-chatbot
包信息"] +M["@modelscope-studio/pro-monaco-editor
包信息"] +U["@modelscope-studio/pro-multimodal-input
包信息"] +W["@modelscope-studio/pro-web-sandbox
包信息"] +end +subgraph "Svelte 桥接层" +CI["chatbot/Index.svelte"] +MI["monaco-editor/Index.svelte"] +UI["multimodal-input/Index.svelte"] +WI["web-sandbox/Index.svelte"] +end +subgraph "运行时共享上下文" +G["gradio.shared.*
root/api_prefix/theme"] +end +P --> CI +P --> MI +P --> UI +P --> WI +C --> CI +M --> MI +U --> UI +W --> WI +CI --> G +MI --> G +UI --> G +WI --> G +``` + +图示来源 + +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) +- [frontend/pro/chatbot/package.json:1-15](file://frontend/pro/chatbot/package.json#L1-L15) +- [frontend/pro/monaco-editor/package.json:1-15](file://frontend/pro/monaco-editor/package.json#L1-L15) +- [frontend/pro/multimodal-input/package.json:1-15](file://frontend/pro/multimodal-input/package.json#L1-L15) +- [frontend/pro/web-sandbox/package.json:1-15](file://frontend/pro/web-sandbox/package.json#L1-L15) +- [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) +- [frontend/pro/monaco-editor/Index.svelte:1-101](file://frontend/pro/monaco-editor/Index.svelte#L1-L101) +- [frontend/pro/multimodal-input/Index.svelte:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) +- [frontend/pro/web-sandbox/Index.svelte:1-76](file://frontend/pro/web-sandbox/Index.svelte#L1-L76) + +章节来源 + +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) +- [frontend/pro/chatbot/package.json:1-15](file://frontend/pro/chatbot/package.json#L1-L15) +- [frontend/pro/monaco-editor/package.json:1-15](file://frontend/pro/monaco-editor/package.json#L1-L15) +- [frontend/pro/multimodal-input/package.json:1-15](file://frontend/pro/multimodal-input/package.json#L1-L15) +- [frontend/pro/web-sandbox/package.json:1-15](file://frontend/pro/web-sandbox/package.json#L1-L15) + +## 核心组件 + +本节概述四个专业组件的职责与通用能力： + +- Chatbot：对话消息流展示与交互，支持文本、工具调用、文件、欢迎语与建议提示等复合内容，具备用户/助手动作（复制、编辑、删除、点赞/踩、重试）与主题适配。 +- MultimodalInput：多模态输入入口，支持文本与文件上传，提供上传钩子与事件回调，便于与 Gradio 客户端集成。 +- WebSandbox：可编译与渲染的网页沙盒，提供编译错误/成功与渲染错误事件，支持主题模式与插槽扩展。 +- MonacoEditor：基于 Monaco 的代码编辑器，支持本地或 CDN 加载器初始化，提供值变更事件与主题模式。 + +章节来源 + +- [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) +- [frontend/pro/multimodal-input/Index.svelte:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) +- [frontend/pro/web-sandbox/Index.svelte:1-76](file://frontend/pro/web-sandbox/Index.svelte#L1-L76) +- [frontend/pro/monaco-editor/Index.svelte:1-101](file://frontend/pro/monaco-editor/Index.svelte#L1-L101) + +## 架构总览 + +四个组件均采用统一的桥接模式：Svelte 层负责属性解析、事件回写、动态导入与插槽渲染；底层 TSX 组件承载具体 UI 逻辑；运行时共享上下文（gradio.shared）提供 root、api_prefix、theme 等全局配置。 + +```mermaid +sequenceDiagram +participant App as "应用" +participant S as "Svelte 桥接层" +participant R as "React/TSX 组件" +participant G as "Gradio 共享上下文" +App->>S : 传递属性与插槽 +S->>G : 读取 root/api_prefix/theme +S->>R : 动态导入并传递属性/事件 +R-->>S : 值变更回调 +S->>App : updateProps 回写值 +S-->>App : 渲染插槽内容 +``` + +图示来源 + +- [frontend/pro/chatbot/Index.svelte:14-64](file://frontend/pro/chatbot/Index.svelte#L14-L64) +- [frontend/pro/monaco-editor/Index.svelte:14-89](file://frontend/pro/monaco-editor/Index.svelte#L14-L89) +- [frontend/pro/multimodal-input/Index.svelte:17-66](file://frontend/pro/multimodal-input/Index.svelte#L17-L66) +- [frontend/pro/web-sandbox/Index.svelte:14-57](file://frontend/pro/web-sandbox/Index.svelte#L14-L57) + +## 详细组件分析 + +### Chatbot 组件 API + +- 包导出与入口 + - 包名与导出映射遵循标准，主入口指向 Index.svelte。 +- 属性定义 + - additional_props：附加属性透传 + - as_item：元素标识 + - \_internal：内部布局标记 + - value：消息数组，类型见 ChatbotMessages + - suggestion_select / welcome_prompt_select：事件回调别名映射 + - 可见性与样式：visible、elem_id、elem_classes、elem_style + - 运行时共享：gradio.shared.root、gradio.shared.api_prefix、gradio.shared.theme +- 事件与回调 + - onValueChange：值变更回写到父组件 +- 插槽系统 + - 支持 children 插槽与 slots 映射 +- 数据模型与类型 + - ChatbotMessages、ChatbotMessage、ChatbotMessageContentObject、动作类型（like/dislike/retry/copy/edit/delete）等 +- 高级特性 + - 主题模式继承自 gradio.shared.theme + - 内置欢迎语、建议提示、文件/工具/文本内容的复合展示 +- 使用示例（路径） + - 基础使用与值绑定：[frontend/pro/chatbot/Index.svelte:76-84](file://frontend/pro/chatbot/Index.svelte#L76-L84) + - 事件回写：[frontend/pro/chatbot/Index.svelte:76-80](file://frontend/pro/chatbot/Index.svelte#L76-L80) + - 类型定义参考：[frontend/pro/chatbot/type.ts:160-197](file://frontend/pro/chatbot/type.ts#L160-L197) + +```mermaid +classDiagram +class ChatbotMessage { ++role ++content ++status ++meta ++key +} +class ChatbotMessages { +} +class ChatbotMessageContentObject { ++type ++content ++options +} +ChatbotMessages --> ChatbotMessage +ChatbotMessage --> ChatbotMessageContentObject +``` + +图示来源 + +- [frontend/pro/chatbot/type.ts:137-158](file://frontend/pro/chatbot/type.ts#L137-L158) +- [frontend/pro/chatbot/type.ts:121-135](file://frontend/pro/chatbot/type.ts#L121-L135) + +章节来源 + +- [frontend/pro/chatbot/package.json:1-15](file://frontend/pro/chatbot/package.json#L1-L15) +- [frontend/pro/chatbot/Index.svelte:14-64](file://frontend/pro/chatbot/Index.svelte#L14-L64) +- [frontend/pro/chatbot/Index.svelte:76-84](file://frontend/pro/chatbot/Index.svelte#L76-L84) +- [frontend/pro/chatbot/type.ts:160-197](file://frontend/pro/chatbot/type.ts#L160-L197) + +### MultimodalInput 组件 API + +- 包导出与入口 + - 包名与导出映射遵循标准，主入口指向 Index.svelte。 +- 属性定义 + - additional_props：附加属性透传 + - \_internal：内部标记 + - value：多模态输入值，类型来自底层组件 + - key_press / paste_file / key_down：事件回调别名映射 + - 可见性与样式：visible、elem_id、elem_classes、elem_style + - 运行时共享：gradio.shared.theme +- 事件与回调 + - onValueChange：值变更回写 +- 插槽系统 + - 支持 children 插槽与 slots 映射 +- 文件上传 + - upload 钩子：通过 gradio.shared.client.upload 上传文件，返回 FileData[] +- 使用示例（路径） + - 值绑定与事件回写：[frontend/pro/multimodal-input/Index.svelte:88-92](file://frontend/pro/multimodal-input/Index.svelte#L88-L92) + - 上传流程：[frontend/pro/multimodal-input/Index.svelte:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) + +```mermaid +sequenceDiagram +participant UI as "MultimodalInput" +participant GR as "Gradio 客户端" +participant SV as "Svelte 桥接层" +UI->>GR : upload(prepare_files(files)) +GR-->>UI : FileData[] +UI->>SV : updateProps({ value }) +``` + +图示来源 + +- [frontend/pro/multimodal-input/Index.svelte:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) +- [frontend/pro/multimodal-input/Index.svelte:88-92](file://frontend/pro/multimodal-input/Index.svelte#L88-L92) + +章节来源 + +- [frontend/pro/multimodal-input/package.json:1-15](file://frontend/pro/multimodal-input/package.json#L1-L15) +- [frontend/pro/multimodal-input/Index.svelte:17-66](file://frontend/pro/multimodal-input/Index.svelte#L17-L66) +- [frontend/pro/multimodal-input/Index.svelte:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) + +### WebSandbox 组件 API + +- 包导出与入口 + - 包名与导出映射遵循标准，主入口指向 Index.svelte。 +- 属性定义 + - additional_props：附加属性透传 + - \_internal：内部标记 + - value：沙盒值，类型来自底层组件 + - compile_error / compile_success / render_error：事件回调别名映射 + - 可见性与样式：visible、elem_id、elem_classes、elem_style + - 运行时共享：gradio.shared.theme +- 插槽系统 + - 支持 children 插槽与 slots 映射 +- 使用示例（路径） + - 值绑定与主题：[frontend/pro/web-sandbox/Index.svelte:62-70](file://frontend/pro/web-sandbox/Index.svelte#L62-L70) + +```mermaid +flowchart TD +Start(["开始"]) --> CheckVisible["检查 visible"] +CheckVisible --> |否| End(["结束"]) +CheckVisible --> |是| Load["动态加载 WebSandbox"] +Load --> Render["渲染并传递 value/slots/theme"] +Render --> End +``` + +图示来源 + +- [frontend/pro/web-sandbox/Index.svelte:60-75](file://frontend/pro/web-sandbox/Index.svelte#L60-L75) + +章节来源 + +- [frontend/pro/web-sandbox/package.json:1-15](file://frontend/pro/web-sandbox/package.json#L1-L15) +- [frontend/pro/web-sandbox/Index.svelte:14-57](file://frontend/pro/web-sandbox/Index.svelte#L14-L57) +- [frontend/pro/web-sandbox/Index.svelte:62-70](file://frontend/pro/web-sandbox/Index.svelte#L62-L70) + +### MonacoEditor 组件 API + +- 包导出与入口 + - 包名与导出映射遵循标准，主入口指向 Index.svelte。 +- 属性定义 + - additional_props：附加属性透传 + - \_internal：内部标记 + - value：编辑器初始值 + - \_loader：加载器配置 + - mode：'cdn' | 'local' + - cdn_url：CDN 路径 + - 可见性与样式：visible、elem_id、elem_classes、elem_style + - 运行时共享：gradio.shared.theme +- 事件与回调 + - onValueChange：值变更回写 +- 插槽系统 + - 支持 children 插槽与 slots 映射 +- 加载器机制 + - 本地加载：初始化 Monaco 并按语言注册 Worker + - CDN 加载：设置 vs 路径 +- 使用示例（路径） + - 值绑定与主题：[frontend/pro/monaco-editor/Index.svelte:79-89](file://frontend/pro/monaco-editor/Index.svelte#L79-L89) + - 加载器选择与初始化：[frontend/pro/monaco-editor/Index.svelte:61-70](file://frontend/pro/monaco-editor/Index.svelte#L61-L70) + - 加载器实现：[frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +```mermaid +flowchart TD +A["选择加载器"] --> B{"mode=local?"} +B --> |是| C["initLocalLoader()
注册 Monaco 与 Worker"] +B --> |否| D{"存在 cdn_url?"} +D --> |是| E["initCDNLoader(cdn_url)
设置 vs 路径"] +D --> |否| F["使用默认配置"] +C --> G["完成"] +E --> G +F --> G +``` + +图示来源 + +- [frontend/pro/monaco-editor/Index.svelte:61-70](file://frontend/pro/monaco-editor/Index.svelte#L61-L70) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +章节来源 + +- [frontend/pro/monaco-editor/package.json:1-15](file://frontend/pro/monaco-editor/package.json#L1-L15) +- [frontend/pro/monaco-editor/Index.svelte:14-89](file://frontend/pro/monaco-editor/Index.svelte#L14-L89) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +## 依赖关系分析 + +- 统一依赖链 + - Svelte 桥接层依赖 @svelte-preprocess-react 的 getProps/processProps/importComponent 与插槽工具 + - 各组件通过 gradio.shared 获取共享配置（root、api_prefix、theme） + - 文件上传能力来自 @gradio/client 的 prepare_files 与 client.upload +- 组件间耦合 + - 低耦合：每个组件独立维护自身属性与事件 + - 高内聚：桥接层负责属性处理与动态加载，底层组件专注 UI 逻辑 + +```mermaid +graph LR +SP["@svelte-preprocess-react/*"] --> BR["Svelte 桥接层"] +BR --> CH["Chatbot"] +BR --> ME["MonacoEditor"] +BR --> MU["MultimodalInput"] +BR --> WS["WebSandbox"] +GC["@gradio/client"] --> MU +GS["gradio.shared.*"] --> BR +``` + +图示来源 + +- [frontend/pro/chatbot/Index.svelte:1-12](file://frontend/pro/chatbot/Index.svelte#L1-L12) +- [frontend/pro/monaco-editor/Index.svelte:1-12](file://frontend/pro/monaco-editor/Index.svelte#L1-L12) +- [frontend/pro/multimodal-input/Index.svelte:1-9](file://frontend/pro/multimodal-input/Index.svelte#L1-L9) +- [frontend/pro/web-sandbox/Index.svelte:1-8](file://frontend/pro/web-sandbox/Index.svelte#L1-L8) + +章节来源 + +- [frontend/pro/chatbot/Index.svelte:1-12](file://frontend/pro/chatbot/Index.svelte#L1-L12) +- [frontend/pro/monaco-editor/Index.svelte:1-12](file://frontend/pro/monaco-editor/Index.svelte#L1-L12) +- [frontend/pro/multimodal-input/Index.svelte:1-9](file://frontend/pro/multimodal-input/Index.svelte#L1-L9) +- [frontend/pro/web-sandbox/Index.svelte:1-8](file://frontend/pro/web-sandbox/Index.svelte#L1-L8) + +## 性能考虑 + +- 动态导入与懒加载 + - 通过 importComponent 动态导入底层组件，避免首屏阻塞 +- 计算属性与派生值 + - 使用 $derived 复用派生计算，减少不必要的重渲染 +- 加载器策略 + - MonacoEditor 支持本地与 CDN 两种加载器，按需选择以平衡体积与网络开销 +- 事件回写 + - 仅在值变化时触发 updateProps，避免频繁回写 +- 文件上传 + - 使用 prepare_files 与 Gradio 客户端上传，减少手动序列化成本 + +## 故障排查指南 + +- 编辑器未加载 + - 检查 \_loader.mode 与 cdn_url 配置是否正确 + - 确认 initCDNLoader/initLocalLoader 已完成初始化 + - 参考：[frontend/pro/monaco-editor/Index.svelte:61-70](file://frontend/pro/monaco-editor/Index.svelte#L61-L70)、[frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- 上传失败 + - 确认 gradio.shared.client 可用且 root 正确 + - 检查 prepare_files 与返回的 FileData[] + - 参考：[frontend/pro/multimodal-input/Index.svelte:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) +- 主题不生效 + - 确认 gradio.shared.theme 设置为 light/dark + - 参考：[frontend/pro/chatbot/Index.svelte:83](file://frontend/pro/chatbot/Index.svelte#L83)、[frontend/pro/web-sandbox/Index.svelte:70](file://frontend/pro/web-sandbox/Index.svelte#L70)、[frontend/pro/monaco-editor/Index.svelte:88](file://frontend/pro/monaco-editor/Index.svelte#L88) + +章节来源 + +- [frontend/pro/monaco-editor/Index.svelte:61-70](file://frontend/pro/monaco-editor/Index.svelte#L61-L70) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/multimodal-input/Index.svelte:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) +- [frontend/pro/chatbot/Index.svelte:83](file://frontend/pro/chatbot/Index.svelte#L83) +- [frontend/pro/web-sandbox/Index.svelte:70](file://frontend/pro/web-sandbox/Index.svelte#L70) +- [frontend/pro/monaco-editor/Index.svelte:88](file://frontend/pro/monaco-editor/Index.svelte#L88) + +## 结论 + +本参考文档系统梳理了 ModelScope Studio 专业 Svelte 组件的 API 与实现要点，强调了桥接层的统一模式、运行时共享上下文的使用以及与 Gradio 生态的深度集成。通过合理的属性设计、事件回写与动态加载策略，这些组件能够高效支撑 AI 应用中的对话、编辑、多模态输入与沙盒渲染等核心场景。 + +## 附录 + +- TypeScript 类型与接口 + - Chatbot 类型：[frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- 包导出与入口 + - Chatbot：[frontend/pro/chatbot/package.json:1-15](file://frontend/pro/chatbot/package.json#L1-L15) + - MonacoEditor：[frontend/pro/monaco-editor/package.json:1-15](file://frontend/pro/monaco-editor/package.json#L1-L15) + - MultimodalInput：[frontend/pro/multimodal-input/package.json:1-15](file://frontend/pro/multimodal-input/package.json#L1-L15) + - WebSandbox：[frontend/pro/web-sandbox/package.json:1-15](file://frontend/pro/web-sandbox/package.json#L1-L15) +- 组件桥接实现 + - Chatbot：[frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) + - MonacoEditor：[frontend/pro/monaco-editor/Index.svelte:1-101](file://frontend/pro/monaco-editor/Index.svelte#L1-L101) + - MultimodalInput：[frontend/pro/multimodal-input/Index.svelte:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) + - WebSandbox：[frontend/pro/web-sandbox/Index.svelte:1-76](file://frontend/pro/web-sandbox/Index.svelte#L1-L76) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/\345\237\272\347\241\200\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/\345\237\272\347\241\200\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..7fca44a7 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/JavaScript API/Svelte \347\273\204\344\273\266 API/\345\237\272\347\241\200\347\273\204\344\273\266 API.md" @@ -0,0 +1,550 @@ +# 基础组件 API + + +**本文引用的文件** +- [frontend/base/application/Index.svelte](file://frontend/base/application/Index.svelte) +- [frontend/base/auto-loading/Index.svelte](file://frontend/base/auto-loading/Index.svelte) +- [frontend/base/slot/Index.svelte](file://frontend/base/slot/Index.svelte) +- [frontend/base/fragment/Index.svelte](file://frontend/base/fragment/Index.svelte) +- [frontend/base/div/Index.svelte](file://frontend/base/div/Index.svelte) +- [frontend/base/span/Index.svelte](file://frontend/base/span/Index.svelte) +- [frontend/base/text/Index.svelte](file://frontend/base/text/Index.svelte) +- [frontend/base/markdown/Index.svelte](file://frontend/base/markdown/Index.svelte) +- [frontend/base/each/Index.svelte](file://frontend/base/each/Index.svelte) +- [frontend/base/filter/Index.svelte](file://frontend/base/filter/Index.svelte) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 ModelScope Studio 基础 Svelte 组件的权威参考，覆盖 Application、AutoLoading、Slot、Fragment、Div、Span、Text、Markdown、Each、Filter 等组件的完整 API 规范与使用说明。内容包括： + +- 属性定义与默认值 +- 事件与回调约定 +- 插槽系统与参数映射 +- 生命周期与渲染控制（可见性、延迟加载） +- 组件间通信机制（上下文、插槽键、加载状态） +- TypeScript 类型约束与接口规范 +- 实例化与配置示例路径 +- 性能优化与最佳实践 + +## 项目结构 + +基础组件位于前端工作区的 base 目录下，采用“按组件分目录”的组织方式，每个组件包含一个入口 Index.svelte 以及对应的实现文件（如 .tsx 或 .svelte）。组件通过统一的预处理工具链进行属性提取、额外属性注入与延迟加载。 + +```mermaid +graph TB +subgraph "基础组件" +APP["application/Index.svelte"] +AL["auto-loading/Index.svelte"] +SLOT["slot/Index.svelte"] +FRAG["fragment/Index.svelte"] +DIV["div/Index.svelte"] +SPAN["span/Index.svelte"] +TEXT["text/Index.svelte"] +MD["markdown/Index.svelte"] +EACH["each/Index.svelte"] +FILT["filter/Index.svelte"] +end +subgraph "通用工具" +PREACT["@svelte-preprocess-react/*"] +CLS["classnames"] +end +APP --> PREACT +AL --> PREACT +SLOT --> PREACT +FRAG --> PREACT +DIV --> PREACT +SPAN --> PREACT +TEXT --> PREACT +MD --> PREACT +EACH --> PREACT +FILT --> PREACT +DIV --> CLS +SPAN --> CLS +MD --> CLS +AL --> CLS +``` + +图表来源 + +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) +- [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [frontend/base/filter/Index.svelte:1-52](file://frontend/base/filter/Index.svelte#L1-L52) + +章节来源 + +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) +- [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [frontend/base/filter/Index.svelte:1-52](file://frontend/base/filter/Index.svelte#L1-L52) + +## 核心组件 + +本节对各组件的关键属性、事件、插槽与生命周期进行系统梳理，并给出类型约束与使用要点。 + +- Application + - 作用：动态导入并渲染应用级组件，支持延迟加载与 children 渲染。 + - 关键属性 + - children: 可选的渲染函数，用于传递子节点。 + - 其余属性由 getProps 提取并透传至内部组件。 + - 生命周期 + - 使用 {#await} 进行异步渲染，确保组件在导入完成后才挂载。 + - 示例路径 + - [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) + +- AutoLoading + - 作用：包装任意组件，提供可见性、生成态、错误态与样式透传能力。 + - 关键属性 + - visible: 控制是否渲染。 + - generating: 标识生成态，影响加载状态。 + - showError: 是否显示错误态。 + - elem_id/elem_classes/elem_style: DOM 属性透传。 + - as_item/\_internal: 内部标记与容器化标识。 + - 其余属性经 getComponentProps/processProps 处理后透传。 + - 上下文 + - 读取配置类型、插槽集合、加载状态。 + - 示例路径 + - [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) + +- Slot + - 作用：注册与更新具名插槽，支持参数映射与可见性控制。 + - 关键属性 + - value: 插槽键值。 + - params_mapping: 参数映射表达式字符串，运行时转换为函数。 + - visible/as_item/\_internal: 控制可见性与容器化。 + - 行为 + - 在 effect 中检测 value 变化，调用 setSlot 更新上下文。 + - 设置当前插槽键与参数映射。 + - 示例路径 + - [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) + +- Fragment + - 作用：轻量容器，包裹多个子节点，不引入额外 DOM。 + - 关键属性 + - visible/\_internal/as_item: 控制可见性与容器化。 + - 其余属性透传给内部 Fragment。 + - 注意 + - shouldResetSlotKey: 配置中禁用插槽键重置。 + - 示例路径 + - [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + +- Div + - 作用：块级容器，支持样式、类名、ID 与内部布局标记。 + - 关键属性 + - value: 文本或内容值。 + - elem_style: 内联样式对象。 + - additional_props: 额外属性对象。 + - \_internal.layout: 标记是否为布局相关内部元素。 + - visible/as_item/elem_id/elem_classes: 控制可见性与 DOM 属性。 + - 示例路径 + - [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) + +- Span + - 作用：行内容器，行为与 Div 类似但语义为行内。 + - 关键属性 + - value: 文本或内容值。 + - additional_props: 额外属性对象。 + - \_internal.layout: 标记是否为布局相关内部元素。 + - visible/as_item/elem_id/elem_classes/elem_style: 控制可见性与 DOM 属性。 + - 示例路径 + - [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) + +- Text + - 作用：文本展示组件，支持值与通用属性透传。 + - 关键属性 + - value: 文本值。 + - visible/as_item/\_internal: 控制可见性与容器化。 + - 示例路径 + - [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) + +- Markdown + - 作用：Markdown 渲染组件，支持主题、根路径与插槽。 + - 关键属性 + - value: Markdown 文本。 + - elem_id/elem_classes/elem_style: DOM 属性透传。 + - visible/as_item/\_internal: 控制可见性与容器化。 + - 上下文 + - 读取共享配置中的 root 与 theme。 + - 读取插槽集合以支持自定义组件嵌入。 + - 示例路径 + - [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) + +- Each + - 作用：列表渲染组件，支持上下文合并、索引计算与占位符。 + - 关键属性 + - value: 待渲染数组。 + - context_value: 上下文对象。 + - \_internal.index: 内部起始索引。 + - visible/as_item/elem_id/elem_classes/elem_style: 控制可见性与 DOM 属性。 + - 行为 + - 使用 EachPlaceholder 合并外部变更，决定是否强制克隆渲染。 + - 支持嵌套 Each，通过 getSubIndex 与 getSlotKey 计算子索引与插槽键。 + - 示例路径 + - [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +- Filter + - 作用：条件过滤组件，将 children 包裹为可按参数映射过滤的片段。 + - 关键属性 + - params_mapping: 参数映射表达式字符串。 + - visible/as_item/\_internal: 控制可见性与容器化。 + - 示例路径 + - [frontend/base/filter/Index.svelte:1-52](file://frontend/base/filter/Index.svelte#L1-L52) + +章节来源 + +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) +- [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [frontend/base/filter/Index.svelte:1-52](file://frontend/base/filter/Index.svelte#L1-L52) + +## 架构总览 + +基础组件通过统一的预处理管线完成属性解析、额外属性注入与延迟加载，同时借助上下文系统实现插槽注册、加载状态与配置类型管理。组件间通过 props 与上下文协作，形成清晰的职责边界与可组合性。 + +```mermaid +sequenceDiagram +participant U as "用户代码" +participant IDX as "Index.svelte" +participant PRE as "@svelte-preprocess-react/*" +participant CMP as "内部组件" +participant CTX as "上下文(插槽/配置/加载)" +U->>IDX : 传入 props 与 children +IDX->>PRE : getProps()/processProps() +PRE-->>IDX : 规范化后的 props 与附加属性 +IDX->>CTX : 读取/设置插槽/配置/加载状态 +IDX->>CMP : 异步导入并渲染组件 +CMP-->>U : 渲染结果 +``` + +图表来源 + +- [frontend/base/auto-loading/Index.svelte:15-52](file://frontend/base/auto-loading/Index.svelte#L15-L52) +- [frontend/base/slot/Index.svelte:16-54](file://frontend/base/slot/Index.svelte#L16-L54) +- [frontend/base/markdown/Index.svelte:19-44](file://frontend/base/markdown/Index.svelte#L19-L44) + +## 详细组件分析 + +### Application 组件 + +- 设计要点 + - 使用 importComponent 动态导入内部 Application.svelte。 + - 将 children 渲染为插槽内容。 +- API 摘要 + - 属性 + - children: 可选渲染函数 + - 其余属性由 getProps 提取并透传 + - 插槽 + - 默认插槽：children() + - 生命周期 + - {#await} 异步渲染，避免未导入即挂载 +- 示例路径 + - [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) + +章节来源 + +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) + +### AutoLoading 组件 + +- 设计要点 + - 包装任意组件，提供可见性、生成态、错误态与样式透传。 + - 通过 getLoadingStatus 与配置类型联动。 +- API 摘要 + - 属性 + - visible/generating/showError + - elem_id/elem_classes/elem_style + - as_item/\_internal + - 其余属性经 processProps 处理 + - 上下文 + - 读取配置类型、插槽集合、加载状态 + - 插槽 + - 默认插槽：children() +- 示例路径 + - [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) + +章节来源 + +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) + +### Slot 组件 + +- 设计要点 + - 注册具名插槽，支持参数映射与可见性控制。 + - 在 effect 中检测 value 变化并更新上下文。 +- API 摘要 + - 属性 + - value: 插槽键 + - params_mapping: 参数映射表达式 + - visible/as_item/\_internal + - 行为 + - setSlotKey/setSlotParamsMapping + - 通过 svelte-slot bind:this 获取宿主元素 +- 示例路径 + - [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) + +章节来源 + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) + +### Fragment 组件 + +- 设计要点 + - 轻量容器，不引入额外 DOM。 + - 禁用插槽键重置，保持上下文稳定性。 +- API 摘要 + - 属性 + - visible/\_internal/as_item + - 其余属性透传 + - 插槽 + - 默认插槽：children() +- 示例路径 + - [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + +章节来源 + +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + +### Div 组件 + +- 设计要点 + - 块级容器，支持样式、类名、ID 与内部布局标记。 +- API 摘要 + - 属性 + - value/additional_props/\_internal.layout + - elem_id/elem_classes/elem_style + - visible/as_item/\_internal + - 插槽 + - 默认插槽：children() +- 示例路径 + - [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) + +章节来源 + +- [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) + +### Span 组件 + +- 设计要点 + - 行内容器，行为与 Div 类似。 +- API 摘要 + - 属性 + - value/additional_props/\_internal.layout + - elem_id/elem_classes/elem_style + - visible/as_item/\_internal + - 插槽 + - 默认插槽：children() +- 示例路径 + - [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) + +章节来源 + +- [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) + +### Text 组件 + +- 设计要点 + - 文本展示组件，最小化开销。 +- API 摘要 + - 属性 + - value + - visible/as_item/\_internal +- 示例路径 + - [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) + +章节来源 + +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) + +### Markdown 组件 + +- 设计要点 + - 支持主题与根路径，结合插槽实现可扩展渲染。 +- API 摘要 + - 属性 + - value + - elem_id/elem_classes/elem_style + - visible/as_item/\_internal + - 上下文 + - 读取 shared.root 与 theme + - 读取插槽集合 +- 示例路径 + - [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) + +章节来源 + +- [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) + +### Each 组件 + +- 设计要点 + - 列表渲染，支持上下文合并、索引计算与占位符。 + - 嵌套 Each 通过 getSubIndex 与 getSlotKey 计算子索引与插槽键。 +- API 摘要 + - 属性 + - value/context_value/\_internal.index + - elem_id/elem_classes/elem_style + - visible/as_item/\_internal + - 插槽 + - 默认插槽：children() + - 事件 + - EachPlaceholder.onChange：接收合并后的 value 与 contextValue +- 示例路径 + - [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +章节来源 + +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +### Filter 组件 + +- 设计要点 + - 条件过滤容器，将 children 包裹为可按参数映射过滤的片段。 +- API 摘要 + - 属性 + - params_mapping + - visible/as_item/\_internal + - 插槽 + - 默认插槽：children() +- 示例路径 + - [frontend/base/filter/Index.svelte:1-52](file://frontend/base/filter/Index.svelte#L1-L52) + +章节来源 + +- [frontend/base/filter/Index.svelte:1-52](file://frontend/base/filter/Index.svelte#L1-L52) + +## 依赖关系分析 + +基础组件普遍依赖 @svelte-preprocess-react 工具集与样式库，形成统一的属性处理与延迟加载机制；部分组件还依赖上下文系统以实现插槽注册与加载状态管理。 + +```mermaid +graph LR +subgraph "工具" +PRE["@svelte-preprocess-react/*"] +CLS["classnames"] +end +subgraph "组件" +AL["AutoLoading"] +SLOT["Slot"] +MD["Markdown"] +DIV["Div"] +SPAN["Span"] +FRAG["Fragment"] +EACH["Each"] +FILT["Filter"] +end +AL --> PRE +SLOT --> PRE +MD --> PRE +DIV --> PRE +SPAN --> PRE +FRAG --> PRE +EACH --> PRE +FILT --> PRE +DIV -.-> CLS +SPAN -.-> CLS +MD -.-> CLS +AL -.-> CLS +``` + +图表来源 + +- [frontend/base/auto-loading/Index.svelte:1-10](file://frontend/base/auto-loading/Index.svelte#L1-L10) +- [frontend/base/slot/Index.svelte:1-8](file://frontend/base/slot/Index.svelte#L1-L8) +- [frontend/base/markdown/Index.svelte:1-8](file://frontend/base/markdown/Index.svelte#L1-L8) +- [frontend/base/div/Index.svelte:1-8](file://frontend/base/div/Index.svelte#L1-L8) +- [frontend/base/span/Index.svelte:1-7](file://frontend/base/span/Index.svelte#L1-L7) + +章节来源 + +- [frontend/base/auto-loading/Index.svelte:1-10](file://frontend/base/auto-loading/Index.svelte#L1-L10) +- [frontend/base/slot/Index.svelte:1-8](file://frontend/base/slot/Index.svelte#L1-L8) +- [frontend/base/markdown/Index.svelte:1-8](file://frontend/base/markdown/Index.svelte#L1-L8) +- [frontend/base/div/Index.svelte:1-8](file://frontend/base/div/Index.svelte#L1-L8) +- [frontend/base/span/Index.svelte:1-7](file://frontend/base/span/Index.svelte#L1-L7) + +## 性能考虑 + +- 延迟加载 + - 使用 importComponent 与 {#await} 仅在需要时加载组件，减少首屏负担。 +- 可见性控制 + - 通过 visible 属性快速隐藏/显示，避免不必要的渲染与上下文更新。 +- 插槽键与上下文 + - 合理设置插槽键与参数映射，避免重复注册与无效更新。 +- 样式透传 + - 优先使用 elem_classes 与 elem_style，减少内联样式的频繁变更。 +- 列表渲染 + - Each 组件支持占位符与强制克隆策略，按需选择以平衡性能与一致性。 +- 加载状态 + - AutoLoading 结合 generating 与 showError 状态，避免重复请求与闪烁。 + +## 故障排查指南 + +- 组件未渲染 + - 检查 visible 属性是否为 true。 + - 确认 {#await} 导入流程是否成功。 +- 插槽不生效 + - 确认 Slot 的 value 与 params_mapping 是否正确设置。 + - 检查父级组件是否正确注册插槽键。 +- Each 渲染异常 + - 检查 value 是否为数组，context_value 是否为对象。 + - 嵌套 Each 时确认索引与插槽键计算逻辑。 +- Markdown 主题或资源路径问题 + - 确认 shared.root 与 theme 配置是否正确。 +- AutoLoading 状态不同步 + - 检查 generating 与 showError 是否与业务状态一致。 + +章节来源 + +- [frontend/base/each/Index.svelte:66-104](file://frontend/base/each/Index.svelte#L66-L104) +- [frontend/base/markdown/Index.svelte:47-63](file://frontend/base/markdown/Index.svelte#L47-L63) +- [frontend/base/auto-loading/Index.svelte:65-80](file://frontend/base/auto-loading/Index.svelte#L65-L80) +- [frontend/base/slot/Index.svelte:57-61](file://frontend/base/slot/Index.svelte#L57-L61) + +## 结论 + +ModelScope Studio 的基础组件通过统一的预处理管线与上下文系统，实现了高内聚、低耦合且易于组合的 UI 基础设施。遵循本文档的属性规范、插槽约定与性能建议，可在保证开发效率的同时获得稳定的运行表现。 + +## 附录 + +- TypeScript 类型约束与接口规范 + - getProps
omitUndefinedProps"] +P2["patchProps/applyPatchToProps"] +P3["renderSlot/renderItems/patchSlots"] +P4["style.ts 计算"] +P5["upload.ts 解析"] +P6["walkHtmlNodes 遍历"] +P7["createFunction/函数工厂"] +end +subgraph "输出层" +OUT1["React 组件树"] +OUT2["内联样式字符串/对象"] +OUT3["可访问的文件 URL"] +end +IN1 --> P1 --> P2 --> P3 --> OUT1 +IN2 --> P3 --> OUT1 +IN2 --> P6 --> OUT1 +IN3 --> P5 --> OUT3 +IN1 --> P4 --> OUT2 +IN1 --> P7 --> P3 +``` + +图表来源 + +- [convertToCamelCase.ts:1-22](file://frontend/utils/convertToCamelCase.ts#L1-L22) +- [patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [omitUndefinedProps.ts:1-17](file://frontend/utils/omitUndefinedProps.ts#L1-L17) +- [renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [style.ts:1-77](file://frontend/utils/style.ts#L1-L77) +- [upload.ts:1-45](file://frontend/utils/upload.ts#L1-L45) +- [walkHtmlNodes.ts:1-19](file://frontend/utils/walkHtmlNodes.ts#L1-L19) +- [createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) + +## 详细组件分析 + +### 属性处理函数 + +#### convertToCamelCase 与 convertObjectKeyToCamelCase + +- 功能：将下划线命名转换为驼峰命名；批量转换对象键名 +- 参数与返回： + - convertToCamelCase(str: string): string + - convertObjectKeyToCamelCase
ModelScopeLayoutComponent
ModelScopeDataLayoutComponent"] +B["AntdButton"] +C["AntdForm / AntdFormItem"] +D["AntdTable / AntdTableColumn"] +E["AntdInput / AntdSelect"] +F["AntdLayout / AntdMenu / AntdModal"] +G["AntdMessage / AntdNotification"] +H["AntdCard / AntdBreadcrumb"] +end +subgraph "前端层Svelte" +P["button/*"] +Q["form/*"] +R["table/*"] +S["input/*"] +T["select/*"] +U["layout/*"] +V["menu/*"] +W["modal/*"] +X["message/*"] +Y["notification/*"] +Z["card/*"] +AA["breadcrumb/*"] +end +A --> B +A --> C +A --> D +A --> E +A --> F +A --> G +A --> H +B --> P +C --> Q +D --> R +E --> S +E --> T +F --> U +F --> V +F --> W +G --> X +G --> Y +H --> Z +H --> AA +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:54-169](file://backend/modelscope_studio/utils/dev/component.py#L54-L169) +- [backend/modelscope_studio/components/antd/button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) +- [backend/modelscope_studio/components/antd/table/**init**.py:16-153](file://backend/modelscope_studio/components/antd/table/__init__.py#L16-L153) +- [backend/modelscope_studio/components/antd/input/**init**.py:16-127](file://backend/modelscope_studio/components/antd/input/__init__.py#L16-L127) +- [backend/modelscope_studio/components/antd/select/**init**.py:12-231](file://backend/modelscope_studio/components/antd/select/__init__.py#L12-L231) +- [backend/modelscope_studio/components/antd/layout/**init**.py:14-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L14-L91) +- [backend/modelscope_studio/components/antd/menu/**init**.py:12-123](file://backend/modelscope_studio/components/antd/menu/__init__.py#L12-L123) +- [backend/modelscope_studio/components/antd/modal/**init**.py:11-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L11-L136) +- [backend/modelscope_studio/components/antd/message/**init**.py:10-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L10-L91) +- [backend/modelscope_studio/components/antd/notification/**init**.py:10-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L10-L109) +- [backend/modelscope_studio/components/antd/card/**init**.py:12-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L12-L149) +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:9-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L9-L73) + +章节来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) + +## 核心组件 + +- 基础组件类 + - ModelScopeComponent：通用组件基类，支持 value、visible、elem\_\*、key、inputs、load_fn、render 等 Gradio 属性；提供 skip_api 控制是否暴露 API。 + - ModelScopeLayoutComponent：布局组件基类，支持 **enter**/**exit** 上下文管理，用于嵌套布局。 + - ModelScopeDataLayoutComponent：数据型布局组件基类，兼具数据组件能力与布局能力。 +- 事件与插槽 + - EVENTS：组件支持的事件列表，通过 EventListener 绑定回调。 + - SLOTS：组件支持的插槽名称集合，用于渲染子内容或自定义节点。 +- 前端目录解析 + - FRONTEND_DIR：通过 resolve_frontend_dir(...) 指向对应 Svelte 组件目录。 + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:54-169](file://backend/modelscope_studio/utils/dev/component.py#L54-L169) +- [backend/modelscope_studio/components/antd/button/**init**.py:41-49](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L49) +- [backend/modelscope_studio/components/antd/table/**init**.py:32-53](file://backend/modelscope_studio/components/antd/table/__init__.py#L32-L53) +- [backend/modelscope_studio/components/antd/input/**init**.py:25-41](file://backend/modelscope_studio/components/antd/input/__init__.py#L25-L41) + +## 架构总览 + +以下序列图展示一个典型组件从构造到事件绑定的调用链： + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Py as "Antd 组件类" +participant Base as "ModelScopeComponent/ModelScopeLayoutComponent" +participant FE as "Svelte 前端组件" +Dev->>Py : 实例化组件(传入参数) +Py->>Base : 调用父类 __init__(visible, elem_*, render, ...) +Base->>Base : 初始化内部状态(_internal, as_item, elem_style) +Py->>FE : 设置 FRONTEND_DIR 并传递 props +Py->>Py : 配置 EVENTS/SLOTS +Dev->>Py : 绑定事件监听器(EventListener) +Py->>FE : 通过内部标记绑定前端事件回调 +FE-->>Py : 触发事件回调 +Py-->>Dev : 返回处理后的值/payload +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:54-99](file://backend/modelscope_studio/utils/dev/component.py#L54-L99) +- [backend/modelscope_studio/components/antd/button/**init**.py:51-87](file://backend/modelscope_studio/components/antd/button/__init__.py#L51-L87) +- [backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) + +## 详细组件分析 + +### Button（按钮） + +- 导入路径：modelscope_studio.components.antd.AntdButton 或 modelscope_studio.components.antd.Button +- 支持子组件：Group +- 事件：click +- 插槽：icon, loading.icon +- 关键参数（节选）：value, block, danger, ghost, disabled, href, html_type, icon, icon_position, loading, shape, size, type, variant, color, root_class_name +- 方法：preprocess/postprocess/example_payload/example_value +- 代码片段路径（示例） + - [basic usage:51-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L51-L157) +- 事件绑定流程 + - 通过 EVENTS 中的 EventListener("click", ...) 将回调映射到前端事件。 +- 数据绑定 + - 作为输入输出时，value 类型为字符串；preprocess/postprocess 返回字符串。 +- 参数验证与异常 + - 参数多为可空标量或字面量枚举；未见显式校验逻辑，建议在应用层进行输入约束。 +- 组件间通信 + - 通过 Gradio 的 inputs/outputs 机制与表单或其他组件联动。 + +章节来源 + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) + +### Form（表单）与 Form.Item（表单项） + +- 导入路径：modelscope_studio.components.antd.AntdForm / AntdFormItem +- 子组件：Item, Provider +- 事件：fields_change, finish, finish_failed, values_change +- 插槽：requiredMark +- Form 关键参数（节选）：colon, disabled, component, feedback_icons, initial_values, label_align, label_col, label_wrap, layout, preserve, required_mark, scroll_to_first_error, size, validate_messages, validate_trigger, variant, wrapper_col, clear_on_destroy, root_class_name, class_names, styles +- FormItem 关键参数（节选）：label, form_name, colon, dependencies, extra, help, hidden, initial_value, label_align, label_col, message_variants, normalize, no_style, preserve, required, rules, should_update, tooltip, trigger, validate_debounce, validate_first, validate_status, validate_trigger, value_prop_name, wrapper_col, layout, root_class_name +- 方法：preprocess/postprocess/example_payload/example_value +- 代码片段路径（示例） + - [form:43-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L43-L133) + - [form item:21-126](file://backend/modelscope_studio/components/antd/form/item/__init__.py#L21-L126) + +章节来源 + +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) +- [backend/modelscope_studio/components/antd/form/item/**init**.py:9-126](file://backend/modelscope_studio/components/antd/form/item/__init__.py#L9-L126) + +### Table（表格）与 Table.Column（列） + +- 导入路径：modelscope_studio.components.antd.AntdTable / AntdTableColumn +- 子组件：Column, ColumnGroup, Expandable, RowSelection +- 事件：change, scroll +- 插槽：footer, title, summary, expandable, rowSelection, loading.tip, loading.indicator, pagination.showQuickJumper.goButton, pagination.itemRender, showSorterTooltip.title +- Table 关键参数（节选）：data_source, columns, bordered, components, expandable, footer, get_popup_container, loading, locale, pagination, row_class_name, row_key, row_selection, row_hoverable, scroll, show_header, show_sorter_tooltip, size, sort_directions, sticky, summary, table_layout, title, virtual, on_row, on_header_row, root_class_name, class_names, styles +- Table.Column 关键参数（节选）：built_in_column, align, col_span, data_index, default_filtered_value, filter_reset_to_default_filtered_value, default_sort_order, ellipsis, filter_dropdown, filter_dropdown_open, filtered, filtered_value, filter_icon, filter_on_close, filter_multiple, filter_mode, filter_search, filters, filter_dropdown_props, fixed, key, column_render, responsive, row_scope, should_cell_update, show_sorter_tooltip, sorter, sort_order, sort_icon, title, width, min_width, hidden, on_cell, on_header_cell, class_names, styles +- 方法：preprocess/postprocess/example_payload/example_value +- 代码片段路径（示例） + - [table:55-153](file://backend/modelscope_studio/components/antd/table/__init__.py#L55-L153) + - [table.column:33-150](file://backend/modelscope_studio/components/antd/table/column/__init__.py#L33-L150) + +章节来源 + +- [backend/modelscope_studio/components/antd/table/**init**.py:16-153](file://backend/modelscope_studio/components/antd/table/__init__.py#L16-L153) +- [backend/modelscope_studio/components/antd/table/column/**init**.py:10-150](file://backend/modelscope_studio/components/antd/table/column/__init__.py#L10-L150) + +### Input（输入框）与 Select（选择器） + +- 导入路径：modelscope_studio.components.antd.AntdInput / AntdSelect +- 子组件：Textarea, Password, OTP, Search（Input），Option（Select） +- Input 事件：change, press_enter, clear +- Select 事件：change, blur, focus, search, select, clear, popup_scroll, dropdown_visible_change, popup_visible_change, active +- 插槽（Input）：addonAfter, addonBefore, allowClear.clearIcon, prefix, suffix, showCount.formatter +- 插槽（Select）：allowClear.clearIcon, maxTagPlaceholder, menuItemSelectedIcon, dropdownRender, popupRender, optionRender, tagRender, labelRender, notFoundContent, removeIcon, suffixIcon, prefix, options +- Input 关键参数（节选）：addon_after, addon_before, allow_clear, count, default_value, read_only, disabled, max_length, prefix, show_count, size, status, suffix, type, placeholder, variant, root_class_name, class_names, styles +- Select 关键参数（节选）：allow_clear, auto_clear_search_value, auto_focus, default_active_first_option, default_open, default_value, disabled, popup_class_name, popup_match_select_width, dropdown_render, popup_render, dropdown_style, field_names, filter_option, filter_sort, get_popup_container, label_in_value, list_height, loading, max_count, max_tag_count, max_tag_placeholder, max_tag_text_length, menu_item_selected_icon, mode, not_found_content, open, option_filter_prop, option_label_prop, options, option_render, placeholder, placement, remove_icon, search_value, show_search, size, status, suffix_icon, prefix, tag_render, label_render, token_separators, variant, virtual, class_names, styles, root_class_name +- 方法：preprocess/postprocess/example_payload/example_value +- 代码片段路径（示例） + - [input:43-127](file://backend/modelscope_studio/components/antd/input/__init__.py#L43-L127) + - [select:59-231](file://backend/modelscope_studio/components/antd/select/__init__.py#L59-L231) + +章节来源 + +- [backend/modelscope_studio/components/antd/input/**init**.py:16-127](file://backend/modelscope_studio/components/antd/input/__init__.py#L16-L127) +- [backend/modelscope_studio/components/antd/select/**init**.py:12-231](file://backend/modelscope_studio/components/antd/select/__init__.py#L12-L231) + +### Layout（布局）、Menu（菜单）、Modal（模态框） + +- 导入路径：modelscope_studio.components.antd.AntdLayout / AntdMenu / AntdModal +- 子组件：Layout.Content/Footer/Header/Sider（Layout）；Menu.Item（Menu）；Modal.Static（Modal） +- 事件（Layout/Menu/Modal）：click、deselect、open_change、select、ok、cancel 等 +- 插槽（Layout/Menu/Modal）：详见各组件定义 +- 代码片段路径（示例） + - [layout:39-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L39-L91) + - [menu:36-123](file://backend/modelscope_studio/components/antd/menu/__init__.py#L36-L123) + - [modal:34-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L34-L136) + +章节来源 + +- [backend/modelscope_studio/components/antd/layout/**init**.py:14-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L14-L91) +- [backend/modelscope_studio/components/antd/menu/**init**.py:12-123](file://backend/modelscope_studio/components/antd/menu/__init__.py#L12-L123) +- [backend/modelscope_studio/components/antd/modal/**init**.py:11-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L11-L136) + +### Message（消息）、Notification（通知）、Card（卡片）、Breadcrumb（面包屑） + +- 导入路径：modelscope_studio.components.antd.AntdMessage / AntdNotification / AntdCard / AntdBreadcrumb +- 事件：click, close（部分组件） +- 插槽：icon/content（Message）；actions/closeIcon/description/icon/message/title（Notification）；title/tabList/tabProps.\*（Card）；separator/itemRender/items/dropdownIcon（Breadcrumb） +- 代码片段路径（示例） + - [message:26-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L26-L91) + - [notification:26-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L26-L109) + - [card:56-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L56-L149) + - [breadcrumb:20-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L20-L73) + +章节来源 + +- [backend/modelscope_studio/components/antd/message/**init**.py:10-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L10-L91) +- [backend/modelscope_studio/components/antd/notification/**init**.py:10-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L10-L109) +- [backend/modelscope_studio/components/antd/card/**init**.py:12-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L12-L149) +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:9-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L9-L73) + +## 依赖分析 + +- 组件导出 + - modelscope_studio.components.antd.**init** 与 components.py 同步导出所有 Antd 组件类，便于统一导入。 +- 基类依赖 + - 所有组件均依赖 modelscope_studio.utils.dev.component 中的基础组件类，确保统一的生命周期、事件与插槽机制。 +- 前端依赖 + - 每个组件通过 FRONTEND_DIR 指向对应的 Svelte 组件目录，保持前后端一致的目录结构。 + +```mermaid +graph LR +A["antd/__init__.py"] --> B["Button/Form/Table/Input/Select/Layout/..."] +C["antd/components.py"] --> B +D["utils/dev/component.py"] --> B +B --> E["Svelte 前端组件"] +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [backend/modelscope_studio/utils/dev/component.py:54-169](file://backend/modelscope_studio/utils/dev/component.py#L54-L169) + +章节来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [backend/modelscope_studio/utils/dev/component.py:54-169](file://backend/modelscope_studio/utils/dev/component.py#L54-L169) + +## 性能考虑 + +- 事件绑定 + - 通过 EVENTS 将 Python 回调映射到前端事件，避免不必要的重渲染；合理设置事件触发频率与防抖。 +- 插槽与虚拟化 + - 表格等组件支持 virtual、sticky、scroll 等参数，建议在大数据场景启用虚拟滚动与固定表头以提升性能。 +- 渲染控制 + - 使用 render、visible 控制组件初始渲染与可见性，减少首屏压力。 +- 数据流 + - 输入组件（如 Input、Select）建议配合 Form 进行批量校验与去抖，降低频繁更新带来的开销。 + +## 故障排查指南 + +- 事件未触发 + - 检查 EVENTS 是否正确声明，确认 EventListener 名称与前端事件一致。 + - 确认组件已正确设置 FRONTEND_DIR，且前端事件回调已绑定。 +- 插槽不生效 + - 核对 SLOTS 列表中是否存在对应插槽名；确保传入的插槽内容符合预期格式。 +- 数据类型不符 + - 输入组件的 preprocess/postprocess 返回值类型需与组件定义一致；若出现类型错误，检查 value 与 api_info 返回类型。 +- 表单校验失败 + - 检查 FormItem 的 rules、validate_trigger、validate_status 等配置；必要时调整 validate_first 与 validate_debounce。 +- 布局闪烁或样式异常 + - 布局组件（如 Layout、Menu）可通过 has_sider、inline_collapsed、theme_value 等参数优化 SSR 场景下的样式闪烁问题。 + +章节来源 + +- [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) +- [backend/modelscope_studio/components/antd/form/item/**init**.py:13-19](file://backend/modelscope_studio/components/antd/form/item/__init__.py#L13-L19) +- [backend/modelscope_studio/components/antd/table/**init**.py:32-53](file://backend/modelscope_studio/components/antd/table/__init__.py#L32-L53) +- [backend/modelscope_studio/components/antd/menu/**init**.py:96-103](file://backend/modelscope_studio/components/antd/menu/__init__.py#L96-L103) +- [backend/modelscope_studio/components/antd/layout/**init**.py:33-37](file://backend/modelscope_studio/components/antd/layout/__init__.py#L33-L37) + +## 结论 + +本参考文档系统梳理了 Antd 组件库的 Python API，明确了组件类的导入路径、构造参数、事件与插槽、数据绑定与状态管理接口。建议在实际开发中结合示例路径快速定位实现细节，并依据性能与故障排查指南优化组件使用体验。 + +## 附录：按功能分类的 API 索引 + +- 通用组件 + - Button、Message、Notification、Card、Breadcrumb + - 示例路径：[button:51-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L51-L157)，[message:26-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L26-L91)，[notification:26-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L26-L109)，[card:56-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L56-L149)，[breadcrumb:20-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L20-L73) +- 布局组件 + - Layout（含 Content/Footer/Header/Sider）、Menu（含 Item） + - 示例路径：[layout:39-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L39-L91)，[menu:36-123](file://backend/modelscope_studio/components/antd/menu/__init__.py#L36-L123) +- 导航组件 + - Breadcrumb（含 Item） + - 示例路径：[breadcrumb:20-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L20-L73) +- 数据录入组件 + - Input（含 Textarea/Password/OTP/Search）、Select（含 Option） + - 示例路径：[input:43-127](file://backend/modelscope_studio/components/antd/input/__init__.py#L43-L127)，[select:59-231](file://backend/modelscope_studio/components/antd/select/__init__.py#L59-L231) +- 数据展示组件 + - Table（含 Column/ColumnGroup/Expandable/RowSelection） + - 示例路径：[table:55-153](file://backend/modelscope_studio/components/antd/table/__init__.py#L55-L153)，[table.column:33-150](file://backend/modelscope_studio/components/antd/table/column/__init__.py#L33-L150) +- 反馈组件 + - Modal（含 Static）、Message、Notification + - 示例路径：[modal:34-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L34-L136)，[message:26-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L26-L91)，[notification:26-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L26-L109) +- 表单组件 + - Form（含 Item/Provider） + - 示例路径：[form:43-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L43-L133)，[form.item:21-126](file://backend/modelscope_studio/components/antd/form/item/__init__.py#L21-L126) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\345\205\266\344\273\226\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\345\205\266\344\273\226\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..e8300de9 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\345\205\266\344\273\226\347\273\204\344\273\266 API.md" @@ -0,0 +1,422 @@ +# 其他组件 API + + +**本文引用的文件** +- [backend/modelscope_studio/components/antd/config_provider/__init__.py](file://backend/modelscope_studio/components/antd/config_provider/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) +- [frontend/antd/config-provider/Index.svelte](file://frontend/antd/config-provider/Index.svelte) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [docs/demos/example.py](file://docs/demos/example.py) +- [docs/components/antd/config_provider/README.md](file://docs/components/antd/config_provider/README.md) +- [frontend/antd/config-provider/package.json](file://frontend/antd/config-provider/package.json) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 Ant Design Studio 中“其他组件”的 Python API 参考文档，重点覆盖 ConfigProvider（全局配置提供者）的完整 API 规范与使用说明。内容涵盖： + +- 构造函数参数、属性定义、方法签名与返回值类型 +- 标准的全局配置用法：主题定制、语言设置、组件默认配置 +- 作用域管理、配置继承与动态更新机制 +- 国际化配置、主题切换与组件行为定制方案 +- 最佳实践与性能优化建议 + +## 项目结构 + +ConfigProvider 在后端以 Python 类实现，在前端以 Svelte 包装并对接 Ant Design 的 ConfigProvider，同时通过本地化模块支持多语言。 + +```mermaid +graph TB +subgraph "Python 后端" +PY_INIT["backend/modelscope_studio/components/antd/__init__.py"] +PY_CP["backend/modelscope_studio/components/antd/config_provider/__init__.py"] +PY_DEV["backend/modelscope_studio/utils/dev/component.py"] +PY_RESOLVE["backend/modelscope_studio/utils/dev/resolve_frontend_dir.py"] +end +subgraph "前端" +FE_INDEX["frontend/antd/config-provider/Index.svelte"] +FE_TSX["frontend/antd/config-provider/config-provider.tsx"] +FE_LOCALES["frontend/antd/config-provider/locales.ts"] +FE_PKG["frontend/antd/config-provider/package.json"] +end +PY_INIT --> PY_CP +PY_CP --> PY_RESOLVE +PY_CP --> PY_DEV +PY_CP --> FE_INDEX +FE_INDEX --> FE_TSX +FE_TSX --> FE_LOCALES +FE_INDEX --> FE_PKG +``` + +**图表来源** + +- [backend/modelscope_studio/components/antd/**init**.py:32](file://backend/modelscope_studio/components/antd/__init__.py#L32) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:22](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L22) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4) +- [frontend/antd/config-provider/Index.svelte:11](file://frontend/antd/config-provider/Index.svelte#L11) +- [frontend/antd/config-provider/config-provider.tsx:51](file://frontend/antd/config-provider/config-provider.tsx#L51) +- [frontend/antd/config-provider/locales.ts:7](file://frontend/antd/config-provider/locales.ts#L7) +- [frontend/antd/config-provider/package.json:1](file://frontend/antd/config-provider/package.json#L1) + +**章节来源** + +- [backend/modelscope_studio/components/antd/**init**.py:32](file://backend/modelscope_studio/components/antd/__init__.py#L32) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:22](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L22) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4) +- [frontend/antd/config-provider/Index.svelte:11](file://frontend/antd/config-provider/Index.svelte#L11) +- [frontend/antd/config-provider/config-provider.tsx:51](file://frontend/antd/config-provider/config-provider.tsx#L51) +- [frontend/antd/config-provider/locales.ts:7](file://frontend/antd/config-provider/locales.ts#L7) +- [frontend/antd/config-provider/package.json:1](file://frontend/antd/config-provider/package.json#L1) + +## 核心组件 + +- 组件名称：AntdConfigProvider +- 所属模块：backend.modelscope_studio.components.antd.config_provider +- 基类：ModelScopeLayoutComponent +- 前端映射：frontend/antd/config-provider/Index.svelte → frontend/antd/config-provider/config-provider.tsx +- 作用：为应用内所有 Ant Design 组件提供统一的全局配置（主题、语言、尺寸、前缀、弹层容器等），并支持插槽注入与动态更新。 + +关键点： + +- 支持的插槽：renderEmpty +- 事件：无 +- 前端目录解析：通过 resolve_frontend_dir("config-provider") 指向前端组件目录 +- 跳过 API 导出：skip_api 返回 True，避免在某些自动化导出中暴露该组件 + +**章节来源** + +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:22](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L22) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:28](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L28) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:95](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L95) +- [backend/modelscope_studio/utils/dev/component.py:20](file://backend/modelscope_studio/utils/dev/component.py#L20) + +## 架构总览 + +ConfigProvider 的调用链路如下： + +```mermaid +sequenceDiagram +participant App as "应用 Blocks" +participant CP_Py as "AntdConfigProvider(Python)" +participant CP_Index as "Index.svelte" +participant CP_TSX as "config-provider.tsx" +participant AD as "Ant Design ConfigProvider" +App->>CP_Py : 创建并传入配置参数 +CP_Py->>CP_Index : 解析前端目录并渲染 +CP_Index->>CP_TSX : 传递 props 与 slots +CP_TSX->>AD : 注入主题、语言、容器回调等 +AD-->>CP_TSX : 提供上下文 +CP_TSX-->>CP_Index : 渲染子树 +CP_Index-->>App : 子组件继承全局配置 +``` + +**图表来源** + +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:95](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L95) +- [frontend/antd/config-provider/Index.svelte:11](file://frontend/antd/config-provider/Index.svelte#L11) +- [frontend/antd/config-provider/config-provider.tsx:108](file://frontend/antd/config-provider/config-provider.tsx#L108) + +## 详细组件分析 + +### 构造函数与属性定义 + +- 类名：AntdConfigProvider +- 继承：ModelScopeLayoutComponent +- 关键属性（部分）： + - component_disabled: 可选布尔，控制组件禁用状态 + - component_size: 可选字符串，取值 small/middle/large 或 None + - csp: 可选字典，用于 CSP 配置 + - direction: 可选字符串，取值 ltr/rtl 或 None + - get_popup_container: 可选字符串，指定弹层挂载容器 + - get_target_container: 可选字符串，指定目标容器 + - icon_prefix_cls: 可选字符串，图标前缀类名 + - locale: 可选字符串，取值为预定义的 LocaleType + - popup_match_select_width: 可选布尔或数值，影响弹层宽度策略 + - popup_overflow: 可选字符串，取值 viewport/scroll + - prefix_cls: 可选字符串，组件前缀类名 + - render_empty: 可选字符串，用于空状态渲染 + - theme: 可选字典（已弃用），警告提示使用 theme_config + - theme_config: 可选字典，主题配置（推荐） + - variant: 可选字符串，取值 outlined/filled/borderless + - virtual: 可选布尔 + - warning: 可选字典，警告配置 + - 元素级样式与类名：class_names、styles + - 布局与可见性：visible、elem_id、elem_classes、elem_style、render、as_item + - 额外属性：additional_props + - 其他通用属性：\_internal（内部保留） + +注意： + +- theme 与 theme_config 的关系：若传入 theme，将触发警告，建议使用 theme_config +- 插槽：仅支持 renderEmpty + +方法签名与返回类型： + +- preprocess(payload: None) -> None +- postprocess(value: None) -> None +- example_payload() -> Any +- example_value() -> Any + +**章节来源** + +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:31](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L31) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:42](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L42) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:86](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L86) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:101](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L101) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:104](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L104) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:108](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L108) +- [backend/modelscope_studio/components/antd/config_provider/**init**.py:111](file://backend/modelscope_studio/components/antd/config_provider/__init__.py#L111) + +### 前端实现要点 + +- 类型与导入：基于 Ant Design 的 ConfigProvider 类型，扩展 themeMode 与 theme.algorithm 字段 +- 主题算法：根据 themeMode 自动选择 dark/compact 算法，可与外部 theme.algorithm 合并 +- 语言设置：locale 默认从浏览器环境推断，支持 en_US 作为回退；按需异步加载对应语言包与 dayjs 语言 +- 容器回调：getPopupContainer、getTargetContainer、renderEmpty 通过 useFunction 包装，确保响应式更新 +- 插槽处理：将 slots 中以点号分隔的路径注入到 props 对应位置，renderEmpty 支持 ReactSlot + +```mermaid +flowchart TD +Start(["进入组件"]) --> LocaleCheck["检查 localeProp 是否存在"] +LocaleCheck --> HasLocale{"存在？"} +HasLocale --> |是| LoadLocale["按 locale 加载 Antd 语言与 dayjs 语言"] +HasLocale --> |否| UseDefault["使用 en_US 与默认 dayjs 语言"] +LoadLocale --> ApplyLocale["设置 antd 语言与 dayjs 语言"] +UseDefault --> ApplyLocale +ApplyLocale --> ThemeAlg["合并 themeMode 与 theme.algorithm"] +ThemeAlg --> Render["渲染
ModelScopeComponent
ModelScopeDataLayoutComponent"] +B["antd/__init__.py
导出各组件别名"] +C["alert/__init__.py"] +D["drawer/__init__.py"] +E["message/__init__.py"] +F["modal/__init__.py"] +G["notification/__init__.py"] +H["popconfirm/__init__.py"] +I["progress/__init__.py"] +J["result/__init__.py"] +K["skeleton/__init__.py"] +L["spin/__init__.py"] +M["watermark/__init__.py"] +end +subgraph "前端 Svelte" +P["config-provider/config-provider.tsx"] +Q["message/message.tsx"] +R["drawer/drawer.tsx"] +end +A --> C +A --> D +A --> E +A --> F +A --> G +A --> H +A --> I +A --> J +A --> K +A --> L +A --> M +B --> C +B --> D +B --> E +B --> F +B --> G +B --> H +B --> I +B --> J +B --> K +B --> L +B --> M +P --> E +P --> G +Q --> E +R --> D +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [frontend/antd/config-provider/config-provider.tsx:51-106](file://frontend/antd/config-provider/config-provider.tsx#L51-L106) +- [frontend/antd/message/message.tsx:55-78](file://frontend/antd/message/message.tsx#L55-L78) +- [frontend/antd/drawer/drawer.tsx:14-60](file://frontend/antd/drawer/drawer.tsx#L14-L60) + +章节来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +## 核心组件 + +以下为反馈组件的通用构造函数参数与属性概览（按组件分组）： + +- 通用参数 + - visible: 布尔，是否渲染 + - elem_id: 字符串，元素 ID + - elem_classes: 列表或字符串，CSS 类 + - elem_style: 字典，内联样式 + - render: 布尔，是否渲染 + - as_item: 字符串，布局项标识 + - class_names: 字典或字符串，附加类名映射 + - styles: 字典或字符串，附加样式映射 + - root_class_name: 字符串，根节点类名 + - additional_props: 字典，透传给前端组件的额外属性 + - \_internal: 内部参数，框架保留 + +- 事件绑定（通过 EVENTS 列表注册） + - 事件回调在构造时通过内部更新绑定到前端组件 + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:28-98](file://backend/modelscope_studio/utils/dev/component.py#L28-L98) +- [backend/modelscope_studio/components/antd/alert/**init**.py:16-20](file://backend/modelscope_studio/components/antd/alert/__init__.py#L16-L20) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:14-18](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L14-L18) +- [backend/modelscope_studio/components/antd/message/**init**.py:14-21](file://backend/modelscope_studio/components/antd/message/__init__.py#L14-L21) +- [backend/modelscope_studio/components/antd/modal/**init**.py:18-25](file://backend/modelscope_studio/components/antd/modal/__init__.py#L18-L25) +- [backend/modelscope_studio/components/antd/notification/**init**.py:14-21](file://backend/modelscope_studio/components/antd/notification/__init__.py#L14-L21) +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:14-27](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L14-L27) +- [backend/modelscope_studio/components/antd/watermark/**init**.py:12-16](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L12-L16) + +## 架构总览 + +反馈组件的调用链路如下：Python 层构造组件实例，设置属性与事件；前端 Svelte 组件接收 props 并与 Ant Design 组件对接；全局 ConfigProvider 提供主题与国际化；Message/Notification 通过前端上下文进行全局展示。 + +```mermaid +sequenceDiagram +participant Py as "Python 组件实例" +participant FE as "Svelte 前端组件" +participant CFG as "ConfigProvider" +participant MSG as "Message 上下文" +participant NOTI as "Notification 上下文" +Py->>FE : 设置属性与事件 +FE->>CFG : 应用主题/语言配置 +CFG-->>FE : 返回本地化与主题 +FE->>MSG : 注册消息展示 +FE->>NOTI : 注册通知展示 +MSG-->>Py : 事件回调如点击/关闭 +NOTI-->>Py : 事件回调如点击/关闭 +``` + +图表来源 + +- [frontend/antd/config-provider/config-provider.tsx:51-106](file://frontend/antd/config-provider/config-provider.tsx#L51-L106) +- [frontend/antd/message/message.tsx:55-78](file://frontend/antd/message/message.tsx#L55-L78) +- [backend/modelscope_studio/components/antd/message/**init**.py:14-21](file://backend/modelscope_studio/components/antd/message/__init__.py#L14-L21) +- [backend/modelscope_studio/components/antd/notification/**init**.py:14-21](file://backend/modelscope_studio/components/antd/notification/__init__.py#L14-L21) + +## 详细组件分析 + +### Alert（警告提示） + +- 构造函数参数与属性 + - action: 字符串，操作按钮内容 + - after_close: 字符串，关闭后的回调 + - banner: 布尔，横幅模式 + - closable: 布尔或字典，可关闭配置 + - description: 字符串，描述文本 + - icon: 字符串，图标 + - message: 字符串，标题 + - show_icon: 布尔，是否显示图标 + - type: 文本枚举（success/info/warning/error），类型 + - slots: 支持 action、closable.closeIcon、description、icon、message +- 方法 + - preprocess(payload): 输入预处理 + - postprocess(value): 输出后处理 + - example_payload()/example_value(): 示例数据 +- 事件 + - close: 关闭事件绑定 + +章节来源 + +- [backend/modelscope_studio/components/antd/alert/**init**.py:25-89](file://backend/modelscope_studio/components/antd/alert/__init__.py#L25-L89) + +### Drawer（抽屉） + +- 构造函数参数与属性 + - after_open_change: 字符串，打开状态变化回调 + - auto_focus: 布尔，自动聚焦 + - body_style: 字典，主体样式 + - close_icon: 字符串，关闭图标 + - closable: 布尔或字典，可关闭 + - destroy_on_close/destroy_on_hidden: 布尔，关闭/隐藏时销毁 + - draggable: 布尔，拖拽 + - extra: 字符串，额外内容 + - footer: 字符串，底部 + - force_render: 布尔，强制渲染 + - get_container: 字符串，容器选择器 + - height/width: 数字或字符串，尺寸 + - keyboard: 布尔，键盘支持 + - mask/mask_closable: 布尔，遮罩与点击遮罩关闭 + - placement: 文本枚举（left/right/top/bottom），位置 + - push: 布尔或字典，推动 + - resizable: 布尔，可调整大小 + - size: 文本枚举（default/large），尺寸 + - title: 字符串，标题 + - loading: 布尔，加载中 + - open: 布尔，是否打开 + - z_index: 整数，层级 + - drawer_render: 字符串，渲染函数 + - slots: 支持 closeIcon、closable.closeIcon、extra、footer、title、drawerRender +- 方法 + - preprocess()/postprocess(): 预处理/后处理 + - example_payload()/example_value(): 示例数据 +- 事件 + - close: 关闭事件绑定 + - resizable_resize_start: 调整大小开始事件绑定 + - resizable_resize: 调整大小事件绑定 + - resizable_resize_end: 调整大小结束事件绑定 + +**更新** Drawer组件新增了三个可调整大小相关的事件处理器： + +- resizable_resize_start：当用户开始拖拽调整抽屉大小时触发 +- resizable_resize：在调整过程中持续触发 +- resizable_resize_end：当调整操作完成时触发 + +这些事件允许开发者监听抽屉的动态调整过程，实现更精细的交互控制。 + +章节来源 + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:14-27](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L14-L27) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:26-126](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L26-L126) +- [frontend/antd/drawer/drawer.tsx:14-60](file://frontend/antd/drawer/drawer.tsx#L14-L60) + +### Message（全局消息） + +- 构造函数参数与属性 + - content: 字符串，消息内容 + - type: 文本枚举（success/info/warning/error/loading），类型 + - duration: 数字，持续时间 + - icon: 字符串，图标 + - key: 字符串/数字/浮点，唯一键 + - pause_on_hover: 布尔，悬停暂停 + - get_container: 字符串，容器选择器 + - rtl: 布尔，从右到左 + - top: 数字，顶部距离 + - slots: 支持 icon、content +- 方法 + - preprocess(payload: str|None): str|None + - postprocess(value: str|None): str|None + - example_payload()/example_value(): 示例数据 +- 事件 + - click/close: 点击与关闭事件绑定 + +章节来源 + +- [backend/modelscope_studio/components/antd/message/**init**.py:26-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L26-L91) +- [frontend/antd/message/message.tsx:55-78](file://frontend/antd/message/message.tsx#L55-L78) + +### Modal（模态框） + +- 构造函数参数与属性 + - after_close: 字符串，关闭后回调 + - cancel_button_props/cancel_text: 字典/字符串，取消按钮属性与文本 + - centered: 布尔，居中 + - closable/close_icon: 布尔/字典/字符串，可关闭与关闭图标 + - confirm_loading: 布尔，确认中 + - destroy_on_close/destroy_on_hidden: 布尔，关闭/隐藏时销毁 + - focus_trigger_after_close: 布尔，关闭后焦点触发 + - focusable: 布尔/字典，可聚焦 + - footer: 字符串或默认常量，底部 + - force_render: 布尔，强制渲染 + - get_container: 字符串，容器选择器 + - keyboard: 布尔，键盘支持 + - mask/mask_closable: 布尔，遮罩与点击遮罩关闭 + - modal_render: 字符串，渲染函数 + - ok_text/ok_type/ok_button_props: 字符串/字典，确定按钮属性 + - loading: 布尔，加载中 + - title: 字符串，标题 + - open: 布尔，是否打开 + - width: 数字/字符串，宽度 + - wrap_class_name: 字符串，包裹类名 + - z_index: 整数，层级 + - after_open_change: 字符串，打开状态变化回调 + - slots: 支持 closeIcon、cancelButtonProps.icon、cancelText、closable.closeIcon、closeIcon、footer、title、okButtonProps.icon、okText、modalRender +- 方法 + - preprocess()/postprocess(): 预处理/后处理 + - example_payload()/example_value(): 示例数据 +- 事件 + - ok/cancel: 确定与取消事件绑定 +- 静态子组件 + - Static: 静态模态组件（用于静态场景） + +章节来源 + +- [backend/modelscope_studio/components/antd/modal/**init**.py:34-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L34-L136) +- [backend/modelscope_studio/components/antd/modal/static/**init**.py:30-61](file://backend/modelscope_studio/components/antd/modal/static/__init__.py#L30-L61) + +### Notification（全局通知） + +- 构造函数参数与属性 + - message/description/title: 字符串，消息、描述、标题 + - type: 文本枚举（success/info/warning/error），类型 + - btn: 字符串，按钮 + - close_icon: 字符串/布尔，关闭图标 + - duration: 数字，持续时间 + - show_progress/pause_on_hover: 布尔，进度条与悬停暂停 + - icon: 字符串，图标 + - key: 字符串，唯一键 + - placement: 文本枚举（top/topLeft/topRight/bottom/bottomLeft/bottomRight），位置 + - role: 文本枚举（alert/status），角色 + - bottom/top: 数字，边距 + - rtl: 布尔，从右到左 + - get_container: 字符串，容器选择器 + - stack: 布尔/字典，堆叠配置 + - slots: 支持 actions、closeIcon、description、icon、message、title +- 方法 + - preprocess()/postprocess(): 预处理/后处理 + - example_payload()/example_value(): 示例数据 +- 事件 + - click/close: 点击与关闭事件绑定 + +章节来源 + +- [backend/modelscope_studio/components/antd/notification/**init**.py:26-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L26-L109) + +### Popconfirm（气泡确认框） + +- 构造函数参数与属性 + - title/description: 字符串，标题与描述 + - cancel_button_props/cancel_text: 字典/字符串，取消按钮 + - disabled: 布尔，禁用 + - icon: 字符串，图标 + - ok_button_props/ok_text/ok_type: 字典/字符串/枚举，确定按钮 + - show_cancel: 布尔，显示取消 + - align/arrow/auto_adjust_overflow: 字典/布尔，定位与自适应 + - color: 字符串，颜色 + - default_open: 布尔，初始打开 + - destroy_tooltip_on_hide/destroy_on_hidden: 布尔，销毁策略 + - fresh: 布尔，刷新 + - get_popup_container: 字符串，弹层容器 + - mouse_enter_delay/mouse_leave_delay: 数字，延迟 + - overlay_class_name/overlay_style/overlay_inner_style: 字符串/字典，覆盖层样式 + - placement: 文本枚举（多方向），位置 + - trigger: 文本枚举或列表（hover/focus/click/contextMenu），触发方式 + - open: 布尔，是否打开 + - z_index: 整数，层级 + - slots: 支持 title、description、cancelButtonProps.icon、cancelText、okButtonProps.icon、okText +- 方法 + - preprocess()/postprocess(): 预处理/后处理 + - example_payload()/example_value(): 示例数据 +- 事件 + - open_change/cancel/confirm/popup_click: 打开变化、取消、确认、弹层点击事件绑定 + +章节来源 + +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:39-156](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L39-L156) + +### Progress（进度条） + +- 构造函数参数与属性 + - percent: 整数，默认 0，百分比 + - format: 字符串，格式化函数 + - show_info: 布尔，显示信息 + - status: 文本枚举（success/exception/normal/active），状态 + - rounding: 字符串，圆角 + - stroke_color: 字符串/列表/字典，描边颜色 + - stroke_linecap: 文本枚举（round/butt/square），线帽 + - success: 字典，成功区域 + - trail_color: 字符串，轨道颜色 + - type: 文本枚举（line/circle/dashboard），类型 + - size: 数字/列表/字典/枚举（small/default），尺寸 + - steps: 整数/字典，步进 + - percent_position: 字典，百分比位置 + - stroke_width: 数字/浮点，描边宽度 + - gap_degree/gap_position/gap_placement: 数字/枚举，缺口角度与位置 +- 方法 + - preprocess()/postprocess(): 预处理/后处理 + - example_payload()/example_value(): 示例数据 + +章节来源 + +- [backend/modelscope_studio/components/antd/progress/**init**.py:15-100](file://backend/modelscope_studio/components/antd/progress/__init__.py#L15-L100) + +### Result（结果） + +- 构造函数参数与属性 + - extra: 字符串，额外内容 + - icon: 字符串，图标 + - status: 文本枚举（success/error/info/warning/404/403/500），状态 + - sub_title: 字符串，副标题 + - title: 字符串，标题 + - slots: 支持 extra、icon、subTitle、title +- 方法 + - preprocess()/postprocess(): 预处理/后处理 + - example_payload()/example_value(): 示例数据 + +章节来源 + +- [backend/modelscope_studio/components/antd/result/**init**.py:17-75](file://backend/modelscope_studio/components/antd/result/__init__.py#L17-L75) + +### Skeleton（骨架屏） + +- 构造函数参数与属性 + - active: 布尔，动画 + - avatar: 布尔/字典，头像骨架 + - loading: 布尔，加载中 + - paragraph: 布尔/字典，段落骨架 + - round: 布尔，圆角 + - title: 布尔/字典，标题骨架 +- 子组件 + - Node/Avatar/Button/Image/Input：骨架节点与元素 +- 方法 + - preprocess()/postprocess(): 预处理/后处理 + - example_payload()/example_value(): 示例数据 + +章节来源 + +- [backend/modelscope_studio/components/antd/skeleton/**init**.py:22-80](file://backend/modelscope_studio/components/antd/skeleton/__init__.py#L22-L80) + +### Spin（加载中） + +- 构造函数参数与属性 + - spinning: 布尔，是否旋转 + - delay: 数字，延迟 + - fullscreen: 布尔，全屏 + - indicator: 字符串，指示器 + - percent: 数字/浮点/枚举（'auto'），百分比 + - size: 文本枚举（small/default/large），尺寸 + - tip: 字符串，提示 + - wrapper_class_name: 字符串，包装类名 + - slots: 支持 tip、indicator +- 方法 + - preprocess()/postprocess(): 预处理/后处理 + - example_payload()/example_value(): 示例数据 + +章节来源 + +- [backend/modelscope_studio/components/antd/spin/**init**.py:17-79](file://backend/modelscope_studio/components/antd/spin/__init__.py#L17-L79) + +### Watermark（水印） + +- 构造函数参数与属性 + - content: 字符串/列表，内容（文本或数组） + - width/height: 数字/浮点，尺寸 + - inherit: 布尔，继承 + - rotate: 数字/浮点，旋转角度 + - z_index: 整数，层级 + - image: 字符串，图片水印 + - font: 字典，字体配置 + - gap: 列表，间距 + - offset: 列表，偏移 +- 方法 + - preprocess()/postprocess(): 预处理/后处理 + - example_payload()/example_value(): 示例数据 +- 事件 + - remove: 移除事件绑定 + +章节来源 + +- [backend/modelscope_studio/components/antd/watermark/**init**.py:18-84](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L18-L84) + +## 依赖分析 + +- 组件基类 + - ModelScopeLayoutComponent：布局型组件基类，支持事件与插槽 + - ModelScopeComponent：数据型组件基类，支持值与加载 + - ModelScopeDataLayoutComponent：数据+布局混合基类 +- 导出与别名 + - 通过 antd/**init**.py 将各组件导出为公共别名，便于直接 import 使用 + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +class ModelScopeComponent { ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +class ModelScopeDataLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +class AntdAlert +class AntdDrawer +class AntdMessage +class AntdModal +class AntdNotification +class AntdPopconfirm +class AntdProgress +class AntdResult +class AntdSkeleton +class AntdSpin +class AntdWatermark +ModelScopeLayoutComponent <|-- AntdAlert +ModelScopeLayoutComponent <|-- AntdDrawer +ModelScopeLayoutComponent <|-- AntdMessage +ModelScopeLayoutComponent <|-- AntdModal +ModelScopeLayoutComponent <|-- AntdNotification +ModelScopeLayoutComponent <|-- AntdPopconfirm +ModelScopeLayoutComponent <|-- AntdResult +ModelScopeLayoutComponent <|-- AntdSkeleton +ModelScopeLayoutComponent <|-- AntdSpin +ModelScopeLayoutComponent <|-- AntdWatermark +ModelScopeComponent <|-- AntdProgress +ModelScopeDataLayoutComponent <|-- AntdSkeleton +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/antd/alert/**init**.py:11-15](file://backend/modelscope_studio/components/antd/alert/__init__.py#L11-L15) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:10-13](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L10-L13) +- [backend/modelscope_studio/components/antd/message/**init**.py:10-13](file://backend/modelscope_studio/components/antd/message/__init__.py#L10-L13) +- [backend/modelscope_studio/components/antd/modal/**init**.py:11-16](file://backend/modelscope_studio/components/antd/modal/__init__.py#L11-L16) +- [backend/modelscope_studio/components/antd/notification/**init**.py:10-13](file://backend/modelscope_studio/components/antd/notification/__init__.py#L10-L13) +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:10-13](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L10-L13) +- [backend/modelscope_studio/components/antd/progress/**init**.py:8-11](file://backend/modelscope_studio/components/antd/progress/__init__.py#L8-L11) +- [backend/modelscope_studio/components/antd/result/**init**.py:8-11](file://backend/modelscope_studio/components/antd/result/__init__.py#L8-L11) +- [backend/modelscope_studio/components/antd/skeleton/**init**.py:11-14](file://backend/modelscope_studio/components/antd/skeleton/__init__.py#L11-L14) +- [backend/modelscope_studio/components/antd/spin/**init**.py:8-11](file://backend/modelscope_studio/components/antd/spin/__init__.py#L8-L11) +- [backend/modelscope_studio/components/antd/watermark/**init**.py:8-11](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L8-L11) + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) + +## 性能考虑 + +- 事件绑定与回调 + - 通过 EVENTS 列表在构造时绑定回调，避免运行期重复绑定带来的开销 +- 渲染策略 + - destroy_on_close/destroy_on_hidden：在关闭或隐藏时销毁，减少内存占用 + - force_render：按需强制渲染，避免不必要的重渲染 +- 动画与过渡 + - 通过前端组件的动画配置（如 Spin 的 delay、Progress 的 active）控制视觉反馈与性能平衡 +- 全局组件 + - Message/Notification 采用上下文管理，避免频繁创建销毁实例 + +## 故障排查指南 + +- 事件未触发 + - 检查 EVENTS 列表与回调绑定是否正确 + - 确认前端组件已正确接收并转发事件 +- 显示异常 + - 检查 visible、render、open 等状态参数 + - 对于全局组件（Message/Notification），确认容器选择器与挂载目标 +- 主题与国际化不生效 + - 确认 ConfigProvider 的 locale 与 themeMode 设置 + - 检查 locales.ts 中的语言包是否可用 + +章节来源 + +- [backend/modelscope_studio/components/antd/alert/**init**.py:16-20](file://backend/modelscope_studio/components/antd/alert/__init__.py#L16-L20) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:14-18](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L14-L18) +- [backend/modelscope_studio/components/antd/message/**init**.py:14-21](file://backend/modelscope_studio/components/antd/message/__init__.py#L14-L21) +- [backend/modelscope_studio/components/antd/modal/**init**.py:18-25](file://backend/modelscope_studio/components/antd/modal/__init__.py#L18-L25) +- [backend/modelscope_studio/components/antd/notification/**init**.py:14-21](file://backend/modelscope_studio/components/antd/notification/__init__.py#L14-L21) +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:14-27](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L14-L27) +- [backend/modelscope_studio/components/antd/watermark/**init**.py:12-16](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L12-L16) +- [frontend/antd/config-provider/config-provider.tsx:51-106](file://frontend/antd/config-provider/config-provider.tsx#L51-L106) +- [frontend/antd/config-provider/locales.ts:159-806](file://frontend/antd/config-provider/locales.ts#L159-L806) + +## 结论 + +本参考文档梳理了反馈组件的 Python API、前端集成与全局配置要点。建议在实际使用中： + +- 明确组件职责与适用场景（提示、对话、进度、骨架、加载、水印） +- 合理设置事件与生命周期参数，确保交互顺畅 +- 使用 ConfigProvider 进行主题与国际化统一管理 +- 遵循通知策略与用户体验设计原则，避免过度打扰 + +## 附录 + +- 使用示例（以"示例路径"形式给出） + - Message：见 [docs/components/antd/message/README-zh_CN.md:1-8](file://docs/components/antd/message/README-zh_CN.md#L1-L8) + - Notification：见 [docs/components/antd/notification/README-zh_CN.md:1-8](file://docs/components/antd/notification/README-zh_CN.md#L1-L8) +- 全局配置与国际化 + - ConfigProvider：见 [frontend/antd/config-provider/config-provider.tsx:51-106](file://frontend/antd/config-provider/config-provider.tsx#L51-L106) + - 语言包：见 [frontend/antd/config-provider/locales.ts:159-806](file://frontend/antd/config-provider/locales.ts#L159-L806) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\345\257\274\350\210\252\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\345\257\274\350\210\252\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..19b31cad --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\345\257\274\350\210\252\347\273\204\344\273\266 API.md" @@ -0,0 +1,578 @@ +# 导航组件 API + + +**本文引用的文件** +- [anchor/__init__.py](file://backend/modelscope_studio/components/antd/anchor/__init__.py) +- [anchor/item/__init__.py](file://backend/modelscope_studio/components/antd/anchor/item/__init__.py) +- [breadcrumb/__init__.py](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py) +- [breadcrumb/item/__init__.py](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py) +- [dropdown/__init__.py](file://backend/modelscope_studio/components/antd/dropdown/__init__.py) +- [dropdown/button/__init__.py](file://backend/modelscope_studio/components/antd/dropdown/button/__init__.py) +- [menu/__init__.py](file://backend/modelscope_studio/components/antd/menu/__init__.py) +- [menu/item/__init__.py](file://backend/modelscope_studio/components/antd/menu/item/__init__.py) +- [pagination/__init__.py](file://backend/modelscope_studio/components/antd/pagination/__init__.py) +- [steps/__init__.py](file://backend/modelscope_studio/components/antd/steps/__init__.py) +- [steps/item/__init__.py](file://backend/modelscope_studio/components/antd/steps/item/__init__.py) + + +## 更新摘要 + +**变更内容** + +- 更新Menu组件API文档，新增popupRender插槽功能说明 +- 补充Menu组件popupRender参数的详细说明 +- 对比Menu与Dropdown组件中popupRender功能的差异 + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 Ant Design 导航相关组件的 Python API 参考与使用指南，覆盖以下组件： + +- Anchor（锚点） +- Breadcrumb（面包屑） +- Dropdown（下拉菜单） +- Menu（菜单） +- Pagination（分页） +- Steps（步骤条） + +内容包括：类与子项类的构造参数、事件监听、插槽、状态管理要点、与路由/前端交互模式、可访问性与键盘导航建议、以及性能优化与最佳实践。 + +## 项目结构 + +导航组件均位于后端 Python 包中，采用"组件级目录 + 子项目录"的组织方式，便于扩展与维护。每个组件类负责渲染与事件绑定，子项类用于承载具体条目数据结构。 + +```mermaid +graph TB +subgraph "Antd 组件" +A["anchor/__init__.py"] +B["breadcrumb/__init__.py"] +C["dropdown/__init__.py"] +D["menu/__init__.py"] +E["pagination/__init__.py"] +F["steps/__init__.py"] +end +subgraph "子项" +A1["anchor/item/__init__.py"] +B1["breadcrumb/item/__init__.py"] +C1["dropdown/button/__init__.py"] +D1["menu/item/__init__.py"] +F1["steps/item/__init__.py"] +end +A --> A1 +B --> B1 +C --> C1 +D --> D1 +F --> F1 +``` + +**章节来源** + +- [anchor/**init**.py:1-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L1-L117) +- [breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [dropdown/**init**.py:1-119](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L1-L119) +- [menu/**init**.py:1-125](file://backend/modelscope_studio/components/antd/menu/__init__.py#L1-L125) +- [pagination/**init**.py:1-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L1-L107) +- [steps/**init**.py:1-95](file://backend/modelscope_studio/components/antd/steps/__init__.py#L1-L95) + +## 核心组件 + +本节概述各导航组件的职责、典型用法与关键参数。 + +- Anchor（锚点） + - 职责：在单页内提供锚点跳转，支持固定模式与方向设置。 + - 关键参数：affix、bounds、get_container、offset_top、direction、replace、items 等。 + - 事件：change、click、affix_change。 + - 插槽：items。 + - 使用场景：长文档目录、章节定位。 + +- Breadcrumb（面包屑） + - 职责：显示当前页面在层级结构中的位置。 + - 关键参数：item_render、params、items、separator。 + - 插槽：separator、itemRender、items、dropdownIcon。 + - 使用场景：页面路径导航、层级浏览。 + +- Dropdown（下拉菜单） + - 职责：点击/悬停触发的弹出式菜单。 + - 关键参数：arrow、auto_adjust_overflow、disabled、placement、trigger、menu、open 等。 + - 事件：open_change、menu_click、menu_select、menu_deselect、menu_open_change。 + - 插槽：menu.expandIcon、menu.overflowedIndicator、menu.items、dropdownRender、popupRender。 + - 使用场景：操作入口、功能集合展开。 + +- Menu（菜单） + - 职责：垂直/水平/内联的导航菜单。 + - 关键参数：open_keys、selected_keys、mode、theme/theme_value、inline_indent、items、multiple、trigger_sub_menu_action、popup_render 等。 + - 事件：click、deselect、open_change、select。 + - 插槽：expandIcon、overflowedIndicator、items、popupRender。 + - 使用场景：站点主导航、侧边栏导航。 + +- Pagination（分页） + - 职责：大数据集分页展示与切换。 + - 关键参数：current、default_current、page_size、default_page_size、total、pageSizeOptions、showQuickJumper、showSizeChanger、simple、size 等。 + - 事件：change、show_size_change。 + - 插槽：showQuickJumper.goButton、itemRender。 + - 使用场景：列表/表格分页。 + +- Steps（步骤条） + - 职责：引导用户完成多步骤流程。 + - 关键参数：current、direction、label_placement、title_placement、percent、progress_dot、size、status、type、items。 + - 事件：change。 + - 插槽：progressDot、items。 + - 使用场景：向导、表单分步提交。 + +**章节来源** + +- [anchor/**init**.py:11-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L11-L117) +- [breadcrumb/**init**.py:9-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L9-L73) +- [dropdown/**init**.py:11-119](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L11-L119) +- [menu/**init**.py:12-125](file://backend/modelscope_studio/components/antd/menu/__init__.py#L12-L125) +- [pagination/**init**.py:10-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L10-L107) +- [steps/**init**.py:11-95](file://backend/modelscope_studio/components/antd/steps/__init__.py#L11-L95) + +## 架构总览 + +导航组件统一继承自布局组件基类，通过前端目录映射与事件绑定实现与前端的交互。组件支持额外属性传递、样式/类名注入、可见性与渲染控制等通用能力。 + +```mermaid +classDiagram +class ModelScopeLayoutComponent +class AntdAnchor { ++__init__(...) ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess(...) ++postprocess(...) ++example_payload() ++example_value() +} +class AntdBreadcrumb { ++__init__(...) ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess(...) ++postprocess(...) ++example_payload() ++example_value() +} +class AntdDropdown { ++__init__(...) ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess(...) ++postprocess(...) ++example_payload() ++example_value() +} +class AntdMenu { ++__init__(...) ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess(...) ++postprocess(...) ++example_payload() ++example_value() +} +class AntdPagination { ++__init__(...) ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess(...) ++postprocess(...) ++example_payload() ++example_value() +} +class AntdSteps { ++__init__(...) ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess(...) ++postprocess(...) ++example_payload() ++example_value() +} +AntdAnchor --> ModelScopeLayoutComponent +AntdBreadcrumb --> ModelScopeLayoutComponent +AntdDropdown --> ModelScopeLayoutComponent +AntdMenu --> ModelScopeLayoutComponent +AntdPagination --> ModelScopeLayoutComponent +AntdSteps --> ModelScopeLayoutComponent +``` + +**图表来源** + +- [anchor/**init**.py:11-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L11-L117) +- [breadcrumb/**init**.py:9-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L9-L73) +- [dropdown/**init**.py:11-119](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L11-L119) +- [menu/**init**.py:12-125](file://backend/modelscope_studio/components/antd/menu/__init__.py#L12-L125) +- [pagination/**init**.py:10-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L10-L107) +- [steps/**init**.py:11-95](file://backend/modelscope_studio/components/antd/steps/__init__.py#L11-L95) + +## 详细组件分析 + +### Anchor（锚点）API + +- 类：AntdAnchor +- 子项类：AntdAnchorItem +- 事件 + - change：监听锚点链接变化 + - click：处理点击事件 + - affix_change：固定状态变化回调 +- 插槽 + - items：锚点条目集合 +- 关键参数 + - affix：是否启用固定模式 + - bounds：锚点区域边界距离 + - get_container：滚动容器选择器 + - get_current_anchor：自定义高亮锚点 + - offset_top：计算滚动位置时的顶部偏移 + - show_ink_in_fixed：固定模式下是否显示墨水条 + - target_offset：锚点滚动偏移，默认使用 offsetTop + - items：条目数据，支持嵌套 children + - direction：垂直或水平方向 + - replace：替换浏览器历史而非新增 +- 方法 + - preprocess(payload): 返回 None + - postprocess(value): 返回 None + - example_payload(): 返回 None + - example_value(): 返回 None +- 使用示例（路径参考） + - 页面锚点导航：[anchor/**init**.py:38-98](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L38-L98) + +**章节来源** + +- [anchor/**init**.py:11-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L11-L117) +- [anchor/item/**init**.py](file://backend/modelscope_studio/components/antd/anchor/item/__init__.py) + +### Breadcrumb（面包屑）API + +- 类：AntdBreadcrumb +- 子项类：AntdBreadcrumbItem +- 插槽 + - separator：分隔符 + - itemRender：自定义条目渲染 + - items：条目集合 + - dropdownIcon：下拉图标 +- 关键参数 + - item_render：自定义条目渲染函数 + - params：渲染参数 + - items：条目数组 + - separator：分隔符字符串 +- 方法 + - preprocess(payload): 返回 None + - postprocess(value): 返回 None + - example_payload(): 返回 None + - example_value(): 返回 None +- 使用示例（路径参考） + - 面包屑导航：[breadcrumb/**init**.py:20-54](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L20-L54) + +**章节来源** + +- [breadcrumb/**init**.py:9-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L9-L73) +- [breadcrumb/item/**init**.py](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py) + +### Dropdown（下拉菜单）API + +- 类：AntdDropdown +- 子项类：AntdDropdownButton +- 事件 + - open_change：下拉打开/关闭状态变化 + - menu_click：菜单项点击 + - menu_select：菜单项选中 + - menu_deselect：菜单项取消选中 + - menu_open_change：子菜单打开/关闭状态变化 +- 插槽 + - menu.expandIcon：菜单展开图标 + - menu.overflowedIndicator：溢出指示器 + - menu.items：菜单项集合 + - dropdownRender：自定义下拉渲染 + - popupRender：自定义弹层渲染 +- 关键参数 + - arrow：是否显示箭头 + - auto_adjust_overflow：是否自动调整溢出 + - auto_focus：是否自动聚焦 + - disabled：是否禁用 + - destroy_popup_on_hide：隐藏时销毁弹层 + - destroy_on_hidden：隐藏后销毁 + - dropdown_render：下拉渲染函数 + - popup_render：弹层渲染函数 + - get_popup_container：弹层挂载容器 + - menu：菜单配置对象 + - overlay_class_name：覆盖层类名 + - overlay_style：覆盖层样式 + - placement：弹出位置 + - trigger：触发方式（click/hover/contextMenu） + - open：受控打开状态 + - inner_elem_style：内部元素样式 +- 方法 + - preprocess(payload): 返回 None + - postprocess(value): 返回 None + - example_payload(): 返回 None + - example_value(): 返回 None +- 使用示例（路径参考） + - 下拉菜单：[dropdown/**init**.py:40-100](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L40-L100) + +**章节来源** + +- [dropdown/**init**.py:11-119](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L11-L119) +- [dropdown/button/**init**.py](file://backend/modelscope_studio/components/antd/dropdown/button/__init__.py) + +### Menu（菜单）API + +- 类：AntdMenu +- 子项类：AntdMenuItem +- 事件 + - click：菜单项点击 + - deselect：菜单项取消选中 + - open_change：子菜单打开/关闭状态变化 + - select：菜单项选中 +- 插槽 + - expandIcon：展开图标 + - overflowedIndicator：溢出指示器 + - items：菜单项集合 + - popupRender：弹层渲染 +- 关键参数 + - open_keys：受控打开的子菜单键 + - selected_keys：受控选中的菜单键 + - selectable：是否可选 + - default_open_keys：默认打开的子菜单键 + - default_selected_keys：默认选中的菜单键 + - expand_icon：展开图标 + - force_sub_menu_render：是否强制渲染子菜单 + - inline_collapsed：内联折叠 + - inline_indent：内联缩进像素 + - items：菜单项数组 + - mode：模式（vertical/horizontal/inline） + - multiple：是否多选 + - overflowed_indicator：溢出指示器 + - sub_menu_close_delay：子菜单关闭延迟 + - sub_menu_open_delay：子菜单打开延迟 + - theme/theme_value：主题（light/dark），优先使用 theme_value + - trigger_sub_menu_action：触发子菜单动作（click/hover） + - popup_render：弹层渲染函数 +- 方法 + - preprocess(payload): 返回 None + - postprocess(value): 返回 None + - example_payload(): 返回 None + - example_value(): 返回 None +- 使用示例（路径参考） + - 导航菜单：[menu/**init**.py:36-103](file://backend/modelscope_studio/components/antd/menu/__init__.py#L36-L103) + +**更新** 新增popupRender参数，用于自定义菜单弹层渲染 + +**章节来源** + +- [menu/**init**.py:12-125](file://backend/modelscope_studio/components/antd/menu/__init__.py#L12-L125) +- [menu/item/**init**.py](file://backend/modelscope_studio/components/antd/menu/item/__init__.py) + +### Pagination（分页）API + +- 类：AntdPagination +- 事件 + - change：页码或页大小变化 + - show_size_change：页大小改变 +- 插槽 + - showQuickJumper.goButton：快速跳转按钮 + - itemRender：自定义页码渲染 +- 关键参数 + - align：对齐方式（start/center/end） + - current：当前页 + - default_current：默认当前页 + - default_page_size：默认页大小 + - page_size：当前页大小 + - disabled：是否禁用 + - hide_on_single_page：单页时隐藏 + - item_render：页码项渲染函数 + - page_size_options：页大小选项 + - responsive：响应式布局 + - show_less_items：较少页码 + - show_quick_jumper：快速跳转开关或配置 + - show_size_changer：页大小切换器开关或配置 + - show_title：是否显示标题 + - show_total：总数渲染模板 + - simple：简单模式开关或配置 + - size：尺寸（small/default） + - total：总条目数 +- 方法 + - preprocess(payload): 返回 None + - postprocess(value): 返回 None + - example_payload(): 返回 None + - example_value(): 返回 None +- 使用示例（路径参考） + - 分页控件：[pagination/**init**.py:26-88](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L26-L88) + +**章节来源** + +- [pagination/**init**.py:10-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L10-L107) + +### Steps（步骤条）API + +- 类：AntdSteps +- 子项类：AntdStepsItem +- 事件 + - change：步骤变化 +- 插槽 + - progressDot：进度点渲染 + - items：步骤项集合 +- 关键参数 + - current：当前步骤索引 + - direction：方向（horizontal/vertical） + - initial：初始步骤 + - label_placement：标签放置（horizontal/vertical） + - title_placement：标题放置 + - percent：完成百分比 + - progress_dot：是否使用点状进度 + - responsive：响应式 + - size：尺寸（small/default） + - status：状态（wait/process/finish/error） + - type：类型（default/navigation/inline） + - items：步骤项数组 +- 方法 + - preprocess(payload): 返回 None + - postprocess(value): 返回 None + - example_payload(): 返回 None + - example_value(): 返回 None +- 使用示例（路径参考） + - 步骤条：[steps/**init**.py:25-75](file://backend/modelscope_studio/components/antd/steps/__init__.py#L25-L75) + +**章节来源** + +- [steps/**init**.py:11-95](file://backend/modelscope_studio/components/antd/steps/__init__.py#L11-L95) +- [steps/item/**init**.py](file://backend/modelscope_studio/components/antd/steps/item/__init__.py) + +## 依赖分析 + +- 组件共同依赖 + - 基类：ModelScopeLayoutComponent（统一生命周期与渲染） + - 事件系统：gradio.events.EventListener（事件绑定） + - 前端目录解析：resolve_frontend_dir（按组件名映射前端目录） +- 组件间耦合 + - 各组件相对独立，通过各自子项类承载条目数据，降低耦合度 + - 事件与插槽机制统一，便于扩展与复用 +- 外部依赖 + - 与前端 Svelte 组件配合，通过事件绑定与 props 传递实现交互 + +```mermaid +graph LR +Base["ModelScopeLayoutComponent"] --> Anchor["AntdAnchor"] +Base --> Breadcrumb["AntdBreadcrumb"] +Base --> Dropdown["AntdDropdown"] +Base --> Menu["AntdMenu"] +Base --> Pagination["AntdPagination"] +Base --> Steps["AntdSteps"] +Events["EventListener"] --> Anchor +Events --> Breadcrumb +Events --> Dropdown +Events --> Menu +Events --> Pagination +Events --> Steps +Resolve["resolve_frontend_dir"] --> Anchor +Resolve --> Breadcrumb +Resolve --> Dropdown +Resolve --> Menu +Resolve --> Pagination +Resolve --> Steps +``` + +**图表来源** + +- [anchor/**init**.py:7-99](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L7-L99) +- [breadcrumb/**init**.py:5-56](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L5-L56) +- [dropdown/**init**.py:5-102](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L5-L102) +- [menu/**init**.py:6-105](file://backend/modelscope_studio/components/antd/menu/__init__.py#L6-L105) +- [pagination/**init**.py:5-90](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L5-L90) +- [steps/**init**.py:5-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L5-L77) + +**章节来源** + +- [anchor/**init**.py:1-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L1-L117) +- [breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [dropdown/**init**.py:1-119](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L1-L119) +- [menu/**init**.py:1-125](file://backend/modelscope_studio/components/antd/menu/__init__.py#L1-L125) +- [pagination/**init**.py:1-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L1-L107) +- [steps/**init**.py:1-95](file://backend/modelscope_studio/components/antd/steps/__init__.py#L1-L95) + +## 性能考虑 + +- 事件绑定按需开启：仅在注册对应事件监听时才启用前端绑定，避免不必要的开销。 +- 受控状态：通过 open_keys、selected_keys、current 等受控属性减少重复渲染。 +- 插槽与自定义渲染：合理使用 itemRender/dropdownRender 等插槽，避免过度复杂逻辑导致的重渲染。 +- 列表渲染：Pagination 与 Menu 的 items 应尽量扁平化，减少深层嵌套带来的渲染成本。 +- 固定与滚动：Anchor 的 affix 与 bounds 参数应结合页面滚动性能进行调优，避免频繁重排。 +- popupRender使用：Menu组件的popupRender功能应谨慎使用，避免在渲染函数中执行重型计算，影响菜单性能。 + +## 故障排查指南 + +- 事件未触发 + - 检查是否正确注册了事件监听（如 change、click、open_change 等） + - 确认前端已启用相应事件绑定（由组件内部更新 \_internal 属性触发） +- 样式/类名不生效 + - 确认传入 class_names/styles/root_class_name 是否正确 + - 检查覆盖层样式 overlay_style/overlay_class_name 是否冲突 +- 下拉菜单未显示 + - 检查 disabled、destroy_on_hidden、get_popup_container 等配置 + - 确认触发方式 trigger 与 placement 是否合适 + - 验证popupRender插槽是否正确配置 +- 分页无效 + - 检查 total、page_size、current 等参数是否一致 + - 确认事件回调是否更新受控状态 +- 步骤条状态异常 + - 检查 current、status、type、direction 等参数组合 + - 确认 items 结构与索引匹配 +- Menu组件popupRender问题 + - 确认popupRender函数或插槽是否正确传递给前端组件 + - 检查popupRender的返回值格式是否符合Ant Design要求 + - 验证popupRender不会导致菜单渲染性能问题 + +**章节来源** + +- [anchor/**init**.py:20-33](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L20-L33) +- [dropdown/**init**.py:16-32](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L16-L32) +- [menu/**init**.py:18-31](file://backend/modelscope_studio/components/antd/menu/__init__.py#L18-L31) +- [pagination/**init**.py:14-21](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L14-L21) +- [steps/**init**.py:16-20](file://backend/modelscope_studio/components/antd/steps/__init__.py#L16-L20) + +## 结论 + +本指南系统梳理了导航组件的 API、事件、插槽与使用要点，并提供了与前端交互、状态管理、可访问性与性能优化的实践建议。建议在实际项目中结合业务场景选择合适的组件与参数组合，确保良好的用户体验与开发效率。 + +**更新** Menu组件新增的popupRender插槽功能为开发者提供了更灵活的菜单弹层定制能力，但使用时需要注意性能影响和兼容性要求。 + +## 附录 + +- 无障碍与键盘导航建议 + - 为可交互元素提供明确的焦点顺序与键盘操作（如 Enter/Space 触发、Esc 关闭） + - 为菜单与下拉提供 ARIA 属性（role、aria-expanded、aria-haspopup 等） + - 为分页与步骤条提供清晰的语义化标签与状态提示 +- 路由集成 + - Anchor 与 Steps 可与前端路由联动，通过事件回调更新当前状态 + - Breadcrumb 可根据路由路径动态生成条目 + - Menu组件的popupRender可用于实现自定义的路由导航弹层 +- 最佳实践 + - 将 items 数据结构化，避免在渲染函数中做重型计算 + - 合理使用受控属性，避免状态不同步 + - 在移动端适配响应式布局与触摸交互 + - 使用popupRender时，确保返回的React组件结构符合Ant Design规范 + - 避免在popupRender中执行异步操作，以免影响菜单响应性能 diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\345\270\203\345\261\200\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\345\270\203\345\261\200\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..2bf1f9b3 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\345\270\203\345\261\200\347\273\204\344\273\266 API.md" @@ -0,0 +1,465 @@ +# 布局组件 API + + +**本文引用的文件** +- [divider/__init__.py](file://backend/modelscope_studio/components/antd/divider/__init__.py) +- [flex/__init__.py](file://backend/modelscope_studio/components/antd/flex/__init__.py) +- [grid/row/__init__.py](file://backend/modelscope_studio/components/antd/grid/row/__init__.py) +- [grid/col/__init__.py](file://backend/modelscope_studio/components/antd/grid/col/__init__.py) +- [layout/__init__.py](file://backend/modelscope_studio/components/antd/layout/__init__.py) +- [layout/content/__init__.py](file://backend/modelscope_studio/components/antd/layout/content/__init__.py) +- [layout/footer/__init__.py](file://backend/modelscope_studio/components/antd/layout/footer/__init__.py) +- [layout/header/__init__.py](file://backend/modelscope_studio/components/antd/layout/header/__init__.py) +- [layout/sider/__init__.py](file://backend/modelscope_studio/components/antd/layout/sider/__init__.py) +- [space/__init__.py](file://backend/modelscope_studio/components/antd/space/__init__.py) +- [space/compact/__init__.py](file://backend/modelscope_studio/components/antd/space/compact/__init__.py) +- [splitter/__init__.py](file://backend/modelscope_studio/components/antd/splitter/__init__.py) +- [splitter/panel/__init__.py](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 Antd 布局组件的 Python API 参考文档，覆盖 Divider、Flex、Grid（Row/Col）、Layout（Layout/Header/Sider/Content/Footer）、Space、Splitter（Splitter/Panel）等布局相关组件。内容包括： + +- 每个组件类的构造函数参数、属性定义、方法签名与返回值类型 +- 标准布局组合使用示例（响应式布局、网格系统、弹性布局） +- 嵌套规则、间距控制与对齐方式 +- 布局断点配置、媒体查询集成与移动端适配 +- 组件协作模式与性能优化建议 + +## 项目结构 + +这些布局组件均位于后端 Python 包中，采用统一的基类与前端目录解析机制，便于在运行时映射到对应的前端实现。 + +```mermaid +graph TB +subgraph "Antd 布局组件" +D["Divider"] +F["Flex"] +G["Grid
Row/Col"] +L["Layout
Layout/Header/Sider/Content/Footer"] +S["Space
Space/Compact"] +SP["Splitter
Splitter/Panel"] +end +D --> |"使用"| D +F --> |"使用"| F +G --> |"使用"| G +L --> |"包含"| L +S --> |"使用"| S +SP --> |"包含"| SP +``` + +**图表来源** + +- [divider/**init**.py:1-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L1-L95) +- [flex/**init**.py:1-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L1-L98) +- [grid/row/**init**.py:1-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L1-L94) +- [grid/col/**init**.py:1-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L1-L114) +- [layout/**init**.py:1-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L1-L91) +- [layout/content/**init**.py:1-75](file://backend/modelscope_studio/components/antd/layout/content/__init__.py#L1-L75) +- [layout/footer/**init**.py:1-75](file://backend/modelscope_studio/components/antd/layout/footer/__init__.py#L1-L75) +- [layout/header/**init**.py:1-75](file://backend/modelscope_studio/components/antd/layout/header/__init__.py#L1-L75) +- [layout/sider/**init**.py:1-128](file://backend/modelscope_studio/components/antd/layout/sider/__init__.py#L1-L128) +- [space/**init**.py:1-104](file://backend/modelscope_studio/components/antd/space/__init__.py#L1-L104) +- [space/compact/**init**.py:1-81](file://backend/modelscope_studio/components/antd/space/compact/__init__.py#L1-L81) +- [splitter/**init**.py:1-97](file://backend/modelscope_studio/components/antd/splitter/__init__.py#L1-L97) +- [splitter/panel/**init**.py:1-86](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L1-L86) + +**章节来源** + +- [divider/**init**.py:1-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L1-L95) +- [flex/**init**.py:1-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L1-L98) +- [grid/row/**init**.py:1-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L1-L94) +- [grid/col/**init**.py:1-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L1-L114) +- [layout/**init**.py:1-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L1-L91) +- [layout/content/**init**.py:1-75](file://backend/modelscope_studio/components/antd/layout/content/__init__.py#L1-L75) +- [layout/footer/**init**.py:1-75](file://backend/modelscope_studio/components/antd/layout/footer/__init__.py#L1-L75) +- [layout/header/**init**.py:1-75](file://backend/modelscope_studio/components/antd/layout/header/__init__.py#L1-L75) +- [layout/sider/**init**.py:1-128](file://backend/modelscope_studio/components/antd/layout/sider/__init__.py#L1-L128) +- [space/**init**.py:1-104](file://backend/modelscope_studio/components/antd/space/__init__.py#L1-L104) +- [space/compact/**init**.py:1-81](file://backend/modelscope_studio/components/antd/space/compact/__init__.py#L1-L81) +- [splitter/**init**.py:1-97](file://backend/modelscope_studio/components/antd/splitter/__init__.py#L1-L97) +- [splitter/panel/**init**.py:1-86](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L1-L86) + +## 核心组件 + +- Divider：用于分隔内容区域的分割线，支持水平/垂直、标题位置、虚线/实线样式、纯文本风格等。 +- Flex：弹性布局容器，支持主轴/交叉轴对齐、换行、间距、方向等。 +- Grid：栅格系统，Row 提供行级对齐、间距与换行，Col 提供列跨度、偏移、顺序、响应式断点等。 +- Layout：页面整体布局，包含 Header、Sider、Content、Footer 子组件，支持响应式折叠与断点事件。 +- Space：子元素间距设置，支持方向、对齐、自动换行、分隔符；Space.Compact 用于表单紧凑排列。 +- Splitter：可拖拽分割面板，支持水平/垂直布局、面板尺寸范围、折叠与拖拽事件。 + +**章节来源** + +- [divider/**init**.py:8-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L8-L95) +- [flex/**init**.py:8-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L8-L98) +- [grid/row/**init**.py:8-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L8-L94) +- [grid/col/**init**.py:8-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L8-L114) +- [layout/**init**.py:14-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L14-L91) +- [layout/content/**init**.py:10-75](file://backend/modelscope_studio/components/antd/layout/content/__init__.py#L10-L75) +- [layout/footer/**init**.py:10-75](file://backend/modelscope_studio/components/antd/layout/footer/__init__.py#L10-L75) +- [layout/header/**init**.py:10-75](file://backend/modelscope_studio/components/antd/layout/header/__init__.py#L10-L75) +- [layout/sider/**init**.py:11-128](file://backend/modelscope_studio/components/antd/layout/sider/__init__.py#L11-L128) +- [space/**init**.py:9-104](file://backend/modelscope_studio/components/antd/space/__init__.py#L9-L104) +- [space/compact/**init**.py:8-81](file://backend/modelscope_studio/components/antd/space/compact/__init__.py#L8-L81) +- [splitter/**init**.py:11-97](file://backend/modelscope_studio/components/antd/splitter/__init__.py#L11-L97) +- [splitter/panel/**init**.py:8-86](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L8-L86) + +## 架构总览 + +以下类图展示布局组件的继承与组合关系，以及关键属性与方法。 + +```mermaid +classDiagram +class AntdDivider { ++__init__(value, dashed, variant, orientation, orientation_margin, plain, type, size, ...) ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdFlex { ++__init__(orientation, vertical, wrap, justify, align, flex, gap, component, ...) ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdRow { ++__init__(align, gutter, justify, wrap, ...) +} +class AntdCol { ++__init__(flex, offset, order, pull, push, span, xs, sm, md, lg, xl, xxl, ...) +} +class AntdLayout { ++__init__(has_sider, ...) ++Content ++Footer ++Header ++Sider +} +class AntdLayoutContent +class AntdLayoutFooter +class AntdLayoutHeader +class AntdLayoutSider { ++__init__(breakpoint, collapsed, collapsed_width, collapsible, default_collapsed, reverse_arrow, theme_value, trigger, width, ...) +} +class AntdSpace { ++__init__(align, direction/orientation, size, split/separator, wrap, ...) ++Compact +} +class AntdSpaceCompact { ++__init__(block, direction, size, ...) +} +class AntdSplitter { ++__init__(layout/orientation, lazy, ...) ++Panel +} +class AntdSplitterPanel { ++__init__(default_size, min, max, size, collapsible, resizable, ...) +} +AntdLayout --> AntdLayoutContent : "包含" +AntdLayout --> AntdLayoutFooter : "包含" +AntdLayout --> AntdLayoutHeader : "包含" +AntdLayout --> AntdLayoutSider : "包含" +AntdSpace --> AntdSpaceCompact : "包含" +AntdSplitter --> AntdSplitterPanel : "包含" +``` + +**图表来源** + +- [divider/**init**.py:8-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L8-L95) +- [flex/**init**.py:8-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L8-L98) +- [grid/row/**init**.py:8-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L8-L94) +- [grid/col/**init**.py:8-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L8-L114) +- [layout/**init**.py:14-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L14-L91) +- [layout/content/**init**.py:10-75](file://backend/modelscope_studio/components/antd/layout/content/__init__.py#L10-L75) +- [layout/footer/**init**.py:10-75](file://backend/modelscope_studio/components/antd/layout/footer/__init__.py#L10-L75) +- [layout/header/**init**.py:10-75](file://backend/modelscope_studio/components/antd/layout/header/__init__.py#L10-L75) +- [layout/sider/**init**.py:11-128](file://backend/modelscope_studio/components/antd/layout/sider/__init__.py#L11-L128) +- [space/**init**.py:9-104](file://backend/modelscope_studio/components/antd/space/__init__.py#L9-L104) +- [space/compact/**init**.py:8-81](file://backend/modelscope_studio/components/antd/space/compact/__init__.py#L8-L81) +- [splitter/**init**.py:11-97](file://backend/modelscope_studio/components/antd/splitter/__init__.py#L11-L97) +- [splitter/panel/**init**.py:8-86](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L8-L86) + +## 详细组件分析 + +### Divider（分割线） + +- 构造函数参数 + - value：可选字符串，作为分割线内的标题文本 + - dashed：可选布尔，是否为虚线 + - variant：枚举值，'dashed' | 'dotted' | 'solid' + - orientation：枚举值，'left' | 'right' | 'center' | 'start' | 'end' + - orientation_margin：可选字符串或数值，标题与边界的边距 + - plain：可选布尔，纯文本风格 + - type：枚举值，'horizontal' | 'vertical' + - size：可选枚举值，'small' | 'middle' | 'large'（仅水平有效） + - 其他通用属性：root_class_name、class_names、styles、as_item、elem_id、elem_classes、elem_style、visible、render 等 +- 方法 + - preprocess(payload): 接收字符串或 None，返回字符串或 None + - postprocess(value): 接收字符串或 None，返回字符串或 None + - example_payload/example_value: 返回 None +- 使用场景 + - 文章段落分隔、表格操作列分隔等 + +**章节来源** + +- [divider/**init**.py:21-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L21-L95) + +### Flex（弹性布局） + +- 构造函数参数 + - orientation：枚举值，'horizontal' | 'vertical' + - vertical：布尔，垂直方向（等价于 flex-direction: column） + - wrap：枚举值或布尔，'nowrap' | 'wrap' | 'wrap-reverse' 或布尔 + - justify：主轴对齐方式（多种取值） + - align：交叉轴对齐方式（多种取值） + - flex：flex 简写属性 + - gap：间距大小，支持枚举或数值 + - component：自定义元素类型 + - 其他通用属性同上 +- 方法 + - preprocess/postprocess：接收/返回 None + - example_payload/example_value：返回 None +- 使用场景 + - 设置元素间距、对齐方式，替代传统 CSS 的 flex 布局 + +**章节来源** + +- [flex/**init**.py:21-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L21-L98) + +### Grid（栅格系统） + +- Row（行） + - 构造函数参数 + - align：垂直对齐，'top' | 'middle' | 'bottom' | 'stretch' 或对象 + - gutter：网格间距，支持数值、字符串、对象或数组 + - justify：水平排列，多种取值 + - wrap：布尔，自动换行 + - 其他通用属性同上 + - 方法 + - preprocess/postprocess：接收/返回 None + - example_payload/example_value：返回 None +- Col（列） + - 构造函数参数 + - flex：flex 布局样式 + - offset：向右偏移的栅格数 + - order：排序 + - pull/push：左右移动 + - span：占用栅格数（0 对应 display: none） + - xs/sm/md/lg/xl/xxl：不同断点下的 span 或包含上述属性的对象 + - 其他通用属性同上 + - 方法 + - preprocess/postprocess：接收/返回 None + - example_payload/example_value：返回 None +- 使用场景 + - 基于 24 栅格的响应式布局，支持横向/纵向对齐、间距与断点 + +**章节来源** + +- [grid/row/**init**.py:30-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L30-L94) +- [grid/col/**init**.py:30-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L30-L114) + +### Layout（页面布局） + +- Layout + - 内嵌子组件：Content、Footer、Header、Sider + - 构造函数参数 + - has_sider：是否包含侧边栏（SSR 避免闪烁） + - 其他通用属性同上 + - 方法 + - preprocess/postprocess：接收/返回 None + - example_payload/example_value：返回 None +- Header/Footer/Content + - 构造函数参数：class_names、styles、additional_props、root_class_name、elem_id、elem_classes、elem_style、visible、render 等 + - 方法：同上 +- Sider + - 构造函数参数 + - breakpoint：响应式断点 + - collapsed/collapsible/default_collapsed：折叠状态相关 + - collapsed_width：折叠后的宽度 + - reverse_arrow：箭头方向反转（右侧展开） + - theme_value：主题（light/dark），与 Gradio 预设冲突时使用 + - trigger：自定义触发器 + - width：宽度 + - zero_width_trigger_style：collapsed_width 为 0 时的特殊触发器样式 + - 其他通用属性同上 + - 方法：同上 +- 事件 + - Layout/Sider/Header/Footer Content：支持 click 事件绑定 + - Sider：支持 collapse、breakpoint 事件 +- 使用场景 + - 页面整体布局，配合 Sider 实现侧边导航与响应式折叠 + +**章节来源** + +- [layout/**init**.py:14-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L14-L91) +- [layout/content/**init**.py:10-75](file://backend/modelscope_studio/components/antd/layout/content/__init__.py#L10-L75) +- [layout/footer/**init**.py:10-75](file://backend/modelscope_studio/components/antd/layout/footer/__init__.py#L10-L75) +- [layout/header/**init**.py:10-75](file://backend/modelscope_studio/components/antd/layout/header/__init__.py#L10-L75) +- [layout/sider/**init**.py:11-128](file://backend/modelscope_studio/components/antd/layout/sider/__init__.py#L11-L128) + +### Space（间距） + +- Space + - 内嵌子组件：Compact + - 构造函数参数 + - align：子项对齐 + - direction/orientation：方向（orientation 为 v6 别名） + - size：间距大小，支持枚举、数值或数组 + - split/separator：分隔符（separator 为 v6 别名） + - wrap：水平时自动换行 + - 其他通用属性同上 + - 方法 + - preprocess/postprocess：接收/返回 None + - example_payload/example_value：返回 None +- Space.Compact + - 构造函数参数 + - block：是否占满父宽度 + - direction：方向 + - size：子组件尺寸 + - 其他通用属性同上 + - 方法：同上 +- 使用场景 + - 多个内联元素的等间距排列；表单紧凑连接时使用 Compact + +**章节来源** + +- [space/**init**.py:9-104](file://backend/modelscope_studio/components/antd/space/__init__.py#L9-L104) +- [space/compact/**init**.py:8-81](file://backend/modelscope_studio/components/antd/space/compact/__init__.py#L8-L81) + +### Splitter（分割面板） + +- Splitter + - 内嵌子组件：Panel + - 构造函数参数 + - layout/orientation：布局方向（orientation 为 v6 别名） + - lazy：是否延迟渲染 + - 其他通用属性同上 + - 事件 + - resize_start、resize、resize_end、collapse + - 方法 + - preprocess/postprocess：接收/返回 None + - example_payload/example_value：返回 None +- Splitter.Panel + - 构造函数参数 + - default_size/min/max/size：初始/最小/最大/受控尺寸（支持 px 或百分比） + - collapsible：快速折叠 + - resizable：是否启用拖拽 + - 其他通用属性同上 + - 方法：同上 +- 使用场景 + - 将页面划分为多个可拖拽调整大小的区域，支持折叠与范围限制 + +**章节来源** + +- [splitter/**init**.py:11-97](file://backend/modelscope_studio/components/antd/splitter/__init__.py#L11-L97) +- [splitter/panel/**init**.py:8-86](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L8-L86) + +## 依赖分析 + +- 组件共同点 + - 均继承自统一的布局组件基类，具备相同的预处理/后处理接口与通用属性（如 visible、elem_id、elem_classes、elem_style、render 等） + - 通过前端目录解析函数定位对应前端组件实现 +- 组件间耦合 + - Layout 作为根容器，内部组合 Header/Sider/Content/Footer + - Space 与 Flex 在语义上互补：Space 更关注“间距”，Flex 更关注“布局” + - Grid 的 Row/Col 与 Flex/Splitter 可组合使用以实现复杂布局 + - Splitter 与 Space/Divider 可配合实现面板间分隔与间距控制 + +```mermaid +graph LR +L["Layout"] --> H["Header"] +L --> SD["Sider"] +L --> C["Content"] +L --> F["Footer"] +G["Grid.Row"] --> GC["Grid.Col"] +Fx["Flex"] -.-> G +Sp["Space"] -.-> G +Spp["Splitter"] -.-> G +Dv["Divider"] -.-> G +``` + +**图表来源** + +- [layout/**init**.py:28-31](file://backend/modelscope_studio/components/antd/layout/__init__.py#L28-L31) +- [grid/row/**init**.py:1-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L1-L94) +- [grid/col/**init**.py:1-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L1-L114) +- [flex/**init**.py:1-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L1-L98) +- [space/**init**.py:1-104](file://backend/modelscope_studio/components/antd/space/__init__.py#L1-L104) +- [splitter/**init**.py:1-97](file://backend/modelscope_studio/components/antd/splitter/__init__.py#L1-L97) +- [divider/**init**.py:1-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L1-L95) + +**章节来源** + +- [layout/**init**.py:14-91](file://backend/modelscope_studio/components/antd/layout/__init__.py#L14-L91) +- [grid/row/**init**.py:8-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L8-L94) +- [grid/col/**init**.py:8-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L8-L114) +- [flex/**init**.py:8-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L8-L98) +- [space/**init**.py:9-104](file://backend/modelscope_studio/components/antd/space/__init__.py#L9-L104) +- [splitter/**init**.py:11-97](file://backend/modelscope_studio/components/antd/splitter/__init__.py#L11-L97) +- [divider/**init**.py:8-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L8-L95) + +## 性能考虑 + +- 合理使用懒加载与延迟渲染：Splitter 支持 lazy，避免不必要的面板初始化 +- 控制事件绑定数量：Layout/Sider 的事件回调需按需开启，减少不必要的 DOM 更新 +- 栅格与弹性布局选择：大量内联元素间距优先 Space，块级布局优先 Flex，避免重复包装 +- 响应式断点：Grid 的 xs/sm/md/lg/xl/xxl 应按实际设备分布配置，避免过度细分导致计算开销 +- SSR 优化：Layout 的 has_sider 可在服务端渲染时避免闪烁 + +## 故障排查指南 + +- 主题冲突提示：Sider 的 theme 与 Gradio 预设属性冲突，应使用 theme_value 替代 +- 事件未生效：确认已正确绑定事件监听器（如 click、collapse、breakpoint），并在前端侧启用相应回调 +- 栅格溢出：Row 中 Col 的 span 之和超过 24 时会换行，检查断点配置与布局逻辑 +- 分割面板异常：确保面板尺寸单位一致（px 或百分比），并设置合理的 min/max + +**章节来源** + +- [layout/sider/**init**.py:101-104](file://backend/modelscope_studio/components/antd/layout/sider/__init__.py#L101-L104) + +## 结论 + +本参考文档梳理了 Antd 布局组件的 Python API，明确了各组件的构造参数、方法与典型用法，并提供了组合使用建议与性能优化策略。通过 Layout、Grid、Flex、Space、Splitter、Divider 的协同，可构建从基础栅格到复杂交互的多样化布局方案。 + +## 附录 + +### 常见布局组合示例（概念性说明） + +- 响应式布局 + - 使用 Layout + Sider，在不同断点下折叠/展开；Sider 支持 breakpoint 与 collapse 事件 + - Grid 的 xs/sm/md/lg/xl/xxl 断点配置实现多端自适应 +- 网格系统 + - Row 提供 gutter、justify、align、wrap；Col 提供 span、offset、order、pull/push、响应式断点 +- 弹性布局 + - Flex 提供 orientation/vertical、wrap、justify、align、gap、flex 等，适合灵活对齐与间距控制 +- 间距与分隔 + - Space 用于内联元素间距；Space.Compact 用于表单紧凑排列；Divider 用于内容分隔 + +### 断点与媒体查询 + +- 断点常量：xs（<576px）、sm（≥576px）、md（≥768px）、lg（≥992px）、xl（≥1200px）、xxl（≥1600px） +- 媒体查询集成：通过 Grid 的 xs/sm/md/lg/xl/xxl 参数映射到不同屏幕尺寸的布局行为 + +### 嵌套规则与最佳实践 + +- Layout 必须包含 Header/Sider/Content/Footer 中的若干子组件，且子组件必须置于 Layout 内 +- Grid 的 Col 必须直接置于 Row 内，内容元素置于 Col 内 +- Flex 不添加额外包装，适合块级布局；Space 为每个子元素添加包装以实现内联对齐 +- Splitter 的 Panel 之间通过拖拽调整大小，建议设置 min/max 与 collapsible 以提升可用性 diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..bc2f0f46 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266 API.md" @@ -0,0 +1,661 @@ +# 数据展示组件 API + + +**本文引用的文件** +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antd/avatar/__init__.py](file://backend/modelscope_studio/components/antd/avatar/__init__.py) +- [backend/modelscope_studio/components/antd/badge/__init__.py](file://backend/modelscope_studio/components/antd/badge/__init__.py) +- [backend/modelscope_studio/components/antd/calendar/__init__.py](file://backend/modelscope_studio/components/antd/calendar/__init__.py) +- [backend/modelscope_studio/components/antd/card/__init__.py](file://backend/modelscope_studio/components/antd/card/__init__.py) +- [backend/modelscope_studio/components/antd/carousel/__init__.py](file://backend/modelscope_studio/components/antd/carousel/__init__.py) +- [backend/modelscope_studio/components/antd/collapse/__init__.py](file://backend/modelscope_studio/components/antd/collapse/__init__.py) +- [backend/modelscope_studio/components/antd/descriptions/__init__.py](file://backend/modelscope_studio/components/antd/descriptions/__init__.py) +- [backend/modelscope_studio/components/antd/empty/__init__.py](file://backend/modelscope_studio/components/antd/empty/__init__.py) +- [backend/modelscope_studio/components/antd/image/__init__.py](file://backend/modelscope_studio/components/antd/image/__init__.py) +- [backend/modelscope_studio/components/antd/list/__init__.py](file://backend/modelscope_studio/components/antd/list/__init__.py) +- [backend/modelscope_studio/components/antd/popover/__init__.py](file://backend/modelscope_studio/components/antd/popover/__init__.py) +- [backend/modelscope_studio/components/antd/qr_code/__init__.py](file://backend/modelscope_studio/components/antd/qr_code/__init__.py) +- [backend/modelscope_studio/components/antd/segmented/__init__.py](file://backend/modelscope_studio/components/antd/segmented/__init__.py) +- [backend/modelscope_studio/components/antd/statistic/__init__.py](file://backend/modelscope_studio/components/antd/statistic/__init__.py) +- [backend/modelscope_studio/components/antd/table/__init__.py](file://backend/modelscope_studio/components/antd/table/__init__.py) +- [backend/modelscope_studio/components/antd/tabs/__init__.py](file://backend/modelscope_studio/components/antd/tabs/__init__.py) +- [backend/modelscope_studio/components/antd/tag/__init__.py](file://backend/modelscope_studio/components/antd/tag/__init__.py) +- [backend/modelscope_studio/components/antd/tag/checkable_tag/__init__.py](file://backend/modelscope_studio/components/antd/tag/checkable_tag/__init__.py) +- [backend/modelscope_studio/components/antd/tag/checkable_tag_group/__init__.py](file://backend/modelscope_studio/components/antd/tag/checkable_tag_group/__init__.py) +- [backend/modelscope_studio/components/antd/timeline/__init__.py](file://backend/modelscope_studio/components/antd/timeline/__init__.py) +- [backend/modelscope_studio/components/antd/tooltip/__init__.py](file://backend/modelscope_studio/components/antd/tooltip/__init__.py) +- [backend/modelscope_studio/components/antd/tour/__init__.py](file://backend/modelscope_studio/components/antd/tour/__init__.py) +- [backend/modelscope_studio/components/antd/tree/__init__.py](file://backend/modelscope_studio/components/antd/tree/__init__.py) +- [frontend/antd/timeline/timeline.tsx](file://frontend/antd/timeline/timeline.tsx) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx) +- [frontend/antd/tag/checkable-tag/Index.svelte](file://frontend/antd/tag/checkable-tag/Index.svelte) +- [frontend/antd/tag/tag.tsx](file://frontend/antd/tag/tag.tsx) + + +## 更新摘要 + +**所做更改** + +- 新增 Timeline 时间轴组件的完整 API 说明，包含最新功能特性 +- 新增可勾选标签组组件的详细文档，包括 CheckableTag 和 CheckableTagGroup +- 更新 Tag 组件文档，补充可勾选标签相关功能 +- 完善组件间的关联关系和使用场景说明 + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 Antd 数据展示类组件的 Python API 参考与实践指南，覆盖 Avatar、Badge、Calendar、Card、Carousel、Collapse、Descriptions、Empty、Image、List、Popover、QRCode、Segmented、Statistic、Table、Tabs、Tag、Timeline、Tooltip、Tour、Tree 等组件。内容包括： + +- 构造函数参数、事件绑定、插槽（slots）与渲染行为 +- 预处理与后处理（preprocess/postprocess）流程 +- 使用示例路径与常见场景 +- 渲染优化、懒加载与响应式设计建议 +- 数据格式化、国际化与主题定制思路 +- 用户体验与可访问性最佳实践 + +## 项目结构 + +Antd 组件在后端以 Python 类的形式封装，统一继承自通用组件基类，并通过前端目录映射到对应的 Svelte 实现。组件导出入口集中于 antd/**init**.py 与 antd/components.py。 + +```mermaid +graph TB +A["Python 组件模块
backend/modelscope_studio/components/antd"] --> B["组件导出入口
antd/__init__.py"] +A --> C["通用组件基类
utils.dev.ModelScope*Component"] +D["前端组件目录
frontend/antd/<组件>"] <-- "resolve_frontend_dir" --> E["组件前端实现
*.tsx / Index.svelte"] +B --> F["具体组件类
AntdXxx(...)"] +F --> E +``` + +**图表来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +**章节来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +## 核心组件 + +以下为本次文档聚焦的数据展示类组件清单与共性特征： + +- 统一继承：多数组件继承自 ModelScopeLayoutComponent 或 ModelScopeComponent；部分数据型组件继承自 ModelScopeDataLayoutComponent（如 Avatar、Image） +- 事件系统：通过 EVENTS 列表注册前端事件回调，绑定到内部 \_internal.update +- 插槽系统：通过 SLOTS 定义可用插槽名称，用于传递模板片段或渲染函数 +- 前端目录：通过 resolve_frontend_dir("组件名") 指向前端组件目录 +- 预处理/后处理：根据组件类型实现 preprocess 与 postprocess，处理字符串、文件路径、Gradio FileData 等输入输出 + +**章节来源** + +- [backend/modelscope_studio/components/antd/avatar/**init**.py:18-114](file://backend/modelscope_studio/components/antd/avatar/__init__.py#L18-L114) +- [backend/modelscope_studio/components/antd/image/**init**.py:18-120](file://backend/modelscope_studio/components/antd/image/__init__.py#L18-L120) +- [backend/modelscope_studio/components/antd/calendar/**init**.py:11-102](file://backend/modelscope_studio/components/antd/calendar/__init__.py#L11-L102) +- [backend/modelscope_studio/components/antd/card/**init**.py:12-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L12-L149) +- [backend/modelscope_studio/components/antd/carousel/**init**.py:8-95](file://backend/modelscope_studio/components/antd/carousel/__init__.py#L8-L95) +- [backend/modelscope_studio/components/antd/collapse/**init**.py:11-99](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L11-L99) +- [backend/modelscope_studio/components/antd/descriptions/**init**.py:9-86](file://backend/modelscope_studio/components/antd/descriptions/__init__.py#L9-L86) +- [backend/modelscope_studio/components/antd/empty/**init**.py:8-71](file://backend/modelscope_studio/components/antd/empty/__init__.py#L8-L71) +- [backend/modelscope_studio/components/antd/list/**init**.py:11-101](file://backend/modelscope_studio/components/antd/list/__init__.py#L11-L101) +- [backend/modelscope_studio/components/antd/popover/**init**.py:10-124](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L124) +- [backend/modelscope_studio/components/antd/qr_code/**init**.py:10-96](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L10-L96) +- [backend/modelscope_studio/components/antd/tabs/**init**.py:1-145](file://backend/modelscope_studio/components/antd/tabs/__init__.py#L1-L145) +- [backend/modelscope_studio/components/antd/timeline/**init**.py:1-81](file://backend/modelscope_studio/components/antd/timeline/__init__.py#L1-L81) +- [backend/modelscope_studio/components/antd/tooltip/**init**.py:1-145](file://backend/modelscope_studio/components/antd/tooltip/__init__.py#L1-L145) +- [backend/modelscope_studio/components/antd/tour/**init**.py:1-145](file://backend/modelscope_studio/components/antd/tour/__init__.py#L1-L145) +- [backend/modelscope_studio/components/antd/tree/**init**.py:1-145](file://backend/modelscope_studio/components/antd/tree/__init__.py#L1-L145) + +## 架构总览 + +下图展示了数据展示组件在 Python 层的类关系与事件绑定方式： + +```mermaid +classDiagram +class ModelScopeLayoutComponent +class ModelScopeComponent +class ModelScopeDataLayoutComponent +class AntdAvatar { ++EVENTS ++SLOTS ++FRONTEND_DIR ++preprocess() ++postprocess() +} +class AntdImage { ++EVENTS ++SLOTS ++FRONTEND_DIR ++preprocess() ++postprocess() +} +class AntdCalendar { ++EVENTS ++SLOTS ++FRONTEND_DIR ++api_info() +} +class AntdCard { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdCarousel { ++EVENTS ++FRONTEND_DIR +} +class AntdCollapse { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdDescriptions { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdEmpty { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdList { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdPopover { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdQRCode { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdTag { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdTagCheckableTag { ++EVENTS ++SLOTS ++FRONTEND_DIR ++api_info() +} +class AntdTagCheckableTagGroup { ++EVENTS ++SLOTS ++FRONTEND_DIR ++api_info() +} +class AntdTimeline { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +ModelScopeDataLayoutComponent <|-- AntdAvatar +ModelScopeDataLayoutComponent <|-- AntdImage +ModelScopeLayoutComponent <|-- AntdCard +ModelScopeLayoutComponent <|-- AntdCarousel +ModelScopeLayoutComponent <|-- AntdCollapse +ModelScopeLayoutComponent <|-- AntdDescriptions +ModelScopeLayoutComponent <|-- AntdEmpty +ModelScopeLayoutComponent <|-- AntdList +ModelScopeLayoutComponent <|-- AntdPopover +ModelScopeComponent <|-- AntdCalendar +ModelScopeComponent <|-- AntdQRCode +ModelScopeLayoutComponent <|-- AntdTag +ModelScopeDataLayoutComponent <|-- AntdTagCheckableTag +ModelScopeDataLayoutComponent <|-- AntdTagCheckableTagGroup +ModelScopeLayoutComponent <|-- AntdTimeline +``` + +**图表来源** + +- [backend/modelscope_studio/components/antd/avatar/**init**.py:18-114](file://backend/modelscope_studio/components/antd/avatar/__init__.py#L18-L114) +- [backend/modelscope_studio/components/antd/image/**init**.py:18-120](file://backend/modelscope_studio/components/antd/image/__init__.py#L18-L120) +- [backend/modelscope_studio/components/antd/calendar/**init**.py:11-102](file://backend/modelscope_studio/components/antd/calendar/__init__.py#L11-L102) +- [backend/modelscope_studio/components/antd/card/**init**.py:12-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L12-L149) +- [backend/modelscope_studio/components/antd/carousel/**init**.py:8-95](file://backend/modelscope_studio/components/antd/carousel/__init__.py#L8-L95) +- [backend/modelscope_studio/components/antd/collapse/**init**.py:11-99](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L11-L99) +- [backend/modelscope_studio/components/antd/descriptions/**init**.py:9-86](file://backend/modelscope_studio/components/antd/descriptions/__init__.py#L9-L86) +- [backend/modelscope_studio/components/antd/empty/**init**.py:8-71](file://backend/modelscope_studio/components/antd/empty/__init__.py#L8-L71) +- [backend/modelscope_studio/components/antd/list/**init**.py:11-101](file://backend/modelscope_studio/components/antd/list/__init__.py#L11-L101) +- [backend/modelscope_studio/components/antd/popover/**init**.py:10-124](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L124) +- [backend/modelscope_studio/components/antd/qr_code/**init**.py:10-96](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L10-L96) +- [backend/modelscope_studio/components/antd/tag/**init**.py:12-88](file://backend/modelscope_studio/components/antd/tag/__init__.py#L12-L88) +- [backend/modelscope_studio/components/antd/tag/checkable_tag/**init**.py:11-85](file://backend/modelscope_studio/components/antd/tag/checkable_tag/__init__.py#L11-L85) +- [backend/modelscope_studio/components/antd/tag/checkable_tag_group/**init**.py:12-102](file://backend/modelscope_studio/components/antd/tag/checkable_tag_group/__init__.py#L12-L102) +- [backend/modelscope_studio/components/antd/timeline/**init**.py:9-81](file://backend/modelscope_studio/components/antd/timeline/__init__.py#L9-L81) + +## 详细组件分析 + +### Avatar 头像 + +- 功能定位：头像展示，支持图标、占位与错误处理事件 +- 关键点 + - 支持插槽：icon、src + - 事件：error + - 数据模型：AntdAvatarData（root 支持 FileData 或 str） + - 预处理/后处理：将 FileData 转换为路径或封装为 FileData +- 参数要点（节选） + - value、alt、gap、icon、shape、size、src_set、draggable、cross_origin、class_names、styles、root_class_name +- 使用示例路径 + - [示例：头像与错误处理:18-114](file://backend/modelscope_studio/components/antd/avatar/__init__.py#L18-L114) + +**章节来源** + +- [backend/modelscope_studio/components/antd/avatar/**init**.py:18-114](file://backend/modelscope_studio/components/antd/avatar/__init__.py#L18-L114) + +### Badge 徽标数 + +- 功能定位：信息标记，支持小红点、计数、状态等 +- 关键点 + - 插槽：count、text + - 参数：count、dot、overflow_count、show_zero、size、status、text、title、颜色等 +- 使用示例路径 + - [示例：徽标与状态:9-87](file://backend/modelscope_studio/components/antd/badge/__init__.py#L9-87) + +**章节来源** + +- [backend/modelscope_studio/components/antd/badge/**init**.py:9-87](file://backend/modelscope_studio/components/antd/badge/__init__.py#L9-L87) + +### Calendar 日历 + +- 功能定位：日期选择与面板切换 +- 关键点 + - 事件：change、panel_change、select + - 插槽：cellRender、fullCellRender、headerRender + - API：api_info 返回 number|string 的联合类型 +- 使用示例路径 + - [示例：日历事件与渲染钩子:11-102](file://backend/modelscope_studio/components/antd/calendar/__init__.py#L11-L102) + +**章节来源** + +- [backend/modelscope_studio/components/antd/calendar/**init**.py:11-102](file://backend/modelscope_studio/components/antd/calendar/__init__.py#L11-L102) + +### Card 卡片 + +- 功能定位：信息容器，支持标题、额外内容、封面、动作区、标签页等 +- 关键点 + - 子组件：Grid、Meta + - 事件：click、tab_change + - 插槽：actions、cover、extra、tabBarExtraContent、title、tabList、tabProps.\* 等 + - 生命周期：**exit** 中检测是否包含 Grid +- 使用示例路径 + - [示例：卡片布局与标签页:12-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L12-L149) + +**章节来源** + +- [backend/modelscope_studio/components/antd/card/**init**.py:12-149](file://backend/modelscope_studio/components/antd/card/__init__.py#L12-L149) + +### Carousel 走马灯 + +- 功能定位：轮播图容器 +- 关键点 + - 参数：arrows、autoplay、autoplay_speed、adaptive_height、dot_position、dots、draggable、fade、infinite、speed、effect、after_change、before_change、wait_for_animate +- 使用示例路径 + - [示例：轮播配置:8-95](file://backend/modelscope_studio/components/antd/carousel/__init__.py#L8-L95) + +**章节来源** + +- [backend/modelscope_studio/components/antd/carousel/**init**.py:8-95](file://backend/modelscope_studio/components/antd/carousel/__init__.py#L8-L95) + +### Collapse 折叠面板 + +- 功能定位：内容折叠/展开 +- 关键点 + - 子组件：Item + - 事件：change + - 插槽：expandIcon、items + - 参数：accordion、active_key、bordered、collapsible、default_active_key、destroy_on_hidden、destroy_inactive_panel、expand_icon、ghost、items、size +- 使用示例路径 + - [示例：折叠面板与项:11-99](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L11-L99) + +**章节来源** + +- [backend/modelscope_studio/components/antd/collapse/**init**.py:11-99](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L11-L99) + +### Descriptions 描述列表 + +- 功能定位：键值对描述展示 +- 关键点 + - 子组件：Item + - 插槽：extra、title、items + - 参数：bordered、colon、column、content_style、layout、size、title、items、label_style +- 使用示例路径 + - [示例：描述列表与项:9-86](file://backend/modelscope_studio/components/antd/descriptions/__init__.py#L9-86) + +**章节来源** + +- [backend/modelscope_studio/components/antd/descriptions/**init**.py:9-86](file://backend/modelscope_studio/components/antd/descriptions/__init__.py#L9-L86) + +### Empty 空状态 + +- 功能定位：空态占位 +- 关键点 + - 插槽：description、image + - 参数：description、image（含常量枚举）、image_style +- 使用示例路径 + - [示例：空状态与图片:8-71](file://backend/modelscope_studio/components/antd/empty/__init__.py#L8-71) + +**章节来源** + +- [backend/modelscope_studio/components/antd/empty/**init**.py:8-71](file://backend/modelscope_studio/components/antd/empty/__init__.py#L8-L71) + +### Image 图片 + +- 功能定位：图片展示与预览 +- 关键点 + - 子组件：PreviewGroup + - 事件：error、preview_transform、preview_visible_change + - 插槽：placeholder、preview.mask、preview.closeIcon、preview.toolbarRender、preview.imageRender + - 数据模型：AntdImageData（root 支持 FileData 或 str） + - 预处理/后处理：与 Avatar 类似，处理 FileData 与本地路径 +- 使用示例路径 + - [示例：图片与预览组:18-120](file://backend/modelscope_studio/components/antd/image/__init__.py#L18-120) + +**章节来源** + +- [backend/modelscope_studio/components/antd/image/**init**.py:18-120](file://backend/modelscope_studio/components/antd/image/__init__.py#L18-L120) + +### List 列表 + +- 功能定位：列表渲染与分页 +- 关键点 + - 子组件：Item、Item.Meta + - 事件：pagination_change、pagination_show_size_change + - 插槽：footer、header、loadMore、renderItem + - 参数：bordered、data_source、footer、grid、header、item_layout、loading、load_more、locale、pagination、render_item、row_key、size、split +- 使用示例路径 + - [示例：列表与分页:11-101](file://backend/modelscope_studio/components/antd/list/__init__.py#L11-L101) + +**章节来源** + +- [backend/modelscope_studio/components/antd/list/**init**.py:11-101](file://backend/modelscope_studio/components/antd/list/__init__.py#L11-L101) + +### Popover 气泡卡片 + +- 功能定位：气泡提示与触发 +- 关键点 + - 事件：open_change + - 插槽：title、content + - 参数：align、arrow、auto_adjust_overflow、color、default_open、destroy_tooltip_on_hide、destroy_on_hidden、fresh、get_popup_container、mouse_enter_delay、mouse_leave_delay、overlay_class_name、overlay_style、overlay_inner_style、placement、trigger、open、z_index +- 使用示例路径 + - [示例：气泡卡片与触发器:10-124](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L124) + +**章节来源** + +- [backend/modelscope_studio/components/antd/popover/**init**.py:10-124](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L124) + +### QRCode 二维码 + +- 功能定位：动态二维码生成与状态管理 +- 关键点 + - 事件：refresh + - 插槽：statusRender + - 参数：type、bordered、color、bg_color、boost_level、error_level、icon、icon_size、margin_size、size、status、status_render +- 使用示例路径 + - [示例：二维码与状态渲染:10-96](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L10-96) + +**章节来源** + +- [backend/modelscope_studio/components/antd/qr_code/**init**.py:10-96](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L10-L96) + +### Segmented 分段器 + +- 功能定位：分段选择器（数据展示类） +- 关键点 + - 子组件：Option + - 参数：options、block、size、disabled、onChange 等（按前端定义） +- 使用示例路径 + - [示例：分段器与选项](file://backend/modelscope_studio/components/antd/segmented/__init__.py) + +**章节来源** + +- [backend/modelscope_studio/components/antd/segmented/__init__.py] + +### Statistic 计数 + +- 功能定位：数值展示与倒计时 +- 关键点 + - 子组件：Countdown、Timer + - 参数：value、precision、prefix、suffix、formatter、groupSeparator、format、onFinish 等 +- 使用示例路径 + - [示例：计数与倒计时](file://backend/modelscope_studio/components/antd/statistic/__init__.py) + +**章节来源** + +- [backend/modelscope_studio/components/antd/statistic/__init__.py] + +### Table 表格 + +- 功能定位：数据表格渲染与交互 +- 关键点 + - 子组件：Column、ColumnGroup、Expandable、RowSelection、RowSelection.Selection + - 参数：dataSource、columns、pagination、scroll、size、loading、onChange、onHeaderRow、onRow 等 +- 使用示例路径 + - [示例：表格与列配置](file://backend/modelscope_studio/components/antd/table/__init__.py) + +**章节来源** + +- [backend/modelscope_studio/components/antd/table/__init__.py] + +### Tabs 标签页 + +- 功能定位：标签页容器与切换 +- 关键点 + - 子组件：Item + - 参数：activeKey、defaultActiveKey、type、tabPosition、size、hideAdd、addIcon、removeIcon、renderTabBar、onEdit、onChange 等 +- 使用示例路径 + - [示例：标签页与项](file://backend/modelscope_studio/components/antd/tabs/__init__.py) + +**章节来源** + +- [backend/modelscope_studio/components/antd/tabs/__init__.py] + +### Tag 标签 + +- 功能定位：标签展示与可选中 +- 关键点 + - 子组件：CheckableTag、CheckableTagGroup + - 事件：close、change、click + - 插槽：icon、closeIcon + - 参数：value、disabled、href、bordered、close_icon、color、icon +- 使用示例路径 + - [示例：标签与可选中标签](file://backend/modelscope_studio/components/antd/tag/__init__.py) + +**更新** 新增可勾选标签组组件支持，包括单个可勾选标签和可勾选标签组两种形式 + +**章节来源** + +- [backend/modelscope_studio/components/antd/tag/**init**.py:12-88](file://backend/modelscope_studio/components/antd/tag/__init__.py#L12-L88) + +### Timeline 时间轴 + +- 功能定位：时间线展示 +- 关键点 + - 子组件：Item + - 事件：无 + - 插槽：pending、pendingDot + - 参数：mode、reverse、orientation、title_span、variant、pending、pending_dot、items +- 使用示例路径 + - [示例：时间轴与项](file://backend/modelscope_studio/components/antd/timeline/__init__.py) + +**更新** 新增 Timeline 组件的完整 API 说明，包含最新功能特性 + +**章节来源** + +- [backend/modelscope_studio/components/antd/timeline/**init**.py:9-81](file://backend/modelscope_studio/components/antd/timeline/__init__.py#L9-L81) + +### Tooltip 文字提示 + +- 功能定位：文字提示 +- 关键点 + - 参数：title、color、placement、trigger、mouseEnterDelay、mouseLeaveDelay、overlayClassName、overlayStyle、overlayInnerStyle、destroyTooltipOnHide 等 +- 使用示例路径 + - [示例：文字提示](file://backend/modelscope_studio/components/antd/tooltip/__init__.py) + +**章节来源** + +- [backend/modelscope_studio/components/antd/tooltip/__init__.py] + +### Tour 导览 + +- 功能定位：引导式导航 +- 关键点 + - 子组件：Step + - 参数：steps、current、scrollIntoViewOptions、mask、gap、indicator、prefixCls、onClose、onChange 等 +- 使用示例路径 + - [示例：导览与步骤](file://backend/modelscope_studio/components/antd/tour/__init__.py) + +**章节来源** + +- [backend/modelscope_studio/components/antd/tour/__init__.py] + +### Tree 树形控件 + +- 功能定位：树形结构展示与交互 +- 关键点 + - 子组件：TreeNode、DirectoryTree + - 参数：treeData、defaultExpandAll、defaultExpandedKeys、expandedKeys、selectedKeys、checkable、checkStrictly、multiple、fieldNames、onChange、onCheck、onSelect 等 +- 使用示例路径 + - [示例：树与节点](file://backend/modelscope_studio/components/antd/tree/__init__.py) + +**章节来源** + +- [backend/modelscope_studio/components/antd/tree/__init__.py] + +### 可勾选标签组组件 + +#### AntdTagCheckableTag 可勾选标签 + +- 功能定位：支持选中状态的标签组件 +- 关键点 + - 事件：change、click + - 插槽：icon + - 参数：label、value、icon + - 数据类型：布尔值，表示选中状态 +- 使用示例路径 + - [示例：可勾选标签](file://backend/modelscope_studio/components/antd/tag/checkable_tag/__init__.py) + +#### AntdTagCheckableTagGroup 可勾选标签组 + +- 功能定位：多个可勾选标签的组合容器 +- 关键点 + - 事件：change + - 插槽：options + - 参数：options、disabled、multiple、default_value + - 数据类型：字符串、数字或字符串/数字数组，表示选中的标签值 +- 使用示例路径 + - [示例：可勾选标签组](file://backend/modelscope_studio/components/antd/tag/checkable_tag_group/__init__.py) + +**新增** 完整的可勾选标签组组件文档，包括单个标签和标签组两种使用方式 + +**章节来源** + +- [backend/modelscope_studio/components/antd/tag/checkable_tag/**init**.py:11-85](file://backend/modelscope_studio/components/antd/tag/checkable_tag/__init__.py#L11-L85) +- [backend/modelscope_studio/components/antd/tag/checkable_tag_group/**init**.py:12-102](file://backend/modelscope_studio/components/antd/tag/checkable_tag_group/__init__.py#L12-L102) + +## 依赖分析 + +- 组件导出：所有 Antd 组件均在 antd/**init**.py 与 antd/components.py 中集中导出，便于统一导入与别名使用 +- 基类依赖：各组件依赖 utils.dev 中的 ModelScope\*Component 体系，统一事件绑定与前端目录解析 +- 前端映射：通过 resolve_frontend_dir("组件名") 将 Python 组件与 frontend/antd/<组件>/Index.svelte 对应 + +```mermaid +graph LR +P["Python 组件类"] --> B["antd/__init__.py 导出"] +P --> C["antd/components.py 导出"] +P --> F["frontend/antd/<组件>/Index.svelte"] +U["utils.dev.ModelScope*Component"] --> P +``` + +**图表来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +**章节来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +## 性能考虑 + +- 渲染优化 + - 合理使用 destroy_on_hidden、destroy_inactive_panel 等参数在折叠/抽屉等场景减少 DOM 消耗 + - 列表与表格建议启用虚拟滚动（scroll.y）与分页，避免一次性渲染大量节点 + - Timeline 组件支持 items 参数直接传入数据，避免频繁重新渲染 +- 懒加载 + - 图片组件支持 placeholder 与 fallback，结合懒加载策略提升首屏性能 + - 列表支持 loadMore 与 pagination，按需加载数据 +- 响应式设计 + - 使用 size、responsive、grid 等参数适配不同屏幕尺寸 + - 卡片与描述列表支持 small/default/middle 尺寸，按内容密度调整 + - Timeline 支持 horizontal 和 vertical 两种方向，适应不同布局需求 +- 主题与样式 + - 通过 class_names/styles/root_class_name 注入自定义样式，避免全局污染 + - 使用 color、status 等语义化参数表达状态，减少重复样式代码 + +## 故障排查指南 + +- 事件未触发 + - 确认 EVENTS 列表中的事件名称与前端绑定一致 + - 检查 \_internal.update 是否被正确调用 +- 数据不显示或显示异常 + - Avatar/Image：确认 value 为 http/data 路径或已缓存文件路径；检查 preprocess/postprocess 流程 + - Calendar：确认 value 类型符合 api_info 返回的 number|string + - Timeline：确认 items 参数格式正确，支持直接传入数据或通过插槽提供 +- 插槽无效 + - 确认 SLOTS 中的插槽名称拼写正确，且前端组件已实现对应插槽渲染 + - Timeline 支持 pending 和 pendingDot 插槽，Tag 组件支持 icon 和 closeIcon 插槽 +- 性能问题 + - 大列表/表格：开启分页与虚拟滚动；避免频繁重渲染 + - 折叠面板：合理设置 destroy_on_hidden/destroy_inactive_panel + - 可勾选标签组：合理使用 multiple 参数控制单选或多选模式 + +**章节来源** + +- [backend/modelscope_studio/components/antd/avatar/**init**.py:89-114](file://backend/modelscope_studio/components/antd/avatar/__init__.py#L89-L114) +- [backend/modelscope_studio/components/antd/image/**init**.py:95-120](file://backend/modelscope_studio/components/antd/image/__init__.py#L95-L120) +- [backend/modelscope_studio/components/antd/calendar/**init**.py:84-102](file://backend/modelscope_studio/components/antd/calendar/__init__.py#L84-L102) +- [backend/modelscope_studio/components/antd/collapse/**init**.py:84-99](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L84-L99) +- [backend/modelscope_studio/components/antd/list/**init**.py:86-101](file://backend/modelscope_studio/components/antd/list/__init__.py#L86-L101) +- [backend/modelscope_studio/components/antd/timeline/**init**.py:65-81](file://backend/modelscope_studio/components/antd/timeline/__init__.py#L65-L81) +- [backend/modelscope_studio/components/antd/tag/**init**.py:19-27](file://backend/modelscope_studio/components/antd/tag/__init__.py#L19-L27) + +## 结论 + +本文档基于仓库中的 Python 组件实现，梳理了数据展示类组件的 API 特性、事件与插槽、数据流处理与典型使用路径。本次更新特别加强了 Timeline 时间轴组件和可勾选标签组组件的文档说明，为用户提供了更完整的组件使用指南。建议在实际项目中结合前端组件文档与本参考进行联调，确保事件绑定、插槽渲染与数据格式满足业务需求。 + +## 附录 + +- 国际化支持 + - 通过 locale、title、description 等参数传入本地化文本；必要时在 ConfigProvider 中统一配置语言环境 + - Timeline 组件支持通过插槽自定义待完成状态的文本和图标 +- 主题定制 + - 使用 class_names/styles/root_class_name 注入样式；通过 color/status 等语义参数表达状态 + - 可勾选标签组支持通过 options 参数批量配置标签选项 +- 可访问性 + - 为可交互元素提供明确的 aria-label 或 title；确保键盘可访问与焦点可见 + - Timeline 组件支持 reverse 参数实现反向时间轴，提升用户体验 +- 示例索引 + - 各组件示例均可在对应组件文件中找到 example_payload/example_value 的返回值作为参考 + - Timeline 组件支持通过 items 参数直接传入数据，简化使用方式 + - 可勾选标签组支持多种数据格式，包括简单字符串数组和复杂对象数组 diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..3c687b15 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266 API.md" @@ -0,0 +1,453 @@ +# 数据录入组件 API + + +**本文引用的文件** +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antd/auto_complete/__init__.py](file://backend/modelscope_studio/components/antd/auto_complete/__init__.py) +- [backend/modelscope_studio/components/antd/cascader/__init__.py](file://backend/modelscope_studio/components/antd/cascader/__init__.py) +- [backend/modelscope_studio/components/antd/checkbox/__init__.py](file://backend/modelscope_studio/components/antd/checkbox/__init__.py) +- [backend/modelscope_studio/components/antd/color_picker/__init__.py](file://backend/modelscope_studio/components/antd/color_picker/__init__.py) +- [backend/modelscope_studio/components/antd/date_picker/__init__.py](file://backend/modelscope_studio/components/antd/date_picker/__init__.py) +- [backend/modelscope_studio/components/antd/form/__init__.py](file://backend/modelscope_studio/components/antd/form/__init__.py) +- [backend/modelscope_studio/components/antd/input/__init__.py](file://backend/modelscope_studio/components/antd/input/__init__.py) +- [backend/modelscope_studio/components/antd/input_number/__init__.py](file://backend/modelscope_studio/components/antd/input_number/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 Antd 数据录入组件的 Python API 参考文档，覆盖以下组件：AutoComplete、Cascader、Checkbox、ColorPicker、DatePicker、Form、Input、InputNumber、Mentions（未在已知后端文件中发现）、Radio（未在已知后端文件中发现）、Rate（未在已知后端文件中发现）、Select（未在已知后端文件中发现）、Slider（未在已知后端文件中发现）、Switch（未在已知后端文件中发现）、TimePicker（未在已知后端文件中发现）、Transfer（未在已知后端文件中发现）、TreeSelect（未在已知后端文件中发现）、Upload（未在已知后端文件中发现）。 +文档内容包括：组件类的构造函数参数、事件与插槽、属性定义、方法签名与返回类型、数据类型规范、预处理/后处理行为、示例用法、验证与格式化、错误处理、序列化与 API 集成、实时验证与用户体验设计原则、性能优化建议等。 + +## 项目结构 + +Antd 组件在后端以“按需导入”的方式集中导出，便于统一使用。前端目录中各组件对应独立的 Svelte 实现，后端通过统一基类与前端目录映射进行桥接。 + +```mermaid +graph TB +A["后端模块
backend/modelscope_studio/components/antd/__init__.py"] --> B["AutoComplete
auto_complete/__init__.py"] +A --> C["Cascader
cascader/__init__.py"] +A --> D["Checkbox
checkbox/__init__.py"] +A --> E["ColorPicker
color_picker/__init__.py"] +A --> F["DatePicker
date_picker/__init__.py"] +A --> G["Form
form/__init__.py"] +A --> H["Input
input/__init__.py"] +A --> I["InputNumber
input_number/__init__.py"] +J["前端目录
frontend/antd/*"]:::ext +B --> J +C --> J +D --> J +E --> J +F --> J +G --> J +H --> J +I --> J +classDef ext fill:#fff,stroke:#333,stroke-width:1px; +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/auto_complete/**init**.py:1-146](file://backend/modelscope_studio/components/antd/auto_complete/__init__.py#L1-L146) +- [backend/modelscope_studio/components/antd/cascader/**init**.py:1-191](file://backend/modelscope_studio/components/antd/cascader/__init__.py#L1-L191) +- [backend/modelscope_studio/components/antd/checkbox/**init**.py:1-83](file://backend/modelscope_studio/components/antd/checkbox/__init__.py#L1-L83) +- [backend/modelscope_studio/components/antd/color_picker/**init**.py:1-148](file://backend/modelscope_studio/components/antd/color_picker/__init__.py#L1-L148) +- [backend/modelscope_studio/components/antd/date_picker/**init**.py:1-208](file://backend/modelscope_studio/components/antd/date_picker/__init__.py#L1-L208) +- [backend/modelscope_studio/components/antd/form/**init**.py:1-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L1-L133) +- [backend/modelscope_studio/components/antd/input/**init**.py:1-127](file://backend/modelscope_studio/components/antd/input/__init__.py#L1-L127) +- [backend/modelscope_studio/components/antd/input_number/**init**.py:1-147](file://backend/modelscope_studio/components/antd/input_number/__init__.py#L1-L147) + +章节来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) + +## 核心组件 + +本节概述数据录入相关组件的通用能力与差异点： + +- 所有组件均继承自统一的数据布局组件基类，具备一致的生命周期与事件绑定机制。 +- 每个组件提供： + - 构造函数参数：支持通用属性（如尺寸、状态、样式、类名等）与组件特有属性。 + - 事件列表：通过事件监听器绑定前端回调。 + - 插槽列表：用于定制渲染（如下拉面板、前缀/后缀、占位内容等）。 + - 数据类型规范：通过 API 规范声明输入输出类型。 + - 预处理/后处理：对 payload/value 进行类型转换或格式化。 + - 示例值与示例载荷：便于快速集成与测试。 + +章节来源 + +- [backend/modelscope_studio/components/antd/auto_complete/**init**.py:11-146](file://backend/modelscope_studio/components/antd/auto_complete/__init__.py#L11-L146) +- [backend/modelscope_studio/components/antd/cascader/**init**.py:13-191](file://backend/modelscope_studio/components/antd/cascader/__init__.py#L13-L191) +- [backend/modelscope_studio/components/antd/checkbox/**init**.py:12-83](file://backend/modelscope_studio/components/antd/checkbox/__init__.py#L12-L83) +- [backend/modelscope_studio/components/antd/color_picker/**init**.py:12-148](file://backend/modelscope_studio/components/antd/color_picker/__init__.py#L12-L148) +- [backend/modelscope_studio/components/antd/date_picker/**init**.py:13-208](file://backend/modelscope_studio/components/antd/date_picker/__init__.py#L13-L208) +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) +- [backend/modelscope_studio/components/antd/input/**init**.py:16-127](file://backend/modelscope_studio/components/antd/input/__init__.py#L16-L127) +- [backend/modelscope_studio/components/antd/input_number/**init**.py:11-147](file://backend/modelscope_studio/components/antd/input_number/__init__.py#L11-L147) + +## 架构总览 + +后端组件通过统一基类与前端目录映射连接，前端组件负责 UI 渲染与交互，后端负责数据类型约束、事件绑定与序列化。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant FE as "前端组件(Svelte)" +participant BE as "后端组件(Python)" +participant API as "Gradio/服务端" +U->>FE : 输入/选择/点击 +FE-->>BE : 触发事件(如 change/search/select) +BE->>BE : 绑定事件回调
更新内部状态 +BE->>API : 序列化payload并提交 +API-->>BE : 返回处理后的值 +BE-->>FE : 后处理结果并更新UI +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/auto_complete/**init**.py:18-43](file://backend/modelscope_studio/components/antd/auto_complete/__init__.py#L18-L43) +- [backend/modelscope_studio/components/antd/cascader/**init**.py:20-36](file://backend/modelscope_studio/components/antd/cascader/__init__.py#L20-L36) +- [backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) + +## 详细组件分析 + +### AutoComplete（自动完成） + +- 类型与用途：字符串输入的自动完成组件，支持选项列表与搜索事件。 +- 关键属性 + - 通用：size、status、variant、placeholder、disabled、class_names、styles、root_class_name、as_item 等。 + - 特有：allow_clear、auto_focus、backfill、default_active_first_option、default_open、dropdown_render、popup_render、popup_class_name、popup_match_select_width、filter_option、get_popup_container、not_found_content、open、options、placement、options 等。 +- 事件：change、blur、focus、search、select、clear、dropdown_visible_change、popup_visible_change。 +- 插槽：allowClear.clearIcon、dropdownRender、popupRender、children、notFoundContent、options。 +- 数据类型 + - 输入/输出：字符串。 + - API 规范：字符串类型。 +- 预处理/后处理：直接透传。 +- 示例用法 + - 在表单中作为单项输入，配合校验规则使用。 + - 使用 options 提供候选列表，结合 search 事件实现远程搜索。 +- 错误处理 + - 当未找到匹配项时，可通过 not_found_content 自定义提示。 +- 实时验证 + - 通过 search 事件触发远程校验，结合 Form 的校验触发策略使用。 + +章节来源 + +- [backend/modelscope_studio/components/antd/auto_complete/**init**.py:12-146](file://backend/modelscope_studio/components/antd/auto_complete/__init__.py#L12-L146) + +### Cascader（级联选择） + +- 类型与用途：多级联动选择，支持异步加载与搜索。 +- 关键属性 + - 通用：size、status、variant、placeholder、disabled、class_names、styles、root_class_name、as_item 等。 + - 特有：allow_clear、auto_clear_search_value、auto_focus、change_on_select、display_render、tag_render、popup_class_name、dropdown_render、popup_render、expand_icon、prefix、expand_trigger、filed_names、get_popup_container、max_tag_count、max_tag_placeholder、max_tag_text_length、not_found_content、open、options、placement、show_search、multiple、show_checked_strategy、remove_icon、search_value、dropdown_menu_column_style、option_render 等。 +- 事件：change、search、dropdown_visible_change、popup_visible_change、load_data。 +- 插槽：allowClear.clearIcon、suffixIcon、maxTagPlaceholder、notFoundContent、expandIcon、removeIcon、prefix、displayRender、tagRender、dropdownRender、popupRender、showSearch.render。 +- 数据类型 + - 输入/输出：字符串数组或数字数组（路径键）。 + - API 规范：字符串数组或字符串。 +- 预处理/后处理：直接透传。 +- 示例用法 + - 常用于省市区选择、分类筛选等场景。 + - 结合 load_data 实现懒加载。 +- 错误处理 + - 通过 not_found_content 定制空状态。 +- 实时验证 + - 通过 search 与 change 事件结合 Form 校验。 + +章节来源 + +- [backend/modelscope_studio/components/antd/cascader/**init**.py:13-191](file://backend/modelscope_studio/components/antd/cascader/__init__.py#L13-L191) + +### Checkbox（复选框） + +- 类型与用途：布尔值选择。 +- 关键属性 + - 通用：class_names、styles、additional_props、root_class_name、as_item 等。 + - 特有：auto_focus、default_checked、disabled、indeterminate。 +- 事件：change。 +- 数据类型 + - 输入/输出：布尔值。 + - API 规范：布尔类型。 +- 预处理/后处理：直接透传。 +- 示例用法 + - 单独使用或组合为组（Group）。 +- 错误处理 + - 无特殊错误处理逻辑，遵循布尔值约束。 +- 实时验证 + - 可直接参与 Form 校验。 + +章节来源 + +- [backend/modelscope_studio/components/antd/checkbox/**init**.py:12-83](file://backend/modelscope_studio/components/antd/checkbox/__init__.py#L12-L83) + +### ColorPicker（颜色选择器） + +- 类型与用途：颜色值选择，支持单色与渐变模式。 +- 关键属性 + - 通用：class_names、styles、additional_props、root_class_name、as_item 等。 + - 特有：value_format、allow_clear、arrow、presets、disabled、disabled_alpha、disabled_format、destroy_tooltip_on_hide、destroy_on_hidden、format、mode、open、default_value、default_format、show_text、placement、trigger、panel_render、size。 +- 事件：change、change_complete、clear、open_change、format_change。 +- 插槽：presets、panelRender、showText。 +- 数据类型 + - 输入/输出：十六进制字符串或渐变颜色数组对象。 + - API 规范：字符串或颜色数组对象。 +- 预处理/后处理：直接透传。 +- 示例用法 + - 用于主题色、品牌色等配置。 +- 错误处理 + - 非法格式会由前端校验拦截。 +- 实时验证 + - 通过 change 与 change_complete 事件结合校验。 + +章节来源 + +- [backend/modelscope_studio/components/antd/color_picker/**init**.py:12-148](file://backend/modelscope_studio/components/antd/color_picker/__init__.py#L12-L148) + +### DatePicker（日期选择器） + +- 类型与用途：日期/时间选择，支持多种模式与范围选择。 +- 关键属性 + - 通用：class_names、styles、additional_props、root_class_name、as_item 等。 + - 特有：allow_clear、auto_focus、cell_render、components、disabled、disabled_date、format、order、preserve_invalid_on_blur、input_read_only、locale、mode、need_confirm、next_icon、open、panel_render、picker、placement、placeholder、popup_class_name、popup_style、get_popup_container、min_date、max_date、prefix、prev_icon、size、presets、status、suffix_icon、super_next_icon、super_prev_icon、variant、default_picker_value、default_value、disabled_time、multiple、picker_value、render_extra_footer、show_now、show_time、show_week、preview_value。 +- 事件：change、ok、panel_change、open_change。 +- 插槽：allowClear.clearIcon、prefix、prevIcon、nextIcon、suffixIcon、superNextIcon、superPrevIcon、renderExtraFooter、cellRender、panelRender。 +- 数据类型 + - 输入/输出：字符串、数值或数组（范围）。 + - API 规范：字符串、数值或数组。 +- 预处理/后处理：直接透传。 +- 示例用法 + - 支持日期、周、月、季度、年等多种模式；可开启时间选择与确认按钮。 +- 错误处理 + - 通过 disabled_date、min_date、max_date 限制范围。 +- 实时验证 + - 通过 panel_change 与 change 事件结合校验。 + +章节来源 + +- [backend/modelscope_studio/components/antd/date_picker/**init**.py:13-208](file://backend/modelscope_studio/components/antd/date_picker/__init__.py#L13-L208) + +### Form（表单） + +- 类型与用途：数据收集与校验容器，支持字段变更、提交、重置与校验。 +- 关键属性 + - 通用：class_names、styles、additional_props、root_class_name、as_item 等。 + - 特有：form_action、colon、disabled、component、feedback_icons、initial_values、label_align、label_col、label_wrap、layout、form_name、preserve、required_mark、scroll_to_first_error、size、validate_messages、validate_trigger、variant、wrapper_col、clear_on_destroy。 +- 事件：fields_change、finish、finish_failed、values_change。 +- 插槽：requiredMark。 +- 数据类型 + - 输入/输出：字典或包装模型。 + - 预处理：将包装模型提取为字典。 +- 预处理/后处理：将 AntdFormData 解包为 dict。 +- 示例用法 + - 将各数据录入组件作为子项放入 Form 中，统一管理校验与提交。 +- 错误处理 + - 通过 validate_messages、scroll_to_first_error 控制错误展示与定位。 +- 实时验证 + - 通过 validate_trigger 控制触发时机（如 onChange）。 + +章节来源 + +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) + +### Input（文本输入） + +- 类型与用途：基础文本输入，支持密码、搜索、多行文本、OTP 等变体。 +- 关键属性 + - 通用：class_names、styles、additional_props、root_class_name、as_item 等。 + - 特有：addon_after、addon_before、allow_clear、count、default_value、read_only、disabled、max_length、prefix、show_count、size、status、suffix、type、placeholder、variant。 +- 事件：change、press_enter、clear。 +- 插槽：addonAfter、addonBefore、allowClear.clearIcon、prefix、suffix、showCount.formatter。 +- 数据类型 + - 输入/输出：字符串。 + - API 规范：字符串。 +- 预处理/后处理：直接透传。 +- 示例用法 + - 通过 Password、Search、Textarea、OTP 子类扩展不同形态。 +- 错误处理 + - 通过 status 与校验规则反馈。 +- 实时验证 + - 通过 change 与 press_enter 事件结合校验。 + +章节来源 + +- [backend/modelscope_studio/components/antd/input/**init**.py:16-127](file://backend/modelscope_studio/components/antd/input/__init__.py#L16-L127) + +### InputNumber（数字输入） + +- 类型与用途：数值输入，支持步进、精度、上下控件等。 +- 关键属性 + - 通用：class_names、styles、additional_props、root_class_name、as_item 等。 + - 特有：addon_after、addon_before、auto_focus、change_on_blur、change_on_wheel、controls、decimal_separator、placeholder、default_value、disabled、formatter、keyboard、max、min、mode、parser、precision、prefix、read_only、size、status、step、string_mode、suffix、variant。 +- 事件：change、press_enter、step。 +- 插槽：addonAfter、addonBefore、controls.upIcon、controls.downIcon、prefix、suffix。 +- 数据类型 + - 输入/输出：整数或浮点数。 + - API 规范：数值。 +- 预处理/后处理：将字符串解析为整数或浮点数。 +- 示例用法 + - 适用于价格、数量、评分等数值输入。 +- 错误处理 + - 通过 min/max、precision、step 约束范围与粒度。 +- 实时验证 + - 通过 change 与 step 事件结合校验。 + +章节来源 + +- [backend/modelscope_studio/components/antd/input_number/**init**.py:11-147](file://backend/modelscope_studio/components/antd/input_number/__init__.py#L11-L147) + +### Mentions（提及）（未在后端发现） + +- 状态：当前仓库未发现后端实现文件。 +- 建议：若需要，请参考 Antd 官方文档与前端实现，补充后端适配层。 + +### Radio（单选）（未在后端发现） + +- 状态：当前仓库未发现后端实现文件。 +- 建议：若需要，请参考 Antd 官方文档与前端实现，补充后端适配层。 + +### Rate（评分）（未在后端发现） + +- 状态：当前仓库未发现后端实现文件。 +- 建议：若需要，请参考 Antd 官方文档与前端实现，补充后端适配层。 + +### Select（选择器）（未在后端发现） + +- 状态：当前仓库未发现后端实现文件。 +- 建议：若需要，请参考 Antd 官方文档与前端实现，补充后端适配层。 + +### Slider（滑块）（未在后端发现） + +- 状态：当前仓库未发现后端实现文件。 +- 建议：若需要，请参考 Antd 官方文档与前端实现，补充后端适配层。 + +### Switch（开关）（未在后端发现） + +- 状态：当前仓库未发现后端实现文件。 +- 建议：若需要，请参考 Antd 官方文档与前端实现，补充后端适配层。 + +### TimePicker（时间选择器）（未在后端发现） + +- 状态：当前仓库未发现后端实现文件。 +- 建议：若需要，请参考 Antd 官方文档与前端实现，补充后端适配层。 + +### Transfer（穿梭框）（未在后端发现） + +- 状态：当前仓库未发现后端实现文件。 +- 建议：若需要，请参考 Antd 官方文档与前端实现，补充后端适配层。 + +### TreeSelect（树选择器）（未在后端发现） + +- 状态：当前仓库未发现后端实现文件。 +- 建议：若需要，请参考 Antd 官方文档与前端实现，补充后端适配层。 + +### Upload（上传）（未在后端发现） + +- 状态：当前仓库未发现后端实现文件。 +- 建议：若需要，请参考 Antd 官方文档与前端实现，补充后端适配层。 + +## 依赖分析 + +- 组件间耦合 + - 所有组件共享同一基类与事件系统，耦合度低、内聚性高。 + - Form 作为容器，聚合各数据录入组件，形成弱耦合的表单生态。 +- 外部依赖 + - 事件系统基于 Gradio 的事件监听器。 + - 前端目录映射通过工具函数解析，确保前后端一致。 +- 循环依赖 + - 未发现循环依赖迹象。 + +```mermaid +graph LR +Base["统一基类"] --> AC["AutoComplete"] +Base --> CS["Cascader"] +Base --> CB["Checkbox"] +Base --> CP["ColorPicker"] +Base --> DP["DatePicker"] +Base --> FM["Form"] +Base --> IN["Input"] +Base --> INN["InputNumber"] +FM --> AC +FM --> CS +FM --> CB +FM --> CP +FM --> DP +FM --> IN +FM --> INN +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/auto_complete/**init**.py:12](file://backend/modelscope_studio/components/antd/auto_complete/__init__.py#L12) +- [backend/modelscope_studio/components/antd/cascader/**init**.py:13](file://backend/modelscope_studio/components/antd/cascader/__init__.py#L13) +- [backend/modelscope_studio/components/antd/checkbox/**init**.py:12](file://backend/modelscope_studio/components/antd/checkbox/__init__.py#L12) +- [backend/modelscope_studio/components/antd/color_picker/**init**.py:12](file://backend/modelscope_studio/components/antd/color_picker/__init__.py#L12) +- [backend/modelscope_studio/components/antd/date_picker/**init**.py:13](file://backend/modelscope_studio/components/antd/date_picker/__init__.py#L13) +- [backend/modelscope_studio/components/antd/form/**init**.py:17](file://backend/modelscope_studio/components/antd/form/__init__.py#L17) +- [backend/modelscope_studio/components/antd/input/**init**.py:16](file://backend/modelscope_studio/components/antd/input/__init__.py#L16) +- [backend/modelscope_studio/components/antd/input_number/**init**.py:11](file://backend/modelscope_studio/components/antd/input_number/__init__.py#L11) + +章节来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-151](file://backend/modelscope_studio/components/antd/__init__.py#L1-L151) + +## 性能考虑 + +- 事件绑定与回调 + - 合理设置事件绑定（如仅在必要时启用搜索/可见性变化），避免频繁触发。 +- 数据类型与序列化 + - 数字输入组件在预处理阶段进行字符串到数值的转换，减少前端类型不一致带来的开销。 +- 下拉与弹窗 + - 对于复杂下拉菜单（如 Cascader），建议使用懒加载与虚拟滚动（如前端支持）降低渲染成本。 +- 样式与类名 + - 使用 class_names 与 styles 精简样式，避免重复计算与重绘。 +- 表单校验 + - 合理设置 validate_trigger，避免高频校验导致的性能问题。 + +## 故障排查指南 + +- 事件未触发 + - 检查是否正确绑定事件监听器，确认前端回调已启用。 +- 数据类型不匹配 + - 数字输入组件在输入非数值字符串时，预处理可能失败；请确保输入格式正确。 +- 校验不生效 + - 确认 Form 的 validate_trigger 设置与组件事件一致；检查 required_mark 与 scroll_to_first_error 配置。 +- 下拉/弹窗异常 + - 检查 get_popup_container 与 placement 配置，确保容器可见且位置合理。 +- 级联加载失败 + - 确认 load_data 回调逻辑与 options 结构一致。 + +章节来源 + +- [backend/modelscope_studio/components/antd/input_number/**init**.py:128-140](file://backend/modelscope_studio/components/antd/input_number/__init__.py#L128-L140) +- [backend/modelscope_studio/components/antd/form/**init**.py:48-68](file://backend/modelscope_studio/components/antd/form/__init__.py#L48-L68) +- [backend/modelscope_studio/components/antd/cascader/**init**.py:33-36](file://backend/modelscope_studio/components/antd/cascader/__init__.py#L33-L36) + +## 结论 + +本项目提供了统一的 Antd 数据录入组件后端适配层，覆盖了自动完成、级联选择、复选框、颜色选择器、日期选择器、表单、文本输入与数字输入等核心组件。通过一致的事件系统、数据类型规范与预处理/后处理机制，开发者可以高效地构建表单与数据录入界面。对于缺失的组件（如 Mentions、Radio、Rate、Select、Slider、Switch、TimePicker、Transfer、TreeSelect、Upload），建议参考 Antd 官方文档与前端实现，补充后端适配层以保持生态一致性。 + +## 附录 + +- 使用建议 + - 将数据录入组件置于 Form 容器中，统一管理初始值、校验与提交。 + - 对于复杂输入（如 Cascader、DatePicker），优先采用受控模式与明确的 API 规范。 + - 利用插槽与变体（variant）提升可访问性与一致性。 +- 最佳实践 + - 为每个输入设置合理的默认值与占位符，改善用户体验。 + - 对于大范围输入（如数字），设置 min/max 与 step，避免无效输入。 + - 对于日期输入，明确 format 与 picker 模式，减少歧义。 diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\351\200\232\347\224\250\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\351\200\232\347\224\250\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..154615c0 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antd \347\273\204\344\273\266 API/\351\200\232\347\224\250\347\273\204\344\273\266 API.md" @@ -0,0 +1,370 @@ +# 通用组件 API + + +**本文引用的文件** +- [button/__init__.py](file://backend/modelscope_studio/components/antd/button/__init__.py) +- [float_button/__init__.py](file://backend/modelscope_studio/components/antd/float_button/__init__.py) +- [icon/__init__.py](file://backend/modelscope_studio/components/antd/icon/__init__.py) +- [typography/__init__.py](file://backend/modelscope_studio/components/antd/typography/__init__.py) +- [affix/__init__.py](file://backend/modelscope_studio/components/antd/affix/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 Antd 通用组件的 Python API 参考文档，覆盖 Button、FloatButton、Icon、Typography、Affix 等基础通用组件。内容包括： + +- 组件类的构造函数参数、属性定义、方法签名与返回值类型 +- 标准实例化示例（基本用法与高级配置） +- 事件处理机制、样式定制方式与响应式行为 +- 参数验证规则、异常处理策略与最佳实践 +- 按功能分类的 API 索引，便于快速查阅 + +## 项目结构 + +这些组件均位于后端 Python 包中，通过统一的布局组件基类进行封装，并指向对应的前端目录以渲染 UI。 + +```mermaid +graph TB +subgraph "Python 后端" +A["AntdButton
构造参数/属性/方法"] +B["AntdFloatButton
构造参数/属性/方法"] +C["AntdIcon
构造参数/属性/方法"] +D["AntdTypography
聚合器Text/Title/Paragraph/Link"] +E["AntdAffix
构造参数/属性/方法"] +end +subgraph "前端目录" +F["button 前端目录"] +G["float-button 前端目录"] +H["icon 前端目录"] +I["typography 前端目录"] +J["affix 前端目录"] +end +A --> F +B --> G +C --> H +D --> I +E --> J +``` + +图表来源 + +- [button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) +- [float_button/**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) +- [typography/**init**.py:1-12](file://backend/modelscope_studio/components/antd/typography/__init__.py#L1-L12) +- [affix/**init**.py:10-86](file://backend/modelscope_studio/components/antd/affix/__init__.py#L10-L86) + +章节来源 + +- [button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) +- [float_button/**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) +- [typography/**init**.py:1-12](file://backend/modelscope_studio/components/antd/typography/__init__.py#L1-L12) +- [affix/**init**.py:10-86](file://backend/modelscope_studio/components/antd/affix/__init__.py#L10-L86) + +## 核心组件 + +本节概述五个通用组件的职责与典型用途： + +- Button：触发操作的按钮，支持多种类型、变体、尺寸、形状与状态（禁用、危险、幽灵、加载）。 +- FloatButton：悬浮全局功能按钮，可带描述、提示、徽标与链接。 +- Icon：语义化矢量图标，支持旋转、旋转动画与双色图标颜色设置。 +- Typography：文本排版集合，包含 Text、Title、Paragraph、Link 子组件。 +- Affix：固定定位容器，用于将子元素粘附到视口顶部或底部。 + +章节来源 + +- [button/**init**.py:15-38](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L38) +- [float_button/**init**.py:12-21](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L21) +- [icon/**init**.py:9-14](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L14) +- [typography/**init**.py:7-12](file://backend/modelscope_studio/components/antd/typography/__init__.py#L7-L12) +- [affix/**init**.py:10-20](file://backend/modelscope_studio/components/antd/affix/__init__.py#L10-L20) + +## 架构总览 + +组件遵循“Python 封装 + 前端渲染”的模式，通过统一的布局组件基类注入通用属性（可见性、DOM ID、类名、内联样式、渲染开关等），并通过 resolve_frontend_dir 指向对应前端目录。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Py as "AntdButton/AntdFloatButton/AntdIcon/AntdAffix" +participant Base as "ModelScopeLayoutComponent/ModelScopeDataLayoutComponent" +participant FE as "前端组件目录" +Dev->>Py : 实例化组件并传入参数 +Py->>Base : 调用父类构造，注入通用属性 +Py->>FE : 设置 FRONTEND_DIR 指向对应前端目录 +Base-->>Dev : 返回可渲染组件对象 +``` + +图表来源 + +- [button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) +- [float_button/**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) +- [affix/**init**.py:10-86](file://backend/modelscope_studio/components/antd/affix/__init__.py#L10-L86) + +## 详细组件分析 + +### Button 组件 API + +- 类型与继承 + - 类名：AntdButton + - 基类：ModelScopeLayoutComponent + - 内部嵌套：Group（按钮组） +- 事件 + - click：点击事件，绑定内部回调以启用事件监听 +- 插槽 + - icon、loading.icon +- 关键属性与含义 + - auto_insert_space：是否自动在中文字符间插入空格 + - block：是否撑满父容器宽度 + - class_names：语义化 DOM 类名 + - danger/disabled/ghost/loading：危险/禁用/幽灵/加载状态 + - href/html_type：链接跳转与原生 HTML type + - icon/icon_position：图标与图标位置 + - shape/size/type/variant/color：形状、尺寸、类型、变体、颜色 + - styles/root_class_name：语义化样式与根类名 + - 其他 Gradio 通用属性：visible、elem_id、elem_classes、elem_style、render +- 方法 + - preprocess(payload): 接收字符串或 None，返回字符串或 None + - postprocess(value): 接收字符串或 None，返回字符串或 None + - example_payload/example_value: 示例负载与示例值 +- 实例化要点 + - 支持通过 type/variant/color/shape/size 控制外观与语义 + - loading 可为布尔或字典（如需自定义加载图标） + - href 配合 html_type='button' 或 'submit'/'reset' +- 最佳实践 + - 主要操作使用 primary 类型；危险操作使用 danger + - 需要避免重复提交时设置 loading + - 图标按钮建议配合 icon_position='start'/'end' + +章节来源 + +- [button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) + +### FloatButton 组件 API + +- 类型与继承 + - 类名：AntdFloatButton + - 基类：ModelScopeLayoutComponent + - 内部嵌套：BackTop（回到顶部）、Group（按钮组） +- 事件 + - click：点击事件，绑定内部回调以启用事件监听 +- 插槽 + - icon、description、tooltip、tooltip.title、badge.count +- 关键属性与含义 + - icon/description：图标与描述文本 + - tooltip：提示文本或配置对象 + - type/shape：类型（default/primary）、形状（circle/square） + - href/href_target/html_type：超链接目标与原生 HTML type + - badge：徽标配置（不支持部分状态相关属性） + - class_names/styles/root_class_name：样式与类名 + - 其他 Gradio 通用属性：visible、elem_id、elem_classes、elem_style、render +- 方法 + - preprocess(payload): 接收 None，返回 None + - postprocess(value): 接收 None，返回 None + - example_payload/example_value: 示例负载与示例值 +- 实例化要点 + - 常用于全局功能入口（如回到顶部、快捷操作） + - tooltip 支持传入字符串或对象以扩展标题等 +- 最佳实践 + - 使用 circle 形状提升可发现性 + - 与 BackTop 组合实现“回到顶部”体验 + +章节来源 + +- [float_button/**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) + +### Icon 组件 API + +- 类型与继承 + - 类名：AntdIcon + - 基类：ModelScopeDataLayoutComponent + - 内部嵌套：IconfontProvider（IconFont 提供者） +- 事件 + - click：点击事件，绑定内部回调以启用事件监听 +- 插槽 + - component：自定义根节点组件 +- 关键属性与含义 + - value：默认图标名称（如 "GithubOutlined"） + - spin：是否旋转动画 + - rotate：旋转角度（度） + - two_tone_color：双色图标主色调 + - component：根节点组件替换 + - class_names/styles：样式与类名 + - 其他 Gradio 通用属性：visible、elem_id、elem_classes、elem_style、render +- 方法 + - preprocess(payload): 接收字符串或 None，返回字符串或 None + - postprocess(value): 接收字符串或 None，返回字符串或 None + - example_payload/example_value: 示例负载与示例值 +- 实例化要点 + - 作为装饰性元素时，优先使用语义化的图标名称 + - spin 与 rotate 可叠加使用 +- 最佳实践 + - 在按钮或导航中搭配 icon_position 使用 + - 双色图标场景下明确主色 + +章节来源 + +- [icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) + +### Typography 组件 API + +- 类型与继承 + - 类名：AntdTypography + - 聚合器：包含 Text、Title、Paragraph、Link 四个子组件 +- 说明 + - 该聚合类仅导出子组件，具体子组件定义位于各自模块 +- 实例化要点 + - 通过 AntdTypography.Text/Title/Paragraph/Link 访问各子组件 +- 最佳实践 + - 文档与页面标题使用 Title + - 正文段落使用 Paragraph + - 可点击链接使用 Link + +章节来源 + +- [typography/**init**.py:1-12](file://backend/modelscope_studio/components/antd/typography/__init__.py#L1-L12) + +### Affix 组件 API + +- 类型与继承 + - 类名：AntdAffix + - 基类：ModelScopeLayoutComponent +- 事件 + - change：状态变化事件（附着/脱离），绑定内部回调以启用事件监听 +- 关键属性与含义 + - offset_bottom：距离视口底部偏移（像素） + - offset_top：距离视口顶部偏移（像素） + - get_target：指定滚动区域 DOM 节点选择器 + - class_names/styles/root_class_name：样式与类名 + - 其他 Gradio 通用属性：visible、elem_id、elem_classes、elem_style、render +- 方法 + - preprocess(payload): 接收 None，返回 None + - postprocess(value): 接收 None，返回 None + - example_payload/example_value: 示例负载与示例值 +- 实例化要点 + - 注意不要遮挡页面其他内容，尤其在小屏设备上 + - get_target 可限定滚动容器，避免全局滚动影响 +- 最佳实践 + - 用于菜单、工具栏等需要常驻可视区的场景 + - 结合交互反馈（如 change 事件）更新状态 + +章节来源 + +- [affix/**init**.py:10-86](file://backend/modelscope_studio/components/antd/affix/__init__.py#L10-L86) + +## 依赖分析 + +- 组件共同依赖 + - 基类：ModelScopeLayoutComponent 或 ModelScopeDataLayoutComponent + - 事件系统：gradio.events.EventListener + - 前端目录解析：resolve_frontend_dir +- 组件间关系 + - Button：包含 ButtonGroup + - FloatButton：包含 BackTop 与 FloatButtonGroup + - Icon：包含 IconfontProvider + - Typography：聚合 Text/Title/Paragraph/Link +- 依赖可视化 + +```mermaid +graph LR +subgraph "事件与基类" +EL["EventListener"] +LCB["ModelScopeLayoutComponent"] +DLCB["ModelScopeDataLayoutComponent"] +end +BTN["AntdButton"] --> LCB +BTN --> EL +BTN --> |"resolve_frontend_dir('button')"| FE_BTN["button 前端目录"] +FLT["AntdFloatButton"] --> LCB +FLT --> EL +FLT --> |"resolve_frontend_dir('float-button')"| FE_FLT["float-button 前端目录"] +ICO["AntdIcon"] --> DLCB +ICO --> EL +ICO --> |"resolve_frontend_dir('icon')"| FE_ICO["icon 前端目录"] +TYP["AntdTypography"] --> |"导出 Text/Title/Paragraph/Link"| SUB["子组件"] +AFF["AntdAffix"] --> LCB +AFF --> EL +AFF --> |"resolve_frontend_dir('affix')"| FE_AFF["affix 前端目录"] +``` + +图表来源 + +- [button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) +- [float_button/**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) +- [typography/**init**.py:1-12](file://backend/modelscope_studio/components/antd/typography/__init__.py#L1-L12) +- [affix/**init**.py:10-86](file://backend/modelscope_studio/components/antd/affix/__init__.py#L10-L86) + +## 性能考虑 + +- 渲染与事件 + - 通过 Gradio 通用属性控制渲染时机与可见性，减少不必要的重绘 + - 事件绑定仅在需要时开启（如 click/change），避免过度监听 +- 图标与加载 + - 合理使用 spin/rotate，避免在低端设备上造成额外开销 + - Button 的 loading 状态可防止重复提交，间接降低服务端压力 +- 容器与滚动 + - Affix 的 get_target 应尽量精确，避免对大范围滚动容器频繁计算 +- 建议 + - 大批量列表中谨慎使用重型组件（如 Tooltip/Popover），必要时延迟加载 + - 使用 shape/size/type 等外观属性时保持一致性，减少样式切换成本 + +## 故障排查指南 + +- 事件未触发 + - 确认已正确设置 EVENTS 并确保组件处于可交互状态（非 disabled/loading） + - 对于 FloatButton/Affix，检查 click/change 事件是否已绑定 +- 样式不生效 + - 检查 class_names/styles 是否与主题变量冲突 + - 确认 root_class_name 未被外部样式覆盖 +- 图标显示异常 + - 确认 value 为受支持的图标名称 + - 若使用自定义 component，请确保组件可渲染且无循环依赖 +- 悬浮按钮遮挡内容 + - 调整 offset_top/offset_bottom 或使用 get_target 精确控制滚动区域 +- 加载态无效 + - Button 的 loading 为布尔或字典时，确认传参格式正确 + +章节来源 + +- [button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) +- [float_button/**init**.py:24-29](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L24-L29) +- [affix/**init**.py:21-26](file://backend/modelscope_studio/components/antd/affix/__init__.py#L21-L26) + +## 结论 + +以上为 Antd 通用组件的 Python API 参考与最佳实践总结。通过统一的基类与事件系统，这些组件在保持简洁易用的同时，提供了丰富的外观与交互能力。建议在实际项目中结合业务场景合理选择组件类型与配置项，并关注性能与可维护性。 + +## 附录 + +- 按功能分类的 API 索引 + - 按钮类：AntdButton（含 Group）、AntdFloatButton（含 BackTop/Group） + - 图标类：AntdIcon（含 IconfontProvider） + - 文本排版：AntdTypography（Text/Title/Paragraph/Link） + - 定位容器：AntdAffix +- 常用参数速查 + - 外观：type、variant、color、shape、size + - 状态：disabled、danger、ghost、loading + - 行为：href、html_type、icon、icon_position、tooltip、badge + - 样式：class_names、styles、root_class_name + - 事件：click、change +- 示例路径指引（不含代码内容） + - Button 基本用法与加载态：[button/**init**.py:88-108](file://backend/modelscope_studio/components/antd/button/__init__.py#L88-L108) + - FloatButton 悬浮入口与回到顶部组合：[float_button/**init**.py:59-70](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L59-L70) + - Icon 动画与双色图标：[icon/**init**.py:47-53](file://backend/modelscope_studio/components/antd/icon/__init__.py#L47-L53) + - Affix 定位与滚动区域：[affix/**init**.py:47-52](file://backend/modelscope_studio/components/antd/affix/__init__.py#L47-L52) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/Antdx \347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/Antdx \347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..4289d223 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/Antdx \347\273\204\344\273\266 API.md" @@ -0,0 +1,443 @@ +# Antdx 组件 API + + +**本文引用的文件** +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/antdx/bubble/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/__init__.py) +- [backend/modelscope_studio/components/antdx/conversations/__init__.py](file://backend/modelscope_studio/components/antdx/conversations/__init__.py) +- [backend/modelscope_studio/components/antdx/prompts/__init__.py](file://backend/modelscope_studio/components/antdx/prompts/__init__.py) +- [backend/modelscope_studio/components/antdx/attachments/__init__.py](file://backend/modelscope_studio/components/antdx/attachments/__init__.py) +- [backend/modelscope_studio/components/antdx/sender/__init__.py](file://backend/modelscope_studio/components/antdx/sender/__init__.py) +- [backend/modelscope_studio/components/antdx/actions/__init__.py](file://backend/modelscope_studio/components/antdx/actions/__init__.py) +- [backend/modelscope_studio/components/antdx/file_card/__init__.py](file://backend/modelscope_studio/components/antdx/file_card/__init__.py) +- [backend/modelscope_studio/components/antdx/folder/__init__.py](file://backend/modelscope_studio/components/antdx/folder/__init__.py) +- [backend/modelscope_studio/components/antdx/code_highlighter/__init__.py](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py) +- [backend/modelscope_studio/components/antdx/notification/__init__.py](file://backend/modelscope_studio/components/antdx/notification/__init__.py) +- [backend/modelscope_studio/components/antdx/sources/__init__.py](file://backend/modelscope_studio/components/antdx/sources/__init__.py) +- [backend/modelscope_studio/components/antdx/suggestion/__init__.py](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py) +- [backend/modelscope_studio/components/antdx/think/__init__.py](file://backend/modelscope_studio/components/antdx/think/__init__.py) +- [backend/modelscope_studio/components/antdx/thought_chain/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 Antdx 组件库的 Python API 参考文档，聚焦于 modelscope_studio.components.antdx.\* 下的机器学习与 AI 应用相关组件。内容覆盖 20+ 个组件类的完整导入路径、构造函数参数、属性定义、方法签名与返回值类型说明，并提供面向对话系统、文件处理、用户输入等典型场景的标准实例化示例与最佳实践。同时记录组件的事件处理机制、生命周期管理、状态同步策略以及性能优化建议。 + +## 项目结构 + +Antdx 组件位于后端 Python 包 modelscope_studio/components/antdx/ 下，采用按功能域分层的模块组织方式：每个子目录对应一个组件或组件族（如 bubble、conversations、sender 等），并在 **init**.py 中统一导出。components.py 与 **init**.py 提供一致的聚合导出入口，便于从 modelscope_studio.components.antdx.\* 直接导入。 + +```mermaid +graph TB +A["Python 包
modelscope_studio.components.antdx"] --> B["actions/*"] +A --> C["attachments/*"] +A --> D["bubble/*"] +A --> E["conversations/*"] +A --> F["file_card/*"] +A --> G["folder/*"] +A --> H["prompts/*"] +A --> I["sender/*"] +A --> J["sources/*"] +A --> K["suggestion/*"] +A --> L["think/*"] +A --> M["thought_chain/*"] +A --> N["notification/*"] +A --> O["code_highlighter/*"] +A --> P["x_provider/*"] +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +章节来源 + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## 核心组件 + +以下列出 modelscope_studio.components.antdx.\* 的全部机器学习与 AI 场景相关组件类及其导入路径与用途概览： + +- 基础布局与展示 + - Bubble（气泡）：用于消息/文本展示与交互，支持编辑、打字动画、变体与形状等。 + - Conversations（会话列表）：用于多会话管理与菜单交互。 + - Prompts（提示词）：用于展示一组可点击的提示词项。 + - Suggestions（建议面板）：用于输入建议与选择。 + - Think（思考态）：用于展示“思考中”状态与展开控制。 + - ThoughtChain（思维链）：用于以树形/链式展示推理过程。 + - CodeHighlighter（代码高亮）：用于代码块渲染与主题控制。 + - Notification（通知）：用于 Web Notification 集成与事件绑定。 + - Sources（来源）：用于展示来源条目与展开控制。 + - Welcome（欢迎）：用于引导页或欢迎信息展示（在导出中存在）。 + - XProvider（上下文提供者）：用于全局上下文注入（在导出中存在）。 + +- 数据与输入 + - Attachments（附件上传）：用于文件上传、拖拽、预览、下载与移除。 + - Sender（发送器）：用于用户输入、快捷键、语音、粘贴与提交事件。 + - FileCard（文件卡片）：用于单个文件的卡片展示与操作。 + - Folder（文件夹浏览）：用于树形目录浏览与文件/文件夹选择。 + - Actions（动作组）：用于一组可点击的动作项与下拉菜单。 + +- Pro 扩展（Pro 模块） + - Chatbot（聊天机器人）：用于对话流程与消息流管理（在导出中存在）。 + - MultimodalInput（多模态输入）：用于图文/音视频等多模态输入（在导出中存在）。 + - MonacoEditor（代码编辑器）：用于代码编辑与高亮（在导出中存在）。 + - WebSandbox（Web 沙盒）：用于安全沙盒运行（在导出中存在）。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## 架构总览 + +Antdx 组件通过统一的基类进行封装，继承自 Gradio 的组件体系，支持事件监听、插槽（slots）、样式与类名注入、以及前端资源目录解析。大部分组件为布局型组件（skip_api=True），不直接暴露 API Schema；少数数据型组件（如 Attachments、Sender）实现 preprocess/postprocess 并暴露 API 规范。 + +```mermaid +classDiagram +class ModelScopeLayoutComponent +class ModelScopeDataLayoutComponent +class AntdXBubble +class AntdXConversations +class AntdXPrompts +class AntdXAttachments +class AntdXSender +class AntdXActions +class AntdXFileCard +class AntdXFolder +class AntdXCodeHighlighter +class AntdXNotification +class AntdXSources +class AntdXSuggestion +class AntdXThink +class AntdXThoughtChain +AntdXBubble --|> ModelScopeLayoutComponent +AntdXConversations --|> ModelScopeLayoutComponent +AntdXPrompts --|> ModelScopeLayoutComponent +AntdXFileCard --|> ModelScopeLayoutComponent +AntdXFolder --|> ModelScopeLayoutComponent +AntdXCodeHighlighter --|> ModelScopeLayoutComponent +AntdXNotification --|> ModelScopeLayoutComponent +AntdXSources --|> ModelScopeLayoutComponent +AntdXSuggestion --|> ModelScopeLayoutComponent +AntdXThink --|> ModelScopeLayoutComponent +AntdXThoughtChain --|> ModelScopeLayoutComponent +AntdXAttachments --|> ModelScopeDataLayoutComponent +AntdXSender --|> ModelScopeDataLayoutComponent +AntdXActions --|> ModelScopeLayoutComponent +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:13-135](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L13-L135) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) +- [backend/modelscope_studio/components/antdx/attachments/**init**.py:22-227](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L22-L227) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:14-149](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L14-L149) +- [backend/modelscope_studio/components/antdx/actions/**init**.py:15-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L112) +- [backend/modelscope_studio/components/antdx/file_card/**init**.py:11-112](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L11-L112) +- [backend/modelscope_studio/components/antdx/folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) +- [backend/modelscope_studio/components/antdx/code_highlighter/**init**.py:6-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L6-L71) +- [backend/modelscope_studio/components/antdx/notification/**init**.py:10-97](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L10-L97) +- [backend/modelscope_studio/components/antdx/sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) + +## 详细组件分析 + +### Bubble（气泡） + +- 导入路径：modelscope_studio.components.antdx.Bubble +- 用途：消息/文本展示，支持编辑、打字动画、变体与形状等。 +- 关键参数（节选）：content、avatar、footer、header、loading、placement、editable、shape、typing、streaming、variant、footer_placement、loading_render、content_render、root_class_name、class_names、styles、additional_props、可见性与样式属性。 +- 事件：typing、typing_complete、edit_confirm、edit_cancel。 +- 插槽：avatar、editable.okText、editable.cancelText、content、footer、header、extra、loadingRender、contentRender。 +- 生命周期与 API：skip*api=True，不暴露 API；preprocess/postprocess/example*\* 为空实现。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:13-135](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L13-L135) + +### Conversations（会话列表） + +- 导入路径：modelscope_studio.components.antdx.Conversations +- 子组件：Item +- 关键参数：active_key、default_active_key、items、menu、groupable、shortcut_keys、creation、styles、class_names、root_class_name、additional_props。 +- 事件：active_change、menu_click、menu_deselect、menu_open_change、menu_select、groupable_expand、creation_click。 +- 插槽：menu.expandIcon、menu.overflowedIndicator、menu.trigger、groupable.label、items、creation.icon、creation.label。 +- 生命周期与 API：skip_api=True。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) + +### Prompts（提示词） + +- 导入路径：modelscope_studio.components.antdx.Prompts +- 子组件：Item +- 关键参数：items、prefix_cls、title、vertical、fade_in、fade_in_left、wrap、styles、class_names、root_class_name、additional_props。 +- 事件：item_click。 +- 插槽：title、items。 +- 生命周期与 API：skip_api=True。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) + +### Attachments（附件上传） + +- 导入路径：modelscope_studio.components.antdx.Attachments +- 数据模型：ListFiles +- 关键参数：image_props、accept、action、before_upload、custom_request、data、default_file_list、directory、disabled、items、get_drop_container、overflow、placeholder、headers、icon_render、is_image_url、item_render、list_type、max_count、method、multiple、form_name、open_file_dialog_on_click、preview_file、progress、show_upload_list、with_credentials、class_names、root_style、styles、root_class_name、可见性与定时轮询等。 +- 事件：change、drop、download、preview、remove。 +- 生命周期与 API：skip_api=False；preprocess 将 payload 转换为文件路径列表；postprocess 将文件路径列表转换为 ListFiles；api_info 返回 ListFiles 的 JSON Schema。 +- 典型用法：作为输入组件接收文件列表，作为输出组件返回文件元数据。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/attachments/**init**.py:22-227](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L22-L227) + +### Sender（发送器） + +- 导入路径：modelscope_studio.components.antdx.Sender +- 子组件：Header、Switch +- 关键参数：value、allow_speech、class_names、components、default_value、disabled、auto_size、loading、suffix、footer、header、prefix、read_only、styles、submit_type、placeholder、slot_config、skill、root_class_name、additional_props。 +- 事件：change、submit、cancel、allow_speech_recording_change、key_down、key_press、focus、blur、paste、paste_file、skill_closable_close。 +- 插槽：suffix、header、prefix、footer、skill.title、skill.toolTip.title、skill.closable.closeIcon。 +- 生命周期与 API：skip*api=False；preprocess/postprocess 返回字符串；api_info 返回字符串类型描述；example*\* 返回 None。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/sender/**init**.py:14-149](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L14-L149) + +### Actions（动作组） + +- 导入路径：modelscope_studio.components.antdx.Actions +- 子组件：ActionItem、Item、Feedback、Copy、Audio +- 关键参数：additional_props、items、variant、dropdown_props、fade_in、fade_in_left、class_names、styles。 +- 事件：click、dropdown_open_change、dropdown_menu_click、dropdown_menu_deselect、dropdown_menu_open_change、dropdown_menu_select。 +- 插槽：items、dropdownProps.dropdownRender、dropdownProps.popupRender、dropdownProps.menu.expandIcon、dropdownProps.menu.overflowedIndicator、dropdownProps.menu.items。 +- 生命周期与 API：skip_api=True。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/actions/**init**.py:15-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L112) + +### FileCard（文件卡片） + +- 导入路径：modelscope_studio.components.antdx.FileCard +- 子组件：List +- 关键参数：image_props、filename、byte、size、description、loading、type、src、mask、icon、video_props、audio_props、spin_props、class_names、styles、additional_props。 +- 事件：click。 +- 插槽：imageProps.placeholder、imageProps.preview.mask、imageProps.preview.closeIcon、imageProps.preview.toolbarRender、imageProps.preview.imageRender、description、icon、mask、spinProps.icon、spinProps.description、spinProps.indicator。 +- 生命周期与 API：skip_api=True。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/file_card/**init**.py:11-112](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L11-L112) + +### Folder（文件夹） + +- 导入路径：modelscope_studio.components.antdx.Folder +- 子组件：TreeNode、DirectoryIcon +- 关键参数：additional_props、tree_data、selectable、selected_file、default_selected_file、directory_tree_width、empty_render、preview_render、expanded_paths、default_expanded_paths、default_expand_all、directory_title、preview_title、directory_icons、class_names、styles、root_class_name。 +- 事件：file_click、folder_click、selected_file_change、expanded_paths_change、file_content_service_load_file_content。 +- 插槽：emptyRender、previewRender、directoryTitle、previewTitle、treeData、directoryIcons。 +- 生命周期与 API：skip_api=True。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) + +### CodeHighlighter（代码高亮） + +- 导入路径：modelscope_studio.components.antdx.CodeHighlighter +- 关键参数：value、lang、header、highlight_props、prism_light_mode、styles、class_names、additional_props、root_class_name。 +- 插槽：header。 +- 生命周期与 API：skip_api=True。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/code_highlighter/**init**.py:6-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L6-L71) + +### Notification（通知） + +- 导入路径：modelscope_studio.components.antdx.Notification +- 关键参数：title、duration、badge、body、data、dir、icon、lang、require_interaction、silent、tag、additional_props。 +- 事件：permission、click、close、error、show。 +- 生命周期与 API：skip_api=True。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/notification/**init**.py:10-97](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L10-L97) + +### Sources（来源） + +- 导入路径：modelscope_studio.components.antdx.Sources +- 子组件：Item +- 关键参数：title、items、expand_icon_position、default_expanded、expanded、inline、active_key、popover_overlay_width、styles、class_names、root_class_name、additional_props。 +- 事件：expand、click。 +- 插槽：items。 +- 生命周期与 API：skip_api=True。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) + +### Suggestion（建议） + +- 导入路径：modelscope_studio.components.antdx.Suggestion +- 子组件：Item +- 关键参数：additional_props、items、block、open、should_trigger、class_names、styles、root_class_name。 +- 事件：select、open_change。 +- 插槽：items、children。 +- 生命周期与 API：skip_api=True。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) + +### Think（思考态） + +- 导入路径：modelscope_studio.components.antdx.Think +- 关键参数：additional_props、icon、styles、class_names、loading、title、root_class_name、default_expanded、expanded、blink。 +- 事件：expand。 +- 插槽：loading、icon、title。 +- 生命周期与 API：skip_api=True。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) + +### ThoughtChain（思维链） + +- 导入路径：modelscope_studio.components.antdx.ThoughtChain +- 子组件：Item、ThoughtChainItem +- 关键参数：expanded_keys、default_expanded_keys、items、line、prefix_cls、styles、class_names、root_class_name、additional_props。 +- 事件：expand。 +- 插槽：items。 +- 生命周期与 API：skip_api=True。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) + +## 依赖分析 + +- 组件统一继承自 ModelScopeLayoutComponent 或 ModelScopeDataLayoutComponent，后者支持数据类型的 preprocess/postprocess 与 API 规范导出。 +- 大多数组件为布局型组件，skip_api=True，不暴露 API；少数数据型组件（Attachments、Sender）实现数据序列化规范。 +- 组件通过 resolve_frontend_dir("xxx", type="antdx") 解析前端资源目录，确保与前端组件一一对应。 + +```mermaid +graph LR +A["AntdXBubble"] --> B["ModelScopeLayoutComponent"] +C["AntdXAttachments"] --> D["ModelScopeDataLayoutComponent"] +E["AntdXSender"] --> D +F["AntdXConversations"] --> B +G["AntdXPrompts"] --> B +H["AntdXActions"] --> B +I["AntdXFileCard"] --> B +J["AntdXFolder"] --> B +K["AntdXCodeHighlighter"] --> B +L["AntdXNotification"] --> B +M["AntdXSources"] --> B +N["AntdXSuggestion"] --> B +O["AntdXThink"] --> B +P["AntdXThoughtChain"] --> B +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:13-135](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L13-L135) +- [backend/modelscope_studio/components/antdx/attachments/**init**.py:22-227](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L22-L227) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:14-149](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L14-L149) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) +- [backend/modelscope_studio/components/antdx/actions/**init**.py:15-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L112) +- [backend/modelscope_studio/components/antdx/file_card/**init**.py:11-112](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L11-L112) +- [backend/modelscope_studio/components/antdx/folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) +- [backend/modelscope_studio/components/antdx/code_highlighter/**init**.py:6-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L6-L71) +- [backend/modelscope_studio/components/antdx/notification/**init**.py:10-97](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L10-L97) +- [backend/modelscope_studio/components/antdx/sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) + +## 性能考虑 + +- 事件绑定：通过 EventListener 在构造时绑定回调，避免重复绑定导致的性能损耗。 +- 数据组件序列化：Attachments、Sender 明确实现 preprocess/postprocess，减少不必要的数据转换开销。 +- 前端资源：resolve_frontend_dir 确保仅加载必要资源，避免冗余打包。 +- 渲染优化：布局型组件 skip_api=True，减少 API 层面的额外处理。 + +## 故障排查指南 + +- 事件未触发：检查 EVENTS 列表中的回调是否正确绑定，确认前端组件已启用相应事件。 +- 文件上传异常：核对 Attachments 的 action、headers、with_credentials、max_count 等参数；确认服务端可访问与缓存目录权限。 +- 输入值未更新：Sender 的 value 与 default_value 需保持一致的数据类型；关注 change/submit/cancel 事件的触发时机。 +- 样式与插槽：若插槽内容不显示，检查 SLOTS 定义与传入的 slot 名称是否匹配。 + +## 结论 + +Antdx 组件库围绕 AI/ML 应用场景提供了丰富的布局、输入与数据组件，既满足对话系统、文件处理与用户输入等典型需求，又通过统一的事件与插槽机制保证了良好的扩展性与一致性。建议在实际项目中优先使用数据型组件（如 Attachments、Sender）以获得更清晰的 API 行为与数据流，同时利用布局型组件构建友好的交互界面。 + +## 附录 + +### API 索引（按场景分类） + +- 通用组件 + - Bubble、Conversations、Prompts、Suggestions、Think、ThoughtChain、CodeHighlighter、Notification、Sources、FileCard、Folder、Actions +- 唤醒/输入组件 + - Sender（含 Header、Switch） +- 工具组件 + - Attachments（文件上传/下载/预览/移除） +- 反馈组件 + - Actions（动作组与反馈） +- 表达组件 + - CodeHighlighter（代码高亮） +- 状态与流程组件 + - Think、ThoughtChain、Notification、Sources、Folder、FileCard + +### 标准实例化示例（路径指引） + +- 对话系统 + - 使用 Bubble、Conversations、Prompts、Sender、Actions 组合构建对话界面。 + - 示例路径指引：[Bubble 构造函数:56-116](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L56-L116)、[Conversations 构造函数:49-91](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L49-L91)、[Prompts 构造函数:28-71](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L28-L71)、[Sender 构造函数:68-128](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L68-L128)、[Actions 构造函数:58-94](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L58-L94) +- 文件处理 + - 使用 Attachments 接收文件列表，结合 Sender 的 paste/paste_file 事件实现拖拽与粘贴上传。 + - 示例路径指引：[Attachments 构造函数:66-160](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L66-L160)、[Sender 事件与参数:21-59](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L21-L59) +- 用户输入 + - 使用 Sender 的 submit/cancel 事件与 value/default_value 控制输入状态。 + - 示例路径指引：[Sender 事件与参数:21-99](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L21-L99) + +### 机器学习集成接口与数据格式 + +- 数据型组件（Attachments、Sender） + - preprocess：将 payload 转换为组件期望的内部表示（如文件路径列表）。 + - postprocess：将内部值转换为对外输出的数据结构（如 ListFiles）。 + - api_info：导出 JSON Schema，明确 API 输入输出类型。 +- 布局型组件（其余组件） + - 通常 skip_api=True，不暴露 API；通过属性与事件驱动状态变化。 + +### 生命周期与事件处理机制 + +- 事件绑定：在构造函数中通过 EventListener 注册回调，组件内部通过 \_internal.update 绑定到前端事件。 +- 插槽：通过 SLOTS 定义支持的插槽名称，组件内部解析并渲染对应内容。 +- 样式与类名：支持 styles、class_names、root_class_name 等统一注入样式。 diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\345\217\215\351\246\210\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\345\217\215\351\246\210\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..bc9ac34b --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\345\217\215\351\246\210\347\273\204\344\273\266 API.md" @@ -0,0 +1,446 @@ +# 反馈组件 API + + +**本文档引用的文件** +- [actions/__init__.py](file://backend/modelscope_studio/components/antdx/actions/__init__.py) +- [action_item/__init__.py](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py) +- [item/__init__.py](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py) +- [copy/__init__.py](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py) +- [audio/__init__.py](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py) +- [feedback/__init__.py](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py) +- [notification/__init__.py](file://backend/modelscope_studio/components/antdx/notification/__init__.py) +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：使用示例与最佳实践](#附录使用示例与最佳实践) + +## 简介 + +本文件为 Antdx 反馈组件的 Python API 参考文档，覆盖 Actions 组件的操作列表管理、操作项配置与用户交互；ActionsItem 的操作项定义；ActionItem 的具体操作实现；Copy 组件的复制功能；Audio 组件的音频处理；Feedback 组件的反馈收集机制；Notification 组件的通知管理、消息推送与用户反馈响应。文档同时提供事件处理策略、状态同步机制与用户体验优化配置，并给出与聊天机器人集成及用户行为实时反馈的参考方案。 + +## 项目结构 + +Antdx 反馈相关组件位于后端 Python 包中，采用按功能模块组织的目录结构，前端资源由前端目录中的 Svelte 组件提供。Python 层通过 Gradio 组件封装与事件绑定，统一暴露给应用层调用。 + +```mermaid +graph TB +subgraph "Antdx 组件Python" +A["actions/__init__.py
AntdXActions"] +B["actions/action_item/__init__.py
AntdXActionsActionItem"] +C["actions/item/__init__.py
AntdXActionsItem"] +D["actions/copy/__init__.py
AntdXActionsCopy"] +E["actions/audio/__init__.py
AntdXActionsAudio"] +F["actions/feedback/__init__.py
AntdXActionsFeedback"] +G["notification/__init__.py
AntdXNotification"] +end +subgraph "导出入口" +H["components.py
统一导出"] +end +A --> B +A --> C +A --> D +A --> E +A --> F +H --> A +H --> G +``` + +**图表来源** + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [actions/**init**.py:15-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L112) +- [action_item/**init**.py:10-80](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L10-L80) +- [item/**init**.py:10-77](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L10-L77) +- [copy/**init**.py:10-72](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L10-L72) +- [audio/**init**.py:10-71](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L10-L71) +- [feedback/**init**.py:10-74](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L10-L74) +- [notification/**init**.py:10-97](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L10-L97) + +**章节来源** + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## 核心组件 + +- AntdXActions：操作集合容器，支持事件绑定与插槽扩展，用于承载多个操作项与子菜单。 +- AntdXActionsActionItem：自定义动作项，支持标签、图标、危险样式、触发方式与子项。 +- AntdXActionsItem：标准操作项，支持状态（加载/运行/错误/默认）、图标切换与样式定制。 +- AntdXActionsCopy：复制操作，绑定点击事件，支持自定义图标与文本。 +- AntdXActionsAudio：音频状态指示器，支持状态枚举与样式定制。 +- AntdXActionsFeedback：点赞/点踩/默认状态的反馈组件，支持点击与状态变更事件。 +- AntdXNotification：通知组件，支持权限、点击、关闭、错误、显示等事件与多语言/方向等属性。 + +以上组件均继承自统一的布局组件基类，具备 Gradio 兼容的事件绑定与渲染控制能力。 + +**章节来源** + +- [actions/**init**.py:15-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L112) +- [action_item/**init**.py:10-80](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L10-L80) +- [item/**init**.py:10-77](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L10-L77) +- [copy/**init**.py:10-72](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L10-L72) +- [audio/**init**.py:10-71](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L10-L71) +- [feedback/**init**.py:10-74](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L10-L74) +- [notification/**init**.py:10-97](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L10-L97) + +## 架构总览 + +Antdx 反馈组件在 Python 层以 Gradio 组件形式暴露，前端由对应 Svelte 组件实现 UI 行为与交互。组件通过事件监听器绑定回调，实现用户操作到后端的事件传递与状态更新。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant A as "AntdXActions" +participant AI as "AntdXActionsActionItem" +participant AF as "AntdXActionsFeedback" +participant AN as "AntdXNotification" +U->>A : 触发点击/下拉事件 +A-->>U : 触发绑定的事件回调 +U->>AI : 点击自定义动作项 +AI-->>U : 触发 item_click 回调 +U->>AF : 点击反馈按钮 +AF-->>U : 触发 click/change 回调 +U->>AN : 触发通知显示/点击/关闭 +AN-->>U : 触发 permission/click/close/error/show 回调 +``` + +**图表来源** + +- [actions/**init**.py:26-46](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L26-L46) +- [action_item/**init**.py:15-21](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L15-L21) +- [feedback/**init**.py:15-23](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L15-L23) +- [notification/**init**.py:14-30](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L14-L30) + +## 详细组件分析 + +### Actions 组件（AntdXActions） + +- 职责：作为操作集合容器，管理操作项列表、下拉菜单属性与动画效果；支持事件绑定与插槽扩展。 +- 关键属性 + - items：操作项数组，用于初始化操作列表。 + - variant：外观变体（如 borderless/outlined/filled）。 + - dropdown_props：下拉菜单相关属性对象。 + - fade_in/fade_in_left：进入动画开关。 + - class_names/styles：样式类名与内联样式映射。 + - 插槽：items、dropdownRender、popupRender、menu.expandIcon、overflowedIndicator、menu.items。 +- 事件 + - click：任意操作项被点击时触发。 + - dropdown_open_change/dropdown_menu_open_change：下拉打开/菜单打开状态变化。 + - dropdown_menu_click/dropdown_menu_deselect/dropdown_menu_select：菜单项点击/取消选择/选择事件。 +- 处理流程 + - 初始化时设置内部绑定标志位，使前端事件可回传至后端。 + - 渲染时根据 items 与 dropdown_props 动态生成操作项与菜单结构。 + - 通过插槽扩展自定义渲染逻辑。 + +```mermaid +classDiagram +class AntdXActions { ++属性 : items, variant, dropdown_props, fade_in, fade_in_left ++方法 : preprocess(), postprocess() ++事件 : click, dropdown_open_change, dropdown_menu_*... ++插槽 : items, dropdownRender, popupRender, menu.expandIcon, overflowedIndicator, menu.items +} +``` + +**图表来源** + +- [actions/**init**.py:58-94](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L58-L94) + +**章节来源** + +- [actions/**init**.py:15-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L112) + +### ActionsItem（AntdXActionsItem） + +- 职责：标准操作项，支持状态切换与图标替换。 +- 关键属性 + - status：状态枚举（loading/error/running/default）。 + - label：显示标签。 + - default_icon/running_icon：默认图标与运行中图标。 + - class_names/styles：样式类名与内联样式映射。 + - 插槽：defaultIcon、runningIcon。 +- 事件 + - click：项被点击时触发。 +- 使用建议 + - 结合 Actions 组件的 items 字段进行批量配置。 + - 通过插槽自定义不同状态下的图标与文案。 + +```mermaid +classDiagram +class AntdXActionsItem { ++属性 : status, label, default_icon, running_icon ++方法 : preprocess(), postprocess() ++事件 : click ++插槽 : defaultIcon, runningIcon +} +``` + +**图表来源** + +- [item/**init**.py:24-59](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L24-L59) + +**章节来源** + +- [item/**init**.py:10-77](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L10-L77) + +### ActionItem（AntdXActionsActionItem） + +- 职责：自定义动作项，支持标签、图标、危险样式、子项与触发方式。 +- 关键属性 + - label/icon：标签与图标。 + - danger：是否危险样式。 + - trigger_sub_menu_action：子菜单触发方式（hover/click）。 + - sub_items：子项数组。 + - action_render：自定义渲染函数标识。 + - 插槽：label、icon、actionRender、subItems。 +- 事件 + - item_click：自定义动作按钮被点击时触发。 +- 使用建议 + - 适用于复杂菜单或需要自定义渲染的场景。 + - 子项通过 subItems 插槽注入，形成嵌套菜单树。 + +```mermaid +classDiagram +class AntdXActionsActionItem { ++属性 : label, icon, danger, trigger_sub_menu_action, sub_items, action_render ++方法 : preprocess(), postprocess() ++事件 : item_click ++插槽 : label, icon, actionRender, subItems +} +``` + +**图表来源** + +- [action_item/**init**.py:26-62](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L26-L62) + +**章节来源** + +- [action_item/**init**.py:10-80](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L10-L80) + +### Copy 组件（AntdXActionsCopy） + +- 职责：提供一键复制功能，常用于代码块、链接等文本复制。 +- 关键属性 + - text：待复制文本。 + - icon：自定义图标。 + - class_names/styles：样式类名与内联样式映射。 + - 插槽：icon。 +- 事件 + - click：复制按钮被点击时触发。 +- 使用建议 + - 与 ActionItem 或 ActionsItem 搭配使用，提升用户操作效率。 + - 注意浏览器权限与剪贴板 API 的兼容性。 + +```mermaid +classDiagram +class AntdXActionsCopy { ++属性 : text, icon ++方法 : preprocess(), postprocess() ++事件 : click ++插槽 : icon +} +``` + +**图表来源** + +- [copy/**init**.py:24-54](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L24-L54) + +**章节来源** + +- [copy/**init**.py:10-72](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L10-L72) + +### Audio 组件（AntdXActionsAudio） + +- 职责：音频状态指示器，用于展示录音/播放/加载/错误等状态。 +- 关键属性 + - status：状态枚举（loading/error/running/default）。 + - class_names/styles：样式类名与内联样式映射。 + - 插槽：无。 +- 事件 + - click：音频控件被点击时触发。 +- 使用建议 + - 与录音/播放功能配合，提供即时状态反馈。 + - 通过样式定制适配主题色板。 + +```mermaid +classDiagram +class AntdXActionsAudio { ++属性 : status ++方法 : preprocess(), postprocess() ++事件 : click +} +``` + +**图表来源** + +- [audio/**init**.py:24-53](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L24-L53) + +**章节来源** + +- [audio/**init**.py:10-71](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L10-L71) + +### Feedback 组件（AntdXActionsFeedback） + +- 职责：收集用户对内容/对话的反馈，支持点赞/点踩/默认状态。 +- 关键属性 + - value：当前反馈值（like/dislike/default）。 + - class_names/styles：样式类名与内联样式映射。 + - 插槽：无。 +- 事件 + - click：反馈按钮被点击时触发。 + - change：反馈状态发生改变时触发。 +- 使用建议 + - 与聊天机器人输出或内容卡片搭配，形成闭环反馈链路。 + - 通过 change 事件上报数据，结合后端存储与统计。 + +```mermaid +classDiagram +class AntdXActionsFeedback { ++属性 : value ++方法 : preprocess(), postprocess() ++事件 : click, change +} +``` + +**图表来源** + +- [feedback/**init**.py:28-56](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L28-L56) + +**章节来源** + +- [feedback/**init**.py:10-74](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L10-L74) + +### Notification 组件（AntdXNotification） + +- 职责：系统通知管理，支持权限、点击、关闭、错误、显示等事件与国际化/方向等属性。 +- 关键属性 + - title/body：标题与正文。 + - duration：显示时长。 + - badge/lang/dir/icon/tag/data/silent/require_interaction：徽标、语言、方向、图标、标签、数据、静默模式、需交互。 + - 插槽：无。 +- 事件 + - permission/click/close/error/show：权限请求、点击、关闭、错误、显示。 +- 使用建议 + - 用于系统提示、权限提醒、错误告警与用户反馈响应。 + - 结合 Feedback 组件，形成“通知—反馈”的闭环。 + +```mermaid +classDiagram +class AntdXNotification { ++属性 : title, body, duration, badge, lang, dir, icon, tag, data, silent, require_interaction ++方法 : preprocess(), postprocess() ++事件 : permission, click, close, error, show +} +``` + +**图表来源** + +- [notification/**init**.py:35-79](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L35-L79) + +**章节来源** + +- [notification/**init**.py:10-97](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L10-L97) + +## 依赖关系分析 + +- 统一导出：components.py 将所有 Antdx 组件集中导出，便于上层应用按需引入。 +- 组件间关系：Actions 容器组合 ActionItem、Item、Copy、Audio、Feedback 等子组件；Notification 独立存在，可与 Feedback 协同使用。 + +```mermaid +graph LR +subgraph "导出层" +C["components.py"] +end +subgraph "Actions 家族" +A1["AntdXActions"] +A2["AntdXActionsActionItem"] +A3["AntdXActionsItem"] +A4["AntdXActionsCopy"] +A5["AntdXActionsAudio"] +A6["AntdXActionsFeedback"] +end +subgraph "通知" +N1["AntdXNotification"] +end +C --> A1 +C --> N1 +A1 --> A2 +A1 --> A3 +A1 --> A4 +A1 --> A5 +A1 --> A6 +``` + +**图表来源** + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [actions/**init**.py:15-25](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L25) +- [notification/**init**.py:10-13](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L10-L13) + +**章节来源** + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## 性能考虑 + +- 事件绑定最小化：仅在需要时启用事件绑定，避免不必要的回调开销。 +- 插槽渲染：合理使用插槽减少重复渲染，保持 DOM 结构简洁。 +- 状态同步：通过组件状态与事件联动，避免频繁全量刷新。 +- 样式与动画：谨慎使用进入动画与复杂样式，确保在低端设备上的流畅度。 + +## 故障排查指南 + +- 事件未触发 + - 检查事件绑定是否正确启用（如 click、dropdown\_\*、item_click、change）。 + - 确认前端插槽与属性配置是否匹配。 +- 状态不一致 + - 核对 value/status 的取值范围与默认值。 + - 在 change 事件中检查状态变更逻辑。 +- 样式异常 + - 检查 class_names/styles 是否覆盖了默认样式。 + - 确认主题与全局样式冲突。 +- 通知无效 + - 检查权限事件 permission 的处理流程。 + - 确认显示时长与交互需求配置。 + +**章节来源** + +- [actions/**init**.py:26-46](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L26-L46) +- [action_item/**init**.py:15-21](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L15-L21) +- [feedback/**init**.py:15-23](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L15-L23) +- [notification/**init**.py:14-30](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L14-L30) + +## 结论 + +Antdx 反馈组件通过清晰的组件分层与事件绑定机制，提供了从操作项管理、复制与音频状态指示到用户反馈与通知管理的完整能力。结合统一导出与插槽扩展，开发者可在多种场景中快速构建高质量的用户反馈与交互体验。 + +## 附录：使用示例与最佳实践 + +- 用户操作反馈 + - 在内容卡片或对话输出后添加 Feedback 组件，绑定 click 与 change 事件，上报用户偏好。 + - 示例路径：[feedback/**init**.py:15-23](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L15-L23) +- 快捷操作 + - 使用 Actions 组合 ActionItem 与 Item，配置 subItems 形成二级菜单；通过插槽自定义图标与文案。 + - 示例路径：[actions/**init**.py:48-56](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L48-L56)、[action_item/**init**.py:23-24](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L23-L24) +- 音频交互 + - 使用 Audio 组件展示录音/播放状态，结合 click 事件控制播放/暂停。 + - 示例路径：[audio/**init**.py:15-19](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L15-L19) +- 复制功能 + - 在代码块或链接旁放置 Copy 组件，绑定 click 事件，提升复制效率。 + - 示例路径：[copy/**init**.py:15-19](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L15-L19) +- 通知管理 + - 使用 Notification 组件进行系统提示与权限提醒，绑定 permission/click/close/error/show 事件。 + - 示例路径：[notification/**init**.py:14-30](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L14-L30) +- 与聊天机器人集成 + - 在聊天输出后插入 Feedback 组件，通过 change 事件上报用户反馈；必要时弹出 Notification 进行确认或错误提示。 + - 示例路径：[feedback/**init**.py:15-23](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L15-L23)、[notification/**init**.py:14-30](file://backend/modelscope_studio/components/antdx/notification/__init__.py#L14-L30) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\345\224\244\351\206\222\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\345\224\244\351\206\222\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..c4ef117c --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\345\224\244\351\206\222\347\273\204\344\273\266 API.md" @@ -0,0 +1,334 @@ +# 唤醒组件 API + + +**本文引用的文件** +- [backend/modelscope_studio/components/antdx/welcome/__init__.py](file://backend/modelscope_studio/components/antdx/welcome/__init__.py) +- [backend/modelscope_studio/components/antdx/prompts/__init__.py](file://backend/modelscope_studio/components/antdx/prompts/__init__.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) +- [docs/components/antdx/welcome/app.py](file://docs/components/antdx/welcome/app.py) +- [docs/components/antdx/prompts/app.py](file://docs/components/antdx/prompts/app.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 Antdx 唤醒组件的 Python API 参考文档，聚焦以下目标： + +- 记录 Welcome 组件的欢迎界面展示、欢迎消息配置与用户引导流程 +- 说明 Prompts 组件的提示集管理、提示模板定义与动态提示生成机制 +- 提供 Welcome 组件的消息格式、个性化配置选项与多语言支持说明 +- 给出 AI 助手启动、用户引导、提示激活等标准使用示例 +- 说明初始化参数、回调函数配置与用户体验优化策略 +- 说明与对话系统的集成方式与状态同步机制 + +## 项目结构 + +Antdx 组件位于后端 Python 包中，通过统一的布局组件基类与前端目录解析机制进行桥接。Welcome 与 Prompts 组件均继承自通用布局组件基类，并通过 resolve_frontend_dir 指向对应的前端组件目录。 + +```mermaid +graph TB +subgraph "Python 后端" +A["ModelScopeLayoutComponent
组件基类"] +B["AntdXWelcome
欢迎组件"] +C["AntdXPrompts
提示组件"] +D["AntdXPromptsItem
提示项组件"] +E["resolve_frontend_dir
前端目录解析"] +end +subgraph "前端组件" +F["welcome 组件目录"] +G["prompts 组件目录"] +H["prompts/item 子组件目录"] +end +A --> B +A --> C +C --> D +E --> F +E --> G +E --> H +B -.-> F +C -.-> G +D -.-> H +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:55-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L55-L55) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:70-70](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L70-L70) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-16](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L16) + +章节来源 + +- [backend/modelscope_studio/components/antdx/components.py:24-39](file://backend/modelscope_studio/components/antdx/components.py#L24-L39) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) + +## 核心组件 + +- AntdXWelcome：用于渲染欢迎界面，支持标题、描述、图标、额外内容等插槽化配置，以及样式与变体控制。 +- AntdXPrompts：用于展示一组提示词卡片，支持标题、垂直排列、淡入动画、换行等配置；内置 item_click 回调事件以响应点击行为。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) + +## 架构总览 + +Antdx 组件通过统一的布局组件基类与前端目录解析器连接到对应前端组件目录。组件在初始化时设置前端目录路径，并通过 Gradio 的 BlockContext 机制参与布局更新与内部状态传递。 + +```mermaid +sequenceDiagram +participant Py as "Python 组件" +participant Base as "ModelScopeLayoutComponent" +participant Resolver as "resolve_frontend_dir" +participant FE as "前端组件目录" +Py->>Base : 初始化组件设置可见性/元素属性 +Py->>Resolver : 解析前端目录组件名/子组件/类型 +Resolver-->>Py : 返回相对路径 +Py->>FE : 加载对应前端组件资源 +Py->>Base : 进入上下文触发 layout 更新 +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:24-26](file://backend/modelscope_studio/utils/dev/component.py#L24-L26) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-16](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L16) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:55-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L55-L55) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:70-70](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L70-L70) + +## 详细组件分析 + +### Welcome 组件 API + +- 组件定位：AntdXWelcome +- 继承关系：ModelScopeLayoutComponent +- 插槽支持：extra、icon、description、title +- 关键参数 + - extra：额外内容（字符串或 None） + - icon：图标资源路径（将通过静态文件服务处理） + - description：描述文本 + - title：标题文本 + - variant：外观变体（可选 filled 或 borderless） + - styles/class_names/root_class_name：样式与类名配置 + - 元素属性：elem_id、elem_classes、elem_style、visible、render 等 +- 生命周期与预处理 + - preprocess/postprocess/example_payload/example_value 均返回空值，表明该组件不进行数据转换或示例值生成 +- 事件 + - 无公开事件绑定（EVENTS 为空） + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__enter__() ++__exit__() ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdXWelcome { ++additional_props ++extra ++icon ++styles ++class_names ++description ++variant ++title ++root_class_name ++FRONTEND_DIR ++skip_api ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +ModelScopeLayoutComponent <|-- AntdXWelcome +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) + +章节来源 + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:17-54](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L17-L54) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:57-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L57-L73) + +### Prompts 组件 API + +- 组件定位：AntdXPrompts +- 继承关系：ModelScopeLayoutComponent +- 内部项：AntdXPromptsItem（通过 Item 属性暴露） +- 插槽支持：title、items +- 关键参数 + - items：提示项列表（字典列表，具体字段由前端约定） + - prefix_cls：前缀类名（用于样式隔离） + - title：提示集合标题 + - vertical：是否垂直排列 + - fade_in/fade_in_left：淡入动画开关 + - wrap：是否换行 + - styles/class_names/root_class_name/additional_props：样式与扩展属性 + - 元素属性：elem_id、elem_classes、elem_style、visible、render 等 +- 事件 + - item_click：当某提示项被点击时触发回调，内部通过 \_internal.update(bind_itemClick_event=True) 配置前端事件绑定 +- 生命周期与预处理 + - preprocess/postprocess/example_payload/example_value 均返回空值，表明该组件不进行数据转换或示例值生成 + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__enter__() ++__exit__() ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdXPrompts { ++Item ++EVENTS ++SLOTS ++items ++prefix_cls ++title ++vertical ++fade_in ++fade_in_left ++wrap ++styles ++class_names ++root_class_name ++additional_props ++FRONTEND_DIR ++skip_api ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdXPromptsItem { ++... +} +ModelScopeLayoutComponent <|-- AntdXPrompts +AntdXPrompts o--> AntdXPromptsItem : "内部项" +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) + +章节来源 + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-23](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L23) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:28-68](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L28-L68) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:72-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L72-L88) + +### 使用示例与最佳实践 + +- AI 助手启动与欢迎页展示 + - 在应用启动时渲染 Welcome 组件，设置标题、描述与图标，必要时通过 extra 插槽添加引导按钮或操作区 + - 通过 variant 控制外观风格，通过 styles/class_names/root_class_name 实现主题适配 +- 用户引导与提示激活 + - 使用 Prompts 组件展示一组提示词卡片，设置 title 与 items，启用 fade_in/fade_in_left 增强视觉体验 + - 通过 item_click 事件监听用户选择，结合对话系统将选中提示注入到输入框或直接发起对话 +- 多语言支持 + - 标题、描述、提示文本应来自本地化资源；Welcome 与 Prompts 的文本参数均支持字符串类型，便于替换为不同语言版本 +- 状态同步与集成 + - 组件通过 Gradio BlockContext 参与布局更新；如需与对话系统联动，可在 item_click 回调中触发业务逻辑（例如将提示内容写入输入域或发起请求），并在前端完成状态渲染 + +章节来源 + +- [docs/components/antdx/welcome/app.py:1-7](file://docs/components/antdx/welcome/app.py#L1-L7) +- [docs/components/antdx/prompts/app.py:1-7](file://docs/components/antdx/prompts/app.py#L1-L7) + +## 依赖分析 + +- 组件导出 + - antdx/**init**.py 将 Welcome 与 Prompts 作为别名导出，便于外部按名称导入 + - antdx/components.py 聚合了各子模块，确保完整导入链路 +- 基类与工具 + - ModelScopeLayoutComponent 提供统一的布局组件能力与生命周期钩子 + - resolve_frontend_dir 将组件名映射到前端目录，支持子组件与多级目录拼接 + +```mermaid +graph LR +A["antdx/__init__.py"] --> B["Welcome 导出"] +A --> C["Prompts 导出"] +D["antdx/components.py"] --> E["聚合导入"] +E --> B +E --> C +F["utils/dev/component.py"] --> G["ModelScopeLayoutComponent"] +H["utils/dev/resolve_frontend_dir.py"] --> I["前端目录解析"] +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:24-39](file://backend/modelscope_studio/components/antdx/components.py#L24-L39) +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-16](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L16) + +章节来源 + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:24-39](file://backend/modelscope_studio/components/antdx/components.py#L24-L39) + +## 性能考虑 + +- 组件跳过 API：两个组件的 skip_api 均返回 True，意味着不会生成额外的 API 接口层，减少服务端开销 +- 预处理与后处理：preprocess/postprocess 返回空值，避免不必要的数据转换，有利于低延迟渲染 +- 动画与布局：Prompts 的淡入与换行选项仅影响前端渲染，建议在大量提示项时谨慎开启动画以平衡流畅度与性能 + +## 故障排查指南 + +- 组件未显示 + - 检查 visible 与 render 参数是否正确设置 + - 确认 elem_id/ elem_classes/ elem_style 是否导致样式覆盖 +- 图标或资源无法加载 + - 确认 icon 路径已通过静态文件服务处理（serve_static_file） +- 事件未触发 + - 确认 item_click 事件已在初始化时绑定（内部通过 \_internal.update(bind_itemClick_event=True) 触发） +- 前端目录解析失败 + - 检查 resolve_frontend_dir 的组件名与类型是否匹配实际前端目录结构 + +章节来源 + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:47-47](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L47-L47) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:20-22](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L20-L22) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-16](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L16) + +## 结论 + +AntdXWelcome 与 AntdXPrompts 通过统一的布局组件基类与前端目录解析机制，实现了与前端组件的无缝对接。Welcome 注重欢迎页的文案与样式配置，Prompts 则专注于提示集的展示与交互。二者均可通过 Gradio 的布局与事件机制与对话系统集成，实现从“欢迎引导”到“提示激活”的完整用户体验闭环。 + +## 附录 + +- 初始化参数速查 + - Welcome：extra、icon、description、title、variant、styles、class_names、root_class_name、elem_id、elem_classes、elem_style、visible、render + - Prompts：items、prefix_cls、title、vertical、fade_in、fade_in_left、wrap、styles、class_names、root_class_name、additional_props、elem_id、elem_classes、elem_style、visible、render +- 事件速查 + - Prompts：item_click（点击提示项时触发） diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\345\267\245\345\205\267\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\345\267\245\345\205\267\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..1db255f0 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\345\267\245\345\205\267\347\273\204\344\273\266 API.md" @@ -0,0 +1,399 @@ +# 工具组件 API + + +**本文档引用的文件** +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [code_highlighter/__init__.py](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py) +- [file_card/__init__.py](file://backend/modelscope_studio/components/antdx/file_card/__init__.py) +- [folder/__init__.py](file://backend/modelscope_studio/components/antdx/folder/__init__.py) +- [mermaid/__init__.py](file://backend/modelscope_studio/components/antdx/mermaid/__init__.py) +- [sources/__init__.py](file://backend/modelscope_studio/components/antdx/sources/__init__.py) +- [think/__init__.py](file://backend/modelscope_studio/components/antdx/think/__init__.py) +- [x_provider/__init__.py](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：使用示例与最佳实践](#附录使用示例与最佳实践) + +## 简介 + +本文件为 Antdx 工具组件的 Python API 参考文档，覆盖以下组件的完整 API 规范与使用说明： + +- CodeHighlighter：代码高亮显示 +- FileCard：文件卡片展示（含列表子组件） +- Folder：文件夹树形结构（含目录图标与树节点子组件） +- Mermaid：流程图绘制 +- Sources：源码引用管理（含条目子组件） +- Think：思维标注 +- XProvider：全局配置容器 + +文档从构造函数参数、属性定义、事件与插槽、数据处理与格式化选项、样式与类名定制、性能与渲染策略等方面进行系统梳理，并提供标准使用示例与扩展建议。 + +## 项目结构 + +Antdx 组件位于后端 Python 包中，通过统一的布局组件基类封装前端组件，导出别名便于直接使用。核心入口在 antdx 的 **init**.py 中，components.py 负责聚合导出。 + +```mermaid +graph TB +A["backend/modelscope_studio/components/antdx/components.py"] --> B["backend/modelscope_studio/components/antdx/__init__.py"] +B --> C1["CodeHighlighter"] +B --> C2["FileCard"] +B --> C3["Folder"] +B --> C4["Mermaid"] +B --> C5["Sources"] +B --> C6["Think"] +B --> C7["XProvider"] +``` + +图表来源 + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [**init**.py:14-41](file://backend/modelscope_studio/components/antdx/__init__.py#L14-L41) + +章节来源 + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [**init**.py:14-41](file://backend/modelscope_studio/components/antdx/__init__.py#L14-L41) + +## 核心组件 + +本节概述各组件的职责与通用特性： + +- 均继承自统一的布局组件基类，具备通用的可见性、元素 ID、类名、内联样式、渲染开关等属性。 +- 大多组件声明了支持的插槽（SLOTS）与事件（EVENTS），用于前端渲染与交互绑定。 +- 多数组件设置 skip_api 为真，表明其不参与标准 API 序列化，而是由前端直连渲染。 + +章节来源 + +- [code_highlighter/**init**.py:6-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L6-L71) +- [file_card/**init**.py:11-112](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L11-L112) +- [folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) +- [mermaid/**init**.py:8-77](file://backend/modelscope_studio/components/antdx/mermaid/__init__.py#L8-L77) +- [sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [x_provider/**init**.py:10-101](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L10-L101) + +## 架构总览 + +下图展示了 Python 层对前端组件的封装关系与导出路径： + +```mermaid +classDiagram +class AntdXCodeHighlighter { ++构造函数参数 : value, lang, header, highlight_props, prism_light_mode, styles, class_names, additional_props, root_class_name, as_item, visible, elem_id, elem_classes, elem_style, render ++属性 : SLOTS, EVENTS, skip_api ++方法 : preprocess(), postprocess(), example_payload(), example_value() +} +class AntdXFileCard { ++构造函数参数 : image_props, filename, byte, size, description, loading, type, src, mask, icon, video_props, audio_props, spin_props, styles, class_names, additional_props, as_item, visible, elem_id, elem_classes, elem_style, render ++属性 : SLOTS, EVENTS(List), skip_api ++方法 : preprocess(), postprocess(), example_payload(), example_value() +} +class AntdXFolder { ++构造函数参数 : tree_data, selectable, selected_file, default_selected_file, directory_tree_width, empty_render, preview_render, expanded_paths, default_expanded_paths, default_expand_all, directory_title, preview_title, directory_icons, styles, class_names, additional_props, as_item, visible, elem_id, elem_classes, elem_style, render ++属性 : SLOTS, EVENTS, TreeNode, DirectoryIcon, skip_api ++方法 : preprocess(), postprocess(), example_payload(), example_value() +} +class AntdXMermaid { ++构造函数参数 : value, highlight_props, config, actions, prefix_cls, styles, class_names, additional_props, root_class_name, as_item, visible, elem_id, elem_classes, elem_style, render ++属性 : SLOTS, EVENTS, skip_api ++方法 : preprocess(), postprocess(), example_payload(), example_value() +} +class AntdXSources { ++构造函数参数 : title, items, expand_icon_position, default_expanded, expanded, inline, active_key, popover_overlay_width, styles, class_names, additional_props, as_item, visible, elem_id, elem_classes, elem_style, render ++属性 : SLOTS, EVENTS(Item), skip_api ++方法 : preprocess(), postprocess(), example_payload(), example_value() +} +class AntdXThink { ++构造函数参数 : icon, styles, class_names, loading, title, root_class_name, default_expanded, expanded, blink, as_item, visible, elem_id, elem_classes, elem_style, render ++属性 : SLOTS, EVENTS, skip_api ++方法 : preprocess(), postprocess(), example_payload(), example_value() +} +class AntdXXProvider { ++构造函数参数 : component_disabled, component_size, csp, direction, get_popup_container, get_target_container, icon_prefix_cls, locale, popup_match_select_width, popup_overflow, prefix_cls, render_empty, theme, theme_config, variant, virtual, warning, styles, class_names, additional_props, as_item, visible, elem_id, elem_classes, elem_style, render ++属性 : SLOTS, EVENTS, skip_api ++方法 : preprocess(), postprocess(), example_payload(), example_value() +} +``` + +图表来源 + +- [code_highlighter/**init**.py:6-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L6-L71) +- [file_card/**init**.py:11-112](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L11-L112) +- [folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) +- [mermaid/**init**.py:8-77](file://backend/modelscope_studio/components/antdx/mermaid/__init__.py#L8-L77) +- [sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [x_provider/**init**.py:10-101](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L10-L101) + +## 详细组件分析 + +### CodeHighlighter（代码高亮） + +- 组件定位：用于高亮显示代码片段，支持语言与主题模式等配置。 +- 关键参数 + - value：要高亮的代码字符串 + - lang：语言标识 + - header：标题或布尔控制 + - highlight_props：高亮相关配置 + - prism_light_mode：浅色模式开关 + - styles/class_names/additional_props/root_class_name/as_item：样式与类名、附加属性、根类名、作为子项 + - visible/elem_id/elem_classes/elem_style/render：通用布局属性 +- 插槽：header +- 事件：无 +- 数据处理：skip_api 为真，不参与标准 API；preprocess/postprocess 返回原值 +- 性能：前端直连渲染，避免额外序列化开销 + +章节来源 + +- [code_highlighter/**init**.py:6-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L6-L71) + +### FileCard（文件卡片） + +- 组件定位：展示文件信息，支持图片、音频、视频、普通文件等多种类型，可配置尺寸、加载状态、遮罩与媒体属性。 +- 关键参数 + - image_props：图片预览相关属性 + - filename：文件名 + - byte：字节数 + - size：尺寸 small/default + - description：描述文本 + - loading：是否显示加载态 + - type：类型 image/file/audio/video 或自定义字符串 + - src：资源地址（支持字符串或包含 path/url 的字典） + - mask：遮罩文本 + - icon：内置图标类别或自定义字符串 + - video_props/audio_props/spin_props：视频/音频/加载指示器配置 + - styles/class_names/additional_props/as_item/visible/elem_id/elem_classes/elem_style/render：通用布局属性 +- 插槽：imageProps.placeholder、imageProps.preview.mask、imageProps.preview.closeIcon、imageProps.preview.toolbarRender、imageProps.preview.imageRender、description、icon、mask、spinProps.icon、spinProps.description、spinProps.indicator +- 事件：click（绑定内部事件） +- 数据处理：skip_api 为真；preprocess/postprocess 返回原值；src 支持静态文件服务包装 +- 性能：前端直连渲染；src 字段自动处理静态资源路径 + +章节来源 + +- [file_card/**init**.py:11-112](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L11-L112) + +### Folder（文件夹树形结构） + +- 组件定位：展示文件夹树与选择/展开行为，支持预览渲染、空态渲染、目录图标等。 +- 关键参数 + - tree_data：树形数据 + - selectable：是否可选择 + - selected_file/default_selected_file：选中文件列表 + - directory_tree_width：目录树宽度 + - empty_render/preview_render：空态与预览渲染 + - expanded_paths/default_expanded_paths/default_expand_all：展开路径控制 + - directory_title/preview_title：标题 + - directory_icons：目录图标映射 + - styles/class_names/additional_props/root_class_name/as_item/visible/elem_id/elem_classes/elem_style/render：通用布局属性 +- 子组件：TreeNode、DirectoryIcon +- 插槽：emptyRender、previewRender、directoryTitle、previewTitle、treeData、directoryIcons +- 事件：file_click、folder_click、selected_file_change、expanded_paths_change、file_content_service_load_file_content（绑定到内部事件） +- 数据处理：skip_api 为真；preprocess/postprocess 返回原值 +- 性能：前端直连渲染；支持默认展开全部 + +章节来源 + +- [folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) + +### Mermaid（流程图绘制） + +- 组件定位：基于 Mermaid 语法绘制流程图，支持高亮配置、主题配置与自定义操作。 +- 关键参数 + - value：Mermaid 文本 + - highlight_props：高亮配置 + - config：全局配置 + - actions：自定义动作 + - prefix_cls：前缀类名 + - styles/class_names/additional_props/root_class_name/as_item/visible/elem_id/elem_classes/elem_style/render：通用布局属性 +- 插槽：header、actions.customActions +- 事件：render_type_change（绑定到内部事件） +- 数据处理：skip_api 为真；preprocess/postprocess 返回原值 +- 性能：前端直连渲染 + +章节来源 + +- [mermaid/**init**.py:8-77](file://backend/modelscope_studio/components/antdx/mermaid/__init__.py#L8-L77) + +### Sources（源码引用管理） + +- 组件定位：以折叠面板形式管理源码引用条目，支持展开位置、激活键、弹出层宽度等。 +- 关键参数 + - title：标题 + - items：条目列表 + - expand_icon_position：展开图标位置 start/end + - default_expanded/expanded：默认/当前展开状态 + - inline：是否内联 + - active_key：激活键 + - popover_overlay_width：弹出层宽度 + - styles/class_names/additional_props/root_class_name/as_item/visible/elem_id/elem_classes/elem_style/render：通用布局属性 +- 子组件：Item +- 插槽：items +- 事件：expand、click（绑定到内部事件） +- 数据处理：skip_api 为真；preprocess/postprocess 返回原值 +- 性能：前端直连渲染 + +章节来源 + +- [sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) + +### Think（思维标注） + +- 组件定位：用于展示思维过程或提示信息，支持加载态、标题、闪烁等。 +- 关键参数 + - icon：图标 + - styles/class_names/additional_props/root_class_name/as_item/visible/elem_id/elem_classes/elem_style/render：通用布局属性 + - loading：加载态（字符串或布尔） + - title：标题 + - default_expanded/expanded：默认/当前展开状态 + - blink：闪烁开关 +- 插槽：loading、icon、title +- 事件：expand（绑定到内部事件） +- 数据处理：skip_api 为真；preprocess/postprocess 返回原值 +- 性能：前端直连渲染 + +章节来源 + +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) + +### XProvider（全局配置） + +- 组件定位：全局配置容器，传递主题、语言、方向、变体等配置至子组件树。 +- 关键参数 + - component_disabled：禁用组件 + - component_size：组件尺寸 small/middle/large + - csp：内容安全策略 + - direction：方向 ltr/rtl + - get_popup_container/get_target_container：弹窗容器选择器 + - icon_prefix_cls：图标前缀类名 + - locale：语言环境 + - popup_match_select_width：弹窗匹配选择宽度 + - popup_overflow：弹窗溢出策略 viewport/scroll + - prefix_cls：组件前缀类名 + - render_empty：空状态渲染 + - theme/theme_config：主题与主题配置（存在冲突警告） + - variant：外观 outlined/filled/borderless + - virtual：虚拟化 + - warning：警告配置 + - styles/class_names/additional_props/as_item/visible/elem_id/elem_classes/elem_style/render：通用布局属性 +- 插槽：renderEmpty +- 事件：无 +- 数据处理：skip_api 为真；preprocess/postprocess 返回原值 +- 性能：前端直连渲染；注意 theme 与 theme_config 冲突提示 + +章节来源 + +- [x_provider/**init**.py:10-101](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L10-L101) + +## 依赖关系分析 + +- 导出关系：components.py 聚合导入 antdx 下各组件模块；**init**.py 将组件类导出为易用别名。 +- 组件间关系：部分组件提供子组件（如 FileCard.List、Folder.TreeNode/Folder.DirectoryIcon、Sources.Item、Think 等），用于组合复杂 UI。 +- 事件绑定：多数组件通过事件监听器回调更新内部状态标志位，从而触发前端事件绑定。 + +```mermaid +graph LR +subgraph "导出层" +E1["components.py"] --> E2["__init__.py"] +end +subgraph "组件层" +F1["code_highlighter/__init__.py"] +F2["file_card/__init__.py"] +F3["folder/__init__.py"] +F4["mermaid/__init__.py"] +F5["sources/__init__.py"] +F6["think/__init__.py"] +F7["x_provider/__init__.py"] +end +E2 --> F1 +E2 --> F2 +E2 --> F3 +E2 --> F4 +E2 --> F5 +E2 --> F6 +E2 --> F7 +``` + +图表来源 + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [**init**.py:14-41](file://backend/modelscope_studio/components/antdx/__init__.py#L14-L41) + +章节来源 + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [**init**.py:14-41](file://backend/modelscope_studio/components/antdx/__init__.py#L14-L41) + +## 性能考虑 + +- 跳过 API 序列化：所有组件均设置 skip_api 为真，避免不必要的 Python 到前端数据往返，提升渲染效率。 +- 前端直连：组件通过 resolve_frontend_dir 指向前端组件目录，减少中间层转换成本。 +- 静态资源：FileCard 对 src 进行静态文件服务包装，降低资源访问延迟。 +- 默认展开：Folder 支持 default_expand_all，可在初始化时一次性展开，减少用户交互次数。 +- 主题与变体：XProvider 提供统一主题与外观配置，避免重复计算与样式切换开销。 + +## 故障排查指南 + +- 组件未生效 + - 检查 visible、render 是否为真 + - 确认 elem_id/elem_classes/elem_style 是否正确传入 +- 文件资源无法加载 + - FileCard 的 src 为字典时需确保包含 path 或 url；必要时使用静态文件服务包装 +- 事件未触发 + - 确认事件监听器名称与组件 EVENTS 定义一致 + - 检查前端是否正确绑定内部事件标志位 +- 主题冲突 + - XProvider 中 theme 与 Gradio 预设属性冲突，应使用 theme_config 替代 +- 渲染异常 + - Mermaid/CodeHighlighter/Sources/Think 的插槽内容需按规范提供，避免前端解析错误 + +章节来源 + +- [file_card/**init**.py:87-93](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L87-L93) +- [x_provider/**init**.py:74-78](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L74-L78) + +## 结论 + +Antdx 工具组件通过统一的布局组件基类与前端直连渲染策略，提供了简洁而强大的 Python API。各组件围绕“参数驱动 + 插槽 + 事件绑定”的模式组织，既满足常见场景（代码高亮、文件展示、树形导航、流程图、源码引用、思维标注、全局配置），又为扩展与定制留足空间。建议在实际项目中优先使用组件提供的子组件与插槽，配合 XProvider 进行全局样式与主题管理，并遵循静态资源与事件绑定的最佳实践。 + +## 附录：使用示例与最佳实践 + +- 代码高亮 + - 场景：在对话或文档中展示代码片段 + - 建议：指定 lang 与 highlight_props；必要时开启 prism_light_mode + - 参考路径：[code_highlighter/**init**.py:15-52](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L15-L52) +- 文件卡片 + - 场景：上传或浏览文件列表 + - 建议：根据 type 设置 icon；src 使用静态文件服务包装；合理设置 size 与 loading + - 参考路径：[file_card/**init**.py:32-94](file://backend/modelscope_studio/components/antdx/file_card/__init__.py#L32-L94) +- 文件夹树 + - 场景：文件浏览与选择 + - 建议：tree_data 结构清晰；default_expand_all 仅在数据量可控时启用；使用 directory_icons 自定义图标 + - 参考路径：[folder/**init**.py:43-96](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L43-L96) +- 流程图 + - 场景：可视化算法或业务流程 + - 建议：value 使用标准 Mermaid 语法；config 与 actions 按需配置 + - 参考路径：[mermaid/**init**.py:21-58](file://backend/modelscope_studio/components/antdx/mermaid/__init__.py#L21-L58) +- 源码引用 + - 场景：展示引用来源与条目 + - 建议：items 结构标准化；inline 与 expand_icon_position 按界面风格选择 + - 参考路径：[sources/**init**.py:30-73](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L30-L73) +- 思维标注 + - 场景：提示用户关注要点或加载状态 + - 建议：title 与 icon 明确表达意图；blink 仅在强调时使用 + - 参考路径：[think/**init**.py:21-60](file://backend/modelscope_studio/components/antdx/think/__init__.py#L21-L60) +- 全局配置 + - 场景：统一主题、语言、方向与外观 + - 建议：优先使用 theme_config；locale 与 direction 按地区配置；prefix_cls 与 icon_prefix_cls 保持一致性 + - 参考路径：[x_provider/**init**.py:19-82](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L19-L82) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\347\241\256\350\256\244\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\347\241\256\350\256\244\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..bfe1a97f --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\347\241\256\350\256\244\347\273\204\344\273\266 API.md" @@ -0,0 +1,366 @@ +# 确认组件 API + + +**本文引用的文件** +- [backend/modelscope_studio/components/antdx/thought_chain/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py) +- [backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py) +- [frontend/antdx/thought-chain/thought-chain.tsx](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [frontend/antdx/thought-chain/item/thought-chain.item.tsx](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx) +- [frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [docs/components/antdx/thought_chain/demos/basic.py](file://docs/components/antdx/thought_chain/demos/basic.py) +- [docs/components/antdx/thought_chain/demos/item_status.py](file://docs/components/antdx/thought_chain/demos/item_status.py) +- [docs/components/antdx/thought_chain/demos/nested_use.py](file://docs/components/antdx/thought_chain/demos/nested_use.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 Antdx 确认组件（AntdX）的 Python API 参考文档，聚焦 ThoughtChain 思考链组件的思考链管理、决策过程跟踪与状态可视化能力。重点覆盖以下方面： + +- ThoughtChain 与 ThoughtChainItem 的层级结构管理与节点状态控制 +- 链式操作处理与节点连接关系 +- 数据结构定义、状态变更监听与结果输出机制 +- 面向 AI 决策过程展示、思维链分析、操作确认等场景的标准使用示例 +- 组件状态管理策略、事件传播机制与性能监控配置 +- 与聊天机器人（Chatbot）的集成方式与推理过程可视化展示 + +## 项目结构 + +Antdx 的 ThoughtChain 相关实现由后端 Python 组件与前端 Svelte/React 包装层共同构成： + +- 后端 Python 组件：封装 Gradio 布局组件，负责属性透传与前端资源定位 +- 前端包装层：将 Ant Design X 的 ThoughtChain 与 ThoughtChain.Item 组件桥接至 Gradio 生态，支持插槽渲染与上下文注入 + +```mermaid +graph TB +subgraph "后端 Python 组件" +A["AntdXThoughtChain
__init__.py"] +B["AntdXThoughtChainItem
item/__init__.py"] +C["AntdXThoughtChainThoughtChainItem
thought_chain_item/__init__.py"] +end +subgraph "前端包装层" +D["thought-chain/thought-chain.tsx"] +E["thought-chain/item/thought-chain.item.tsx"] +F["thought-chain-item/thought-chain.thought-chain-item.tsx"] +end +A --> D +B --> E +C --> F +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [backend/modelscope_studio/components/antdx/thought_chain/item/**init**.py:8-78](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L8-L78) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L8-L81) +- [frontend/antdx/thought-chain/thought-chain.tsx:11-42](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L42) +- [frontend/antdx/thought-chain/item/thought-chain.item.tsx:9-32](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L9-L32) +- [frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx:7-13](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L7-L13) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [frontend/antdx/thought-chain/thought-chain.tsx:11-42](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L42) + +## 核心组件 + +- AntdXThoughtChain：思考链容器，支持展开键、线条样式、前缀类名等属性；通过事件监听“expand”实现展开键变更回调；支持插槽“items” +- AntdXThoughtChainItem：顶层节点，支持标题、描述、图标、状态、变体、闪烁等属性；支持“description”、“icon”、“title”插槽 +- AntdXThoughtChainThoughtChainItem：嵌套节点，支持内容、额外信息、页脚、图标、标题、状态、可折叠、闪烁等属性；支持“content”、“description”、“footer”、“icon”、“title”插槽 + +以上组件均继承自 ModelScopeLayoutComponent，具备 Gradio 布局组件通用特性，并通过 resolve_frontend_dir 指定前端目录。 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [backend/modelscope_studio/components/antdx/thought_chain/item/**init**.py:8-78](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L8-L78) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L8-L81) + +## 架构总览 + +下图展示了从 Python 调用到前端渲染的完整链路，以及插槽与上下文的作用位置： + +```mermaid +sequenceDiagram +participant Py as "Python 组件
AntdXThoughtChain/AntdXThoughtChainItem" +participant Wrap as "前端包装层
thought-chain.tsx / item/thought-chain.item.tsx" +participant ADX as "Ant Design X
@ant-design/x" +participant Slot as "插槽系统
ReactSlot / renderItems" +Py->>Wrap : 传递属性与可见性 +Wrap->>ADX : 渲染 ThoughtChain/Item +Wrap->>Slot : 解析并渲染插槽内容 +ADX-->>Wrap : 渲染结果 +Wrap-->>Py : 返回值/占位渲染 +``` + +**图表来源** + +- [frontend/antdx/thought-chain/thought-chain.tsx:11-42](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L42) +- [frontend/antdx/thought-chain/item/thought-chain.item.tsx:9-32](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L9-L32) +- [frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx:7-13](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L7-L13) + +## 详细组件分析 + +### AntdXThoughtChain（思考链容器） + +- 角色与职责 + - 容器化展示多个思考链节点 + - 支持展开键控制、默认展开键、线条样式、前缀类名等外观与交互参数 + - 事件：expand（展开键变更时触发） + - 插槽：items（用于批量注入节点） +- 关键属性 + - expanded_keys：当前展开的节点键列表 + - default_expanded_keys：初始默认展开键列表 + - items：节点数据数组（可选） + - line：连线样式（布尔或特定字符串） + - prefix_cls：前缀类名 + - styles/class_names/root_class_name：样式与类名扩展 +- 处理流程 + - 前端通过上下文解析插槽 items 或直接传入 items + - 使用 renderItems 将插槽节点克隆为 React 结构 + - 渲染 @ant-design/x 的 ThoughtChain 组件 + +```mermaid +flowchart TD +Start(["进入 AntdXThoughtChain"]) --> CheckItems["检查是否传入 items"] +CheckItems --> |是| UsePassed["使用传入 items"] +CheckItems --> |否| ResolveSlot["解析插槽 items/default"] +ResolveSlot --> RenderItems["调用 renderItems 克隆节点"] +UsePassed --> RenderItems +RenderItems --> RenderADX["渲染 @ant-design/x ThoughtChain"] +RenderADX --> End(["完成"]) +``` + +**图表来源** + +- [frontend/antdx/thought-chain/thought-chain.tsx:14-39](file://frontend/antdx/thought-chain/thought-chain.tsx#L14-L39) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [frontend/antdx/thought-chain/thought-chain.tsx:11-42](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L42) + +### AntdXThoughtChainItem（顶层节点） + +- 角色与职责 + - 表示思考链中的一个顶层节点 + - 支持标题、描述、图标、状态、变体、闪烁等属性 + - 支持“description”、“icon”、“title”插槽，用于自定义渲染 +- 关键属性 + - title/description/icon：节点标题、描述、图标 + - status：节点状态（待定/成功/错误/中止） + - variant：节点外观变体（实心/描边/文本） + - blink：是否闪烁提示 + - prefix_cls/class_names/styles：样式与类名扩展 +- 插槽 + - description/title/icon：分别替换对应区域的内容 + +```mermaid +classDiagram +class AntdXThoughtChainItem { ++title : str|None ++description : str|None ++icon : str|None ++status : enum ++variant : enum ++blink : bool|None ++prefix_cls : str|None ++class_names : dict|str|None ++styles : dict|str|None +} +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/item/**init**.py:18-58](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L18-L58) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/item/**init**.py:8-78](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L8-L78) +- [frontend/antdx/thought-chain/item/thought-chain.item.tsx:9-32](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L9-L32) + +### AntdXThoughtChainThoughtChainItem（嵌套节点） + +- 角色与职责 + - 表示在 ThoughtChain 内部使用的嵌套节点 + - 支持内容、额外信息、页脚、图标、标题、状态、可折叠、闪烁等属性 + - 支持“content”、“description”、“footer”、“icon”、“title”插槽 +- 关键属性 + - key：节点唯一标识 + - title/description/content/extra/footer/icon：节点各区域内容 + - status：节点状态 + - collapsible：是否可折叠 + - blink：是否闪烁提示 +- 插槽 + - content/description/footer/icon/title：分别替换对应区域的内容 + +```mermaid +classDiagram +class AntdXThoughtChainThoughtChainItem { ++key : str|None ++title : str|None ++description : str|None ++content : str|None ++extra : str|None ++footer : str|None ++icon : str|None ++status : enum ++collapsible : bool|None ++blink : bool|None +} +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:18-60](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L18-L60) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L8-L81) +- [frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx:7-13](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L7-L13) + +### 数据结构与节点连接关系 + +- 节点数据结构 + - items 数组：每个元素对应一个 ThoughtChainItem 或 ThoughtChainThoughtChainItem + - 字段包括但不限于：title、description、content、icon、status、key、collapsible 等 +- 连接关系 + - AntdXThoughtChain 作为根容器，内部可嵌套多个 ThoughtChainItem + - 每个 ThoughtChainItem 的 content 插槽内可再次嵌套 ThoughtChain，形成多级嵌套 +- 状态变更与监听 + - expand 事件：当展开键发生变化时触发，可用于动态更新 UI 或日志记录 + - status 属性：用于直观反映节点执行状态（成功/失败/进行中/中止） + +**章节来源** + +- [frontend/antdx/thought-chain/thought-chain.tsx:14-39](file://frontend/antdx/thought-chain/thought-chain.tsx#L14-L39) +- [docs/components/antdx/thought_chain/demos/nested_use.py:10-64](file://docs/components/antdx/thought_chain/demos/nested_use.py#L10-L64) +- [docs/components/antdx/thought_chain/demos/item_status.py:9-33](file://docs/components/antdx/thought_chain/demos/item_status.py#L9-L33) + +### 状态管理策略与事件传播 + +- 状态管理 + - 通过 status 属性驱动 UI 状态变化（如颜色、图标、闪烁） + - 通过 expanded_keys/default_expanded_keys 控制节点展开/收起 +- 事件传播 + - expand 事件在容器层监听，回调中可设置 bind_expand_event 以启用事件绑定 + - 事件回调通常用于联动更新其他组件或记录日志 +- 结果输出机制 + - 组件本身不直接产生输出值；可通过外部逻辑（如按钮点击）配合 Gradio 更新 ThoughtChain 的 items 或状态 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:20-25](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L20-L25) + +### 性能监控配置 + +- 建议实践 + - 对于大量节点的场景，优先使用 items 参数一次性传入，减少插槽解析开销 + - 合理使用 expanded_keys/default_expanded_keys，避免一次性渲染过多节点 + - 在需要频繁更新状态时，尽量批量更新 items，减少多次重渲染 +- 监控指标 + - 页面渲染耗时、节点数量、展开/收起频率、状态切换次数 + +[本节为通用建议，无需特定文件引用] + +## 依赖分析 + +- 组件导出与聚合 + - antdx 组件模块统一导出 ThoughtChain 及其子项，便于在业务代码中按需导入 +- 前端依赖 + - @ant-design/x 提供核心渲染能力 + - sveltify 将 Svelte 组件桥接到 React/Gradio + - renderItems 用于插槽节点的克隆与渲染 + +```mermaid +graph LR +Export["antdx/components.py 导出"] --> A["AntdXThoughtChain"] +Export --> B["AntdXThoughtChainItem"] +Export --> C["AntdXThoughtChainThoughtChainItem"] +A --> D["thought-chain/thought-chain.tsx"] +B --> E["thought-chain/item/thought-chain.item.tsx"] +C --> F["thought-chain-item/thought-chain.thought-chain-item.tsx"] +D --> ADX["@ant-design/x"] +E --> ADX +F --> ADX +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/components.py:35-40](file://backend/modelscope_studio/components/antdx/components.py#L35-L40) +- [frontend/antdx/thought-chain/thought-chain.tsx:3-6](file://frontend/antdx/thought-chain/thought-chain.tsx#L3-L6) +- [frontend/antdx/thought-chain/item/thought-chain.item.tsx:4-7](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L4-L7) +- [frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx:3-5](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L3-L5) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/components.py:35-40](file://backend/modelscope_studio/components/antdx/components.py#L35-L40) + +## 性能考虑 + +- 渲染优化 + - 使用 items 参数而非大量插槽，降低前端解析成本 + - 对于长列表，建议分页或懒加载 +- 状态更新 + - 批量更新 items，避免逐项频繁变更 + - 合理使用 expand 事件，避免过度响应导致的重绘 +- 样式与类名 + - 通过 styles/class_names/root_class_name 精准控制样式，避免全局污染 + +[本节为通用建议，无需特定文件引用] + +## 故障排查指南 + +- 常见问题 + - 插槽未生效：确认插槽名称正确且与组件支持的插槽一致 + - 状态不更新：检查是否正确设置 status 并确保外部逻辑触发了 Gradio 更新 + - 展开键无效：确认 expand 事件已绑定且 expanded_keys/default_expanded_keys 设置合理 +- 排查步骤 + - 使用最小化示例验证组件行为 + - 逐步添加插槽与状态，定位问题范围 + - 查看浏览器控制台与网络面板，确认前端资源加载正常 + +**章节来源** + +- [docs/components/antdx/thought_chain/demos/basic.py:31-74](file://docs/components/antdx/thought_chain/demos/basic.py#L31-L74) +- [docs/components/antdx/thought_chain/demos/item_status.py:9-33](file://docs/components/antdx/thought_chain/demos/item_status.py#L9-L33) + +## 结论 + +Antdx 的 ThoughtChain 组件通过清晰的层级结构与丰富的状态控制，为 AI 决策过程展示、思维链分析与操作确认提供了可靠的可视化基础。结合插槽系统与事件机制，可在复杂场景中灵活扩展与定制。建议在大规模数据场景中采用 items 传参与批量更新策略，以获得更佳的性能表现。 + +[本节为总结性内容，无需特定文件引用] + +## 附录 + +### 标准使用示例（路径） + +- 基础用法：展示多个 ThoughtChainItem 并配置状态与插槽 + - [docs/components/antdx/thought_chain/demos/basic.py:31-74](file://docs/components/antdx/thought_chain/demos/basic.py#L31-L74) +- 状态切换演示：通过按钮驱动节点状态变化 + - [docs/components/antdx/thought_chain/demos/item_status.py:46-67](file://docs/components/antdx/thought_chain/demos/item_status.py#L46-L67) +- 嵌套使用：在节点内容中再次嵌套 ThoughtChain + - [docs/components/antdx/thought_chain/demos/nested_use.py:19-64](file://docs/components/antdx/thought_chain/demos/nested_use.py#L19-L64) + +### API 参考速览（路径） + +- 容器组件：AntdXThoughtChain + - [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:30-68](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L30-L68) +- 顶层节点：AntdXThoughtChainItem + - [backend/modelscope_studio/components/antdx/thought_chain/item/**init**.py:18-60](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L18-L60) +- 嵌套节点：AntdXThoughtChainThoughtChainItem + - [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:18-63](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L18-L63) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\350\241\250\350\276\276\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\350\241\250\350\276\276\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..3339a9c5 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\350\241\250\350\276\276\347\273\204\344\273\266 API.md" @@ -0,0 +1,359 @@ +# 表达组件 API + + +**本文引用的文件** +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/antdx/attachments/__init__.py](file://backend/modelscope_studio/components/antdx/attachments/__init__.py) +- [backend/modelscope_studio/components/antdx/sender/__init__.py](file://backend/modelscope_studio/components/antdx/sender/__init__.py) +- [backend/modelscope_studio/components/antdx/sender/header/__init__.py](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py) +- [backend/modelscope_studio/components/antdx/sender/switch/__init__.py](file://backend/modelscope_studio/components/antdx/sender/switch/__init__.py) +- [backend/modelscope_studio/components/antdx/suggestion/__init__.py](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py) +- [backend/modelscope_studio/components/antdx/suggestion/item/__init__.py](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：使用示例与最佳实践](#附录使用示例与最佳实践) + +## 简介 + +本文件为 Antdx 表达组件的 Python API 参考文档，聚焦以下能力： + +- 文件附件处理：上传、拖拽、下载、预览、移除、类型限制与列表展示策略 +- 输入与发送控制：文本输入框管理、提交类型（回车/Shift+回车）、粘贴与键盘事件、语音输入开关 +- 多模态输入支持：通过 Sender 的子组件扩展头区、开关与技能面板 +- 快捷指令：Suggestion 组件及其项的触发、选择与面板状态管理 +- 与聊天机器人的集成：基于 Gradio 数据类与事件回调的数据流与交互协议 + +## 项目结构 + +Antdx 组件位于后端 Python 包中，通过统一入口导出，并在前端以对应目录映射到 Svelte 实现。表达组件相关模块组织如下： + +- 顶层导出：antdx/**init**.py 与 antdx/components.py 提供组件聚合导出 +- 附件：antdx/attachments +- 发送器：antdx/sender（含 header、switch 子组件） +- 建议：antdx/suggestion（含 item 子组件） + +```mermaid +graph TB +subgraph "Python 后端" +A["antdx/__init__.py"] +B["antdx/components.py"] +C["attachments/__init__.py"] +D["sender/__init__.py"] +E["sender/header/__init__.py"] +F["sender/switch/__init__.py"] +G["suggestion/__init__.py"] +H["suggestion/item/__init__.py"] +end +A --> C +A --> D +A --> E +A --> F +A --> G +A --> H +B --> C +B --> D +B --> E +B --> F +B --> G +B --> H +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +章节来源 + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## 核心组件 + +- AntdXAttachments：文件附件上传与管理，支持拖拽、预览、下载、移除、类型过滤、列表样式与占位图等 +- AntdXSender：输入与发送控制，支持自动高度、只读、加载态、占位符、提交类型、语音输入、粘贴文件、键盘事件等 +- AntdXSenderHeader：Sender 头部区域，支持展开/收起、标题、可关闭等 +- AntdXSenderSwitch：Sender 内置开关，支持选中/未选中文案与图标 +- AntdXSuggestion：快捷指令建议面板，支持 items 列表、打开状态、选择事件 +- AntdXSuggestionItem：建议项，支持标签、图标、额外内容等插槽 + +章节来源 + +- [backend/modelscope_studio/components/antdx/attachments/**init**.py:22-227](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L22-L227) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:14-149](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L14-L149) +- [backend/modelscope_studio/components/antdx/sender/header/**init**.py:8-74](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py#L8-L74) +- [backend/modelscope_studio/components/antdx/sender/switch/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/sender/switch/__init__.py#L8-L81) +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/suggestion/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py#L8-L68) + +## 架构总览 + +表达组件的前后端交互遵循 Gradio 数据类与事件模型： + +- 后端组件定义数据模型（如 ListFiles）与事件监听器 +- 前端根据 FRONTEND_DIR 映射到对应 Svelte 组件 +- 通过 preprocess/postprocess 在 Python 与前端之间转换数据格式 +- 事件回调通过 \_internal.update 绑定前端事件 + +```mermaid +sequenceDiagram +participant U as "用户" +participant FE as "前端组件(Svelte)" +participant PY as "后端组件(Python)" +participant GR as "Gradio 数据类" +U->>FE : 触发事件(输入/粘贴/拖拽/点击) +FE->>PY : 事件回调绑定(_internal.update) +PY->>GR : preprocess(payload) 转换为内部值 +GR-->>PY : 返回处理后的值 +PY-->>FE : postprocess(value) 返回前端显示值 +FE-->>U : 更新UI(列表/预览/状态) +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/attachments/**init**.py:168-207](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L168-L207) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:134-142](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L134-L142) + +## 组件详解 + +### 附件组件 AntdXAttachments + +- 功能要点 + - 支持文件上传、拖拽上传、批量选择、最大数量限制 + - 支持文件类型过滤（accept）、HTTP 请求参数（headers、data、method） + - 支持自定义上传请求（custom_request）、前置钩子（before_upload） + - 列表样式与溢出策略（list_type、overflow），默认显示上传列表 + - 占位图与图片预览增强（placeholder、imageProps.\*） + - 事件：change、drop、download、preview、remove + - 插槽：showUploadList._、iconRender、itemRender、placeholder._、imageProps.\* 等 +- 数据流 + - preprocess：将前端传入的 ListFiles 转为本地路径字符串列表 + - postprocess：将本地路径/URL 下载至缓存并封装为 ListFiles 返回前端 +- 文件处理策略 + - 远程 URL：下载到缓存目录 + - 本地路径：直接返回 + - 预览：使用 Gradio FileData 元信息（orig_name、size） + +```mermaid +flowchart TD +Start(["进入 preprocess"]) --> CheckNull{"payload 是否为空?"} +CheckNull --> |是| ReturnNone["返回 None"] +CheckNull --> |否| Loop["遍历每个 FileData"] +Loop --> Process["_process_single_file
生成临时文件名"] +Process --> Append["收集字符串路径"] +Append --> DonePre["返回字符串列表"] +subgraph "postprocess" +PStart["接收字符串列表"] --> PNull{"是否为空?"} +PNull --> |是| PEmpty["返回空列表"] +PNull --> |否| PLoop["遍历路径"] +PLoop --> PType{"是否为 URL?"} +PType --> |是| PDownload["下载到缓存"] +PType --> |否| PUse["直接使用"] +PDownload --> PBuild["构建 FileData(orig_name,size)"] +PUse --> PBuild +PBuild --> PEnd["返回 ListFiles"] +end +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/attachments/**init**.py:162-207](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L162-L207) + +章节来源 + +- [backend/modelscope_studio/components/antdx/attachments/**init**.py:22-227](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L22-L227) + +### 发送器组件 AntdXSender + +- 功能要点 + - 输入框管理：auto_size、placeholder、disabled、read_only、loading + - 提交控制：submit_type（enter 或 shiftEnter） + - 事件：change、submit、cancel、allow_speech_recording_change、key_down/key_press、focus/blur、paste/paste_file、skill_closable_close + - 插槽：suffix、header、prefix、footer、skill.\* 等 + - 子组件：Header、Switch（用于扩展头区与开关） +- 数据流 + - preprocess/postprocess：透传字符串值 +- 多模态输入支持 + - allow_speech：启用语音输入（可为布尔或字典） + - paste_file：粘贴文件事件 + - skill.\*：技能面板的标题、提示与可关闭图标 + +```mermaid +sequenceDiagram +participant U as "用户" +participant FE as "Sender 前端" +participant PY as "AntdXSender" +U->>FE : 输入/按键/粘贴/点击发送 +FE->>PY : 事件回调(如 change/submit/paste_file) +PY-->>FE : 根据 submit_type 控制提交行为 +FE-->>U : 更新状态(loading/disabled) +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/sender/**init**.py:21-59](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L21-L59) + +章节来源 + +- [backend/modelscope_studio/components/antdx/sender/**init**.py:14-149](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L14-L149) + +### 发送器头部 AntdXSenderHeader + +- 功能要点 + - 展开/收起：open、closable + - 标题：title + - 插槽：title +- 用途 + - 作为 Sender 的子组件，用于承载头部标题与可关闭按钮 + +章节来源 + +- [backend/modelscope_studio/components/antdx/sender/header/**init**.py:8-74](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py#L8-L74) + +### 发送器开关 AntdXSenderSwitch + +- 功能要点 + - 值：value（bool） + - 文案与图标：checked_children、un_checked_children、icon + - 状态：disabled、loading + - 插槽：checkedChildren、unCheckedChildren、icon +- 用途 + - 作为 Sender 的子组件，用于切换某些发送行为或模式 + +章节来源 + +- [backend/modelscope_studio/components/antdx/sender/switch/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/sender/switch/__init__.py#L8-L81) + +### 建议组件 AntdXSuggestion 与项 AntdXSuggestionItem + +- 建议面板 + - items：建议项列表（字符串或字典） + - 打开状态：open、block、should_trigger + - 事件：select、open_change + - 插槽：items、children +- 建议项 + - label、icon、extra、key + - 插槽：label、icon、extra + +```mermaid +classDiagram +class AntdXSuggestion { ++items ++open ++block ++should_trigger ++EVENTS ++SLOTS +} +class AntdXSuggestionItem { ++value ++label ++icon ++extra ++key ++EVENTS ++SLOTS +} +AntdXSuggestion --> AntdXSuggestionItem : "包含多个项" +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/suggestion/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py#L8-L68) + +章节来源 + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/suggestion/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py#L8-L68) + +## 依赖关系分析 + +- 组件聚合 + - antdx/**init**.py 与 antdx/components.py 将各子组件统一导出，便于上层应用按需导入 +- 组件内聚 + - 每个组件独立定义 EVENTS、SLOTS、FRONTEND_DIR，职责清晰 +- 事件耦合 + - 通过 EventListener 与 \_internal.update 将前端事件映射到后端回调 +- 数据类依赖 + - 附件组件使用 Gradio ListFiles 与 FileData，确保跨端数据一致性 + +```mermaid +graph LR +A["antdx/__init__.py"] --> C["attachments/__init__.py"] +A --> D["sender/__init__.py"] +D --> E["sender/header/__init__.py"] +D --> F["sender/switch/__init__.py"] +A --> G["suggestion/__init__.py"] +G --> H["suggestion/item/__init__.py"] +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +章节来源 + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## 性能考量 + +- 文件处理 + - 远程 URL 下载应结合缓存目录与异步策略，避免阻塞主线程 + - 大文件上传建议分块或采用服务端直传策略 +- 事件回调 + - 高频事件（如 change、key_down）应避免在回调中执行重计算 +- UI 渲染 + - 列表渲染时启用虚拟化（如适用）以减少 DOM 节点 + - 图片预览与缩略图生成尽量在后台线程完成 + +## 故障排查指南 + +- 附件无法上传/预览 + - 检查 accept 与 headers/data/method 配置是否正确 + - 确认 custom_request 与 before_upload 回调未抛错 +- 远程文件无法下载 + - 核对 URL 可访问性与 with_credentials 设置 + - 查看缓存目录权限与磁盘空间 +- 发送器事件无效 + - 确认 submit_type 与键盘事件绑定是否匹配 + - 检查 disabled/read_only/loading 状态是否阻止交互 +- 建议面板不显示 + - 检查 items 是否为空或 should_trigger 条件是否满足 + - 确认 open/open_change 事件是否被正确绑定 + +## 结论 + +Antdx 表达组件通过清晰的事件与插槽体系，提供了完整的文件附件、输入发送与快捷指令能力。依托 Gradio 数据类与事件模型，可在 Python 侧进行灵活的数据转换与交互控制，同时保持前端 UI 的一致体验。 + +## 附录：使用示例与最佳实践 + +- 文件上传与预览 + - 使用 AntdXAttachments 的 accept 限制类型，设置 headers 与 data 完成鉴权与附加参数传递 + - 通过 list_type 与 show_upload_list 控制列表样式与可见性 + - 使用 preview_file 与 imageProps.\* 增强图片预览体验 +- 输入与发送控制 + - 使用 submit_type 精细控制提交时机（enter/shiftEnter） + - 结合 Sender.Header 与 Sender.Switch 扩展头部区域与开关 + - 通过 paste/paste_file 事件处理粘贴文件场景 +- 快捷指令 + - 使用 AntdXSuggestion 的 items 与 open 控制建议面板 + - 通过 AntdXSuggestionItem 的 label/icon/extra 丰富指令展示 +- 与聊天机器人集成 + - 将 Sender 的 value 作为消息主体，附件列表作为多模态输入 + - 通过事件回调在后端组装消息体并调用机器人接口 + - 使用 preprocess/postprocess 对消息与文件进行序列化/反序列化 diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\351\200\232\347\224\250\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\351\200\232\347\224\250\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..bb07d82d --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Antdx \347\273\204\344\273\266 API/\351\200\232\347\224\250\347\273\204\344\273\266 API.md" @@ -0,0 +1,390 @@ +# 通用组件 API + + +**本文引用的文件** +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/antdx/bubble/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/__init__.py) +- [backend/modelscope_studio/components/antdx/bubble/list/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py) +- [backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py) +- [backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py) +- [backend/modelscope_studio/components/antdx/conversations/__init__.py](file://backend/modelscope_studio/components/antdx/conversations/__init__.py) +- [backend/modelscope_studio/components/antdx/conversations/item/__init__.py](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py) +- [backend/modelscope_studio/components/antdx/prompts/__init__.py](file://backend/modelscope_studio/components/antdx/prompts/__init__.py) +- [backend/modelscope_studio/components/antdx/prompts/item/__init__.py](file://backend/modelscope_studio/components/antdx/prompts/item/__init__.py) +- [docs/components/antdx/bubble/README-zh_CN.md](file://docs/components/antdx/bubble/README-zh_CN.md) +- [docs/components/antdx/conversations/README-zh_CN.md](file://docs/components/antdx/conversations/README-zh_CN.md) +- [docs/components/antdx/prompts/README-zh_CN.md](file://docs/components/antdx/prompts/README-zh_CN.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 Antdx 通用组件的 Python API 参考，重点覆盖以下核心组件： + +- Bubble：对话气泡渲染与交互 +- BubbleList：消息列表管理 +- BubbleListItem：消息项处理 +- BubbleListRole：角色标识 +- Conversations：对话管理、消息存储与状态同步 +- Prompts：提示模板管理、动态内容渲染与用户交互 + +文档提供各组件的构造函数参数、属性定义、事件与插槽（slots）规范，并给出典型 AI 场景下的标准组件实例化与组合方式，帮助开发者快速构建对话系统、消息展示与提示管理功能。 + +## 项目结构 + +Antdx 组件位于后端 Python 包中，通过统一的布局组件基类进行封装，并映射到前端对应组件目录。组件导出入口集中于 antdx/components.py，便于按需导入。 + +```mermaid +graph TB +subgraph "Python 后端" +A["components.py
导出入口"] +B["bubble/*
对话气泡组件族"] +C["conversations/*
对话列表组件族"] +D["prompts/*
提示组件族"] +end +A --> B +A --> C +A --> D +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +章节来源 + +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## 核心组件 + +本节概述三大核心组件族及其职责边界： + +- Bubble 家族：负责单条消息或角色级气泡的渲染与交互，支持打字动画、可编辑、变体、形状等。 +- BubbleList 家族：负责消息列表的滚动、角色分组与项渲染，支持自动滚动、角色配置等。 +- Conversations 家族：负责会话列表的管理、选中态切换、菜单操作与创建按钮等。 +- Prompts 家族：负责预设提示的展示与点击交互，支持垂直排列、淡入效果、换行等。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:13-135](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L13-L135) +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:12-84](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L12-L84) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) + +## 架构总览 + +下图展示了 Antdx 组件在 Python 层的组织方式与依赖关系： + +```mermaid +graph TB +subgraph "Antdx 组件" +B1["AntdXBubble"] +B2["AntdXBubbleList"] +B3["AntdXBubbleListItem"] +B4["AntdXBubbleListRole"] +C1["AntdXConversations"] +C2["AntdXConversationsItem"] +P1["AntdXPrompts"] +P2["AntdXPromptsItem"] +end +E1["事件绑定
EventListener"] +S1["插槽定义
SLOTS"] +B1 --> B2 +B2 --> B3 +B2 --> B4 +C1 --> C2 +P1 --> P2 +B1 --- E1 +B2 --- E1 +B3 --- E1 +B4 --- E1 +C1 --- E1 +P1 --- E1 +B1 --- S1 +B2 --- S1 +B3 --- S1 +B4 --- S1 +C1 --- S1 +P1 --- S1 +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:21-54](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L21-L54) +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:19-30](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L19-L30) +- [backend/modelscope_studio/components/antdx/bubble/list/item/**init**.py:14-47](file://backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py#L14-L47) +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:14-46](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L14-L46) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:18-47](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L18-L47) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-26](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L26) + +## 详细组件分析 + +### Bubble 组件 + +- 组件定位：用于渲染单条对话气泡，支持多种外观变体、形状、打字动画、可编辑、头像、页眉/页脚、额外区域、加载与内容自定义渲染等。 +- 关键属性（构造函数参数） + - content：气泡内容文本 + - avatar：头像地址或占位符 + - extra：附加元素 + - footer/header：页脚/页眉内容 + - loading：是否显示加载态 + - placement：对齐位置（起始/结束） + - editable：是否可编辑（布尔或字典） + - shape：气泡形状（圆润/尖角/默认） + - typing：打字动画（布尔/字典/字符串） + - streaming：流式渲染开关 + - variant：外观变体（填充/无边框/描边/阴影） + - footer_placement：页脚位置（外侧/内侧起始/结束） + - loading_render/content_render：自定义加载与内容渲染 + - class_names/styles/root_class_name：样式与类名控制 + - 其他通用属性：visible、elem_id、elem_classes、elem_style、render 等 +- 事件 + - typing：打字动画回调 + - typing_complete：打字完成回调；若未设置打字，则渲染时立即触发 + - edit_confirm：编辑确认回调 + - edit_cancel：编辑取消回调 +- 插槽（slots） + - avatar、editable.okText、editable.cancelText、content、footer、header、extra、loadingRender、contentRender +- 嵌套子组件 + - List：消息列表容器 + - System：系统消息气泡 + - Divider：分割线 + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:56-116](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L56-L116) +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:21-54](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L21-L54) + +### BubbleList 组件 + +- 组件定位：消息列表容器，负责滚动、角色分组与项渲染，支持自动滚动与角色配置。 +- 关键属性 + - items：消息项数组（字典） + - role：角色配置（字典） + - auto_scroll：是否自动滚动到底部 + - class_names/styles/root_class_name：样式与类名控制 + - 其他通用属性：visible、elem_id、elem_classes、elem_style、render 等 +- 事件 + - scroll：列表滚动回调 +- 插槽 + - items、role +- 嵌套子组件 + - Item：消息项 + - Role：角色标识 + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:32-64](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L32-L64) +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:19-30](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L19-L30) + +### BubbleListItem 组件 + +- 组件定位：消息列表中的单项，行为与 Bubble 基本一致，但作为列表项使用。 +- 关键属性 + - content、avatar、extra、footer、header、loading、placement、editable、shape、typing、streaming、variant、footer_placement、loading_render、content_render、class_names/styles/root_class_name 等 +- 事件 + - typing、typing_complete、edit_confirm、edit_cancel +- 插槽 + - avatar、editable.okText、editable.cancelText、content、footer、header、extra、loadingRender、contentRender + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/list/item/**init**.py:49-108](file://backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py#L49-L108) +- [backend/modelscope_studio/components/antdx/bubble/list/item/**init**.py:14-47](file://backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py#L14-L47) + +### BubbleListRole 组件 + +- 组件定位：用于在列表中标识角色，支持角色头像、页眉/页脚、额外区域、加载与内容自定义渲染等。 +- 关键属性 + - role：角色标识文本 + - avatar、extra、footer、header、loading、placement、editable、shape、typing、streaming、variant、footer_placement、loading_render、content_render、class_names/styles/root_class_name 等 +- 事件 + - typing、typing_complete、edit_confirm、edit_cancel +- 插槽 + - avatar、editable.okText、editable.cancelText、footer、header、extra、loadingRender、contentRender + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:48-107](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L48-L107) +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:14-46](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L14-L46) + +### Conversations 组件 + +- 组件定位：用于管理与查看对话列表，支持选中态切换、菜单操作、分组、快捷键与创建按钮等。 +- 关键属性 + - active_key/default_active_key：当前激活项键值 + - items：对话项数组（字典） + - menu：菜单配置（字符串或字典） + - groupable：是否可分组（布尔或字典） + - shortcut_keys：快捷键映射 + - creation：创建按钮配置（字典） + - styles/class_names/root_class_name：样式与类名控制 + - 其他通用属性：visible、elem_id、elem_classes、elem_style、render 等 +- 事件 + - active_change：选中项变更回调 + - menu_click/menu_deselect/menu_open_change/menu_select：菜单相关回调 + - groupable_expand：分组展开回调 + - creation_click：创建按钮点击回调 +- 插槽 + - menu.expandIcon、menu.overflowedIndicator、menu.trigger、groupable.label、items、creation.icon、creation.label +- 嵌套子组件 + - Item：对话项 + +章节来源 + +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:49-89](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L49-L89) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:18-47](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L18-L47) + +### ConversationsItem 组件 + +- 组件定位：对话列表中的单项，支持标签、图标、类型、分组、禁用、虚线等。 +- 关键属性 + - label：标签文本 + - key：唯一键 + - type：类型（如分隔线） + - group：所属分组 + - icon：图标 + - disabled：是否禁用 + - dashed：是否虚线 + - additional_props/as_item/\_internal：内部与扩展属性 + - 其他通用属性：visible、elem_id、elem_classes、elem_style、render 等 + +章节来源 + +- [backend/modelscope_studio/components/antdx/conversations/item/**init**.py:21-55](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L21-L55) + +### Prompts 组件 + +- 组件定位：用于展示预设提示，支持标题、垂直排列、淡入效果、换行等。 +- 关键属性 + - items：提示项数组（字典） + - prefix_cls：前缀类名 + - title：标题 + - vertical：是否垂直排列 + - fade_in/fade_in_left：淡入效果（左右） + - wrap：是否换行 + - styles/class_names/root_class_name：样式与类名控制 + - 其他通用属性：visible、elem_id、elem_classes、elem_style、render 等 +- 事件 + - item_click：提示项点击回调 +- 插槽 + - title、items +- 嵌套子组件 + - Item：提示项 + +章节来源 + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:28-68](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L28-L68) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-26](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L26) + +### PromptsItem 组件 + +- 组件定位：提示列表中的单项，支持标签、描述、图标、禁用与键值。 +- 关键属性 + - label：标签文本 + - key：唯一键 + - description：描述文本 + - icon：图标 + - disabled：是否禁用 + - additional_props/as_item/\_internal：内部与扩展属性 + - 其他通用属性：visible、elem_id、elem_classes、elem_style、render 等 + +章节来源 + +- [backend/modelscope_studio/components/antdx/prompts/item/**init**.py:18-48](file://backend/modelscope_studio/components/antdx/prompts/item/__init__.py#L18-L48) + +## 依赖分析 + +- 组件导出：所有 antdx 组件均通过 components.py 集中导出，便于统一导入与使用。 +- 组件层次：Bubble 家族（Bubble、BubbleList、BubbleListItem、BubbleListRole）形成完整的消息渲染链路；Conversations 家族与 Prompts 家族分别负责会话管理和提示管理。 +- 事件与插槽：各组件均定义了 EVENTS 与 SLOTS 列表，用于声明支持的事件回调与插槽名称，确保前后端约定一致。 + +```mermaid +graph LR +A["components.py 导出"] --> B["Bubble 家族"] +A --> C["Conversations 家族"] +A --> D["Prompts 家族"] +B --> B1["Bubble"] +B --> B2["BubbleList"] +B2 --> B3["BubbleListItem"] +B2 --> B4["BubbleListRole"] +C --> C1["Conversations"] +C1 --> C2["ConversationsItem"] +D --> D1["Prompts"] +D1 --> D2["PromptsItem"] +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +章节来源 + +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## 性能考虑 + +- 流式渲染与打字动画：合理使用 streaming 与 typing 参数，避免在大量消息同时渲染时造成卡顿。 +- 自动滚动：BubbleList 的 auto_scroll 在消息频繁更新时建议开启，以保持最佳用户体验。 +- 插槽与自定义渲染：loadingRender 与 contentRender 虽灵活，但应避免在渲染函数中执行重计算，必要时缓存结果。 +- 事件绑定：仅在需要时启用相关事件绑定（如 typing_complete），减少不必要的回调开销。 +- 外观与形状：变体（variant）与形状（shape）会影响渲染复杂度，建议按需选择。 + +## 故障排查指南 + +- 事件未触发 + - 检查 EVENTS 中的绑定名称是否正确，确认前端已启用相应 bind\_\* 事件。 + - 确认组件的 visible、render 状态是否影响事件传播。 +- 插槽内容不显示 + - 确认插槽名称拼写与 SLOTS 列表一致。 + - 检查插槽作用域与父组件传递的插槽内容是否匹配。 +- 样式异常 + - 使用 class_names/styles/root_class_name 进行局部覆盖，避免全局样式冲突。 +- 滚动问题 + - BubbleList 的 auto_scroll 与外部容器高度设置有关，检查容器高度与 overflow 设置。 +- 打字动画不生效 + - 确认 typing 参数类型与值范围，避免传入不支持的类型。 + +## 结论 + +Antdx 通用组件提供了从消息渲染、列表管理到会话与提示管理的完整能力。通过统一的事件与插槽约定，开发者可以快速搭建对话系统与提示面板，并结合样式与交互配置实现高性能、可维护的前端体验。 + +## 附录 + +### 典型场景与实例化路径 + +- 对话气泡基础渲染与打字动画 + - 参考路径：[docs/components/antdx/bubble/README-zh_CN.md:7-12](file://docs/components/antdx/bubble/README-zh_CN.md#L7-L12) +- 消息列表与自动滚动 + - 参考路径：[docs/components/antdx/bubble/README-zh_CN.md:10-12](file://docs/components/antdx/bubble/README-zh_CN.md#L10-L12) +- 会话列表与菜单操作 + - 参考路径：[docs/components/antdx/conversations/README-zh_CN.md:7-9](file://docs/components/antdx/conversations/README-zh_CN.md#L7-L9) +- 提示面板与嵌套使用 + - 参考路径：[docs/components/antdx/prompts/README-zh_CN.md:7-8](file://docs/components/antdx/prompts/README-zh_CN.md#L7-L8) + +### 数据格式与字段说明（摘要） + +- Bubble/BubbleListItem/BubbleListRole + - content、avatar、extra、footer、header、loading、placement、editable、shape、typing、streaming、variant、footer_placement、loading_render、content_render、class_names、styles、root_class_name +- BubbleList + - items、role、auto_scroll、class_names、styles、root_class_name +- Conversations + - active_key、default_active_key、items、menu、groupable、shortcut_keys、creation、styles、class_names、root_class_name +- ConversationsItem + - label、key、type、group、icon、disabled、dashed、additional_props、as_item、\_internal +- Prompts + - items、prefix_cls、title、vertical、fade_in、fade_in_left、wrap、styles、class_names、root_class_name +- PromptsItem + - label、key、description、icon、disabled、additional_props、as_item、\_internal diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/Python API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Python API.md" new file mode 100644 index 00000000..af89d40f --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/Python API.md" @@ -0,0 +1,433 @@ +# Python API + + +**本文引用的文件** +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/components/pro/__init__.py](file://backend/modelscope_studio/components/pro/__init__.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [backend/modelscope_studio/components/antd/button/__init__.py](file://backend/modelscope_studio/components/antd/button/__init__.py) +- [backend/modelscope_studio/components/antd/form/__init__.py](file://backend/modelscope_studio/components/antd/form/__init__.py) +- [backend/modelscope_studio/components/base/application/__init__.py](file://backend/modelscope_studio/components/base/application/__init__.py) +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：API 索引与使用示例](#附录api-索引与使用示例) + +## 简介 + +本文件为 ModelScope Studio 的 Python API 参考文档，聚焦于后端 Python 包 modelscope_studio 的组件体系与调用方式。文档覆盖以下内容： + +- 组件导入路径与命名导出规范（modelscope*studio.components.antd.*、modelscope*studio.components.antdx.*、modelscope*studio.components.base.*、modelscope*studio.components.pro.*） +- 关键组件类的构造函数参数、支持的事件、插槽、数据模型与预处理/后处理流程 +- 标准实例化示例（基本用法与高级配置），以及生命周期与状态管理要点 +- 参数校验与异常处理机制提示 +- 版本兼容性信息与常见问题排查 + +## 项目结构 + +Python 包位于 backend/modelscope_studio，顶层通过 **all** 导出聚合各子模块；组件按类型分层组织在 antd、antdx、base、pro 四个子包中，每个子包提供 **init**.py 与 components.py 两种入口，分别用于不同聚合策略。 + +```mermaid +graph TB +A["backend/modelscope_studio/__init__.py"] --> B["backend/modelscope_studio/components/__init__.py"] +B --> C["antd 子包"] +B --> D["antdx 子包"] +B --> E["base 子包"] +B --> F["pro 子包"] +C --> C1["antd/__init__.py
命名导出各组件类"] +D --> D1["antdx/__init__.py
命名导出各组件类"] +E --> E1["base/__init__.py
命名导出基础组件类"] +F --> F1["pro/__init__.py
命名导出专业组件类"] +``` + +**图表来源** + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) + +**章节来源** + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) + +## 核心组件 + +本节给出四大组件族的导入路径与命名导出概览，并说明各组件族的职责边界与典型用途。 + +- modelscope_studio.components.antd.\* + - 职责：Ant Design 组件生态的 Python 封装，覆盖布局、表单、反馈、导航、数据录入等常用 UI 组件。 + - 典型组件：Button、Form、Input、Select、Table、Modal、Message、Notification 等。 + - 导入方式：from modelscope_studio.components.antd import Button, Form, ... + - 命名导出：见 [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) 与 [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) + +- modelscope_studio.components.antdx.\* + - 职责：Ant Design X 扩展组件集合，面向对话式交互与知识工作场景（如消息气泡、会话列表、提示词面板等）。 + - 典型组件：Bubble、Conversations、Prompts、Sender、ThoughtChain、Welcome 等。 + - 导入方式：from modelscope_studio.components.antdx import Bubble, Conversations, ... + - 命名导出：见 [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) 与 [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +- modelscope_studio.components.base.\* + - 职责：基础布局与容器组件，提供应用级容器、循环渲染、条件过滤、占位文本等通用能力。 + - 典型组件：Application、Each、Filter、Fragment、Markdown、Slot、Text、Div 等。 + - 导入方式：from modelscope_studio.components.base import Application, Each, ... + - 命名导出：见 [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +- modelscope_studio.components.pro.\* + - 职责：专业领域组件，面向特定业务形态（如聊天机器人、代码编辑器、多模态输入、网页沙盒等）。 + - 典型组件：Chatbot、MonacoEditor、MultimodalInput、WebSandbox。 + - 导入方式：from modelscope_studio.components.pro import Chatbot, MonacoEditor, ... + - 命名导出：见 [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) 与 [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +**章节来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## 架构总览 + +下图展示 Python 层组件类与前端目录解析的关系，以及事件绑定与数据流的关键节点。 + +```mermaid +graph TB +subgraph "Python 层" +P1["AntdButton.__init__()
构造函数参数与事件绑定"] +P2["AntdForm.__init__()
表单配置与事件绑定"] +P3["ModelScopeApplication.__init__()
应用上下文与事件绑定"] +P4["ModelScopeProChatbot.__init__()
消息配置与静态资源处理"] +end +subgraph "前端目录解析" +F1["resolve_frontend_dir('button')"] +F2["resolve_frontend_dir('form')"] +F3["resolve_frontend_dir('application', type='base')"] +F4["resolve_frontend_dir('chatbot', type='pro')"] +end +P1 --> F1 +P2 --> F2 +P3 --> F3 +P4 --> F4 +``` + +**图表来源** + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) + +## 详细组件分析 + +### 组件：AntdButton（按钮） + +- 导入路径：from modelscope_studio.components.antd import Button +- 作用：封装 Ant Design 按钮，支持多种类型、尺寸、形状、加载态、危险态、幽灵态等。 +- 关键点： + - 支持事件：click + - 插槽：icon、loading.icon + - 预处理/后处理：字符串到字符串的简单转换 + - 前端目录：resolve_frontend_dir("button") + +```mermaid +classDiagram +class AntdButton { ++构造函数参数(...) ++EVENTS ++SLOTS ++FRONTEND_DIR ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +``` + +**图表来源** + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) + +**章节来源** + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) + +### 组件：AntdForm（表单）与 AntdFormItem（表单项） + +- 导入路径：from modelscope_studio.components.antd import Form, Form.Item +- 作用：封装 Ant Design 表单，支持字段变更、提交、失败、值变更等事件，以及表单项规则与提供者。 +- 关键点： + - 支持事件：fields_change、finish、finish_failed、values_change + - 数据模型：AntdFormData + - 预处理/后处理：对数据模型进行 root 字段提取或原样返回 + - 前端目录：resolve_frontend_dir("form") + +```mermaid +classDiagram +class AntdForm { ++Item ++Provider ++data_model ++EVENTS ++FRONTEND_DIR ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdFormItem { ++构造函数参数(...) ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdFormProvider { ++构造函数参数(...) ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdFormData { ++root +} +AntdForm --> AntdFormItem : "包含" +AntdForm --> AntdFormProvider : "包含" +AntdForm --> AntdFormData : "使用" +``` + +**图表来源** + +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) + +**章节来源** + +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) + +### 组件：ModelScopeApplication（应用容器） + +- 导入路径：from modelscope_studio.components.base import Application +- 作用：应用级容器，提供页面环境数据（屏幕尺寸、主题、语言等）与生命周期事件（mount、resize、unmount、custom）。 +- 关键点： + - 支持事件：custom、mount、resize、unmount + - 数据模型：ApplicationPageData + - 预处理/后处理：原样传递 + - 前端目录：resolve_frontend_dir("application", type="base") + +```mermaid +classDiagram +class ModelScopeApplication { ++EVENTS ++data_model ++FRONTEND_DIR ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class ApplicationPageData { ++screen ++language ++theme ++userAgent +} +ModelScopeApplication --> ApplicationPageData : "使用" +``` + +**图表来源** + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) + +**章节来源** + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) + +### 组件：ModelScopeProChatbot（专业聊天机器人） + +- 导入路径：from modelscope_studio.components.pro import Chatbot +- 作用：专业聊天机器人组件，支持欢迎语、提示词、用户/助手消息、动作按钮、文件/工具/建议内容等丰富配置。 +- 关键点： + - 支持事件：change、copy、edit、delete、like、retry、suggestion_select、welcome_prompt_select + - 数据模型：ChatbotDataMessages（根为消息列表） + - 预处理/后处理：消息内容的类型化处理（文件转 FileData、静态资源路径处理） + - 前端目录：resolve_frontend_dir("chatbot", type="pro") + +```mermaid +classDiagram +class ModelScopeProChatbot { ++EVENTS ++data_model ++FRONTEND_DIR ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class ChatbotDataMessages { ++root +} +class ChatbotDataMessage { ++role ++status ++content ++meta +} +ModelScopeProChatbot --> ChatbotDataMessages : "使用" +ChatbotDataMessages --> ChatbotDataMessage : "包含" +``` + +**图表来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) + +**章节来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) + +## 依赖分析 + +- 组件类普遍继承自 ModelScopeDataLayoutComponent 或 ModelScopeLayoutComponent，统一了前端目录解析与事件绑定机制。 +- 事件系统基于 gradio.events.EventListener，通过回调将事件绑定标记注入内部更新逻辑。 +- 数据模型多采用 GradioRootModel/GradioModel，便于前后端一致的数据结构与序列化。 + +```mermaid +graph LR +A["AntdButton"] --> B["ModelScopeLayoutComponent"] +C["AntdForm"] --> D["ModelScopeDataLayoutComponent"] +E["ModelScopeApplication"] --> D +F["ModelScopeProChatbot"] --> D +B --> G["resolve_frontend_dir(...)"] +D --> G +``` + +**图表来源** + +- [backend/modelscope_studio/components/antd/button/**init**.py:7-8](file://backend/modelscope_studio/components/antd/button/__init__.py#L7-L8) +- [backend/modelscope_studio/components/antd/form/**init**.py:8-9](file://backend/modelscope_studio/components/antd/form/__init__.py#L8-L9) +- [backend/modelscope_studio/components/base/application/**init**.py:8-9](file://backend/modelscope_studio/components/base/application/__init__.py#L8-L9) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:11](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L11) + +**章节来源** + +- [backend/modelscope_studio/components/antd/button/**init**.py:7-8](file://backend/modelscope_studio/components/antd/button/__init__.py#L7-L8) +- [backend/modelscope_studio/components/antd/form/**init**.py:8-9](file://backend/modelscope_studio/components/antd/form/__init__.py#L8-L9) +- [backend/modelscope_studio/components/base/application/**init**.py:8-9](file://backend/modelscope_studio/components/base/application/__init__.py#L8-L9) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:11](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L11) + +## 性能考虑 + +- 组件预处理/后处理尽量保持轻量，避免在 Python 层做重型计算。 +- 对大文件内容（如聊天机器人的文件消息）建议在后处理阶段进行最小化包装（如仅保留必要元数据），减少传输开销。 +- 合理设置组件高度与滚动行为，避免不必要的重排与重绘。 + +## 故障排查指南 + +- 事件未触发 + - 检查是否正确注册事件监听（如 Button 的 click、Form 的 finish 等），确认回调已注入绑定标记。 + - 参考：[backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46)，[backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) +- 前端目录解析失败 + - 确认 resolve_frontend_dir 返回的路径存在且可访问。 + - 参考：[backend/modelscope_studio/components/antd/button/**init**.py:139](file://backend/modelscope_studio/components/antd/button/__init__.py#L139)，[backend/modelscope_studio/components/antd/form/**init**.py:114](file://backend/modelscope_studio/components/antd/form/__init__.py#L114) +- 数据模型不匹配 + - 使用 data_model 进行预处理/后处理，确保 payload/value 结构与模型一致。 + - 参考：[backend/modelscope_studio/components/antd/form/**init**.py:13-14](file://backend/modelscope_studio/components/antd/form/__init__.py#L13-L14)，[backend/modelscope_studio/components/pro/chatbot/**init**.py:388](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L388) + +**章节来源** + +- [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) +- [backend/modelscope_studio/components/antd/form/**init**.py:13-14](file://backend/modelscope_studio/components/antd/form/__init__.py#L13-L14) +- [backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) +- [backend/modelscope_studio/components/antd/button/**init**.py:139](file://backend/modelscope_studio/components/antd/button/__init__.py#L139) +- [backend/modelscope_studio/components/antd/form/**init**.py:114](file://backend/modelscope_studio/components/antd/form/__init__.py#L114) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:388](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L388) + +## 结论 + +ModelScope Studio 的 Python API 以清晰的组件族划分与统一的事件/数据模型设计，提供了从基础布局到专业领域的完整组件体系。通过明确的导入路径与命名导出，开发者可以快速定位并使用所需组件；同时，事件绑定与数据预处理/后处理机制保证了前后端协同的一致性与可扩展性。 + +## 附录：API 索引与使用示例 + +### API 索引（按组件族） + +- modelscope_studio.components.antd.\* + - Button：from modelscope_studio.components.antd import Button + - Form：from modelscope_studio.components.antd import Form + - Form.Item：from modelscope_studio.components.antd import Form.Item + - 更多组件：参见 [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) + +- modelscope_studio.components.antdx.\* + - Actions、Bubble、Conversations、Prompts、Sender、ThoughtChain、Welcome 等 + - 导入示例：from modelscope_studio.components.antdx import Bubble, Conversations + - 参见 [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) + +- modelscope_studio.components.base.\* + - Application、Each、Filter、Fragment、Markdown、Slot、Text、Div 等 + - 导入示例：from modelscope_studio.components.base import Application + - 参见 [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +- modelscope_studio.components.pro.\* + - Chatbot、MonacoEditor、MultimodalInput、WebSandbox 等 + - 导入示例：from modelscope_studio.components.pro import Chatbot + - 参见 [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) + +### 使用示例（路径指引） + +- 基础按钮（AntdButton） + - 示例路径：[backend/modelscope_studio/components/antd/button/**init**.py:51-87](file://backend/modelscope_studio/components/antd/button/__init__.py#L51-L87) +- 表单（AntdForm）与表单项（AntdFormItem） + - 示例路径：[backend/modelscope_studio/components/antd/form/**init**.py:43-80](file://backend/modelscope_studio/components/antd/form/__init__.py#L43-L80) +- 应用容器（ModelScopeApplication） + - 示例路径：[backend/modelscope_studio/components/base/application/**init**.py:59-71](file://backend/modelscope_studio/components/base/application/__init__.py#L59-L71) +- 聊天机器人（ModelScopeProChatbot） + - 示例路径：[backend/modelscope_studio/components/pro/chatbot/**init**.py:319-343](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L319-L343) + +### 生命周期与事件回调 + +- AntdButton + - 事件：click + - 插槽：icon、loading.icon + - 参考：[backend/modelscope_studio/components/antd/button/**init**.py:41-49](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L49) +- AntdForm + - 事件：fields_change、finish、finish_failed、values_change + - 数据模型：AntdFormData + - 参考：[backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) +- ModelScopeApplication + - 事件：custom、mount、resize、unmount + - 数据模型：ApplicationPageData + - 参考：[backend/modelscope_studio/components/base/application/**init**.py:30-54](file://backend/modelscope_studio/components/base/application/__init__.py#L30-L54) +- ModelScopeProChatbot + - 事件：change、copy、edit、delete、like、retry、suggestion_select、welcome_prompt_select + - 数据模型：ChatbotDataMessages + - 参考：[backend/modelscope_studio/components/pro/chatbot/**init**.py:289-314](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L289-L314) + +### 参数验证与异常处理 + +- 参数验证 + - 组件构造函数参数多为可选或带默认值，类型注解覆盖常见枚举与字典结构。 + - 参考：[backend/modelscope_studio/components/antd/button/**init**.py:51-87](file://backend/modelscope_studio/components/antd/button/__init__.py#L51-L87)，[backend/modelscope_studio/components/antd/form/**init**.py:43-80](file://backend/modelscope_studio/components/antd/form/__init__.py#L43-L80) +- 异常处理 + - 建议在业务层捕获事件回调中的异常，并结合日志输出错误上下文。 + - 前端目录解析失败时，检查 resolve_frontend_dir 返回路径是否存在。 + +### 版本兼容性 + +- 当前版本：2.0.0 + - 参考：[backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/\344\270\223\344\270\232\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/\344\270\223\344\270\232\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..75c607b7 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/\344\270\223\344\270\232\347\273\204\344\273\266 API.md" @@ -0,0 +1,487 @@ +# 专业组件 API + + +**本文引用的文件** +- [backend/modelscope_studio/components/pro/__init__.py](file://backend/modelscope_studio/components/pro/__init__.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) +- [backend/modelscope_studio/components/pro/multimodal_input/__init__.py](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py) +- [backend/modelscope_studio/components/pro/web_sandbox/__init__.py](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py) +- [backend/modelscope_studio/components/pro/monaco_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) +- [backend/modelscope_studio/utils/dev/process_links.py](file://backend/modelscope_studio/utils/dev/process_links.py) +- [docs/demos/example.py](file://docs/demos/example.py) +- [docs/layout_templates/chatbot/app.py](file://docs/layout_templates/chatbot/app.py) +- [docs/layout_templates/chatbot/demos/basic.py](file://docs/layout_templates/chatbot/demos/basic.py) +- [docs/components/pro/chatbot/demos/chatbot_config.py](file://docs/components/pro/chatbot/demos/chatbot_config.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为专业组件库（modelscope_studio.components.pro）的 Python API 参考文档，覆盖以下 AI 应用专用组件： + +- Chatbot：对话消息容器与渲染组件，支持用户/助手消息、欢迎提示、建议提示、工具调用、文件内容等丰富能力。 +- MultimodalInput：多模态输入组件，支持文本与附件上传、粘贴、拖拽、语音等输入形态。 +- WebSandbox：网页沙盒组件，用于在隔离环境中渲染 React/HTML 模板，支持编译与渲染错误事件。 +- MonacoEditor：代码编辑器组件，支持语言高亮、只读、选项配置、挂载/变更/校验事件；提供 DiffEditor 子类。 + +文档记录各组件的导入路径、构造函数参数、属性定义、方法签名与返回值类型，并给出面向复杂 AI 应用的标准实例化与使用示例，涵盖聊天机器人集成、多模态输入处理、网页沙盒隔离等高级用法。同时说明组件的事件绑定、数据流处理策略、前后端数据转换逻辑以及性能与并发相关注意事项。 + +## 项目结构 + +专业组件位于后端 Python 包 modelscope_studio/components/pro 下，按功能划分为 chatbot、multimodal_input、web_sandbox、monaco_editor 四个子模块，另有统一导出入口与别名导出。 + +```mermaid +graph TB +subgraph "Python 后端" +PRO["pro/__init__.py
统一导出"] +COMP["pro/components.py
别名导出"] +CHAT["pro/chatbot/__init__.py"] +MMI["pro/multimodal_input/__init__.py"] +WS["pro/web_sandbox/__init__.py"] +ME["pro/monaco_editor/__init__.py"] +MED["pro/monaco_editor/diff_editor/__init__.py"] +end +subgraph "通用基类" +DEV["utils/dev/component.py
ModelScope*Component 家族"] +RES["utils/dev/resolve_frontend_dir.py"] +LNK["utils/dev/process_links.py"] +end +PRO --> CHAT +PRO --> MMI +PRO --> WS +PRO --> ME +ME --> MED +COMP --> CHAT +COMP --> MMI +COMP --> WS +COMP --> ME +COMP --> MED +CHAT --> DEV +MMI --> DEV +WS --> DEV +ME --> DEV +MED --> DEV +CHAT --> RES +MMI --> RES +WS --> RES +ME --> RES +MED --> RES +CHAT --> LNK +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:15-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L86) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:10-106](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L10-L106) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L17) +- [backend/modelscope_studio/utils/dev/process_links.py:9-61](file://backend/modelscope_studio/utils/dev/process_links.py#L9-L61) + +章节来源 + +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## 核心组件 + +本节概述四个专业组件的职责与典型用途： + +- Chatbot：用于构建对话界面，管理消息列表、欢迎提示、建议提示、动作按钮、Markdown 渲染、文件/工具内容等。 +- MultimodalInput：用于接收文本与附件的多模态输入，支持上传、粘贴、拖拽、预览、下载等流程。 +- WebSandbox：用于在隔离环境中渲染模板（React/HTML），捕获编译与渲染错误事件。 +- MonacoEditor：用于在浏览器中嵌入代码编辑器，支持语言、只读、选项、挂载/变更/校验事件；提供 DiffEditor 对比视图。 + +章节来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:15-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L86) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) + +## 架构总览 + +专业组件基于 Gradio 组件体系扩展，通过统一的基类与前端目录解析实现前后端桥接。组件在初始化时设置 FRONTEND_DIR，指向对应前端 Svelte 组件目录；通过 preprocess/postprocess 实现数据的前后端转换；通过 EVENTS/SLOTS 提供事件与插槽扩展点。 + +```mermaid +sequenceDiagram +participant Py as "Python 组件" +participant Base as "ModelScope*Component 基类" +participant FE as "前端组件(Svelte)" +participant App as "Gradio 应用" +App->>Py : 实例化组件(传入 value/配置) +Py->>Base : 调用父类构造(继承 Gradio Component) +Py->>Py : 设置 FRONTEND_DIR/数据模型/事件/SLOTS +Py->>FE : 渲染时传递配置与数据 +FE-->>Py : 触发事件回调(如 change/copy/edit/delete/like/retry/suggestion_select/welcome_prompt_select) +Py-->>App : 返回处理后的 value(可能经过 postprocess) +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L17) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:15-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L86) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) + +## 详细组件分析 + +### Chatbot 组件 + +- 导入路径 + - 主类：modelscope_studio.components.pro.Chatbot + - 别名：modelscope_studio.components.pro.ProChatbot +- 作用 + - 管理对话消息列表，支持用户/助手消息、欢迎提示、建议提示、动作按钮、Markdown 渲染、文件/工具内容等。 +- 关键数据模型 + - ChatbotWelcomeConfig、ChatbotPromptsConfig、ChatbotPromptConfig、ChatbotMarkdownConfig、ChatbotUserConfig、ChatbotBotConfig、ChatbotDataMessageContent、ChatbotDataMessage、ChatbotDataMessages、ChatbotDataMeta +- 构造函数参数要点 + - value：可为回调或消息列表/字典，支持消息状态 pending/done、分隔符、元数据反馈等 + - 高度与滚动：height、min_height、max_height、auto_scroll、show_scroll_to_bottom_button、scroll_to_bottom_button_offset + - 欢迎与 Markdown：welcome_config、markdown_config + - 用户/助手样式与动作：user_config、bot_config（含 actions/disabled_actions、avatar、typing 等） + - 其他：elem_id、elem_classes、elem_style、visible、render 等 +- 方法与行为 + - preprocess：将消息内容中的文件路径标准化，便于前端展示 + - postprocess：将文件路径转换为 FileData 结构，支持本地与远程 URL + - 事件：change、copy、edit、delete、like、retry、suggestion_select、welcome_prompt_select + - 插槽：role +- 使用示例（参考） + - 基础聊天模板应用入口：[docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) + - 聊天配置与事件演示：[docs/components/pro/chatbot/demos/chatbot_config.py:1-40](file://docs/components/pro/chatbot/demos/chatbot_config.py#L1-L40) + +```mermaid +classDiagram +class ModelScopeProChatbot { ++EVENTS ++SLOTS ++FRONTEND_DIR ++data_model ++__init__(...) ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class ChatbotWelcomeConfig +class ChatbotPromptsConfig +class ChatbotPromptConfig +class ChatbotMarkdownConfig +class ChatbotUserConfig +class ChatbotBotConfig +class ChatbotDataMessageContent +class ChatbotDataMessage +class ChatbotDataMessages +class ChatbotDataMeta +ModelScopeProChatbot --> ChatbotWelcomeConfig : "使用" +ModelScopeProChatbot --> ChatbotPromptsConfig : "使用" +ModelScopeProChatbot --> ChatbotMarkdownConfig : "使用" +ModelScopeProChatbot --> ChatbotUserConfig : "使用" +ModelScopeProChatbot --> ChatbotBotConfig : "使用" +ModelScopeProChatbot --> ChatbotDataMessageContent : "使用" +ModelScopeProChatbot --> ChatbotDataMessage : "使用" +ModelScopeProChatbot --> ChatbotDataMessages : "使用" +ModelScopeProChatbot --> ChatbotDataMeta : "使用" +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-285](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L285) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) + +章节来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-285](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L285) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) +- [docs/components/pro/chatbot/demos/chatbot_config.py:1-40](file://docs/components/pro/chatbot/demos/chatbot_config.py#L1-L40) + +### MultimodalInput 组件 + +- 导入路径 + - 主类：modelscope_studio.components.pro.MultimodalInput + - 别名：modelscope_studio.components.pro.ProMultimodalInput +- 作用 + - 接收文本与附件的多模态输入，支持上传、粘贴、拖拽、预览、下载等流程。 +- 关键数据模型 + - MultimodalInputUploadConfig：上传行为与 UI 配置 + - MultimodalInputValue：包含 files 与 text 的输入值 +- 构造函数参数要点 + - value：MultimodalInputValue 或其字典形式 + - 模式与尺寸：mode、auto_size、footer/header/prefix/suffix、placeholder、submit_type + - 上传配置：upload_config（fullscreen_drop、allow_upload、allow_paste_file、allow_speech、max_count、directory、multiple、overflow、title、image_props、placeholder 等） + - 样式与状态：disabled、read_only、loading、class_names、styles、root_class_name + - 其他：elem_id、elem_classes、elem_style、visible、render 等 +- 方法与行为 + - preprocess：将上传的文件转换为可缓存的命名字符串，便于后续处理 + - postprocess：将文件路径下载到本地缓存并封装为 FileData 列表 + - 事件：change、submit、cancel、key_down/key_press、focus、blur、upload、paste、paste_file、skill_closable_close、drop、download、preview、remove + - 插槽：suffix、header、prefix、footer、skill.title、skill.toolTip.title、skill.closable.closeIcon +- 使用示例（参考） + - 示例应用入口：[docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +```mermaid +classDiagram +class ModelScopeProMultimodalInput { ++EVENTS ++SLOTS ++FRONTEND_DIR ++data_model ++__init__(...) ++preprocess(payload) ++postprocess(value) ++_process_single_file(f) ++_download_files(value) ++skip_api ++example_payload() ++example_value() +} +class MultimodalInputUploadConfig +class MultimodalInputValue +ModelScopeProMultimodalInput --> MultimodalInputUploadConfig : "使用" +ModelScopeProMultimodalInput --> MultimodalInputValue : "使用" +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:18-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L18-L259) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) + +章节来源 + +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:18-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L18-L259) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +### WebSandbox 组件 + +- 导入路径 + - 主类：modelscope_studio.components.pro.WebSandbox + - 别名：modelscope_studio.components.pro.ProWebSandbox +- 作用 + - 在隔离环境中渲染 React/HTML 模板，支持编译与渲染错误事件监听。 +- 关键数据模型 + - SandboxFileData：模板文件结构（code、is_entry） +- 构造函数参数要点 + - value：字典，键为文件名，值为字符串或 SandboxFileData + - 模板类型：template（'react' | 'html'） + - 错误显示：show_render_error、show_compile_error、compile_error_render + - 外部依赖：imports（模块映射） + - 尺寸：height + - 其他：elem_id、elem_classes、elem_style、visible、render 等 +- 方法与行为 + - preprocess/postprocess：直接透传（skip_api=True） + - 事件：compile_success、compile_error、render_error、custom + - 插槽：compileErrorRender +- 使用示例（参考） + - 示例应用入口：[docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +```mermaid +classDiagram +class ModelScopeProWebSandbox { ++EVENTS ++SLOTS ++FRONTEND_DIR ++__init__(...) ++preprocess(payload) ++postprocess(value) ++skip_api ++example_payload() ++example_value() +} +class SandboxFileData +ModelScopeProWebSandbox --> SandboxFileData : "使用" +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:10-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L10-L86) +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:15-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L86) + +章节来源 + +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:10-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L10-L86) +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:15-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L86) +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +### MonacoEditor 组件 + +- 导入路径 + - 主类：modelscope_studio.components.pro.MonacoEditor + - 别名：modelscope_studio.components.pro.ProMonacoEditor + - DiffEditor：modelscope_studio.components.pro.MonacoEditorDiffEditor（作为子类） +- 作用 + - 提供代码编辑器，支持语言、只读、选项、挂载/变更/校验事件；DiffEditor 提供对比视图。 +- 构造函数参数要点 + - value：初始编辑内容 + - 语言与只读：language、read_only + - 生命周期钩子：before_mount、after_mount + - 服务覆盖：override_services + - 加载文案：loading + - 编辑器选项：options + - 行定位：line + - 尺寸：height + - 其他：elem_id、elem_classes、elem_style、visible、render 等 +- 方法与行为 + - preprocess/postprocess：直接透传（skip_api=False） + - 事件：mount、change、validate + - 插槽：loading + - DiffEditor：与主编辑器共享加载器配置，支持 original/original_language/modified_language +- 使用示例（参考） + - 示例应用入口：[docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +```mermaid +classDiagram +class ModelScopeProMonacoEditor { ++EVENTS ++SLOTS ++LOADER ++FRONTEND_DIR ++__init__(...) ++preprocess(payload) ++postprocess(value) ++api_info() ++skip_api ++example_payload() ++example_value() +} +class ModelScopeProMonacoEditorDiffEditor { ++EVENTS ++SLOTS ++FRONTEND_DIR ++__init__(...) ++preprocess(payload) ++postprocess(value) ++api_info() ++skip_api ++example_payload() ++example_value() +} +ModelScopeProMonacoEditor <|-- ModelScopeProMonacoEditorDiffEditor : "子类" +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:10-106](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L10-L106) + +章节来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:10-106](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L10-L106) +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +## 依赖分析 + +- 组件基类 + - ModelScopeLayoutComponent：布局型组件基类，适用于无需数据传输的容器组件（如 WebSandbox） + - ModelScopeComponent：基础组件基类，适用于数据型组件（如 Chatbot/MultimodalInput/MonacoEditor） + - ModelScopeDataLayoutComponent：兼具数据与布局能力，适用于需要前后端数据交换的组件（如 Chatbot/MultimodalInput/MonacoEditor） +- 前端目录解析 + - resolve_frontend_dir：根据组件名与类型（pro/antd/antdx/base）生成相对路径，确保前端资源正确加载 +- 数据链接处理 + - process_links：对 HTML/Markdown 中的链接进行转换，将本地文件转为可访问的缓存 URL + +```mermaid +graph LR +A["ModelScopeLayoutComponent"] --> C["WebSandbox"] +B["ModelScopeComponent"] --> D["Chatbot"] +B --> E["MultimodalInput"] +B --> F["MonacoEditor"] +G["ModelScopeDataLayoutComponent"] --> D +G --> E +G --> F +H["resolve_frontend_dir"] --> C +H --> D +H --> E +H --> F +I["process_links"] --> D +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L17) +- [backend/modelscope_studio/utils/dev/process_links.py:9-61](file://backend/modelscope_studio/utils/dev/process_links.py#L9-L61) + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L17) +- [backend/modelscope_studio/utils/dev/process_links.py:9-61](file://backend/modelscope_studio/utils/dev/process_links.py#L9-L61) + +## 性能考虑 + +- 数据序列化与传输 + - Chatbot/MultimodalInput/MonacoEditor 为数据型组件，preprocess/postprocess 会进行文件路径与 FileData 的转换，避免在前端直接处理大文件导致的内存压力。 +- 前端资源加载 + - MonacoEditor 支持本地或 CDN 加载器配置，合理选择可减少首屏加载时间；DiffEditor 复用主编辑器的加载器配置。 +- 事件绑定与更新 + - 组件通过 \_internal.update 动态绑定事件，避免不必要的重渲染；WebSandbox 的 skip_api=True，减少 API 层开销。 +- 文件处理 + - MultimodalInput 在 postprocess 中将远程 URL 下载至缓存目录，避免重复网络请求；process_links 将本地资源转为缓存 URL，提升稳定性与性能。 + +## 故障排查指南 + +- 编辑器加载失败 + - 检查 MonacoEditor 的 LOADER 配置（mode/local/cdn），确认 CDN 可达性或切换为本地加载。 + - 查看 mount/change/validate 事件是否触发，定位问题阶段。 +- 文件无法显示或下载异常 + - Chatbot 的文件内容在 postprocess 中转换为 FileData，检查路径是否为本地文件或有效 URL。 + - MultimodalInput 的 postprocess 会将远程 URL 下载到缓存，确认缓存目录权限与网络可达性。 +- 沙盒编译/渲染错误 + - WebSandbox 提供 compile_error/render_error 事件，结合 compileErrorRender 插槽定位错误。 +- 链接失效 + - 使用 process_links 对 HTML/Markdown 中的链接进行转换，确保本地资源被正确缓存与访问。 + +章节来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:44-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L44-L107) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:475-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L475-L495) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:233-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L233-L259) +- [backend/modelscope_studio/components/pro/web_sandbox/**init**.py:19-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L19-L86) +- [backend/modelscope_studio/utils/dev/process_links.py:9-61](file://backend/modelscope_studio/utils/dev/process_links.py#L9-L61) + +## 结论 + +专业组件库围绕对话、多模态输入、网页沙盒与代码编辑四大方向，提供了完整的 Python API 与前端集成方案。通过统一的基类体系、灵活的事件与插槽机制、完善的前后端数据转换，能够满足复杂 AI 应用的开发需求。建议在实际项目中结合示例与最佳实践，合理配置加载器、事件与数据流，以获得稳定且高性能的用户体验。 + +## 附录 + +- 统一导出与别名 + - 主模块导出：Chatbot、MonacoEditor、MonacoEditorDiffEditor、MultimodalInput、WebSandbox + - 别名导出：ProChatbot、ProMonacoEditor、ProMonacoEditorDiffEditor、ProMultimodalInput、ProWebSandbox +- 示例入口 + - 基础示例：[docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + - 聊天模板应用：[docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) + - 聊天配置与事件演示：[docs/components/pro/chatbot/demos/chatbot_config.py:1-40](file://docs/components/pro/chatbot/demos/chatbot_config.py#L1-L40) + +章节来源 + +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) +- [docs/components/pro/chatbot/demos/chatbot_config.py:1-40](file://docs/components/pro/chatbot/demos/chatbot_config.py#L1-L40) diff --git "a/.wiki/zh/API \345\217\202\350\200\203/Python API/\345\237\272\347\241\200\347\273\204\344\273\266 API.md" "b/.wiki/zh/API \345\217\202\350\200\203/Python API/\345\237\272\347\241\200\347\273\204\344\273\266 API.md" new file mode 100644 index 00000000..644d8dd0 --- /dev/null +++ "b/.wiki/zh/API \345\217\202\350\200\203/Python API/\345\237\272\347\241\200\347\273\204\344\273\266 API.md" @@ -0,0 +1,495 @@ +# 基础组件 API + + +**本文引用的文件** +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/components/base/application/__init__.py](file://backend/modelscope_studio/components/base/application/__init__.py) +- [backend/modelscope_studio/components/base/auto_loading/__init__.py](file://backend/modelscope_studio/components/base/auto_loading/__init__.py) +- [backend/modelscope_studio/components/base/slot/__init__.py](file://backend/modelscope_studio/components/base/slot/__init__.py) +- [backend/modelscope_studio/components/base/each/__init__.py](file://backend/modelscope_studio/components/base/each/__init__.py) +- [backend/modelscope_studio/components/base/filter/__init__.py](file://backend/modelscope_studio/components/base/filter/__init__.py) +- [backend/modelscope_studio/components/base/fragment/__init__.py](file://backend/modelscope_studio/components/base/fragment/__init__.py) +- [backend/modelscope_studio/components/base/div/__init__.py](file://backend/modelscope_studio/components/base/div/__init__.py) +- [backend/modelscope_studio/components/base/text/__init__.py](file://backend/modelscope_studio/components/base/text/__init__.py) +- [backend/modelscope_studio/components/base/span/__init__.py](file://backend/modelscope_studio/components/base/span/__init__.py) +- [backend/modelscope_studio/components/base/markdown/__init__.py](file://backend/modelscope_studio/components/base/markdown/__init__.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/app_context.py](file://backend/modelscope_studio/utils/dev/app_context.py) +- [docs/components/base/application/README.md](file://docs/components/base/application/README.md) +- [docs/components/base/each/README.md](file://docs/components/base/each/README.md) +- [docs/components/base/slot/README.md](file://docs/components/base/slot/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：使用示例与最佳实践](#附录使用示例与最佳实践) + +## 简介 + +本文件为基础组件库的 Python API 参考文档，覆盖 modelscope_studio.components.base.\* 下的核心组件，包括 Application、AutoLoading、Slot、Each、Filter、Fragment、Layout（以 Div/Span/Markdown 等常用布局型组件为代表）、Text 等。文档内容基于仓库源码与配套文档整理，重点说明： + +- 完整导入路径与使用方式 +- 构造函数参数、属性定义、方法签名与返回值类型 +- 组件组合模式（应用容器、条件渲染、循环遍历） +- 生命周期管理、上下文传递与插槽系统接口 +- 性能优化策略、内存管理与错误处理机制 +- 组件继承模式、扩展开发与最佳实践 + +## 项目结构 + +基础组件位于后端 Python 包 modelscope_studio/components/base，通过统一的导出入口聚合；前端资源由工具模块解析并绑定到对应前端目录。 + +```mermaid +graph TB +subgraph "Python 后端" +BASE["backend/modelscope_studio/components/base/__init__.py"] +APP["application/__init__.py"] +AUTO["auto_loading/__init__.py"] +SLOT["slot/__init__.py"] +EACH["each/__init__.py"] +FILTER["filter/__init__.py"] +FRAG["fragment/__init__.py"] +DIV["div/__init__.py"] +TEXT["text/__init__.py"] +SPAN["span/__init__.py"] +MARK["markdown/__init__.py"] +DEV["utils/dev/component.py"] +CTX["utils/dev/app_context.py"] +end +BASE --> APP +BASE --> AUTO +BASE --> SLOT +BASE --> EACH +BASE --> FILTER +BASE --> FRAG +BASE --> DIV +BASE --> TEXT +BASE --> SPAN +BASE --> MARK +APP --> DEV +AUTO --> DEV +SLOT --> DEV +EACH --> DEV +FILTER --> DEV +FRAG --> DEV +DIV --> DEV +TEXT --> DEV +SPAN --> DEV +MARK --> DEV +APP --> CTX +DEV --> CTX +``` + +图表来源 + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:8-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L8-L65) +- [backend/modelscope_studio/components/base/slot/**init**.py:8-50](file://backend/modelscope_studio/components/base/slot/__init__.py#L8-L50) +- [backend/modelscope_studio/components/base/each/**init**.py:17-73](file://backend/modelscope_studio/components/base/each/__init__.py#L17-L73) +- [backend/modelscope_studio/components/base/filter/**init**.py:8-45](file://backend/modelscope_studio/components/base/filter/__init__.py#L8-L45) +- [backend/modelscope_studio/components/base/fragment/**init**.py:8-49](file://backend/modelscope_studio/components/base/fragment/__init__.py#L8-L49) +- [backend/modelscope_studio/components/base/div/**init**.py:10-86](file://backend/modelscope_studio/components/base/div/__init__.py#L10-L86) +- [backend/modelscope_studio/components/base/text/**init**.py:8-57](file://backend/modelscope_studio/components/base/text/__init__.py#L8-L57) +- [backend/modelscope_studio/components/base/span/**init**.py:10-87](file://backend/modelscope_studio/components/base/span/__init__.py#L10-L87) +- [backend/modelscope_studio/components/base/markdown/**init**.py:11-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L11-L174) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) + +章节来源 + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +## 核心组件 + +以下为核心基础组件的导入路径与关键能力概览（按字母排序）： + +- Application + - 导入路径：from modelscope_studio.components.base import Application + - 能力：应用根容器，监听页面生命周期事件（mount、resize、unmount、custom），提供页面环境数据（屏幕尺寸、语言、主题、userAgent）。 + - 关键点：必须作为所有组件的根容器；支持自定义事件桥接（window.ms_globals.dispatch → Python 侧事件）。 + +- AutoLoading + - 导入路径：from modelscope_studio.components.base import AutoLoading + - 能力：自动加载状态包装器，支持插槽（render、errorRender、loadingText），可控制遮罩、计时器与错误展示。 + +- Slot + - 导入路径：from modelscope_studio.components.base import Slot + - 能力：插槽占位组件，配合目标组件的 SLOTS 使用，支持 params_mapping 参数映射。 + +- Each + - 导入路径：from modelscope_studio.components.base import Each + - 能力：列表遍历渲染，注入上下文，支持 as_item 过滤与 context_value 深合并。 + +- Filter + - 导入路径：from modelscope_studio.components.base import Filter + - 能力：条件过滤组件，用于根据参数映射决定是否渲染子树。 + +- Fragment + - 导入路径：from modelscope_studio.components.base import Fragment + - 能力：分组容器，不产生额外 DOM，适合逻辑分组与插槽挂载。 + +- Div/Text/Span/Markdown + - 导入路径：from modelscope_studio.components.base import Div, Text, Span, Markdown + - 能力：基础布局与文本组件，支持附加属性、事件绑定、复制按钮等特性。 + +章节来源 + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [docs/components/base/application/README.md:1-56](file://docs/components/base/application/README.md#L1-L56) +- [docs/components/base/each/README.md:1-32](file://docs/components/base/each/README.md#L1-L32) +- [docs/components/base/slot/README.md:1-17](file://docs/components/base/slot/README.md#L1-L17) + +## 架构总览 + +基础组件的运行时架构围绕“应用上下文 + 组件基类 + 前端资源解析”展开。组件在构造时会断言已存在 Application 上下文，并通过内部 \_internal 字典传递布局与索引信息给前端；部分组件支持插槽与事件绑定，最终由前端渲染引擎消费。 + +```mermaid +graph TB +APP["Application
应用根容器"] --> CTX["AppContext
全局上下文"] +CTX --> BASE["ModelScopeLayoutComponent / ModelScopeComponent
组件基类"] +BASE --> EACH["Each"] +BASE --> SLOT["Slot"] +BASE --> FILTER["Filter"] +BASE --> FRAG["Fragment"] +BASE --> LAYOUT["Div / Span / Markdown 等布局组件"] +BASE --> AUTO["AutoLoading"] +BASE --> DATA["ModelScopeDataLayoutComponent
带数据模型的布局组件"] +DATA --> APPCOMP["Application"] +DATA --> MARK["Markdown"] +subgraph "前端资源解析" +RESOLVE["resolve_frontend_dir(type='base')"] +end +BASE --> RESOLVE +DATA --> RESOLVE +AUTO --> RESOLVE +LAYOUT --> RESOLVE +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/components/base/markdown/**init**.py:11-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L11-L174) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:8-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L8-L65) +- [backend/modelscope_studio/components/base/div/**init**.py:10-86](file://backend/modelscope_studio/components/base/div/__init__.py#L10-L86) +- [backend/modelscope_studio/components/base/slot/**init**.py:8-50](file://backend/modelscope_studio/components/base/slot/__init__.py#L8-L50) +- [backend/modelscope_studio/components/base/each/**init**.py:17-73](file://backend/modelscope_studio/components/base/each/__init__.py#L17-L73) +- [backend/modelscope_studio/components/base/filter/**init**.py:8-45](file://backend/modelscope_studio/components/base/filter/__init__.py#L8-L45) +- [backend/modelscope_studio/components/base/fragment/**init**.py:8-49](file://backend/modelscope_studio/components/base/fragment/__init__.py#L8-L49) + +## 详细组件分析 + +### Application + +- 导入路径：from modelscope_studio.components.base import Application +- 继承关系：ModelScopeDataLayoutComponent +- 事件： + - mount：页面挂载 + - resize：窗口大小变化 + - unmount：页面卸载 + - custom：通过 window.ms_globals.dispatch 触发的自定义事件 +- 数据模型： + - ApplicationPageScreenData：width、height、scrollX、scrollY + - ApplicationPageData：screen、language、theme、userAgent +- 关键行为： + - 构造时设置 AppContext + - 支持 preprocess/postprocess 原样透传 + - 提供 example_payload/example_value + +章节来源 + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [docs/components/base/application/README.md:1-56](file://docs/components/base/application/README.md#L1-L56) + +### AutoLoading + +- 导入路径：from modelscope_studio.components.base import AutoLoading +- 继承关系：ModelScopeLayoutComponent +- 插槽：render、errorRender、loadingText +- 关键属性： + - generating、show_error、show_mask、show_timer、loading_text +- 关键行为： + - skip_api=True，不参与常规 API 流程 + - preprocess/postprocess 对字符串进行原样处理 + +章节来源 + +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:8-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L8-L65) + +### Slot + +- 导入路径：from modelscope_studio.components.base import Slot +- 继承关系：ModelScopeLayoutComponent +- 关键属性： + - value：插槽名称 + - params_mapping：JS 函数字符串，用于参数映射 +- 关键行为： + - 当父级为 Slot 时，value 会拼接形成层级路径 + - skip_api=True + +章节来源 + +- [backend/modelscope_studio/components/base/slot/**init**.py:8-50](file://backend/modelscope_studio/components/base/slot/__init__.py#L8-L50) +- [docs/components/base/slot/README.md:1-17](file://docs/components/base/slot/README.md#L1-L17) + +### Each + +- 导入路径：from modelscope_studio.components.base import Each +- 继承关系：ModelScopeDataLayoutComponent +- 数据模型：ModelScopeEachData（root: list） +- 关键属性： + - value：list[dict] 或 Callable + - context_value：dict，用于深合并到上下文 + - as_item：字符串，过滤上下文字段 +- 关键行为： + - preprocess 将 ModelScopeEachData 解包为 list + - postprocess 返回 list + - skip_api=False，参与 API 流程 + +章节来源 + +- [backend/modelscope_studio/components/base/each/**init**.py:17-73](file://backend/modelscope_studio/components/base/each/__init__.py#L17-L73) +- [docs/components/base/each/README.md:1-32](file://docs/components/base/each/README.md#L1-L32) + +### Filter + +- 导入路径：from modelscope_studio.components.base import Filter +- 继承关系：ModelScopeLayoutComponent +- 关键属性： + - params_mapping：参数映射字符串 +- 关键行为： + - skip_api=True，不参与 API 流程 + +章节来源 + +- [backend/modelscope_studio/components/base/filter/**init**.py:8-45](file://backend/modelscope_studio/components/base/filter/__init__.py#L8-L45) + +### Fragment + +- 导入路径：from modelscope_studio.components.base import Fragment +- 继承关系：ModelScopeLayoutComponent +- 关键行为： + - skip_api=True，不参与 API 流程 + - 适合逻辑分组与插槽挂载 + +章节来源 + +- [backend/modelscope_studio/components/base/fragment/**init**.py:8-49](file://backend/modelscope_studio/components/base/fragment/__init__.py#L8-L49) + +### Div + +- 导入路径：from modelscope_studio.components.base import Div +- 继承关系：ModelScopeLayoutComponent +- 事件：click、dblclick、mousedown、mouseup、mouseover、mouseout、mousemove、scroll +- 关键属性： + - value：字符串 + - additional_props：字典，附加属性 +- 关键行为： + - skip_api=True + +章节来源 + +- [backend/modelscope_studio/components/base/div/**init**.py:10-86](file://backend/modelscope_studio/components/base/div/__init__.py#L10-L86) + +### Text + +- 导入路径：from modelscope_studio.components.base import Text +- 继承关系：ModelScopeComponent +- 关键行为： + - skip_api=True + +章节来源 + +- [backend/modelscope_studio/components/base/text/**init**.py:8-57](file://backend/modelscope_studio/components/base/text/__init__.py#L8-L57) + +### Span + +- 导入路径：from modelscope_studio.components.base import Span +- 继承关系：ModelScopeLayoutComponent +- 事件：click、dblclick、mousedown、mouseup、mouseover、mouseout、mousemove、scroll +- 关键属性： + - value：字符串 + - additional_props：字典，附加属性 +- 关键行为： + - skip_api=True + +章节来源 + +- [backend/modelscope_studio/components/base/span/**init**.py:10-87](file://backend/modelscope_studio/components/base/span/__init__.py#L10-L87) + +### Markdown + +- 导入路径：from modelscope_studio.components.base import Markdown +- 继承关系：ModelScopeDataLayoutComponent +- 事件：change、copy、click、dblclick、mousedown、mouseup、mouseover、mouseout、mousemove、scroll +- 插槽：copyButtons +- 关键属性： + - value：字符串 + - rtl、latex_delimiters、sanitize_html、line_breaks、header_links、allow_tags、show_copy_button、copy_buttons、additional_props +- 关键行为： + - preprocess 原样返回 + - postprocess 清理缩进并返回字符串 + - api_info 返回 {"type": "string"} + +章节来源 + +- [backend/modelscope_studio/components/base/markdown/**init**.py:11-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L11-L174) + +## 依赖分析 + +- 组件基类与上下文 + - 所有基础组件均依赖 utils/dev/component.py 中的基类（ModelScopeLayoutComponent、ModelScopeComponent、ModelScopeDataLayoutComponent），并在构造时断言 AppContext 存在。 + - utils/dev/app_context.py 提供 set_app/assert_app/get_app，确保组件在 Application 根容器内使用。 + +- 前端资源解析 + - 各组件通过 resolve_frontend_dir("xxx", type="base") 解析前端目录，保证前后端资源一致。 + +```mermaid +graph LR +CTX["AppContext"] --> |assert_app| BASE["组件基类"] +BASE --> |继承| LCOMP["ModelScopeLayoutComponent"] +BASE --> |继承| DCOMP["ModelScopeDataLayoutComponent"] +BASE --> |继承| SCOMP["ModelScopeComponent"] +LCOMP --> |frontend| RES["resolve_frontend_dir('...')"] +DCOMP --> |frontend| RES +SCOMP --> |frontend| RES +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) + +## 性能考虑 + +- 避免不必要的 API 交互 + - 多数基础组件 skip_api=True（如 AutoLoading、Slot、Filter、Fragment、Div/Span/Text/Markdown），不参与常规 API 流程，减少前后端往返开销。 +- 列表渲染优化 + - Each 的 value 支持 Callable，可在复杂场景延迟计算；结合 as_item/context_value 可减少重复属性传递与冲突。 +- 事件绑定 + - 仅在需要时绑定事件（如 Div/Markdown 的鼠标与滚动事件），避免过度绑定导致的前端压力。 +- 内存管理 + - 组件在 **exit** 中统一标记 layout=True，确保前端正确释放与重建；避免在组件树中持有过长生命周期的引用。 +- HTML 清理 + - Markdown 的 postprocess 会对内容进行清理，减少渲染抖动与异常字符影响。 + +## 故障排查指南 + +- 缺少 Application 根容器 + - 现象：出现警告提示未找到 Application 组件。 + - 处理：确保所有组件包裹在 Application 内部。 + - 参考：AppContext.assert_app 的警告信息。 + +- 插槽未生效 + - 现象：Slot 无法插入到目标组件。 + - 处理：确认目标组件 SLOTS 支持该插槽名；检查 params_mapping 是否正确配置。 + +- Each 上下文冲突 + - 现象：多个组件迭代时属性冲突或覆盖。 + - 处理：使用 as_item 进行字段过滤；必要时通过 context_value 深合并统一注入。 + +- AutoLoading 不显示 + - 现象：loading/error/render 插槽未显示。 + - 处理：确认 generating/show_error/show_mask 状态与插槽命名一致。 + +章节来源 + +- [backend/modelscope_studio/utils/dev/app_context.py:16-20](file://backend/modelscope_studio/utils/dev/app_context.py#L16-L20) +- [docs/components/base/slot/README.md:1-17](file://docs/components/base/slot/README.md#L1-L17) +- [docs/components/base/each/README.md:16-22](file://docs/components/base/each/README.md#L16-L22) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:15-46](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L15-L46) + +## 结论 + +基础组件库提供了统一的应用根容器、布局与文本组件、条件与循环渲染辅助组件以及插槽系统。通过严格的上下文约束与前端资源解析机制，确保组件在 Gradio 生态中的稳定运行。建议优先使用 Each 的 as_item 与 context_value 进行上下文管理，合理选择 skip_api 组件以降低 API 开销，并在需要时利用 Application 的生命周期事件与自定义事件实现页面行为控制。 + +## 附录：使用示例与最佳实践 + +### 应用容器与页面环境 + +- 在应用最外层包裹 Application，并监听页面生命周期事件。 +- 通过 Application 的 value 获取用户语言、主题、屏幕信息与 UA。 + +章节来源 + +- [docs/components/base/application/README.md:12-20](file://docs/components/base/application/README.md#L12-L20) +- [backend/modelscope_studio/components/base/application/**init**.py:30-54](file://backend/modelscope_studio/components/base/application/__init__.py#L30-L54) + +### 条件渲染（Filter） + +- 使用 Filter 根据 params_mapping 决定是否渲染子树。 +- 适用于根据上下文参数动态隐藏/显示部分内容。 + +章节来源 + +- [backend/modelscope_studio/components/base/filter/**init**.py:13-25](file://backend/modelscope_studio/components/base/filter/__init__.py#L13-L25) + +### 循环遍历（Each） + +- Each 接收列表或可调用对象，注入上下文；支持 as_item 与 context_value。 +- 适用于不确定长度的列表渲染与统一属性注入。 + +章节来源 + +- [docs/components/base/each/README.md:7-22](file://docs/components/base/each/README.md#L7-L22) +- [backend/modelscope_studio/components/base/each/**init**.py:23-52](file://backend/modelscope_studio/components/base/each/__init__.py#L23-L52) + +### 插槽系统（Slot） + +- Slot 与目标组件的 SLOTS 协作，params_mapping 支持参数映射。 +- 适用于复杂布局与可插拔内容区。 + +章节来源 + +- [docs/components/base/slot/README.md:1-17](file://docs/components/base/slot/README.md#L1-L17) +- [backend/modelscope_studio/components/base/slot/**init**.py:13-30](file://backend/modelscope_studio/components/base/slot/__init__.py#L13-L30) + +### 自动加载（AutoLoading） + +- 包裹可能耗时的操作区域，使用 render/errorRender/loadingText 插槽。 +- 控制遮罩、计时器与错误展示，提升用户体验。 + +章节来源 + +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:17-46](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L17-L46) + +### 布局与文本组件 + +- Div/Span：用于基础块级/行内布局，支持多种鼠标与滚动事件。 +- Text/Markdown：文本渲染，Markdown 支持复制按钮与 LaTeX 表达式配置。 + +章节来源 + +- [backend/modelscope_studio/components/base/div/**init**.py:44-67](file://backend/modelscope_studio/components/base/div/__init__.py#L44-L67) +- [backend/modelscope_studio/components/base/span/**init**.py:44-67](file://backend/modelscope_studio/components/base/span/__init__.py#L44-L67) +- [backend/modelscope_studio/components/base/text/**init**.py:17-37](file://backend/modelscope_studio/components/base/text/__init__.py#L17-L37) +- [backend/modelscope_studio/components/base/markdown/**init**.py:54-141](file://backend/modelscope_studio/components/base/markdown/__init__.py#L54-L141) + +### 组件继承与扩展开发 + +- 新组件建议继承相应基类： + - 需要数据模型与布局：ModelScopeDataLayoutComponent + - 仅需布局：ModelScopeLayoutComponent + - 纯组件：ModelScopeComponent +- 在构造函数中设置 FRONTEND_DIR，确保前端资源正确解析。 +- 如需插槽，定义 SLOTS 并在文档中说明支持的插槽名与用途。 + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/Ant Design X \347\273\204\344\273\266\345\272\223.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/Ant Design X \347\273\204\344\273\266\345\272\223.md" new file mode 100644 index 00000000..e4539818 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/Ant Design X \347\273\204\344\273\266\345\272\223.md" @@ -0,0 +1,626 @@ +# Ant Design X 组件库 + + +**本文引用的文件** +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/antdx/file_card/__init__.py](file://backend/modelscope_studio/components/antdx/file_card/__init__.py) +- [backend/modelscope_studio/components/antdx/file_card/list/__init__.py](file://backend/modelscope_studio/components/antdx/file_card/list/__init__.py) +- [backend/modelscope_studio/components/antdx/file_card/list/item/__init__.py](file://backend/modelscope_studio/components/antdx/file_card/list/item/__init__.py) +- [backend/modelscope_studio/components/antdx/mermaid/__init__.py](file://backend/modelscope_studio/components/antdx/mermaid/__init__.py) +- [backend/modelscope_studio/components/antdx/folder/directory_icon/__init__.py](file://backend/modelscope_studio/components/antdx/folder/directory_icon/__init__.py) +- [backend/modelscope_studio/components/antdx/folder/tree_node/__init__.py](file://backend/modelscope_studio/components/antdx/folder/tree_node/__init__.py) +- [frontend/antdx/file-card/file-card.tsx](file://frontend/antdx/file-card/file-card.tsx) +- [frontend/antdx/file-card/base.tsx](file://frontend/antdx/file-card/base.tsx) +- [frontend/antdx/mermaid/mermaid.tsx](file://frontend/antdx/mermaid/mermaid.tsx) +- [frontend/antdx/folder/folder.tsx](file://frontend/antdx/folder/folder.tsx) +- [frontend/antdx/thought-chain/thought-chain.tsx](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [frontend/antdx/conversations/conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [frontend/antdx/welcome/welcome.tsx](file://frontend/antdx/welcome/welcome.tsx) +- [frontend/antdx/prompts/prompts.tsx](file://frontend/antdx/prompts/prompts.tsx) +- [frontend/antdx/attachments/attachments.tsx](file://frontend/antdx/attachments/attachments.tsx) +- [frontend/antdx/sender/sender.tsx](file://frontend/antdx/sender/sender.tsx) +- [frontend/antdx/suggestion/suggestion.tsx](file://frontend/antdx/suggestion/suggestion.tsx) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/think/think.tsx](file://frontend/antdx/think/think.tsx) +- [frontend/antdx/notification/notification.tsx](file://frontend/antdx/notification/notification.tsx) +- [frontend/antdx/sources/sources.tsx](file://frontend/antdx/sources/sources.tsx) + + +## 更新摘要 + +**所做更改** + +- 新增文件卡片组件体系（FileCard、FileCardList、FileCardListItem） +- 新增 Mermaid 图表组件 +- 新增文件夹组件（Folder）及其子组件（DirectoryIcon、TreeNode） +- 新增思考链组件（ThoughtChain）及其子组件 +- 更新组件导出结构，与 Ant Design X 版本保持同步 +- 增强组件间协作能力，支持更丰富的插槽化渲染 + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能与可用性建议](#性能与可用性建议) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向 ModelScope Studio 的 Ant Design X 组件库，聚焦于机器学习与 AI 应用场景下的专用组件。文档系统性梳理通用组件（如气泡、会话列表）、唤醒组件（欢迎页、提示词）、表达组件（附件、发送器、建议）、确认组件（思考链）、反馈组件（动作）等，并新增文件卡片、Mermaid 图表、文件夹等高级组件。提供端到端示例思路与最佳实践，帮助开发者在对话式 AI、多模态输入、知识检索增强、图表可视化等场景下构建一致、可扩展且体验友好的界面。 + +## 项目结构 + +Ant Design X 组件库在后端通过 Python 包导出，在前端以 Svelte/React 双向桥接的方式封装 @ant-design/x 的能力，统一对外暴露为可组合的组件。整体结构如下： + +```mermaid +graph TB +subgraph "后端导出层" +A["backend/modelscope_studio/components/antdx/__init__.py"] +B["backend/modelscope_studio/components/antdx/components.py"] +end +subgraph "前端封装层" +C["frontend/antdx/bubble/bubble.tsx"] +D["frontend/antdx/conversations/conversations.tsx"] +E["frontend/antdx/welcome/welcome.tsx"] +F["frontend/antdx/prompts/prompts.tsx"] +G["frontend/antdx/attachments/attachments.tsx"] +H["frontend/antdx/sender/sender.tsx"] +I["frontend/antdx/suggestion/suggestion.tsx"] +J["frontend/antdx/actions/actions.tsx"] +K["frontend/antdx/think/think.tsx"] +L["frontend/antdx/notification/notification.tsx"] +M["frontend/antdx/sources/sources.tsx"] +N["frontend/antdx/file-card/file-card.tsx"] +O["frontend/antdx/mermaid/mermaid.tsx"] +P["frontend/antdx/folder/folder.tsx"] +Q["frontend/antdx/thought-chain/thought-chain.tsx"] +end +A --> C +A --> D +A --> E +A --> F +A --> G +A --> H +A --> I +A --> J +A --> K +A --> L +A --> M +A --> N +A --> O +A --> P +A --> Q +B --> C +B --> D +B --> E +B --> F +B --> G +B --> H +B --> I +B --> J +B --> K +B --> L +B --> M +B --> N +B --> O +B --> P +B --> Q +``` + +**图示来源** + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## 核心组件 + +本节对 AI 场景关键组件进行分类与功能概览，包括新增的高级组件，便于快速定位与组合使用。 + +- 通用组件 + - 气泡 Bubble：用于展示消息内容、头像、额外信息与脚注，支持插槽化渲染与可编辑配置。 + - 会话列表 Conversations：用于展示与管理历史会话，支持菜单、分组与展开控制。 +- 唤醒组件 + - 欢迎页 Welcome：用于应用启动或重置后的引导页面，支持标题、描述、图标与附加区域。 + - 提示词 Prompts：用于展示一组可点击的提示词模板，辅助用户快速开始对话。 +- 表达组件 + - 附件 Attachments：用于上传与管理文件，支持占位、预览、图片属性与上传钩子。 + - 发送器 Sender：用于输入文本与粘贴文件上传，支持技能提示、前缀/后缀与提交拦截。 + - 建议 Suggestion：用于输入上下文中的自动补全/建议面板，支持触发策略与插槽化项渲染。 +- 确认组件 + - 思考 Think：用于展示推理过程中的加载状态、图标与标题，提升可感知性。 + - 思考链 ThoughtChain：用于展示多步骤推理过程，支持子项组件与插槽化渲染。 +- 反馈组件 + - 动作 Actions：用于在内容区右侧提供操作入口（如复制、下载、反馈），支持下拉菜单与弹出渲染。 +- 高级组件 + - 文件卡片 FileCard：用于展示文件信息，支持多种类型、预览、遮罩与加载状态。 + - Mermaid 图表：用于渲染 Mermaid 流程图、序列图等，支持主题切换与自定义动作。 + - 文件夹 Folder：用于文件系统浏览，支持目录图标映射、文件内容服务与预览渲染。 +- 工具组件 + - XProvider：全局配置与上下文提供器，扩展 antd 的 ConfigProvider，统一为 @ant-design/x 组件提供主题、语言、弹层容器等全局能力。 + - CodeHighlighter：代码高亮展示组件，支持主题定制、头部插槽、语法高亮样式覆盖。 + - Mermaid：流程图/思维导图组件，集成高亮与动作项渲染，支持深浅主题切换与自定义动作。 + - Notification：浏览器通知封装，提供权限请求、打开/关闭、可见性控制与回调。 +- 数据组件 + - FileCard：用于展示单个文件卡片，支持图片占位、预览配置、遮罩与加载指示器的插槽化定制。 + - Folder：用于展示文件夹树形结构，支持 treeData、directoryIcons、空态渲染、目录标题、预览渲染等插槽。 + - Sources：用于展示数据源列表，支持 items 与 title 插槽。 + - Think：用于展示“思考”记录与状态，支持 loading、icon、title 插槽，便于在不同状态下显示不同的视觉反馈。 + +**章节来源** + +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/welcome/welcome.tsx:1-44](file://frontend/antdx/welcome/welcome.tsx#L1-L44) +- [frontend/antdx/prompts/prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) +- [frontend/antdx/suggestion/suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) +- [frontend/antdx/think/think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) + +## 架构总览 + +下图展示了前端组件如何桥接到 @ant-design/x 并通过插槽与函数包装实现灵活渲染与事件处理，包括新增组件的架构。 + +```mermaid +graph TB +subgraph "前端封装" +U["sveltify 封装
slot 渲染/函数包装"] +V["@ant-design/x 原生组件"] +W["工具与上下文
renderItems / renderParamsSlot / useFunction"] +X["文件服务与资源解析
getFetchableUrl / resolveFileSrc"] +Y["主题与样式
themeMode / highlightProps"] +end +U --> V +U --> W +U --> X +U --> Y +``` + +**图示来源** + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) + +## 组件详解 + +### 通用组件 + +#### 气泡 Bubble + +- 能力要点 + - 支持头像、标题、内容、底部、额外区域等插槽化渲染。 + - 支持可编辑配置（含"确定/取消"文案插槽）。 + - 支持加载态与内容渲染函数包装。 +- 使用建议 + - 在对话流中作为消息载体，结合 Sender 输入与 Attachments 附件使用。 + - 对长内容建议开启可编辑与内容渲染函数，提升交互效率。 +- 关键路径 + - [frontend/antdx/bubble/bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) + +**章节来源** + +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) + +#### 会话列表 Conversations + +- 能力要点 + - 支持菜单项、溢出指示器、展开图标等插槽化配置。 + - 支持分组与折叠行为的函数化配置。 + - 内部复用菜单上下文，统一事件传播与 DOM 阻断。 +- 使用建议 + - 与 Sender/Attachments 配合，形成"输入-生成-回看"的闭环。 + - 通过菜单项实现"删除、重命名、导出"等操作。 +- 关键路径 + - [frontend/antdx/conversations/conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) + +**章节来源** + +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) + +### 唤醒组件 + +#### 欢迎页 Welcome + +- 能力要点 + - 支持标题、描述、图标与附加区域的插槽化。 + - 图标支持传入文件数据并自动解析为可访问 URL。 +- 使用建议 + - 作为应用初始化或会话重置后的首屏引导。 +- 关键路径 + - [frontend/antdx/welcome/welcome.tsx:8-41](file://frontend/antdx/welcome/welcome.tsx#L8-L41) + +**章节来源** + +- [frontend/antdx/welcome/welcome.tsx:1-44](file://frontend/antdx/welcome/welcome.tsx#L1-L44) + +#### 提示词 Prompts + +- 能力要点 + - 支持标题插槽与项集合的插槽化渲染。 + - 通过上下文提供项集合，简化外部传参。 +- 使用建议 + - 在欢迎页或输入框上方放置，帮助用户快速选择意图模板。 +- 关键路径 + - [frontend/antdx/prompts/prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) + +**章节来源** + +- [frontend/antdx/prompts/prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) + +### 表达组件 + +#### 附件 Attachments + +- 能力要点 + - 支持占位、预览、图片属性、上传钩子与最大数量限制。 + - 支持自定义 beforeUpload、customRequest、isImageUrl、previewFile 等函数。 + - 通过插槽化扩展"额外图标、下载/移除/预览图标、占位内容"等。 +- 使用建议 + - 与 Sender 的粘贴上传配合，实现拖拽/粘贴即传。 + - 注意 maxCount 与上传状态的联动，避免并发冲突。 +- 关键路径 + - [frontend/antdx/attachments/attachments.tsx:36-410](file://frontend/antdx/attachments/attachments.tsx#L36-L410) + +**章节来源** + +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) + +#### 发送器 Sender + +- 能力要点 + - 支持前缀/后缀/头部/底部插槽；支持"技能提示"配置。 + - 支持粘贴文件上传回调，统一输出文件路径数组。 + - 通过值变化钩子与提交拦截，避免在建议面板打开时误提交。 +- 使用建议 + - 与 Suggestion 协作，确保建议面板关闭后再提交。 + - 通过 onValueChange 与后端流式输出对接。 +- 关键路径 + - [frontend/antdx/sender/sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) + +**章节来源** + +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) + +#### 建议 Suggestion + +- 能力要点 + - 支持 items 插槽化与 children 插槽化渲染。 + - 通过上下文传递键盘事件与触发逻辑，支持自定义 shouldTrigger。 + - 支持 getPopupContainer 函数化配置。 +- 使用建议 + - 与 Sender/Textarea 结合，实现@提及、/命令、关键词补全。 + - 控制 open 状态与 shouldTrigger，避免在输入法组合字阶段触发。 +- 关键路径 + - [frontend/antdx/suggestion/suggestion.tsx:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) + +**章节来源** + +- [frontend/antdx/suggestion/suggestion.tsx:1-165](file://frontend/antdx/suggestion/suggestion.tsx#L1-L165) + +### 确认组件 + +#### 思考 Think + +- 能力要点 + - 展示推理过程中的加载态、图标与标题，提升可感知性。 + - 支持插槽化覆盖默认渲染。 +- 使用建议 + - 在流式输出前插入，明确告知用户模型正在思考。 +- 关键路径 + - [frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +**章节来源** + +- [frontend/antdx/think/think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +#### 思考链 ThoughtChain + +- 能力要点 + - 支持多步骤推理过程展示，内置默认与子项渲染逻辑。 + - 通过上下文提供项集合，支持插槽化与默认项回退。 + - 复用通用渲染工具，保持与其它组件的一致性。 +- 使用建议 + - 在复杂推理场景中展示逐步思考过程。 + - 与 Bubble 组件配合，形成完整的推理展示链路。 +- 关键路径 + - [frontend/antdx/thought-chain/thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) + +**章节来源** + +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) + +### 反馈组件 + +#### 动作 Actions + +- 能力要点 + - 支持下拉菜单、弹出渲染与菜单项插槽化。 + - 复用菜单上下文，统一事件传播。 +- 使用建议 + - 在 Bubble 或内容卡片右侧提供"复制、下载、反馈"等操作。 +- 关键路径 + - [frontend/antdx/actions/actions.tsx:17-120](file://frontend/antdx/actions/actions.tsx#L17-L120) + +**章节来源** + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) + +### 高级组件 + +#### 文件卡片 FileCard + +- 能力要点 + - 支持多种文件类型（image、file、audio、video）展示。 + - 支持图标、描述、遮罩、加载状态等插槽化配置。 + - 内置图片预览功能，支持自定义预览容器与工具栏。 + - 自动解析文件源，支持本地文件与远程 URL。 +- 使用建议 + - 在文件上传完成后展示文件信息。 + - 与文件列表组件配合，形成完整的文件管理界面。 +- 关键路径 + - [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) + - [frontend/antdx/file-card/base.tsx:15-41](file://frontend/antdx/file-card/base.tsx#L15-L41) + +**章节来源** + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) + +#### Mermaid 图表 + +- 能力要点 + - 支持 Mermaid 语法图表渲染，包括流程图、序列图等。 + - 内置语法高亮，支持明暗主题切换。 + - 支持自定义动作按钮与头部插槽。 + - 复用动作组件上下文，保持一致的交互体验。 +- 使用建议 + - 在文档生成或流程展示场景中使用。 + - 结合思考链组件，展示复杂的算法流程。 +- 关键路径 + - [frontend/antdx/mermaid/mermaid.tsx:33-82](file://frontend/antdx/mermaid/mermaid.tsx#L33-L82) + +**章节来源** + +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) + +#### 文件夹 Folder + +- 能力要点 + - 支持文件系统浏览与目录结构展示。 + - 支持自定义目录图标映射与节点渲染。 + - 内置文件内容服务，支持动态加载文件内容。 + - 支持空态渲染、预览渲染与标题插槽化。 +- 使用建议 + - 在知识库或工程文件管理场景中使用。 + - 与文件卡片组件配合，提供完整的文件浏览体验。 +- 关键路径 + - [frontend/antdx/folder/folder.tsx:16-121](file://frontend/antdx/folder/folder.tsx#L16-L121) + +**章节来源** + +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) + +### 其他实用组件 + +#### 通知 Notification + +- 能力要点 + - 基于浏览器通知权限的轻量提示，支持可见性控制与权限回调。 +- 使用建议 + - 在后台任务完成或重要事件发生时推送桌面通知。 +- 关键路径 + - [frontend/antdx/notification/notification.tsx:6-50](file://frontend/antdx/notification/notification.tsx#L6-L50) + +**章节来源** + +- [frontend/antdx/notification/notification.tsx:1-51](file://frontend/antdx/notification/notification.tsx#L1-L51) + +#### 来源 Sources + +- 能力要点 + - 支持标题插槽与项集合的插槽化渲染。 +- 使用建议 + - 在回答末尾展示引用来源，增强可信度。 +- 关键路径 + - [frontend/antdx/sources/sources.tsx:9-41](file://frontend/antdx/sources/sources.tsx#L9-L41) + +**章节来源** + +- [frontend/antdx/sources/sources.tsx:1-42](file://frontend/antdx/sources/sources.tsx#L1-L42) + +## 依赖关系分析 + +- 后端导出层 + - 通过 **init**.py 与 components.py 将 Ant Design X 组件统一导出，包括新增的文件卡片、Mermaid、文件夹等组件。 +- 前端封装层 + - 所有组件均采用 sveltify 包裹，统一处理插槽、函数包装与事件透传。 + - 大量使用 renderItems、renderParamsSlot、useFunction 等工具，保证渲染一致性与灵活性。 + - 多数组件复用菜单与项集合上下文，降低重复配置成本。 + - 新增组件引入文件服务解析与主题切换机制。 + +```mermaid +graph LR +P["Python 导出
__init__.py / components.py
新增组件导出"] --> Q["Svelte/React 封装
sveltify + 新增组件"] +Q --> R["工具与渲染
renderItems / renderParamsSlot / useFunction"] +Q --> S["上下文提供者
menu/items/context + 新增上下文"] +Q --> T["@ant-design/x 原生组件"] +Q --> U["文件服务
getFetchableUrl / resolveFileSrc"] +Q --> V["主题系统
themeMode / highlightProps"] +``` + +**图示来源** + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## 性能与可用性建议 + +- 渲染优化 + - 使用 useMemo 包裹复杂计算结果（如菜单项、建议项、树数据、文件列表），减少不必要的重渲染。 + - 合理拆分插槽渲染，避免在父级频繁变更导致子级插槽重复挂载。 + - 对大型文件列表使用虚拟滚动，提升渲染性能。 +- 事件与状态 + - 在建议面板打开期间拦截提交，避免误触发。 + - 上传过程中禁用交互或显示进度，防止重复上传。 + - 文件卡片组件支持懒加载，避免一次性渲染过多图片。 +- 可访问性 + - 为图标与按钮提供替代文本，确保屏幕阅读器友好。 + - 为通知与提示提供键盘可达性与焦点管理。 + - Mermaid 图表提供无障碍标签，支持屏幕阅读器朗读。 +- 数据一致性 + - 上传成功后统一更新文件列表，避免状态漂移。 + - 在流式输出场景中，保持"思考态-内容态-动作态"的清晰过渡。 + - 文件服务采用缓存机制，避免重复加载相同文件。 +- 主题适配 + - Mermaid 组件自动适配主题模式，确保图表可读性。 + - 文件卡片支持暗色模式，提升视觉体验。 + +## 故障排查指南 + +- 插槽未生效 + - 检查是否正确传入 slots 对象与对应 key 名称。 + - 确认插槽渲染函数是否被正确包裹为可执行函数。 +- 上传失败或卡住 + - 核查 beforeUpload/customRequest/isImageUrl 等函数返回值与异常处理。 + - 检查 maxCount 与当前文件列表长度，避免超出限制。 +- 建议面板不出现 + - 确认 shouldTrigger 触发条件与输入焦点状态。 + - 检查 open 状态与 getPopupContainer 容器是否存在。 +- 通知未显示 + - 确认浏览器通知权限已授予，必要时调用请求权限流程。 +- 菜单事件异常 + - 检查 onClick 是否被正确阻止冒泡，避免影响外层交互。 +- 文件卡片显示异常 + - 检查文件源解析是否正确，确认 getFetchableUrl 函数正常工作。 + - 确认文件类型与图标映射是否匹配。 +- Mermaid 图表渲染失败 + - 检查 Mermaid 语法是否正确，确认图表类型支持。 + - 确认主题模式配置是否正确。 +- 文件夹组件无响应 + - 检查文件内容服务是否正确实现，确认异步加载函数正常工作。 + - 确认目录图标映射与节点数据格式是否正确。 + +**章节来源** + +- [frontend/antdx/attachments/attachments.tsx:275-354](file://frontend/antdx/attachments/attachments.tsx#L275-L354) +- [frontend/antdx/sender/sender.tsx:126-130](file://frontend/antdx/sender/sender.tsx#L126-L130) +- [frontend/antdx/suggestion/suggestion.tsx:135-140](file://frontend/antdx/suggestion/suggestion.tsx#L135-L140) +- [frontend/antdx/notification/notification.tsx:20-46](file://frontend/antdx/notification/notification.tsx#L20-L46) +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/mermaid/mermaid.tsx:33-82](file://frontend/antdx/mermaid/mermaid.tsx#L33-L82) +- [frontend/antdx/folder/folder.tsx:16-121](file://frontend/antdx/folder/folder.tsx#L16-L121) + +## 结论 + +Ant Design X 组件库在 ModelScope Studio 中为 AI 应用提供了从"输入-生成-反馈-确认-展示"的完整闭环。通过统一的插槽化与函数包装机制，组件既保持了与 @ant-design/x 的强一致性，又增强了在多模态、对话式、图表可视化场景下的可定制性与可维护性。新增的文件卡片、Mermaid 图表、文件夹等组件进一步丰富了 AI 应用的展示能力。建议在实际项目中遵循"先模板后生成、先思考后展示、先确认再提交"的交互节奏，结合最佳实践持续优化性能与可访问性。 + +## 附录 + +### 组件协作与集成示例（概念流程） + +以下为典型"问答+附件+图表+文件管理"的端到端流程示意，帮助理解新增组件间的协作方式。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant W as "欢迎页 Welcome" +participant P as "提示词 Prompts" +participant S as "发送器 Sender" +participant A as "附件 Attachments" +participant B as "气泡 Bubble" +participant T as "思考 Think" +participant TC as "思考链 ThoughtChain" +participant X as "动作 Actions" +participant So as "来源 Sources" +participant FC as "文件卡片 FileCard" +participant M as "Mermaid 图表" +U->>W : 打开应用 +W-->>U : 展示欢迎页 +U->>P : 点击提示词 +P-->>S : 回填输入内容 +U->>A : 上传附件 +A-->>FC : 渲染文件卡片 +U->>S : 提交问题 +S-->>T : 显示思考态 +T-->>TC : 展示推理过程 +TC-->>B : 展示生成内容 +B-->>X : 右侧提供动作 +B-->>So : 展示引用来源 +U->>B : 查看图表 +B-->>M : 渲染 Mermaid 图表 +``` + +**图示来源** + +- [frontend/antdx/welcome/welcome.tsx:8-41](file://frontend/antdx/welcome/welcome.tsx#L8-L41) +- [frontend/antdx/prompts/prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) +- [frontend/antdx/sender/sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) +- [frontend/antdx/attachments/attachments.tsx:36-410](file://frontend/antdx/attachments/attachments.tsx#L36-L410) +- [frontend/antdx/bubble/bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) +- [frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) +- [frontend/antdx/thought-chain/thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [frontend/antdx/actions/actions.tsx:17-120](file://frontend/antdx/actions/actions.tsx#L17-L120) +- [frontend/antdx/sources/sources.tsx:9-41](file://frontend/antdx/sources/sources.tsx#L9-L41) +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/mermaid/mermaid.tsx:33-82](file://frontend/antdx/mermaid/mermaid.tsx#L33-L82) + +### 新增组件功能对比表 + +| 组件类别 | 组件名称 | 主要功能 | 适用场景 | +| -------- | ---------------------- | ---------------------------- | -------------------------- | +| 通用组件 | 气泡 Bubble | 消息内容展示、头像、额外信息 | 对话界面、消息展示 | +| 通用组件 | 会话列表 Conversations | 历史会话管理、菜单操作 | 会话管理、历史记录 | +| 唤醒组件 | 欢迎页 Welcome | 应用引导、初始化界面 | 首次访问、重置界面 | +| 唤醒组件 | 提示词 Prompts | 模板化提示词、快速开始 | 引导用户、提高效率 | +| 表达组件 | 附件 Attachments | 文件上传管理、预览 | 多模态输入、文件处理 | +| 表达组件 | 发送器 Sender | 文本输入、粘贴上传 | 用户输入、实时交互 | +| 表达组件 | 建议 Suggestion | 自动补全、建议面板 | 提升输入效率、智能提示 | +| 确认组件 | 思考 Think | 推理过程指示、加载状态 | 流式输出、状态反馈 | +| 确认组件 | 思考链 ThoughtChain | 多步骤推理展示 | 复杂算法、流程展示 | +| 反馈组件 | 动作 Actions | 操作入口、菜单渲染 | 内容操作、快捷功能 | +| 高级组件 | 文件卡片 FileCard | 文件信息展示、预览 | 文件管理、内容展示 | +| 高级组件 | Mermaid 图表 | 流程图、序列图渲染 | 文档生成、算法展示 | +| 高级组件 | 文件夹 Folder | 文件系统浏览、内容服务 | 知识库、工程管理 | +| 工具组件 | XProvider | 全局配置、主题/语言提供器 | 应用根节点、全局配置 | +| 工具组件 | CodeHighlighter | 代码高亮、主题定制 | 代码展示、文档生成 | +| 数据组件 | Sources | 数据源列表展示、标题插槽 | 引用来源展示、知识检索增强 | +| 数据组件 | Think | 思考状态展示、插槽化 | AI 思考过程可视化 | + +**章节来源** + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/mermaid/mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/ActionItem \346\223\215\344\275\234\351\241\271.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/ActionItem \346\223\215\344\275\234\351\241\271.md" new file mode 100644 index 00000000..715b1d3c --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/ActionItem \346\223\215\344\275\234\351\241\271.md" @@ -0,0 +1,258 @@ +# ActionItem 操作项 + + +**本文引用的文件** +- [frontend/antdx/actions/action-item/Index.svelte](file://frontend/antdx/actions/action-item/Index.svelte) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [backend/modelscope_studio/components/antdx/actions/__init__.py](file://backend/modelscope_studio/components/antdx/actions/__init__.py) +- [backend/modelscope_studio/components/antdx/actions/action_item/__init__.py](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py) +- [backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js](file://backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：使用示例与参数参考](#附录使用示例与参数参考) + +## 简介 + +ActionItem 是 Ant Design X Actions 组件体系中的核心子组件，用于在 Actions 容器中呈现单个可点击或可交互的操作项。它支持多种形态（文本、图标、自定义渲染）、嵌套子菜单、危险态、触发策略（悬停/点击）以及通过插槽扩展内容的能力。该组件同时提供前端 Svelte 包装层与后端 Gradio Python 封装层，形成“Python 配置 + 前端渲染”的完整链路。 + +## 项目结构 + +ActionItem 所在的目录与相关文件组织如下： + +- 前端包装层（Svelte）：frontend/antdx/actions/action-item/Index.svelte +- 前端主组件（React）：frontend/antdx/actions/actions.tsx（包含主 Actions 组件） +- 后端封装层（Gradio Python）：backend/modelscope_studio/components/antdx/actions/action_item/**init**.py +- 前端桥接与运行时（打包产物）：backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js +- 后端 Actions 主组件：backend/modelscope_studio/components/antdx/actions/**init**.py + +```mermaid +graph TB +subgraph "后端" +PY_INIT["Python: actions/__init__.py
定义 AntdXActions"] +PY_ITEM["Python: action_item/__init__.py
定义 AntdXActionsActionItem"] +end +subgraph "前端" +SVELTE["Svelte: action-item/Index.svelte
包装 React 组件"] +REACT_MAIN["React: actions.tsx
主 Actions 组件"] +RUNTIME["JS 运行时: actions.action-item-*.js
桥接与渲染逻辑"] +end +PY_ITEM --> SVELTE +SVELTE --> RUNTIME +PY_INIT --> REACT_MAIN +REACT_MAIN --> RUNTIME +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/actions/**init**.py:15-94](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L94) +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:10-62](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L10-L62) +- [frontend/antdx/actions/action-item/Index.svelte:14-98](file://frontend/antdx/actions/action-item/Index.svelte#L14-L98) +- [frontend/antdx/actions/actions.tsx:1-200](file://frontend/antdx/actions/actions.tsx#L1-L200) +- [backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js:419-431](file://backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js#L419-L431) + +章节来源 + +- [backend/modelscope_studio/components/antdx/actions/**init**.py:15-94](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L94) +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:10-62](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L10-L62) +- [frontend/antdx/actions/action-item/Index.svelte:14-98](file://frontend/antdx/actions/action-item/Index.svelte#L14-L98) +- [frontend/antdx/actions/actions.tsx:1-200](file://frontend/antdx/actions/actions.tsx#L1-L200) +- [backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js:419-431](file://backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js#L419-L431) + +## 核心组件 + +- AntdXActionsActionItem（后端封装）：负责将 Python 层的配置映射到前端组件，并声明事件与插槽能力。 +- ActionsActionItem（前端桥接）：由 Svelte 包装层动态导入并渲染，负责处理插槽、附加属性、事件映射与可见性控制。 +- Actions（主组件）：AntdXActions 的前端实现，承载多个 ActionItem 并提供下拉、动画等高级特性。 + +关键职责与关系 + +- 后端封装：定义 ActionItem 的参数、事件、插槽；决定前端资源路径。 +- 前端包装：解析 props、处理插槽、生成最终渲染所需的 props 与 slots。 +- 运行时桥接：将 Svelte/React 渲染树与 Gradio 上下文打通，支持事件透传与上下文合并。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:10-62](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L10-L62) +- [frontend/antdx/actions/action-item/Index.svelte:19-84](file://frontend/antdx/actions/action-item/Index.svelte#L19-L84) +- [backend/modelscope_studio/components/antdx/actions/**init**.py:15-94](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L94) + +## 架构总览 + +ActionItem 的调用链从 Python 到前端的完整流程如下： + +```mermaid +sequenceDiagram +participant Py as "Python : AntdXActionsActionItem" +participant Svelte as "Svelte : action-item/Index.svelte" +participant Runtime as "JS 运行时 : actions.action-item-*.js" +participant React as "React : actions.tsx" +Py->>Svelte : 传递组件配置与事件绑定 +Svelte->>Runtime : 导入并实例化 ActionsActionItem +Runtime->>React : 渲染 React 版本的 ActionItem +React-->>Runtime : 触发事件回调如 item_click +Runtime-->>Svelte : 事件回传至 Gradio +Svelte-->>Py : 事件结果返回 +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:15-21](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L15-L21) +- [frontend/antdx/actions/action-item/Index.svelte:14-98](file://frontend/antdx/actions/action-item/Index.svelte#L14-L98) +- [backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js:419-431](file://backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js#L419-L431) +- [frontend/antdx/actions/actions.tsx:1-200](file://frontend/antdx/actions/actions.tsx#L1-L200) + +## 详细组件分析 + +### 后端封装：AntdXActionsActionItem + +- 事件绑定 + - item_click：当操作项被点击时触发，后端通过内部标志位启用事件绑定。 +- 插槽支持 + - 支持 label、icon、actionRender、subItems 等插槽，便于灵活扩展。 +- 关键属性 + - label、icon、danger、trigger_sub_menu_action、sub_items、action_render、as_item、key 等。 +- 资源定位 + - 使用 resolve_frontend_dir("actions", "action-item", type="antdx") 指定前端资源目录。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:10-62](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L10-L62) +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:15-21](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L15-L21) +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:24](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L24) + +### 前端包装：Svelte 包装层 + +- 动态导入 + - 通过 importComponent 动态加载 React 版本的 ActionItem。 +- Props 处理 + - 使用 getProps/processProps 提取并转换 props，将 item_click 映射为前端事件名。 + - 合并 elem_id、elem_classes、elem_style、additionalProps 等。 +- 插槽处理 + - 通过 getSlots 获取插槽内容，并对 actionRender 设置 withParams 与 clone。 +- 可见性与索引 + - 根据 visible 控制渲染；传入 itemIndex 与 itemSlotKey 以配合上下文。 + +章节来源 + +- [frontend/antdx/actions/action-item/Index.svelte:14-98](file://frontend/antdx/actions/action-item/Index.svelte#L14-L98) + +### 运行时桥接：JS 运行时 + +- 组件桥接 + - 通过 Ge(...) 创建 Svelte-React 桥接实例，将 React 组件挂载到共享根节点。 +- 上下文与插槽 + - 使用 createItemsContext 提供 items 上下文，支持默认插槽与子项渲染。 +- 事件与属性透传 + - 将 Gradio 上下文与 props 合并，确保事件与样式正确传递。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js:419-431](file://backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js#L419-L431) + +### 主组件：AntdXActions（关联） + +- 作用 + - 作为 ActionItem 的容器，提供 items 列表、变体、下拉配置、动画等能力。 +- 事件与插槽 + - 支持 click、dropdown*open_change、dropdown_menu*\* 系列事件与多处插槽。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/actions/**init**.py:15-94](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L15-L94) + +## 依赖关系分析 + +- 后端到前端 + - AntdXActionsActionItem 通过 FRONTEND_DIR 指向前端资源，Svelte 包装层动态导入对应 JS 模块。 +- 前端到运行时 + - Svelte 包装层将 props 与 slots 传给运行时桥接模块，后者负责渲染 React 组件并与 Gradio 上下文集成。 +- 组件间协作 + - ActionItem 通常作为 Actions 的子项存在，二者共同构成操作面板。 + +```mermaid +graph LR +PY_ITEM["Python: ActionItem 封装"] --> SVELTE["Svelte: 包装层"] +SVELTE --> RUNTIME["JS: 桥接与渲染"] +RUNTIME --> REACT_MAIN["React: Actions 主组件"] +REACT_MAIN --> ACTIONITEM["React: ActionItem 子项"] +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:62](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L62) +- [frontend/antdx/actions/action-item/Index.svelte:14-98](file://frontend/antdx/actions/action-item/Index.svelte#L14-L98) +- [backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js:419-431](file://backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js#L419-L431) +- [frontend/antdx/actions/actions.tsx:1-200](file://frontend/antdx/actions/actions.tsx#L1-L200) + +## 性能考量 + +- 动态导入与懒加载 + - Svelte 侧通过 importComponent 实现按需加载，降低初始包体与首屏压力。 +- 渲染优化 + - 使用 $derived 与 useMemo 化策略，避免不必要的重渲染。 +- 事件透传 + - 事件在运行时桥接层进行统一处理，减少重复绑定与内存占用。 +- 插槽克隆 + - 对 actionRender 设置 clone 与 withParams，确保插槽内容稳定复用与参数传递。 + +章节来源 + +- [frontend/antdx/actions/action-item/Index.svelte:14-98](file://frontend/antdx/actions/action-item/Index.svelte#L14-L98) +- [backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js:163-209](file://backend/modelscope_studio/components/antdx/actions/action_item/templates/component/actions.action-item-76joNQSL.js#L163-L209) + +## 故障排查指南 + +- 事件未触发 + - 检查后端是否启用 item_click 事件绑定；确认前端 props 中 item_click 是否正确映射。 +- 插槽不生效 + - 确认插槽名称与支持列表一致（label、icon、actionRender、subItems）；检查 actionRender 的 withParams 与 clone 设置。 +- 样式或类名异常 + - 检查 elem_id、elem_classes、elem_style 是否正确传入；确认运行时桥接层对样式与类名的合并逻辑。 +- 子菜单不显示 + - 检查 trigger_sub_menu_action（hover/click）与 sub_items 结构是否正确；确认主 Actions 的 dropdown 配置。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:15-21](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L15-L21) +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:24](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L24) +- [frontend/antdx/actions/action-item/Index.svelte:61-84](file://frontend/antdx/actions/action-item/Index.svelte#L61-L84) + +## 结论 + +ActionItem 通过后端 Python 封装与前端 Svelte/React 桥接，实现了高可配置、可扩展、可维护的操作项组件。其事件、插槽、样式与上下文整合能力，使其能够适配复杂场景下的操作面板需求。结合 AntdXActions 主组件，可快速构建美观且功能完备的操作区。 + +## 附录：使用示例与参数参考 + +以下为常见使用场景与参数说明（以路径代替具体代码）： + +- 文本操作项 + - 参数：label、danger、as_item + - 示例路径：[frontend/antdx/actions/action-item/Index.svelte:61-84](file://frontend/antdx/actions/action-item/Index.svelte#L61-L84) +- 图标操作项 + - 参数：icon、label、elem_classes + - 示例路径：[frontend/antdx/actions/action-item/Index.svelte:61-84](file://frontend/antdx/actions/action-item/Index.svelte#L61-L84) +- 自定义渲染（actionRender） + - 参数：actionRender（函数字符串）、插槽 withParams/clone + - 示例路径：[frontend/antdx/actions/action-item/Index.svelte:71-83](file://frontend/antdx/actions/action-item/Index.svelte#L71-L83) +- 危险态与触发策略 + - 参数：danger、trigger_sub_menu_action（hover/click） + - 示例路径：[backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:26-61](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L26-L61) +- 子菜单 + - 参数：sub_items、插槽 subItems + - 示例路径：[backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:24](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L24) + +章节来源 + +- [frontend/antdx/actions/action-item/Index.svelte:61-84](file://frontend/antdx/actions/action-item/Index.svelte#L61-L84) +- [backend/modelscope_studio/components/antdx/actions/action_item/**init**.py:24-61](file://backend/modelscope_studio/components/antdx/actions/action_item/__init__.py#L24-L61) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Actions \346\246\202\350\247\210.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Actions \346\246\202\350\247\210.md" new file mode 100644 index 00000000..d05f114f --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Actions \346\246\202\350\247\210.md" @@ -0,0 +1,335 @@ +# Actions 概览 + + +**本文引用的文件** +- [frontend/antdx/actions/Index.svelte](file://frontend/antdx/actions/Index.svelte) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [frontend/antdx/actions/item/Index.svelte](file://frontend/antdx/actions/item/Index.svelte) +- [frontend/antdx/actions/action-item/Index.svelte](file://frontend/antdx/actions/action-item/Index.svelte) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [backend/modelscope_studio/components/antdx/actions/__init__.py](file://backend/modelscope_studio/components/antdx/actions/__init__.py) +- [docs/components/antdx/actions/README.md](file://docs/components/antdx/actions/README.md) + + +## 目录 + +1. [引言](#引言) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 引言 + +Actions 是 Ant Design X 组件库在 ModelScope Studio 中的一个布局与交互组件，用于在 AI 场景中快速配置一组可复用的操作按钮或功能入口。它通过统一的“操作项”模型与插槽（slots）机制，将静态配置与动态渲染解耦，既支持直接传入 items 列表，也支持以子组件形式声明式地组织操作项，从而提升开发效率与可维护性。 + +在 ModelScope Studio 的整体架构中，Actions 位于前端 Svelte 层与后端 Gradio 组件层之间，承担“桥接与适配”的角色：前端负责将 Ant Design X 的 Actions 渲染到页面；后端通过自定义组件类暴露事件与插槽能力，并将额外属性透传给前端，实现从 Python 端到浏览器端的完整交互闭环。 + +## 项目结构 + +Actions 组件由前后端两部分组成： + +- 前端（Svelte + React）：负责将 Ant Design X 的 Actions 渲染为页面元素，并通过插槽与上下文系统收集子项。 +- 后端（Python + Gradio）：定义组件接口、事件与插槽，负责属性与事件的绑定与转发。 + +```mermaid +graph TB +subgraph "前端" +A_Index["frontend/antdx/actions/Index.svelte"] +A_Component["frontend/antdx/actions/actions.tsx"] +A_Context["frontend/antdx/actions/context.ts"] +A_Item["frontend/antdx/actions/item/Index.svelte"] +A_ActionItem["frontend/antdx/actions/action-item/Index.svelte"] +U_CreateItems["frontend/utils/createItemsContext.tsx"] +end +subgraph "后端" +P_Init["backend/modelscope_studio/components/antdx/actions/__init__.py"] +end +A_Index --> A_Component +A_Component --> A_Context +A_Component --> U_CreateItems +A_Item --> A_Component +A_ActionItem --> A_Component +P_Init --> A_Index +``` + +**图表来源** + +- [frontend/antdx/actions/Index.svelte:1-77](file://frontend/antdx/actions/Index.svelte#L1-L77) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/antdx/actions/item/Index.svelte:1-60](file://frontend/antdx/actions/item/Index.svelte#L1-L60) +- [frontend/antdx/actions/action-item/Index.svelte:1-99](file://frontend/antdx/actions/action-item/Index.svelte#L1-L99) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [backend/modelscope_studio/components/antdx/actions/**init**.py:1-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L1-L112) + +**章节来源** + +- [frontend/antdx/actions/Index.svelte:1-77](file://frontend/antdx/actions/Index.svelte#L1-L77) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/antdx/actions/item/Index.svelte:1-60](file://frontend/antdx/actions/item/Index.svelte#L1-L60) +- [frontend/antdx/actions/action-item/Index.svelte:1-99](file://frontend/antdx/actions/action-item/Index.svelte#L1-L99) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [backend/modelscope_studio/components/antdx/actions/**init**.py:1-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L1-L112) + +## 核心组件 + +- Actions 主组件：负责接收 items 或插槽中的操作项，结合 dropdownProps 对下拉菜单进行定制化渲染，并将最终的 Ant Design X Actions 渲染到页面。 +- 操作项上下文：通过 createItemsContext 提供的 ItemsContext，收集子级操作项（含默认插槽与命名插槽），并支持子项的 props、slots、children 的合并与传递。 +- 子组件包装器：item 与 action-item 分别对“操作容器”和“具体操作项”进行包装，负责属性透传、可见性控制、样式与 ID 注入，以及事件映射（如 item_click 映射为 itemClick）。 + +**章节来源** + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/antdx/actions/item/Index.svelte:1-60](file://frontend/antdx/actions/item/Index.svelte#L1-L60) +- [frontend/antdx/actions/action-item/Index.svelte:1-99](file://frontend/antdx/actions/action-item/Index.svelte#L1-L99) + +## 架构总览 + +Actions 的运行时流程如下： + +- 前端 Svelte 层通过 Index.svelte 动态导入 React 包装器 actions.tsx。 +- actions.tsx 使用上下文与插槽工具函数，将 items 与 dropdownProps 转换为 Ant Design X 所需的数据结构。 +- 后端组件类在 Python 端声明事件与插槽，将额外属性与可见性等信息透传至前端。 +- 最终由 Ant Design X 的 Actions 渲染出 UI，并触发回调事件。 + +```mermaid +sequenceDiagram +participant Py as "后端组件类
AntdXActions" +participant FE_Index as "前端 Index.svelte" +participant FE_Actions as "React 包装器
actions.tsx" +participant Ctx as "Items 上下文
createItemsContext" +participant ADX as "Ant Design X Actions" +Py->>FE_Index : "渲染请求包含属性与事件" +FE_Index->>FE_Actions : "动态导入并传递 props" +FE_Actions->>Ctx : "读取 items 插槽与菜单项" +FE_Actions->>ADX : "生成 items 与 dropdownProps" +ADX-->>FE_Actions : "渲染结果" +FE_Actions-->>FE_Index : "返回渲染节点" +FE_Index-->>Py : "完成渲染" +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/actions/**init**.py:1-112](file://backend/modelscope_studio/components/antdx/actions/__init__.py#L1-L112) +- [frontend/antdx/actions/Index.svelte:1-77](file://frontend/antdx/actions/Index.svelte#L1-L77) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +## 详细组件分析 + +### Actions 主组件（React 包装器） + +- 职责：将 Ant Design X 的 Actions 与插槽、上下文系统集成，负责 items 与 dropdownProps 的合并与渲染。 +- 关键点： + - 使用 withItemsContextProvider 与 withMenuItemsContextProvider 将 items 与菜单项上下文注入。 + - 通过 renderItems、renderSlot、renderParamsSlot 等工具函数，将插槽内容转换为 Ant Design X 所需的结构。 + - 对 dropdownProps 进行条件性合并，仅在存在有效值时才注入，避免冗余配置。 + +```mermaid +flowchart TD +Start(["进入 Actions 包装器"]) --> ReadItems["读取 items 或插槽中的操作项"] +ReadItems --> MergeDropdown["合并 dropdownProps菜单项/渲染器/指示器"] +MergeDropdown --> BuildItems["使用 renderItems 构建最终 items"] +BuildItems --> Render["渲染 Ant Design X Actions"] +Render --> End(["完成"]) +``` + +**图表来源** + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +**章节来源** + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) + +### 操作项上下文（createItemsContext） + +- 职责：提供 ItemsContext，用于收集与更新“操作项”数据，支持多插槽（default 与其他命名插槽）。 +- 关键点： + - setItem 支持按插槽键与索引更新单项，内部使用不可变更新策略，配合 useEffect 触发 onChange 回调。 + - ItemHandler 负责将子组件的 props、slots、children 等封装为标准 Item 结构，并写入上下文。 + - 通过 useMemoizedEqualValue 与 useMemoizedFn 优化渲染与回调开销。 + +```mermaid +classDiagram +class ItemsContext { ++items : Record
frontend/antdx/actions/audio/Index.svelte"] +B["React 桥接层
frontend/antdx/actions/audio/actions.audio.tsx"] +C["多模态输入工具
frontend/pro/multimodal-input/utils.ts"] +D["录音 Hook
frontend/pro/multimodal-input/recorder.ts"] +E["音量/进度滑块
frontend/antd/slider/Index.svelte"] +end +subgraph "后端" +F["AntdXActionsAudio 组件类
backend/.../antdx/actions/audio/__init__.py"] +end +A --> B +B --> F +C --> D +E --> A +``` + +**图表来源** + +- [frontend/antdx/actions/audio/Index.svelte:1-59](file://frontend/antdx/actions/audio/Index.svelte#L1-L59) +- [frontend/antdx/actions/audio/actions.audio.tsx:1-17](file://frontend/antdx/actions/audio/actions.audio.tsx#L1-L17) +- [backend/modelscope_studio/components/antdx/actions/audio/**init**.py:10-71](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L10-L71) +- [frontend/pro/multimodal-input/utils.ts:1-126](file://frontend/pro/multimodal-input/utils.ts#L1-L126) +- [frontend/pro/multimodal-input/recorder.ts:1-48](file://frontend/pro/multimodal-input/recorder.ts#L1-L48) +- [frontend/antd/slider/Index.svelte:62-84](file://frontend/antd/slider/Index.svelte#L62-L84) + +**章节来源** + +- [frontend/antdx/actions/audio/Index.svelte:1-59](file://frontend/antdx/actions/audio/Index.svelte#L1-L59) +- [frontend/antdx/actions/audio/actions.audio.tsx:1-17](file://frontend/antdx/actions/audio/actions.audio.tsx#L1-L17) +- [backend/modelscope_studio/components/antdx/actions/audio/**init**.py:10-71](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L10-L71) +- [frontend/pro/multimodal-input/utils.ts:1-126](file://frontend/pro/multimodal-input/utils.ts#L1-L126) +- [frontend/pro/multimodal-input/recorder.ts:1-48](file://frontend/pro/multimodal-input/recorder.ts#L1-L48) +- [frontend/antd/slider/Index.svelte:62-84](file://frontend/antd/slider/Index.svelte#L62-L84) + +## 核心组件 + +- AntdXActionsAudio（后端组件类）：封装 Ant Design X 的 Actions.Audio，提供状态、样式、可见性等属性，并声明跳过 API 调用以直接渲染前端组件。 +- Actions.Audio（前端包装）：通过 Svelte 包装桥接 React 组件，将属性透传到 Ant Design X 的 Actions.Audio。 +- 音频处理工具（Pro 多模态输入）：提供音频缓冲区转 WAV、按时间范围裁剪音频、从 Blob 解码并导出等能力。 +- 录音 Hook：基于 wavesurfer.js 的 record 插件，提供录音开始/结束回调与录制状态管理。 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/actions/audio/**init**.py:10-71](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L10-L71) +- [frontend/antdx/actions/audio/actions.audio.tsx:1-17](file://frontend/antdx/actions/audio/actions.audio.tsx#L1-L17) +- [frontend/pro/multimodal-input/utils.ts:1-126](file://frontend/pro/multimodal-input/utils.ts#L1-L126) +- [frontend/pro/multimodal-input/recorder.ts:1-48](file://frontend/pro/multimodal-input/recorder.ts#L1-L48) + +## 架构总览 + +Audio 能力在前端通过 Svelte 组件桥接 React 组件，后端通过自定义组件类将属性传递给前端；同时提供录音与音频处理工具，便于在多模态输入场景中完成“录音 → 预览 → 导出”的闭环。 + +```mermaid +sequenceDiagram +participant Py as "Python 后端
AntdXActionsAudio" +participant FE as "前端包装
Index.svelte" +participant RA as "React 组件
Actions.Audio" +participant AU as "浏览器音频接口
AudioContext/Web Audio API" +Py->>FE : 渲染组件属性透传 +FE->>RA : 传递 props状态/样式/可见性 +RA->>AU : 初始化音频上下文/加载音频资源 +AU-->>RA : 播放/暂停/停止/进度/音量/循环 +RA-->>FE : 触发事件回调点击等 +FE-->>Py : 更新状态/触发交互 +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/actions/audio/**init**.py:10-71](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L10-L71) +- [frontend/antdx/actions/audio/Index.svelte:19-41](file://frontend/antdx/actions/audio/Index.svelte#L19-L41) +- [frontend/antdx/actions/audio/actions.audio.tsx:6-14](file://frontend/antdx/actions/audio/actions.audio.tsx#L6-L14) + +## 组件详解 + +### AntdXActionsAudio（后端组件类） + +- 责任边界：负责将前端组件映射到 Python 端，提供状态、样式、可见性等属性；声明跳过 API 调用，避免重复处理。 +- 关键点：事件监听绑定、属性透传、渲染控制。 + +```mermaid +classDiagram +class AntdXActionsAudio { ++status ++additional_props ++class_names ++styles ++visible ++elem_id ++elem_classes ++elem_style ++skip_api ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/actions/audio/**init**.py:10-71](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L10-L71) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/actions/audio/**init**.py:10-71](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L10-L71) + +### Actions.Audio（前端包装） + +- 责任边界：将 Ant Design X 的 Actions.Audio 通过 Svelte 包装桥接至 Gradio 生态，统一属性与事件。 +- 关键点：sveltify 包装、slots 透传、样式与 ID 注入。 + +```mermaid +flowchart TD +A["Index.svelte 获取 props"] --> B["processProps 生成最终属性"] +B --> C["渲染 Actions.Audio 并注入样式/ID/事件"] +C --> D["用户交互触发事件回调"] +``` + +**图表来源** + +- [frontend/antdx/actions/audio/Index.svelte:19-41](file://frontend/antdx/actions/audio/Index.svelte#L19-L41) +- [frontend/antdx/actions/audio/actions.audio.tsx:6-14](file://frontend/antdx/actions/audio/actions.audio.tsx#L6-L14) + +**章节来源** + +- [frontend/antdx/actions/audio/Index.svelte:1-59](file://frontend/antdx/actions/audio/Index.svelte#L1-L59) +- [frontend/antdx/actions/audio/actions.audio.tsx:1-17](file://frontend/antdx/actions/audio/actions.audio.tsx#L1-L17) + +### 音频处理工具（裁剪/导出） + +- 功能概览：将 AudioBuffer 写入 WAV 头部与 PCM 数据；按起止时间裁剪音频；从 Blob 解码并导出 WAV。 +- 关键流程：解码 → 创建裁剪缓冲区 → 写入 WAV → 返回二进制数据。 + +```mermaid +flowchart TD +Start(["开始"]) --> Decode["解码音频数据AudioContext.decodeAudioData"] +Decode --> Trim{"是否指定裁剪区间？"} +Trim --> |是| CreateBuf["创建裁剪后的 AudioBuffer"] +Trim --> |否| KeepAll["保持原长度"] +CreateBuf --> Copy["复制通道数据到新缓冲区"] +KeepAll --> Copy +Copy --> ToWAV["写入 WAV 头与 PCM 数据"] +ToWAV --> End(["结束，返回 Uint8Array"]) +``` + +**图表来源** + +- [frontend/pro/multimodal-input/utils.ts:1-126](file://frontend/pro/multimodal-input/utils.ts#L1-L126) + +**章节来源** + +- [frontend/pro/multimodal-input/utils.ts:1-126](file://frontend/pro/multimodal-input/utils.ts#L1-L126) + +### 录音与波形可视化 + +- 录音：基于 wavesurfer.js 的 record 插件，提供 start/stop 回调与录制状态。 +- 波形：初始化 WaveSurfer 容器并注册 record 插件，实时显示波形。 + +```mermaid +sequenceDiagram +participant UI as "界面" +participant WS as "WaveSurfer 实例" +participant REC as "Record 插件" +participant CB as "回调函数" +UI->>WS : 创建实例并传入容器 +WS->>REC : 注册 record 插件 +UI->>REC : 调用 startRecording() +REC-->>UI : 触发 record-start 事件 +UI->>REC : 调用 stopRecording() +REC-->>CB : 触发 record-end 并返回 Blob +UI-->>UI : 更新录制状态 +``` + +**图表来源** + +- [frontend/pro/multimodal-input/recorder.ts:24-41](file://frontend/pro/multimodal-input/recorder.ts#L24-L41) + +**章节来源** + +- [frontend/pro/multimodal-input/recorder.ts:1-48](file://frontend/pro/multimodal-input/recorder.ts#L1-L48) + +### 音量/进度控制（Slider） + +- 通过 Slider 组件实现音量与进度的双向控制，onValueChange 事件用于同步状态。 +- 适配 Gradio 的属性透传机制，确保与后端状态一致。 + +**章节来源** + +- [frontend/antd/slider/Index.svelte:62-84](file://frontend/antd/slider/Index.svelte#L62-L84) + +## 依赖关系分析 + +- 前端包导出：两个关键包分别导出 Svelte 入口，供 Gradio 运行时加载。 +- 组件耦合：AntdXActionsAudio 与前端包装组件松耦合，通过属性透传实现交互。 +- 工具链：音频处理依赖 Web Audio API；录音依赖 wavesurfer.js 及其 record 插件。 + +```mermaid +graph LR +PkgA["pro/multimodal-input/package.json"] --> Utils["utils.ts音频处理"] +PkgB["antdx-actions.audio/package.json"] --> Wrap["actions.audio.tsxReact 包装"] +Wrap --> Fe["Index.svelte属性透传"] +Fe --> Py["AntdXActionsAudio后端组件类"] +Utils --> Recorder["recorder.ts录音 Hook"] +``` + +**图表来源** + +- [frontend/pro/multimodal-input/package.json:1-14](file://frontend/pro/multimodal-input/package.json#L1-L14) +- [frontend/antdx/actions/audio/package.json:1-14](file://frontend/antdx/actions/audio/package.json#L1-L14) +- [frontend/pro/multimodal-input/utils.ts:1-126](file://frontend/pro/multimodal-input/utils.ts#L1-L126) +- [frontend/pro/multimodal-input/recorder.ts:1-48](file://frontend/pro/multimodal-input/recorder.ts#L1-L48) +- [frontend/antdx/actions/audio/Index.svelte:1-59](file://frontend/antdx/actions/audio/Index.svelte#L1-L59) +- [backend/modelscope_studio/components/antdx/actions/audio/**init**.py:10-71](file://backend/modelscope_studio/components/antdx/actions/audio/__init__.py#L10-L71) + +**章节来源** + +- [frontend/pro/multimodal-input/package.json:1-14](file://frontend/pro/multimodal-input/package.json#L1-L14) +- [frontend/antdx/actions/audio/package.json:1-14](file://frontend/antdx/actions/audio/package.json#L1-L14) + +## 性能考量 + +- 音频解码与裁剪：优先在浏览器端进行，避免大文件在网络传输中的开销；对长音频建议分段处理或延迟解码。 +- 缓冲区管理：裁剪时仅复制必要片段，减少内存占用；导出前确认采样率与通道数一致性。 +- 录音性能：合理设置 normalize 与容器大小，避免频繁重绘；在移动端注意后台播放限制与权限申请。 +- UI 响应：音量/进度滑块采用受控组件模式，避免不必要的重渲染；事件回调使用记忆化函数降低抖动。 + +## 故障排查指南 + +- 无法播放音频 + - 检查音频格式是否被浏览器支持；尝试转换为 WAV/MP3 等常见格式。 + - 确认 AudioContext 初始化与权限（部分浏览器需要用户手势激活）。 +- 录音无输出 + - 确认设备权限已授权；检查容器是否正确挂载。 + - 核对 record-end 回调是否被触发，Blob 是否为空。 +- 导出失败 + - 确认裁剪区间合法（start/end 不越界）；检查采样率与通道数是否一致。 +- 滑块不生效 + - 检查 onValueChange 事件是否正确更新状态；确认受控值与后备值的同步逻辑。 + +**章节来源** + +- [frontend/pro/multimodal-input/utils.ts:60-126](file://frontend/pro/multimodal-input/utils.ts#L60-L126) +- [frontend/pro/multimodal-input/recorder.ts:24-41](file://frontend/pro/multimodal-input/recorder.ts#L24-L41) +- [frontend/antd/slider/Index.svelte:62-84](file://frontend/antd/slider/Index.svelte#L62-L84) + +## 结论 + +Audio 音频操作组件在模型库前端中通过“后端组件类 + 前端包装 + 工具链”的方式实现了从播放控制到录音导出的完整能力。结合多模态输入场景，可快速构建语音播报、音效播放与音频预览等体验。建议在实际工程中关注格式兼容、性能优化与权限处理，以获得更稳定的用户体验。 + +## 附录 + +### 使用示例（场景化） + +- 语音播报 + - 使用 AntdXActionsAudio 渲染播放按钮，结合 Slider 控制音量；通过事件回调触发播放/暂停。 +- 音效播放 + - 加载本地音效文件，设置循环播放与音量；在交互事件中切换状态。 +- 音频预览 + - 录音完成后，将 Blob 解码为 AudioBuffer，再导出为 WAV；在预览区域播放并提供下载。 + +**章节来源** + +- [docs/components/pro/multimodal_input/README.md:1-43](file://docs/components/pro/multimodal_input/README.md#L1-L43) +- [docs/components/pro/multimodal_input/README-zh_CN.md:1-43](file://docs/components/pro/multimodal_input/README-zh_CN.md#L1-L43) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Copy \345\244\215\345\210\266\346\223\215\344\275\234.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Copy \345\244\215\345\210\266\346\223\215\344\275\234.md" new file mode 100644 index 00000000..fb054f95 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Copy \345\244\215\345\210\266\346\223\215\344\275\234.md" @@ -0,0 +1,431 @@ +# 复制操作组件 + + +**本文档引用的文件** +- [actions.copy.tsx](file://frontend/antdx/actions/copy/actions.copy.tsx) +- [Index.svelte](file://frontend/antdx/actions/copy/Index.svelte) +- [__init__.py](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py) +- [package.json](file://frontend/antdx/actions/copy/package.json) +- [gradio.config.js](file://frontend/antdx/actions/copy/gradio.config.js) +- [utils.ts](file://frontend/globals/components/markdown/utils.ts) +- [chatbot-footer.tsx](file://frontend/pro/chatbot/chatbot-footer.tsx) +- [utils.ts](file://frontend/pro/chatbot/utils.ts) +- [basic.py](file://docs/components/antdx/actions/demos/basic.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构概览](#架构概览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) + +## 简介 + +复制操作组件是 ModelScope Studio 中用于快速配置复制功能的组件，基于 Ant Design X 的 Actions.Copy 实现。该组件提供了统一的复制操作接口，支持多种数据类型的复制，包括纯文本、链接、代码片段等常见场景。 + +该组件采用前后端分离的设计模式，前端使用 Svelte 构建，后端通过 Gradio 组件包装，实现了完整的复制功能生命周期管理。 + +## 项目结构 + +复制操作组件位于 Ant Design X 组件库中，具体结构如下： + +```mermaid +graph TB +subgraph "前端组件结构" +A[Index.svelte] --> B[actions.copy.tsx] +B --> C[Ant Design X Actions.Copy] +D[package.json] --> A +E[gradio.config.js] --> A +end +subgraph "后端组件结构" +F[__init__.py] --> G[ModelScopeLayoutComponent] +G --> H[Gradio事件处理] +end +subgraph "工具函数" +I[utils.ts] --> J[复制功能实现] +K[chatbot-footer.tsx] --> L[聊天机器人集成] +M[utils.ts] --> N[消息内容处理] +end +A --> F +B --> I +L --> N +``` + +**图表来源** + +- [Index.svelte:1-60](file://frontend/antdx/actions/copy/Index.svelte#L1-L60) +- [actions.copy.tsx:1-22](file://frontend/antdx/actions/copy/actions.copy.tsx#L1-L22) +- [**init**.py:1-72](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L1-L72) + +**章节来源** + +- [Index.svelte:1-60](file://frontend/antdx/actions/copy/Index.svelte#L1-L60) +- [actions.copy.tsx:1-22](file://frontend/antdx/actions/copy/actions.copy.tsx#L1-L22) +- [**init**.py:1-72](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L1-L72) + +## 核心组件 + +复制操作组件由三个主要部分组成： + +### 前端组件层 + +- **Index.svelte**: 主要的前端入口组件，负责属性处理和渲染逻辑 +- **actions.copy.tsx**: React 包装器，将 Ant Design X 的 Actions.Copy 组件适配到 Svelte 环境 + +### 后端组件层 + +- ****init**.py**: Python 后端组件定义，继承自 ModelScopeLayoutComponent + +### 工具函数层 + +- **utils.ts**: 提供复制功能的核心实现，包括剪贴板 API 和降级方案 + +**章节来源** + +- [Index.svelte:19-44](file://frontend/antdx/actions/copy/Index.svelte#L19-L44) +- [actions.copy.tsx:7-19](file://frontend/antdx/actions/copy/actions.copy.tsx#L7-L19) +- [**init**.py:10-72](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L10-L72) + +## 架构概览 + +复制操作组件采用分层架构设计，实现了清晰的关注点分离： + +```mermaid +sequenceDiagram +participant User as 用户 +participant Frontend as 前端组件 +participant Backend as 后端组件 +participant Clipboard as 浏览器剪贴板 +participant Utils as 工具函数 +User->>Frontend : 点击复制按钮 +Frontend->>Utils : 调用复制函数 +Utils->>Clipboard : 写入剪贴板 +Clipboard-->>Utils : 返回复制结果 +Utils-->>Frontend : 返回成功状态 +Frontend-->>User : 显示反馈效果 +Note over Frontend,Clipboard : 支持现代浏览器和降级方案 +``` + +**图表来源** + +- [utils.ts:382-410](file://frontend/globals/components/markdown/utils.ts#L382-L410) +- [Index.svelte:46-59](file://frontend/antdx/actions/copy/Index.svelte#L46-L59) + +### 组件交互流程 + +```mermaid +flowchart TD +Start([组件初始化]) --> Props[处理组件属性] +Props --> Slots[解析插槽内容] +Slots --> Render{组件可见性} +Render --> |可见| Load[加载React组件] +Render --> |不可见| Hide[隐藏组件] +Load --> Ready[组件就绪] +Ready --> Click[等待点击事件] +Click --> Copy[执行复制操作] +Copy --> Feedback[显示反馈效果] +Feedback --> End([完成]) +Hide --> End +``` + +**图表来源** + +- [Index.svelte:19-44](file://frontend/antdx/actions/copy/Index.svelte#L19-L44) +- [actions.copy.tsx:8-18](file://frontend/antdx/actions/copy/actions.copy.tsx#L8-L18) + +## 详细组件分析 + +### 前端组件实现 + +#### Index.svelte 分析 + +Index.svelte 是复制组件的主要前端入口，负责以下关键功能： + +```mermaid +classDiagram +class CopyComponent { ++props : ComponentProps ++slots : Slots ++proceedProps : ProcessedProps ++visible : boolean ++getProps() ComponentProps ++processProps() ProcessedProps ++getSlots() Slots ++render() JSX.Element +} +class ProcessProps { ++visible : boolean ++_internal : object ++as_item : string ++elem_classes : array ++elem_id : string ++elem_style : object ++restProps : object ++additionalProps : object +} +CopyComponent --> ProcessProps : 使用 +``` + +**图表来源** + +- [Index.svelte:12-44](file://frontend/antdx/actions/copy/Index.svelte#L12-L44) + +#### actions.copy.tsx 分析 + +actions.copy.tsx 作为 React 包装器，实现了与 Ant Design X 的无缝集成： + +```mermaid +classDiagram +class ActionsCopyWrapper { ++slots : object ++children : any ++props : ActionsCopyProps ++sveltify() ReactComponent ++render() JSX.Element +} +class ReactSlot { ++slot : string ++render() ReactElement +} +class AntdXActionsCopy { ++text : string ++icon : string ++onClick : function ++tooltips : boolean ++onCopy : function +} +ActionsCopyWrapper --> ReactSlot : 使用 +ActionsCopyWrapper --> AntdXActionsCopy : 包装 +``` + +**图表来源** + +- [actions.copy.tsx:7-19](file://frontend/antdx/actions/copy/actions.copy.tsx#L7-L19) + +**章节来源** + +- [Index.svelte:19-59](file://frontend/antdx/actions/copy/Index.svelte#L19-L59) +- [actions.copy.tsx:7-21](file://frontend/antdx/actions/copy/actions.copy.tsx#L7-L21) + +### 后端组件实现 + +#### Python 组件分析 + +后端组件继承自 ModelScopeLayoutComponent，提供了完整的 Gradio 集成： + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++visible : boolean ++elem_id : string ++elem_classes : array ++elem_style : object ++render : boolean ++preprocess() void ++postprocess() void ++example_payload() any ++example_value() any +} +class AntdXActionsCopy { ++EVENTS : array ++SLOTS : array ++text : string ++icon : string ++additional_props : object ++class_names : string|array ++styles : string|array ++skip_api : boolean ++FRONTEND_DIR : string +} +ModelScopeLayoutComponent <|-- AntdXActionsCopy : 继承 +``` + +**图表来源** + +- [**init**.py:10-72](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L10-L72) + +**章节来源** + +- [**init**.py:15-19](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L15-L19) +- [**init**.py:21-22](file://backend/modelscope_studio/components/antdx/actions/copy/__init__.py#L21-L22) + +### 复制功能实现 + +#### 核心复制逻辑 + +复制功能通过 utils.ts 中的工具函数实现，支持现代浏览器和传统浏览器两种方案： + +```mermaid +flowchart TD +Start([开始复制]) --> CheckClipboard{检查Clipboard API} +CheckClipboard --> |支持| Modern[使用navigator.clipboard] +CheckClipboard --> |不支持| Legacy[使用textarea降级方案] +Modern --> WriteText[writeText方法] +WriteText --> Success[复制成功] +Legacy --> CreateTextarea[创建textarea元素] +CreateTextarea --> SetValue[设置文本值] +SetValue --> Position[定位到屏幕外] +Position --> Select[选择文本] +Select --> ExecCommand[执行copy命令] +ExecCommand --> RemoveTextarea[移除textarea] +RemoveTextarea --> Success +Success --> Return[返回true] +``` + +**图表来源** + +- [utils.ts:382-410](file://frontend/globals/components/markdown/utils.ts#L382-L410) + +**章节来源** + +- [utils.ts:382-410](file://frontend/globals/components/markdown/utils.ts#L382-L410) + +## 依赖分析 + +### 组件依赖关系 + +复制操作组件的依赖关系相对简单，主要依赖于 Ant Design X 和 Gradio 生态系统： + +```mermaid +graph TB +subgraph "外部依赖" +A[@ant-design/x] --> B[Actions.Copy] +C[Gradio] --> D[事件系统] +E[Svelte Preprocess React] --> F[组件包装] +end +subgraph "内部依赖" +G[utils.ts] --> H[复制功能] +I[markdown组件] --> J[代码块复制] +K[chatbot组件] --> L[消息复制] +end +subgraph "复制组件" +B --> M[ActionsCopyWrapper] +F --> M +H --> M +M --> N[Index.svelte] +end +M --> O[Python后端组件] +O --> D +``` + +**图表来源** + +- [actions.copy.tsx:4](file://frontend/antdx/actions/copy/actions.copy.tsx#L4) +- [Index.svelte:10](file://frontend/antdx/actions/copy/Index.svelte#L10) + +### 版本兼容性 + +组件支持的版本要求： + +- Node.js: >= 14.0.0 +- Svelte: >= 3.0.0 +- Ant Design X: >= latest +- Gradio: >= latest + +**章节来源** + +- [package.json:1-15](file://frontend/antdx/actions/copy/package.json#L1-L15) +- [gradio.config.js:1-4](file://frontend/antdx/actions/copy/gradio.config.js#L1-L4) + +## 性能考虑 + +### 渲染优化 + +复制组件采用了懒加载策略，只有在需要时才加载 React 组件： + +```mermaid +flowchart LR +A[组件初始化] --> B{检查可见性} +B --> |不可见| C[直接返回空] +B --> |可见| D[异步加载组件] +D --> E[组件就绪] +E --> F[渲染最终组件] +style C fill:#f9f9f9 +style F fill:#e1f5fe +``` + +**图表来源** + +- [Index.svelte:46-59](file://frontend/antdx/actions/copy/Index.svelte#L46-L59) + +### 内存管理 + +组件实现了适当的内存清理机制： + +- 自动移除事件监听器 +- 及时清理临时 DOM 元素 +- 避免内存泄漏 + +## 故障排除指南 + +### 常见问题及解决方案 + +#### 复制功能失效 + +**问题描述**: 用户点击复制按钮但无法复制到剪贴板 + +**可能原因**: + +1. 浏览器安全策略限制 +2. HTTPS 环境问题 +3. 权限不足 + +**解决方案**: + +1. 确保网站运行在 HTTPS 环境 +2. 检查浏览器权限设置 +3. 尝试手动触发复制操作 + +#### 组件渲染异常 + +**问题描述**: 复制组件无法正常显示或渲染 + +**可能原因**: + +1. 前端构建配置问题 +2. 依赖包版本冲突 +3. 插槽内容格式错误 + +**解决方案**: + +1. 检查前端构建日志 +2. 更新依赖包到兼容版本 +3. 验证插槽内容格式 + +**章节来源** + +- [utils.ts:382-410](file://frontend/globals/components/markdown/utils.ts#L382-L410) +- [Index.svelte:46-59](file://frontend/antdx/actions/copy/Index.svelte#L46-L59) + +## 结论 + +复制操作组件是一个设计精良的通用组件，具有以下特点： + +### 技术优势 + +- **模块化设计**: 清晰的前后端分离架构 +- **兼容性强**: 支持多种浏览器环境 +- **易于扩展**: 插槽系统支持灵活定制 +- **性能优化**: 懒加载和内存管理 + +### 使用场景 + +- 文本内容复制 +- 代码片段复制 +- 链接分享 +- 文件下载链接复制 + +### 最佳实践 + +1. 合理使用插槽系统进行定制 +2. 注意浏览器兼容性问题 +3. 实现适当的错误处理机制 +4. 考虑用户体验的反馈设计 + +该组件为 ModelScope Studio 提供了可靠的复制功能基础，可以满足大多数应用场景的需求。 diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Feedback \345\217\215\351\246\210\346\223\215\344\275\234.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Feedback \345\217\215\351\246\210\346\223\215\344\275\234.md" new file mode 100644 index 00000000..db1038ea --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Feedback \345\217\215\351\246\210\346\223\215\344\275\234.md" @@ -0,0 +1,268 @@ +# Feedback 反馈操作 + + +**本文档引用的文件** +- [frontend/antdx/actions/feedback/actions.feedback.tsx](file://frontend/antdx/actions/feedback/actions.feedback.tsx) +- [frontend/antdx/actions/feedback/Index.svelte](file://frontend/antdx/actions/feedback/Index.svelte) +- [frontend/antdx/actions/feedback/package.json](file://frontend/antdx/actions/feedback/package.json) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [backend/modelscope_studio/components/antdx/actions/feedback/__init__.py](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py) +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件系统性阐述 Feedback 反馈操作组件的设计与实现，聚焦于用户反馈收集、数据流转与处理机制，并提供可复用的使用范式（如满意度调查、功能评价、问题报告等）。该组件基于 Ant Design X 的 Actions.Feedback 能力，通过 Gradio 生态中的 Svelte 包装层实现前后端一体化集成，具备以下关键特性： + +- 前端以 Svelte 组件形式暴露，内部桥接 React 实现； +- 后端作为 Gradio 组件参与界面渲染与事件分发； +- 支持“点赞/点踩/默认”三种反馈值，便于后续统计与分析； +- 面向产品改进与体验优化，提供可扩展的反馈采集与响应能力。 + +## 项目结构 + +Feedback 组件位于前端 antdx/actions/feedback 目录，后端位于 backend/modelscope_studio/components/antdx/actions/feedback。其与 Actions 主容器组件协同工作，形成“容器-子项”的组合关系。 + +```mermaid +graph TB +subgraph "前端" +A["Index.svelte
反馈组件入口"] +B["actions.feedback.tsx
React 桥接包装"] +C["actions.tsx
Actions 容器"] +D["context.ts
上下文提供者"] +end +subgraph "后端" +E["__init__.py
Gradio 组件定义"] +end +A --> B +B --> C +C --> D +A --> E +``` + +图表来源 + +- [frontend/antdx/actions/feedback/Index.svelte:1-62](file://frontend/antdx/actions/feedback/Index.svelte#L1-L62) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:1-16](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L1-L16) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [backend/modelscope_studio/components/antdx/actions/feedback/**init**.py:25-73](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L25-L73) + +章节来源 + +- [frontend/antdx/actions/feedback/Index.svelte:1-62](file://frontend/antdx/actions/feedback/Index.svelte#L1-L62) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:1-16](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L1-L16) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [backend/modelscope_studio/components/antdx/actions/feedback/**init**.py:25-73](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L25-L73) + +## 核心组件 + +- 前端入口组件：Index.svelte 将反馈组件按需加载并注入属性与插槽，支持可见性控制与样式类名拼接。 +- React 桥接包装：actions.feedback.tsx 将 @ant-design/x 的 Actions.Feedback 以 Svelte 形式导出，简化调用。 +- Actions 容器：actions.tsx 提供 Actions 容器能力，负责菜单项、下拉渲染、插槽与事件的统一处理。 +- 上下文提供者：context.ts 提供 Items 上下文，支撑 Actions 子项的注册与渲染。 +- 后端 Gradio 组件：反馈组件后端定义了属性、可见性、样式等基础能力，并声明跳过标准 API 流程，直接由前端驱动交互。 + +章节来源 + +- [frontend/antdx/actions/feedback/Index.svelte:10-61](file://frontend/antdx/actions/feedback/Index.svelte#L10-L61) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:5-13](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L5-L13) +- [frontend/antdx/actions/actions.tsx:17-120](file://frontend/antdx/actions/actions.tsx#L17-L120) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [backend/modelscope_studio/components/antdx/actions/feedback/**init**.py:28-73](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L28-L73) + +## 架构总览 + +Feedback 组件的运行时架构如下：前端 Svelte 组件通过 importComponent 动态加载 React 包装层，再由 React 层调用 @ant-design/x 的 Actions.Feedback；后端组件负责属性透传与渲染控制，不参与数据 API 处理，事件由前端完成。 + +```mermaid +sequenceDiagram +participant UI as "页面/应用" +participant FE_Index as "Index.svelte" +participant FE_Wrapper as "actions.feedback.tsx" +participant FE_Actions as "actions.tsx" +participant BE_Comp as "__init__.py(后端)" +participant ADX as "@ant-design/x
Actions.Feedback" +UI->>FE_Index : 渲染反馈组件 +FE_Index->>FE_Wrapper : 动态导入包装层 +FE_Wrapper->>FE_Actions : 传递属性与插槽 +FE_Actions->>ADX : 渲染 Actions.Feedback +ADX-->>UI : 用户交互点赞/点踩 +note over FE_Index,BE_Comp : 后端组件跳过 API 流程，仅负责渲染与属性透传 +``` + +图表来源 + +- [frontend/antdx/actions/feedback/Index.svelte:10-61](file://frontend/antdx/actions/feedback/Index.svelte#L10-L61) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:5-13](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L5-L13) +- [frontend/antdx/actions/actions.tsx:98-116](file://frontend/antdx/actions/actions.tsx#L98-L116) +- [backend/modelscope_studio/components/antdx/actions/feedback/**init**.py:56-60](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L56-L60) + +## 详细组件分析 + +### 前端组件链路分析 + +- Index.svelte + - 负责动态导入包装层，处理组件属性与额外属性合并，支持可见性、样式、类名、元素 ID 等通用属性透传。 + - 使用 getSlots 获取插槽内容，将 children 渲染到包装层。 +- actions.feedback.tsx + - 通过 sveltify 将 React 组件 Actions.Feedback 包装为 Svelte 组件，保持属性透传与事件兼容。 +- actions.tsx（Actions 容器） + - 统一处理 items、dropdownProps、插槽渲染与函数参数化，确保 Actions.Feedback 在容器内正确渲染。 +- context.ts + - 提供 Items 上下文，支撑 Actions 子项注册与渲染。 + +```mermaid +flowchart TD +Start(["进入 Index.svelte"]) --> LoadWrapper["动态导入 actions.feedback.tsx"] +LoadWrapper --> MergeProps["合并组件属性与附加属性"] +MergeProps --> VisibleCheck{"是否可见？"} +VisibleCheck --> |是| RenderWrapper["渲染 ActionsFeedback 包装层"] +VisibleCheck --> |否| Skip["跳过渲染"] +RenderWrapper --> PassSlots["透传插槽与 children"] +PassSlots --> End(["完成"]) +Skip --> End +``` + +图表来源 + +- [frontend/antdx/actions/feedback/Index.svelte:21-61](file://frontend/antdx/actions/feedback/Index.svelte#L21-L61) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:5-13](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L5-L13) + +章节来源 + +- [frontend/antdx/actions/feedback/Index.svelte:10-61](file://frontend/antdx/actions/feedback/Index.svelte#L10-L61) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:5-13](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L5-L13) +- [frontend/antdx/actions/actions.tsx:27-120](file://frontend/antdx/actions/actions.tsx#L27-L120) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) + +### 数据收集与处理机制 + +- 反馈值类型 + - 支持 value 字段取值："like"（点赞）、"dislike"（点踩）、"default"（默认），用于区分用户反馈倾向。 +- 事件与状态 + - 组件本身不执行后端 API，交互结果由前端处理；后端组件声明 skip_api=True，避免进入标准 API 流程。 +- 插槽与扩展 + - 通过插槽机制可扩展反馈按钮组、自定义文案或图标，配合 Actions 容器实现更丰富的交互形态。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/actions/feedback/**init**.py:30-54](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L30-L54) +- [backend/modelscope_studio/components/antdx/actions/feedback/**init**.py:59-60](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L59-L60) + +### 使用示例与最佳实践 + +- 满意度调查 + - 场景：在对话记录末尾提供“满意/不满意”反馈按钮，点击后更新对应记录的元信息。 + - 实施要点：使用 Actions 容器承载反馈按钮，设置 value 为 "like"/"dislike"，结合业务状态更新逻辑。 +- 功能评价 + - 场景：在功能模块页提供“有用/无用”评价入口，便于收集功能使用反馈。 + - 实施要点：通过插槽扩展按钮文案与图标，结合后端状态管理进行统计归档。 +- 问题报告 + - 场景：在错误提示或异常路径提供“问题反馈”入口，引导用户提供问题描述。 + - 实施要点：结合表单组件与 Actions，收集用户输入与上下文信息，统一提交至问题跟踪系统。 + +说明：以上为通用使用范式，具体实现需结合业务状态与后端服务进行扩展。 + +### 分析方法、统计展示与响应处理 + +- 分析方法 + - 基于 value 字段进行聚合统计（如“like”占比、“dislike”占比）。 + - 结合时间维度、会话维度、功能模块维度进行交叉分析。 +- 统计展示 + - 前端可采用图表组件（如柱状图、饼图）直观呈现反馈分布。 + - 后端可提供聚合接口，返回各维度统计结果。 +- 响应处理 + - 对“dislike”反馈建议触发告警或自动转人工客服。 + - 对高频负面反馈进行根因分析与修复优先级排序。 + +说明：上述为通用分析与处理思路，具体实现需根据产品需求与数据平台能力定制。 + +## 依赖关系分析 + +- 前端依赖 + - @svelte-preprocess-react：实现 React 组件到 Svelte 的桥接。 + - @ant-design/x：提供 Actions.Feedback 的 React 实现。 + - @utils/\*：提供渲染工具（renderItems、renderParamsSlot、createFunction）与上下文工具。 +- 后端依赖 + - Gradio 组件基类：提供 visible、elem_id、elem_classes、elem_style 等通用属性。 + - 前端目录解析：通过 resolve_frontend_dir 指定前端资源路径。 + +```mermaid +graph LR +FE_Index["Index.svelte"] --> FE_Wrapper["actions.feedback.tsx"] +FE_Wrapper --> FE_Actions["actions.tsx"] +FE_Actions --> Utils["@utils/*"] +FE_Actions --> ADX["@ant-design/x"] +BE_Init["后端 __init__.py"] --> FE_Index +``` + +图表来源 + +- [frontend/antdx/actions/feedback/Index.svelte:10-12](file://frontend/antdx/actions/feedback/Index.svelte#L10-L12) +- [frontend/antdx/actions/feedback/actions.feedback.tsx](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L3) +- [frontend/antdx/actions/actions.tsx:1-10](file://frontend/antdx/actions/actions.tsx#L1-L10) +- [backend/modelscope_studio/components/antdx/actions/feedback/**init**.py](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L56) + +章节来源 + +- [frontend/antdx/actions/feedback/package.json:1-15](file://frontend/antdx/actions/feedback/package.json#L1-L15) +- [frontend/antdx/actions/feedback/actions.feedback.tsx:1-3](file://frontend/antdx/actions/feedback/actions.feedback.tsx#L1-L3) +- [frontend/antdx/actions/actions.tsx:1-10](file://frontend/antdx/actions/actions.tsx#L1-L10) +- [backend/modelscope_studio/components/antdx/actions/feedback/**init**.py](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L56) + +## 性能考虑 + +- 按需加载：Index.svelte 通过 importComponent 动态导入包装层，减少初始包体与首屏渲染压力。 +- 属性透传：仅透传必要属性，避免冗余计算与 DOM 更新。 +- 插槽渲染：利用 renderItems/renderParamsSlot 等工具，确保插槽内容按需渲染与克隆，降低重复开销。 +- 事件绑定：Actions 容器集中处理事件与渲染，避免多层嵌套导致的事件风暴。 + +## 故障排查指南 + +- 组件未显示 + - 检查 visible 属性是否为 true。 + - 确认 elem_id、elem_classes、elem_style 是否影响布局或被覆盖。 +- 交互无效 + - 确认 Actions 容器已正确渲染，且 dropdownProps、items 等属性已正确传递。 + - 检查插槽键名是否匹配（如 dropdownProps.menu.items）。 +- 后端报错 + - 后端组件 skip_api=True，若出现 API 相关错误，请检查前端是否误用后端 API 流程。 + - 确认 FRONTEND_DIR 指向的前端目录存在且可访问。 + +章节来源 + +- [frontend/antdx/actions/feedback/Index.svelte:48-61](file://frontend/antdx/actions/feedback/Index.svelte#L48-L61) +- [frontend/antdx/actions/actions.tsx:39-96](file://frontend/antdx/actions/actions.tsx#L39-L96) +- [backend/modelscope_studio/components/antdx/actions/feedback/**init**.py:59-60](file://backend/modelscope_studio/components/antdx/actions/feedback/__init__.py#L59-L60) + +## 结论 + +Feedback 反馈操作组件通过“Svelte 入口 + React 包装 + Actions 容器”的架构，实现了对用户反馈的高效采集与扩展。其设计强调前后端解耦、按需加载与插槽扩展，适用于满意度调查、功能评价、问题报告等多种场景。结合合理的统计分析与响应处理策略，可显著提升产品改进效率与用户体验质量。 + +## 附录 + +- 组件导出与打包 + - package.json 中通过 exports 映射将 Gradio 与默认入口指向同一 Svelte 文件，便于不同环境加载。 +- 相关组件索引 + - 后端 antdx 组件索引包含 Feedback 组件映射，便于统一管理与查找。 + +章节来源 + +- [frontend/antdx/actions/feedback/package.json:4-13](file://frontend/antdx/actions/feedback/package.json#L4-L13) +- [backend/modelscope_studio/components/antdx/**init**.py](file://backend/modelscope_studio/components/antdx/__init__.py#L5) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Item \345\256\271\345\231\250.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Item \345\256\271\345\231\250.md" new file mode 100644 index 00000000..3f72a067 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Item \345\256\271\345\231\250.md" @@ -0,0 +1,318 @@ +# Item 容器 + + +**本文引用的文件** +- [frontend/antdx/actions/item/Index.svelte](file://frontend/antdx/actions/item/Index.svelte) +- [frontend/antdx/actions/item/actions.item.tsx](file://frontend/antdx/actions/item/actions.item.tsx) +- [backend/modelscope_studio/components/antdx/actions/item/__init__.py](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/antdx/actions/Index.svelte](file://frontend/antdx/actions/Index.svelte) +- [docs/components/antdx/actions/demos/basic.py](file://docs/components/antdx/actions/demos/basic.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本篇文档聚焦于 AntdX Actions 组件体系中的 Item 容器（ActionItem），系统阐述其作为 Actions 内部容器的职责、布局与样式控制、响应式设计思路、与子操作项的协作机制、事件传递与状态同步，并给出多种布局（水平、垂直、网格）的实践建议与最佳实践。该容器在整体组件架构中承担“子项定义与渲染”的关键角色，是构建复杂操作列表的基础构件。 + +## 项目结构 + +- 前端层：Svelte 入口负责属性透传与可见性控制；React 包装层负责对接 Ant Design X 的 Actions.Item；后端 Python 组件负责 Gradio 集成与事件绑定。 +- 工具层：通用的 items 上下文与渲染管线，支撑多级子项、插槽（slots）与参数化渲染。 + +```mermaid +graph TB +subgraph "前端" +A["Index.svelte
Actions 主入口"] +B["actions.tsx
封装 Ant Design X Actions"] +C["context.ts
Items 上下文"] +D["createItemsContext.tsx
上下文与 ItemHandler 实现"] +E["renderItems.tsx
渲染管线"] +F["item/Index.svelte
Item 容器入口"] +G["item/actions.item.tsx
React 包装与插槽注入"] +end +subgraph "后端" +H["backend/.../item/__init__.py
Gradio 组件定义与事件"] +end +A --> B +B --> C +C --> D +D --> E +B --> E +F --> G +G --> |"包装"| B +H --> A +``` + +图表来源 + +- [frontend/antdx/actions/Index.svelte:1-77](file://frontend/antdx/actions/Index.svelte#L1-L77) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/antdx/actions/item/Index.svelte:1-60](file://frontend/antdx/actions/item/Index.svelte#L1-L60) +- [frontend/antdx/actions/item/actions.item.tsx:1-35](file://frontend/antdx/actions/item/actions.item.tsx#L1-L35) +- [backend/modelscope_studio/components/antdx/actions/item/**init**.py:1-77](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L1-L77) + +章节来源 + +- [frontend/antdx/actions/Index.svelte:1-77](file://frontend/antdx/actions/Index.svelte#L1-L77) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/antdx/actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/antdx/actions/item/Index.svelte:1-60](file://frontend/antdx/actions/item/Index.svelte#L1-L60) +- [frontend/antdx/actions/item/actions.item.tsx:1-35](file://frontend/antdx/actions/item/actions.item.tsx#L1-L35) +- [backend/modelscope_studio/components/antdx/actions/item/**init**.py:1-77](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L1-L77) + +## 核心组件 + +- Item 容器入口（Svelte） + - 负责接收父级传入的属性、额外属性、可见性、样式与类名，并将这些信息透传给 React 包装层。 + - 使用延迟派生计算最终属性，确保只在必要时更新。 + - 支持插槽（slots）与子节点渲染，便于在子项内注入图标、动作渲染器等。 +- React 包装层（sveltify） + - 将 Ant Design X 的 Actions.Item 与插槽系统对接，支持 defaultIcon、runningIcon 等插槽。 + - 通过 ReactSlot 将 Svelte 插槽内容克隆并注入到对应位置。 +- 后端组件（Python） + - 定义支持的插槽（defaultIcon、runningIcon）、事件（如 click）与属性（label、status、样式等）。 + - 控制是否跳过 API（skip_api），以及预处理/后处理流程。 + +章节来源 + +- [frontend/antdx/actions/item/Index.svelte:1-60](file://frontend/antdx/actions/item/Index.svelte#L1-L60) +- [frontend/antdx/actions/item/actions.item.tsx:1-35](file://frontend/antdx/actions/item/actions.item.tsx#L1-L35) +- [backend/modelscope_studio/components/antdx/actions/item/**init**.py:1-77](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L1-L77) + +## 架构总览 + +Item 容器在 Actions 体系中的定位：作为子项的“容器”，负责将用户配置的属性与插槽内容转换为 Ant Design X 所需的结构，并参与整体的渲染与事件分发。 + +```mermaid +sequenceDiagram +participant U as "用户代码" +participant S as "Svelte 入口(Index.svelte)" +participant R as "React 包装(actions.item.tsx)" +participant A as "Ant Design X Actions.Item" +participant P as "后端组件(__init__.py)" +U->>S : 配置 ActionItem 属性与插槽 +S->>R : 透传属性与插槽 +R->>A : 渲染并注入插槽(defaultIcon/runningIcon) +A-->>U : 触发事件回调 +U->>P : 事件绑定(click 等) +P-->>U : 事件数据回传 +``` + +图表来源 + +- [frontend/antdx/actions/item/Index.svelte:1-60](file://frontend/antdx/actions/item/Index.svelte#L1-L60) +- [frontend/antdx/actions/item/actions.item.tsx:1-35](file://frontend/antdx/actions/item/actions.item.tsx#L1-L35) +- [backend/modelscope_studio/components/antdx/actions/item/**init**.py:1-77](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L1-L77) + +## 详细组件分析 + +### 组件关系与职责 + +- Actions 主容器：负责聚合子项、处理下拉菜单、溢出指示器、扩展图标等高级能力。 +- Item 容器：负责单个子项的渲染、插槽注入、状态（如 loading/error/running/default）与标签展示。 +- 上下文与渲染管线：统一管理 items 的收集、子项树构建、插槽与参数化渲染。 + +```mermaid +classDiagram +class Actions主容器 { ++聚合子项 ++处理下拉菜单 ++溢出指示器 +} +class Item容器 { ++属性透传 ++插槽注入 ++状态渲染 +} +class 上下文与渲染 { ++收集items ++子项树构建 ++插槽/参数化渲染 +} +Actions主容器 --> 上下文与渲染 : "消费" +上下文与渲染 --> Item容器 : "生成" +``` + +图表来源 + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/antdx/actions/item/actions.item.tsx:1-35](file://frontend/antdx/actions/item/actions.item.tsx#L1-L35) + +章节来源 + +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/antdx/actions/item/actions.item.tsx:1-35](file://frontend/antdx/actions/item/actions.item.tsx#L1-L35) + +### 布局管理与样式控制 + +- 可见性控制：通过 visible 属性决定是否渲染，避免无用 DOM。 +- 类名与 ID：elem_classes、elem_id 用于样式覆盖与定位。 +- 行为样式：elem_style 用于动态样式注入，适合响应式场景下的尺寸、间距调整。 +- 容器样式：在 Svelte 入口处将样式与类名合并应用到根元素，保证与上层布局一致。 + +章节来源 + +- [frontend/antdx/actions/item/Index.svelte:19-60](file://frontend/antdx/actions/item/Index.svelte#L19-L60) +- [frontend/antdx/actions/Index.svelte:27-77](file://frontend/antdx/actions/Index.svelte#L27-L77) + +### 响应式设计 + +- 基于 Ant Design X 的 Actions 自带的溢出与下拉菜单能力，Item 容器无需额外响应式逻辑即可适配窄屏。 +- 若需自定义响应式行为，可在 elem_style 中按断点设置宽度、间距等；或通过外部容器（如 Space、Grid）进行布局约束。 + +章节来源 + +- [frontend/antdx/actions/actions.tsx:39-96](file://frontend/antdx/actions/actions.tsx#L39-L96) + +### 子操作项协作机制 + +- 插槽注入：defaultIcon、runningIcon 等插槽通过 ReactSlot 注入到 Ant Design X 的对应字段，实现图标与运行态图标的差异化展示。 +- 子项树：通过 createItemsContext 与 renderItems 构建子项树，支持嵌套 ActionItem 与 subItems 插槽。 +- 参数化渲染：插槽可携带 withParams，实现按需传参的渲染。 + +```mermaid +flowchart TD +Start(["开始"]) --> Collect["收集插槽与属性"] +Collect --> BuildTree["构建子项树"] +BuildTree --> InjectSlots["注入插槽(defaultIcon/runningIcon)"] +InjectSlots --> Render["渲染为 Ant Design X 结构"] +Render --> End(["结束"]) +``` + +图表来源 + +- [frontend/utils/createItemsContext.tsx:190-261](file://frontend/utils/createItemsContext.tsx#L190-L261) +- [frontend/utils/renderItems.tsx:8-114](file://frontend/utils/renderItems.tsx#L8-L114) +- [frontend/antdx/actions/item/actions.item.tsx:10-32](file://frontend/antdx/actions/item/actions.item.tsx#L10-L32) + +章节来源 + +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/antdx/actions/item/actions.item.tsx:1-35](file://frontend/antdx/actions/item/actions.item.tsx#L1-L35) + +### 事件传递与状态同步 + +- 事件绑定：后端组件声明 click 事件监听，并通过内部标记启用事件绑定。 +- 状态同步：Item 的状态（如 loading/error/running/default）由后端属性驱动，前端根据状态切换图标与交互反馈。 +- 回调数据：事件回调中可获取 keyPath、key 等关键信息，便于业务侧做分支处理。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/actions/item/**init**.py:15-19](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L15-L19) +- [docs/components/antdx/actions/demos/basic.py:7-10](file://docs/components/antdx/actions/demos/basic.py#L7-L10) + +### 复杂布局实践建议 + +- 水平排列：直接在 Actions 下放置多个 ActionItem，利用 Ant Design X 的默认行内布局。 +- 垂直排列：通过外层容器（如 Flex、Space）控制方向与对齐。 +- 网格布局：在更复杂的场景中，可结合 Grid 或自定义容器，配合 elem_style 控制列宽与间距。 +- 溢出策略：当子项较多时，利用 Actions 的下拉菜单与溢出指示器自动折叠，保持界面整洁。 + +章节来源 + +- [frontend/antdx/actions/actions.tsx:39-96](file://frontend/antdx/actions/actions.tsx#L39-L96) +- [frontend/antdx/actions/Index.svelte:27-77](file://frontend/antdx/actions/Index.svelte#L27-L77) + +## 依赖关系分析 + +- 组件耦合 + - Item 容器与 Actions 主容器通过上下文与渲染管线解耦，仅在渲染阶段产生依赖。 + - 插槽系统通过 ReactSlot 与 ContextPropsProvider 解耦插槽内容与宿主组件。 +- 外部依赖 + - Ant Design X：提供 Actions 与 Actions.Item 的基础能力。 + - Gradio：后端组件桥接前端事件与数据流。 + +```mermaid +graph LR +Item["Item 容器"] --> ADX["Ant Design X"] +Item --> Slots["插槽系统"] +ADX --> Events["事件系统"] +Slots --> Params["参数化渲染"] +Events --> Backend["后端组件"] +``` + +图表来源 + +- [frontend/antdx/actions/item/actions.item.tsx:10-32](file://frontend/antdx/actions/item/actions.item.tsx#L10-L32) +- [frontend/antdx/actions/actions.tsx:39-96](file://frontend/antdx/actions/actions.tsx#L39-L96) +- [backend/modelscope_studio/components/antdx/actions/item/**init**.py:15-19](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L15-L19) + +章节来源 + +- [frontend/antdx/actions/item/actions.item.tsx:1-35](file://frontend/antdx/actions/item/actions.item.tsx#L1-L35) +- [frontend/antdx/actions/actions.tsx:1-123](file://frontend/antdx/actions/actions.tsx#L1-L123) +- [backend/modelscope_studio/components/antdx/actions/item/**init**.py:1-77](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L1-L77) + +## 性能考量 + +- 渲染优化 + - 使用延迟派生（$derived）与 useMemo 化简不必要的重渲染。 + - 通过 renderItems 的 clone/forceClone 控制克隆策略，减少重复渲染成本。 +- 事件与状态 + - 事件绑定仅在需要时启用，避免全局监听带来的开销。 + - 状态切换（如 loading/error/running/default）尽量通过属性驱动，减少副作用。 + +章节来源 + +- [frontend/antdx/actions/item/Index.svelte:19-41](file://frontend/antdx/actions/item/Index.svelte#L19-L41) +- [frontend/antdx/actions/actions.tsx:104-113](file://frontend/antdx/actions/actions.tsx#L104-L113) +- [frontend/utils/renderItems.tsx:8-114](file://frontend/utils/renderItems.tsx#L8-L114) + +## 故障排查指南 + +- 插槽未生效 + - 检查插槽键名是否正确（如 defaultIcon、runningIcon）。 + - 确认插槽内容是否为有效元素或配置对象。 +- 图标不显示 + - 确保插槽内容已通过 ReactSlot 正确注入。 + - 检查 Ant Design X 对应字段是否被覆盖。 +- 事件未触发 + - 确认后端组件已声明相应事件（如 click）。 + - 检查事件绑定是否启用（\_internal 标记）。 +- 子项不显示 + - 检查 visible 属性与渲染条件。 + - 确认 items 上下文是否正确收集并传递。 + +章节来源 + +- [frontend/antdx/actions/item/actions.item.tsx:15-28](file://frontend/antdx/actions/item/actions.item.tsx#L15-L28) +- [backend/modelscope_studio/components/antdx/actions/item/**init**.py:15-19](file://backend/modelscope_studio/components/antdx/actions/item/__init__.py#L15-L19) +- [frontend/antdx/actions/item/Index.svelte:46-59](file://frontend/antdx/actions/item/Index.svelte#L46-L59) + +## 结论 + +Item 容器在 Actions 体系中扮演“子项定义与渲染”的核心角色。它通过插槽系统与上下文渲染管线，将用户配置转化为 Ant Design X 所需的数据结构，并与事件系统协同完成状态同步与交互反馈。借助其解耦的设计与灵活的插槽机制，开发者可以轻松实现从简单到复杂的操作列表布局，并在响应式场景中获得良好的兼容性。 + +## 附录 + +- 使用示例参考：演示了如何在 Actions 中添加 ActionItem 并通过插槽注入图标与动作渲染器，同时绑定点击事件与子项删除事件。 + +章节来源 + +- [docs/components/antdx/actions/demos/basic.py:17-53](file://docs/components/antdx/actions/demos/basic.py#L17-L53) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\345\217\215\351\246\210\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\345\217\215\351\246\210\347\273\204\344\273\266.md" new file mode 100644 index 00000000..82a408ae --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\345\217\215\351\246\210\347\273\204\344\273\266.md" @@ -0,0 +1,340 @@ +# 反馈组件 + + +**本文引用的文件** +- [frontend/antdx/actions/Index.svelte](file://frontend/antdx/actions/Index.svelte) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [frontend/antdx/actions/action-item/Index.svelte](file://frontend/antdx/actions/action-item/Index.svelte) +- [frontend/antdx/actions/action-item/actions.action-item.tsx](file://frontend/antdx/actions/action-item/actions.action-item.tsx) +- [frontend/antdx/actions/feedback/Index.svelte](file://frontend/antdx/actions/feedback/Index.svelte) +- [frontend/antdx/actions/feedback/actions.feedback.tsx](file://frontend/antdx/actions/feedback/actions.feedback.tsx) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件聚焦于 Ant Design X 的反馈组件体系，尤其是 Actions 操作列表组件与 ActionItem 子组件。Actions 提供统一的操作入口与反馈收集能力，支持通过插槽与属性灵活配置菜单项、下拉渲染、溢出指示器等；ActionItem 则作为子项容器，负责将子树（默认插槽或子项插槽）转换为可被 Actions 解析的结构化数据，并通过上下文机制完成父子通信与状态管理。反馈组件（ActionsFeedback）则封装了 Ant Design X 的反馈能力，便于在对话气泡、消息流等场景中快速集成。 + +该组件体系在改善用户交互体验方面的关键价值在于： + +- 统一的操作入口与视觉风格，降低认知负担 +- 基于插槽的灵活扩展，支持复杂嵌套与动态渲染 +- 通过上下文与状态管理，确保操作项的生命周期与事件正确传递 +- 将“反馈”能力内嵌到操作列表中，提升信息闭环与可用性 + +## 项目结构 + +Ant Design X 的反馈组件位于前端目录的 antdx/actions 下，包含主组件 Actions、子项 ActionItem、反馈组件 ActionsFeedback，以及用于构建操作项结构的上下文工具 createItemsContext。 + +```mermaid +graph TB +subgraph "Ant Design X 反馈组件" +A_Index["actions/Index.svelte"] +A_Tsx["actions/actions.tsx"] +A_Ctx["actions/context.ts"] +AI_Index["actions/action-item/Index.svelte"] +AI_Tsx["actions/action-item/actions.action-item.tsx"] +AF_Index["actions/feedback/Index.svelte"] +AF_Tsx["actions/feedback/actions.feedback.tsx"] +U_Ctx["utils/createItemsContext.tsx"] +end +A_Index --> A_Tsx +A_Tsx --> A_Ctx +A_Tsx --> U_Ctx +AI_Index --> AI_Tsx +AI_Tsx --> A_Ctx +AF_Index --> AF_Tsx +``` + +**图表来源** + +- [frontend/antdx/actions/Index.svelte](file://frontend/antdx/actions/Index.svelte) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [frontend/antdx/actions/action-item/Index.svelte](file://frontend/antdx/actions/action-item/Index.svelte) +- [frontend/antdx/actions/action-item/actions.action-item.tsx](file://frontend/antdx/actions/action-item/actions.action-item.tsx) +- [frontend/antdx/actions/feedback/Index.svelte](file://frontend/antdx/actions/feedback/Index.svelte) +- [frontend/antdx/actions/feedback/actions.feedback.tsx](file://frontend/antdx/actions/feedback/actions.feedback.tsx) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) + +**章节来源** + +- [frontend/antdx/actions/Index.svelte](file://frontend/antdx/actions/Index.svelte) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [frontend/antdx/actions/action-item/Index.svelte](file://frontend/antdx/actions/action-item/Index.svelte) +- [frontend/antdx/actions/action-item/actions.action-item.tsx](file://frontend/antdx/actions/action-item/actions.action-item.tsx) +- [frontend/antdx/actions/feedback/Index.svelte](file://frontend/antdx/actions/feedback/Index.svelte) +- [frontend/antdx/actions/feedback/actions.feedback.tsx](file://frontend/antdx/actions/feedback/actions.feedback.tsx) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) + +## 核心组件 + +- Actions 主组件：负责接收 items 或插槽中的子项，结合上下文与插槽渲染，生成 Ant Design X 的操作列表，并支持下拉渲染、溢出指示器等高级特性。 +- ActionItem 子组件：作为单个操作项的容器，将默认插槽与子项插槽合并为统一的数据结构，交由上下文进行收集与传递。 +- ActionsFeedback 反馈组件：对 Ant Design X 的反馈能力进行轻量封装，便于直接在界面中插入反馈入口。 +- 上下文工具 createItemsContext：提供 ItemsContext 的创建、Provider 包装、useItems 钩子与 ItemHandler 组件，支撑操作项的结构化收集与子项递归处理。 + +**章节来源** + +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/actions/action-item/actions.action-item.tsx](file://frontend/antdx/actions/action-item/actions.action-item.tsx) +- [frontend/antdx/actions/feedback/actions.feedback.tsx](file://frontend/antdx/actions/feedback/actions.feedback.tsx) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) + +## 架构总览 + +Actions 的渲染链路分为两层： + +- Svelte 层：Index.svelte 负责解析属性、附加类名与 ID、处理插槽映射，并按需导入 React 实现。 +- React 层：actions.tsx 将插槽与属性转换为 Ant Design X 所需的 items 结构，同时处理下拉菜单的渲染与溢出指示器等高级配置。 + +ActionItem 的职责是将自身包裹的子树（默认插槽与 subItems 插槽）转化为结构化的 Item 数据，并通过上下文写入到父级 Actions 中。 + +```mermaid +sequenceDiagram +participant UI as "调用方" +participant S as "actions/Index.svelte" +participant R as "actions/actions.tsx" +participant C as "actions/context.ts" +participant U as "utils/createItemsContext.tsx" +UI->>S : 传入属性与插槽 +S->>R : 导入并传递 props、slots、额外属性 +R->>C : 使用上下文 Provider 包裹 +R->>U : 使用 createItemsContext 收集 items +R->>R : 渲染 Ant Design X 的 Actions +Note over R : 处理 dropdownRender/popupRender/overflowedIndicator 等插槽 +``` + +**图表来源** + +- [frontend/antdx/actions/Index.svelte](file://frontend/antdx/actions/Index.svelte) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) + +## 详细组件分析 + +### Actions 主组件 + +- 输入与属性处理：通过 Svelte 的 getProps/processProps 对可见性、元素样式/类名、ID、额外属性等进行统一处理，并将部分事件映射为 Ant Design X 所需的命名。 +- 插槽与渲染：支持 children、dropdownRender、popupRender、overflowedIndicator、expandIcon 等插槽；通过 renderSlot/renderParamsSlot 将插槽转换为 React 可识别的渲染函数或节点。 +- 下拉菜单增强：当存在 dropdownProps.menu.items 或插槽时，优先使用插槽生成的 items；同时支持自定义 expandIcon 与 overflowedIndicator。 +- 状态与事件：通过 useItems 与 useMenuItems 获取上下文中的 items，避免重复渲染；事件如 openChange/select/deselect 等通过 props 透传给底层组件。 + +```mermaid +flowchart TD +Start(["进入 Actions 渲染"]) --> CheckVisible{"是否可见?"} +CheckVisible --> |否| End(["结束"]) +CheckVisible --> |是| ResolveItems["解析 items 或插槽子项"] +ResolveItems --> BuildDropdown["构建 dropdownProps
合并插槽与属性"] +BuildDropdown --> RenderX["渲染 Ant Design X Actions"] +RenderX --> End +``` + +**图表来源** + +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) + +**章节来源** + +- [frontend/antdx/actions/Index.svelte](file://frontend/antdx/actions/Index.svelte) +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) + +### ActionItem 子组件 + +- 插槽与属性：支持 actionRender 插槽与 actionRender 属性，通过 createFunction 将字符串或函数转换为可执行函数；同时保留默认插槽与子项插槽。 +- 上下文写入：通过 ItemHandler 将当前项的 props、slots、子项等结构化数据写入上下文，供父级 Actions 消费。 +- 子项选择策略：若存在 subItems，则优先使用 subItems；否则回退到 default 插槽，形成灵活的层级结构。 + +```mermaid +sequenceDiagram +participant Parent as "Actions" +participant Child as "ActionItem" +participant Handler as "ItemHandler" +participant Ctx as "ItemsContext" +Parent->>Child : 传入 props 与 slots +Child->>Handler : 包装并设置 allowedSlots=['default','subItems'] +Handler->>Ctx : 写入当前项的 props/slots/子项 +Ctx-->>Parent : 提供 items 供 Actions 渲染 +``` + +**图表来源** + +- [frontend/antdx/actions/action-item/Index.svelte](file://frontend/antdx/actions/action-item/Index.svelte) +- [frontend/antdx/actions/action-item/actions.action-item.tsx](file://frontend/antdx/actions/action-item/actions.action-item.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) + +**章节来源** + +- [frontend/antdx/actions/action-item/Index.svelte](file://frontend/antdx/actions/action-item/Index.svelte) +- [frontend/antdx/actions/action-item/actions.action-item.tsx](file://frontend/antdx/actions/action-item/actions.action-item.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) + +### ActionsFeedback 反馈组件 + +- 角色定位：对 Ant Design X 的 Actions.Feedback 进行轻量封装，简化调用方式。 +- 插槽与属性：保持与上层一致的插槽与属性处理流程，便于在对话气泡、消息流等场景中直接使用。 + +```mermaid +sequenceDiagram +participant UI as "调用方" +participant F_Index as "feedback/Index.svelte" +participant F_Tsx as "feedback/actions.feedback.tsx" +UI->>F_Index : 传入属性与插槽 +F_Index->>F_Tsx : 导入并传递 props、slots +F_Tsx-->>UI : 渲染 Ant Design X 的 Actions.Feedback +``` + +**图表来源** + +- [frontend/antdx/actions/feedback/Index.svelte](file://frontend/antdx/actions/feedback/Index.svelte) +- [frontend/antdx/actions/feedback/actions.feedback.tsx](file://frontend/antdx/actions/feedback/actions.feedback.tsx) + +**章节来源** + +- [frontend/antdx/actions/feedback/Index.svelte](file://frontend/antdx/actions/feedback/Index.svelte) +- [frontend/antdx/actions/feedback/actions.feedback.tsx](file://frontend/antdx/actions/feedback/actions.feedback.tsx) + +### 上下文与状态管理（createItemsContext） + +- ItemsContext：维护每个插槽下的 Item 数组，提供 setItem 以按索引更新项；onChange 回调用于通知父级更新。 +- ItemHandler：在组件挂载时将当前项的 props、slots、子项等结构化数据写入上下文；支持 itemProps 与 itemChildren 的动态计算。 +- withItemsContextProvider：为子树提供 ItemsContextProvider，使子项可继续写入自己的子项，形成递归结构。 + +```mermaid +classDiagram +class ItemsContextProvider { ++allowedSlots ++onChange(items) ++setItem(slotKey, index, item) +} +class ItemHandler { ++itemIndex ++itemSlotKey ++itemProps(props, items) ++itemChildren(items) ++allowedSlots +} +class ItemsContext { ++items ++setItem() ++initial +} +ItemsContextProvider --> ItemsContext : "提供上下文" +ItemHandler --> ItemsContext : "写入项" +``` + +**图表来源** + +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) + +**章节来源** + +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) + +## 依赖关系分析 + +- Actions 依赖： + - 上下文：actions/context.ts 与 utils/createItemsContext.tsx 共同构成项收集与传递的基础。 + - 插槽渲染：renderSlot/renderParamsSlot 将插槽转换为 React 可执行函数或节点。 + - Ant Design X：最终渲染由 @ant-design/x 的 Actions 组件承担。 +- ActionItem 依赖： + - ItemHandler 与上下文：将自身结构写入上下文，供父级消费。 + - 插槽处理：支持 actionRender 与默认/子项插槽。 +- ActionsFeedback 依赖： + - 直接封装 Ant Design X 的 Actions.Feedback。 + +```mermaid +graph LR +Actions["actions.tsx"] --> Ctx["actions/context.ts"] +Actions --> Utils["utils/createItemsContext.tsx"] +Actions --> ADX["@ant-design/x Actions"] +ActionItem["action-item/actions.action-item.tsx"] --> Ctx +ActionItem --> Utils +Feedback["feedback/actions.feedback.tsx"] --> ADX_F["@ant-design/x Actions.Feedback"] +``` + +**图表来源** + +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/antdx/actions/feedback/actions.feedback.tsx](file://frontend/antdx/actions/feedback/actions.feedback.tsx) + +**章节来源** + +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/actions/context.ts](file://frontend/antdx/actions/context.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/antdx/actions/feedback/actions.feedback.tsx](file://frontend/antdx/actions/feedback/actions.feedback.tsx) + +## 性能考量 + +- 渲染优化： + - 使用 useMemo 缓存 dropdownProps 的构建结果，避免不必要的重渲染。 + - 仅在存在有效值时才注入 dropdownProps，减少空对象带来的副作用。 +- 事件与属性： + - 通过 processProps 将事件名映射为底层组件所需的命名，避免运行时转换开销。 +- 插槽处理： + - renderSlot/renderParamsSlot 在必要时才进行克隆与参数化包装，降低 DOM 操作成本。 +- 上下文写入： + - 使用 useRef 与 isEqual 比较前后值，仅在变化时触发 setItem，避免重复写入。 + +[本节为通用性能建议，不直接分析具体文件] + +## 故障排查指南 + +- 问题：操作项未显示 + - 排查点：确认 visible 属性为真；检查 items 是否为空；确认插槽键名是否匹配 allowedSlots。 + - 参考路径：[frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- 问题：下拉菜单未生效 + - 排查点：检查 dropdownProps.menu.items 是否正确传入；确认插槽 dropdownProps.menu.items 是否被渲染。 + - 参考路径：[frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- 问题：子项未正确嵌套 + - 排查点：确认 ActionItem 的 subItems 插槽是否正确命名；检查 ItemHandler 的 itemChildrenKey 设置。 + - 参考路径：[frontend/antdx/actions/action-item/actions.action-item.tsx](file://frontend/antdx/actions/action-item/actions.action-item.tsx) +- 问题：事件未触发 + - 排查点：确认事件名映射是否正确；检查 props 是否透传到底层组件。 + - 参考路径：[frontend/antdx/actions/Index.svelte](file://frontend/antdx/actions/Index.svelte) + +**章节来源** + +- [frontend/antdx/actions/actions.tsx](file://frontend/antdx/actions/actions.tsx) +- [frontend/antdx/actions/action-item/actions.action-item.tsx](file://frontend/antdx/actions/action-item/actions.action-item.tsx) +- [frontend/antdx/actions/Index.svelte](file://frontend/antdx/actions/Index.svelte) + +## 结论 + +Actions 操作列表组件通过清晰的上下文与插槽机制，实现了灵活且高性能的操作项管理；ActionItem 作为子项容器，提供了稳定的结构化数据写入能力；ActionsFeedback 则将反馈能力无缝集成到操作列表中。整体设计在保证易用性的同时，兼顾了扩展性与性能，能够显著提升用户在对话、消息、提示等场景中的交互体验。 + +[本节为总结性内容，不直接分析具体文件] + +## 附录 + +- 使用示例（场景指引） + - 反馈收集：在需要收集用户反馈的区域放置 ActionsFeedback，通过插槽与属性配置反馈入口。 + - 操作执行：在 Actions 中配置 items，结合插槽 dropdownRender/popupRender 自定义菜单外观；通过事件回调处理点击与选择。 + - 结果展示：利用插槽 overflowedIndicator 与 expandIcon 控制菜单的溢出与展开行为，确保在小屏设备上的良好体验。 +- 最佳实践 + - 合理划分插槽键名，避免冲突；统一命名规范，便于维护。 + - 使用 useMemo 缓存复杂计算，减少渲染压力。 + - 事件处理函数尽量保持稳定，避免因函数引用变化导致的重渲染。 + +[本节为概念性内容，不直接分析具体文件] diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\224\244\351\206\222\347\273\204\344\273\266/Prompts \346\217\220\347\244\272\351\233\206\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\224\244\351\206\222\347\273\204\344\273\266/Prompts \346\217\220\347\244\272\351\233\206\347\273\204\344\273\266.md" new file mode 100644 index 00000000..7cb134b2 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\224\244\351\206\222\347\273\204\344\273\266/Prompts \346\217\220\347\244\272\351\233\206\347\273\204\344\273\266.md" @@ -0,0 +1,408 @@ +# Prompts 提示集组件 + + +**本文引用的文件** +- [frontend/antdx/prompts/prompts.tsx](file://frontend/antdx/prompts/prompts.tsx) +- [frontend/antdx/prompts/context.ts](file://frontend/antdx/prompts/context.ts) +- [frontend/antdx/prompts/item/Index.svelte](file://frontend/antdx/prompts/item/Index.svelte) +- [frontend/antdx/prompts/item/prompts.item.tsx](file://frontend/antdx/prompts/item/prompts.item.tsx) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [backend/modelscope_studio/components/antdx/prompts/__init__.py](file://backend/modelscope_studio/components/antdx/prompts/__init__.py) +- [backend/modelscope_studio/components/antdx/prompts/item/__init__.py](file://backend/modelscope_studio/components/antdx/prompts/item/__init__.py) +- [docs/components/antdx/prompts/README.md](file://docs/components/antdx/prompts/README.md) +- [docs/components/antdx/prompts/demos/basic.py](file://docs/components/antdx/prompts/demos/basic.py) +- [docs/components/antdx/prompts/demos/nest_usage.py](file://docs/components/antdx/prompts/demos/nest_usage.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：使用示例与配置](#附录使用示例与配置) + +## 简介 + +Prompts 提示集组件用于展示一组预设的问题或建议项，帮助用户快速选择输入方向，提升对话引导的自然性与效率。该组件基于 Ant Design X 的 Prompts 实现，并在前端通过 Svelte/React 混合框架进行桥接，支持： + +- 提示模板管理：通过插槽（slots）灵活组织标题、图标、标签、描述等子内容 +- 预设指令配置：支持垂直布局、换行、样式覆盖、类名等配置 +- 嵌套使用：支持在提示项内部再嵌套提示项，形成层级化建议 +- 动态内容生成：通过上下文收集子项并渲染为 Ant Design X 所需的数据结构 +- 事件处理：提供 item_click 回调，便于在点击提示项时执行业务逻辑 + +## 项目结构 + +本组件位于前端 antdx 分类下，采用“容器组件 + 子项处理器”的分层设计： + +- 容器组件：负责收集插槽内容、解析上下文、渲染为 Ant Design X 所需的 items 结构 +- 子项处理器：负责将每个提示项包装为可被容器识别的结构，并支持嵌套 +- 工具函数：提供通用的“项目上下文”与“渲染子项”能力，复用到多个组件中 + +```mermaid +graph TB +subgraph "前端 antdx" +P["Prompts 容器
frontend/antdx/prompts/prompts.tsx"] +Ctx["Items 上下文
frontend/antdx/prompts/context.ts"] +Item["提示项处理器
frontend/antdx/prompts/item/prompts.item.tsx"] +ItemUI["提示项 UI 包装
frontend/antdx/prompts/item/Index.svelte"] +Utils1["createItemsContext
frontend/utils/createItemsContext.tsx"] +Utils2["renderItems
frontend/utils/renderItems.tsx"] +end +subgraph "后端" +BP["后端容器组件
backend/.../prompts/__init__.py"] +BI["后端子项组件
backend/.../prompts/item/__init__.py"] +end +P --> Ctx +P --> Utils2 +Ctx --> Utils1 +Item --> Ctx +ItemUI --> Item +P --> BP +Item --> BI +``` + +图表来源 + +- [frontend/antdx/prompts/prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [frontend/antdx/prompts/context.ts:1-7](file://frontend/antdx/prompts/context.ts#L1-L7) +- [frontend/antdx/prompts/item/prompts.item.tsx:1-22](file://frontend/antdx/prompts/item/prompts.item.tsx#L1-L22) +- [frontend/antdx/prompts/item/Index.svelte:1-69](file://frontend/antdx/prompts/item/Index.svelte#L1-L69) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:1-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L1-L88) +- [backend/modelscope_studio/components/antdx/prompts/item/**init**.py:1-48](file://backend/modelscope_studio/components/antdx/prompts/item/__init__.py#L1-L48) + +章节来源 + +- [frontend/antdx/prompts/prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [frontend/antdx/prompts/context.ts:1-7](file://frontend/antdx/prompts/context.ts#L1-L7) +- [frontend/antdx/prompts/item/prompts.item.tsx:1-22](file://frontend/antdx/prompts/item/prompts.item.tsx#L1-L22) +- [frontend/antdx/prompts/item/Index.svelte:1-69](file://frontend/antdx/prompts/item/Index.svelte#L1-L69) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:1-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L1-L88) +- [backend/modelscope_studio/components/antdx/prompts/item/**init**.py:1-48](file://backend/modelscope_studio/components/antdx/prompts/item/__init__.py#L1-L48) + +## 核心组件 + +- 容器组件：Prompts + - 职责：收集插槽（title、items）与子项，解析上下文，将子项转换为 Ant Design X 所需的 items 数据结构，并渲染 + - 关键点：支持传入 items 外部数据；若未传入，则从上下文解析默认或命名插槽中的子项；title 插槽优先于 props.title +- 子项处理器：Prompts.Item + - 职责：将每个提示项包装为可被容器识别的结构，支持插槽（label、icon、description）与可见性控制 + - 关键点：仅允许 default 插槽作为子项内容；支持额外属性透传与内部索引、插槽键传递 +- 项目上下文：createItemsContext + - 职责：提供 ItemsContext，统一收集与更新各插槽中的子项，支持嵌套子上下文 + - 关键点：setItem 支持按插槽键与索引更新；onChange 回调通知父级上下文 +- 渲染工具：renderItems + - 职责：将上下文中的 Item 结构渲染为 React 可用的对象树，自动处理插槽、克隆与参数化渲染 + - 关键点：支持 children 键、withParams 参数化渲染、forceClone 强制克隆 + +章节来源 + +- [frontend/antdx/prompts/prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) +- [frontend/antdx/prompts/item/prompts.item.tsx:7-19](file://frontend/antdx/prompts/item/prompts.item.tsx#L7-L19) +- [frontend/antdx/prompts/item/Index.svelte:16-68](file://frontend/antdx/prompts/item/Index.svelte#L16-L68) +- [frontend/utils/createItemsContext.tsx:97-273](file://frontend/utils/createItemsContext.tsx#L97-L273) +- [frontend/utils/renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +## 架构总览 + +Prompts 的运行时架构由“前端容器 + 子项处理器 + 上下文收集 + 渲染工具”构成，后端通过 Gradio 组件桥接到前端。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant F as "前端容器(Prompts)" +participant C as "Items 上下文" +participant R as "渲染工具(renderItems)" +participant X as "Ant Design X(Prompts)" +U->>F : 创建 Prompts 并传入 props/插槽 +F->>C : useItems 获取 items 上下文 +C-->>F : 返回默认/命名插槽中的子项 +F->>R : 将子项转换为 Ant Design X 所需结构 +R-->>F : 返回 items 数组 +F->>X : 渲染并传入 items/title/其他配置 +X-->>U : 展示提示集 UI +``` + +图表来源 + +- [frontend/antdx/prompts/prompts.tsx:16-38](file://frontend/antdx/prompts/prompts.tsx#L16-L38) +- [frontend/utils/renderItems.tsx:23-38](file://frontend/utils/renderItems.tsx#L23-L38) +- [frontend/utils/createItemsContext.tsx:108-170](file://frontend/utils/createItemsContext.tsx#L108-L170) + +## 详细组件分析 + +### 容器组件：Prompts + +- 插槽与属性 + - 支持插槽：title、items + - 支持属性：vertical、wrap、styles、class_names、root_class_name、fade_in、fade_in_left 等 +- 上下文解析 + - 若外部传入 items 则直接使用；否则从上下文解析 default 或 items 插槽 + - title 插槽优先于 props.title +- 渲染策略 + - 使用 renderItems 将上下文中的 Item 结构转换为 Ant Design X 所需对象数组 + - 对插槽内容进行克隆与参数化处理，确保 React 渲染正确 + +```mermaid +flowchart TD +Start(["进入 Prompts"]) --> CheckItems["是否传入 items?"] +CheckItems --> |是| UseExternal["使用外部 items"] +CheckItems --> |否| ResolveCtx["从上下文解析 items/default"] +ResolveCtx --> Render["调用 renderItems 转换"] +UseExternal --> Render +Render --> PassProps["传给 Ant Design X 组件"] +PassProps --> End(["完成渲染"]) +``` + +图表来源 + +- [frontend/antdx/prompts/prompts.tsx:16-38](file://frontend/antdx/prompts/prompts.tsx#L16-L38) +- [frontend/utils/renderItems.tsx:23-38](file://frontend/utils/renderItems.tsx#L23-L38) + +章节来源 + +- [frontend/antdx/prompts/prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:28-69](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L28-L69) + +### 子项处理器：Prompts.Item + +- 插槽与属性 + - 支持插槽：label、icon、description + - 支持属性：key、label、description、icon、disabled、visible、elem_id、elem_classes、elem_style 等 +- 内部处理 + - 通过 ItemHandler 将子项注册到上下文中，并支持子项的 children 递归渲染 + - 仅允许 default 插槽作为子项内容，避免多级插槽导致的歧义 +- 可见性与样式 + - visible 控制是否渲染；elem_id/ elem_classes/ elem_style 支持样式定制 + +```mermaid +classDiagram +class PromptsItem { ++props : Partial
__init__.py"] +DEV_COMP["基础组件基类
component.py"] +end +subgraph "前端" +SV_INDEX["Svelte 入口
Index.svelte"] +TS_WELCOME["React 桥接组件
welcome.tsx"] +PKG["包导出配置
package.json"] +CFG["Gradio 构建配置
gradio.config.js"] +end +subgraph "文档" +DOC_README["组件文档
README.md"] +DOC_DEMOS["示例脚本
demos/basic.py"] +DOC_APP["文档应用入口
app.py"] +DOC_HELPER["文档渲染器
Docs.py"] +end +PY_INIT --> DEV_COMP +PY_INIT --> SV_INDEX +SV_INDEX --> TS_WELCOME +PKG --> SV_INDEX +CFG --> SV_INDEX +DOC_README --> DOC_APP +DOC_DEMOS --> DOC_APP +DOC_HELPER --> DOC_APP +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:1-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L1-L73) +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [frontend/antdx/welcome/Index.svelte:1-65](file://frontend/antdx/welcome/Index.svelte#L1-L65) +- [frontend/antdx/welcome/welcome.tsx:1-51](file://frontend/antdx/welcome/welcome.tsx#L1-L51) +- [frontend/antdx/welcome/package.json:1-15](file://frontend/antdx/welcome/package.json#L1-L15) +- [frontend/antdx/welcome/gradio.config.js:1-4](file://frontend/antdx/welcome/gradio.config.js#L1-L4) +- [docs/components/antdx/welcome/README.md:1-8](file://docs/components/antdx/welcome/README.md#L1-L8) +- [docs/components/antdx/welcome/demos/basic.py:1-37](file://docs/components/antdx/welcome/demos/basic.py#L1-L37) +- [docs/components/antdx/welcome/app.py:1-7](file://docs/components/antdx/welcome/app.py#L1-L7) +- [docs/helper/Docs.py:1-178](file://docs/helper/Docs.py#L1-L178) + +## 核心组件 + +- 后端包装类：负责声明支持的插槽、属性、样式与渲染生命周期，同时将静态资源路径转换为可访问的 URL。 +- 前端桥接层：将 Ant Design X 的 React 组件以 Svelte 方式封装，支持 slot 渲染与静态资源 URL 解析。 +- 文档与示例：提供最小可用示例与文档页面，便于快速上手。 + +关键职责与行为 + +- 插槽支持：title、description、icon、extra。 +- 属性配置：icon、title、description、variant（filled/borderless）、样式与类名注入、可见性与 DOM 属性透传。 +- 资源处理：对后端传入的图标路径进行解析，确保在 Gradio 环境下可正确加载。 +- 渲染策略：根据 visible 控制是否渲染；在 Gradio 上下文中注入共享的 rootUrl 与 apiPrefix。 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:14-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L14-L55) +- [frontend/antdx/welcome/welcome.tsx:8-41](file://frontend/antdx/welcome/welcome.tsx#L8-L41) +- [frontend/antdx/welcome/Index.svelte:12-44](file://frontend/antdx/welcome/Index.svelte#L12-L44) + +## 架构总览 + +Welcome 组件采用"后端组件 + 前端桥接 + 文档示例"的分层设计。后端负责组件语义与资源处理，前端负责 UI 渲染与插槽对接，文档系统负责示例与说明的统一呈现。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant G as "Gradio 应用" +participant PY as "后端包装类
AntdXWelcome" +participant SV as "Svelte 入口
Index.svelte" +participant RX as "React 组件桥接
welcome.tsx" +participant ADX as "Ant Design X
Welcome" +U->>G : 打开页面 +G->>PY : 初始化并传递属性与插槽 +PY-->>SV : 注入额外属性与静态资源 +SV->>SV : 判断 visible 并按需渲染 +SV->>RX : 传递属性、插槽与共享上下文 +RX->>ADX : 渲染 Ant Design X Welcome +ADX-->>U : 展示标题/描述/图标/附加操作 +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:37-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L37-L55) +- [frontend/antdx/welcome/Index.svelte:49-64](file://frontend/antdx/welcome/Index.svelte#L49-L64) +- [frontend/antdx/welcome/welcome.tsx:16-41](file://frontend/antdx/welcome/welcome.tsx#L16-L41) + +## 详细组件分析 + +### 后端包装类（Python） + +- 支持的插槽：extra、icon、description、title。 +- 关键属性： + - 图标：icon（支持本地静态文件路径，经后端转换为可访问 URL）。 + - 标题与描述：title、description。 + - 变体：variant（filled 或 borderless）。 + - 样式与类名：styles、class_names、elem_id、elem_classes、elem_style。 + - 渲染控制：visible、render、as_item。 +- 生命周期： + - preprocess/postprocess/example_payload/example_value 等占位实现，skip_api 返回 True，表明该组件不参与标准 API 流程。 +- 前端目录定位：通过 resolve_frontend_dir("welcome", type="antdx") 指向前端实现。 + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__() ++__init__(visible, elem_id, elem_classes, elem_style, render, ...) +} +class AntdXWelcome { ++EVENTS ++SLOTS ++additional_props ++extra ++icon ++styles ++class_names ++description ++variant ++title ++root_class_name ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +AntdXWelcome --|> ModelScopeLayoutComponent : "继承" +``` + +**图表来源** + +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:14-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L14-L55) +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) + +### 前端桥接层（Svelte + React） + +- Svelte 入口负责： + - 获取组件属性与额外属性，过滤掉内部保留字段（如 visible、\_internal），并将剩余属性透传给 React 组件。 + - 使用条件渲染仅在 visible 为真时加载并渲染 React 组件。 + - 将 Gradio 共享的 rootUrl 与 apiPrefix 传递给 React 组件，以便解析静态资源。 +- React 桥接负责： + - 将 Ant Design X 的 Welcome 组件以 sveltify 包裹，支持 slot 渲染。 + - 对 icon 进行优先级处理：若存在 slot 则渲染 slot 内容，否则解析静态资源 URL。 + - 对 title、description、extra 同样支持 slot 与字符串值的双模式。 + - **新增**：增强样式支持系统，提供更好的布局控制能力。 + +```mermaid +flowchart TD +Start(["进入 Svelte 入口"]) --> GetProps["获取组件属性与额外属性"] +GetProps --> Filter["过滤内部字段并透传"] +Filter --> Visible{"visible 为真？"} +Visible --> |否| Skip["跳过渲染"] +Visible --> |是| Load["动态导入 React 组件"] +Load --> Render["渲染 React 桥接组件"] +Render --> Styles["应用样式增强系统"] +Styles --> Slots{"是否存在插槽？"} +Slots --> |是| SlotRender["使用 ReactSlot 渲染插槽内容"] +Slots --> |否| StaticURL["解析静态资源 URL"] +SlotRender --> Done(["完成"]) +StaticURL --> Done +Skip --> End(["结束"]) +Done --> End +``` + +**图表来源** + +- [frontend/antdx/welcome/Index.svelte:22-44](file://frontend/antdx/welcome/Index.svelte#L22-L44) +- [frontend/antdx/welcome/welcome.tsx:16-41](file://frontend/antdx/welcome/welcome.tsx#L16-L41) + +**章节来源** + +- [frontend/antdx/welcome/Index.svelte:12-44](file://frontend/antdx/welcome/Index.svelte#L12-L44) +- [frontend/antdx/welcome/welcome.tsx:8-41](file://frontend/antdx/welcome/welcome.tsx#L8-L41) + +### 文档与示例（Docs 系统） + +- 文档应用通过 Docs 类扫描 README 与 demos 目录，自动渲染示例代码与运行结果。 +- 示例脚本演示了两种变体（默认与 borderless），并通过插槽注入额外操作按钮。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant DocApp as "文档应用
app.py" +participant Helper as "Docs 渲染器
Docs.py" +participant Demo as "示例脚本
basic.py" +participant Comp as "Welcome 组件" +Dev->>DocApp : 启动文档服务 +DocApp->>Helper : 初始化并加载文档与示例 +Helper->>Demo : 动态导入示例模块 +Demo->>Comp : 创建 Welcome 实例并配置属性 +Comp-->>Dev : 在文档页面中展示效果 +``` + +**图表来源** + +- [docs/components/antdx/welcome/app.py:1-7](file://docs/components/antdx/welcome/app.py#L1-L7) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) +- [docs/components/antdx/welcome/demos/basic.py:6-36](file://docs/components/antdx/welcome/demos/basic.py#L6-L36) + +**章节来源** + +- [docs/components/antdx/welcome/README.md:1-8](file://docs/components/antdx/welcome/README.md#L1-L8) +- [docs/components/antdx/welcome/demos/basic.py:1-37](file://docs/components/antdx/welcome/demos/basic.py#L1-L37) +- [docs/components/antdx/welcome/app.py:1-7](file://docs/components/antdx/welcome/app.py#L1-L7) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) + +## 样式增强特性 + +### 增强的样式支持系统 + +Welcome 组件现已提供更强大的样式支持和布局控制能力，主要体现在以下几个方面： + +#### 图标区域布局优化 + +- **flexShrink 控制**：为图标区域设置了 `flexShrink: 0`，确保图标在响应式布局中保持固定尺寸 +- **样式合并机制**：支持用户自定义样式与默认样式的智能合并 +- **响应式适配**：优化了不同屏幕尺寸下的布局表现 + +#### 样式定制能力 + +- **styles 参数支持**：完全支持 Ant Design X 的 styles 参数传递 +- **icon 样式独立控制**：允许对图标区域进行单独的样式定制 +- **主题一致性**：保持与 Ant Design X 主题系统的兼容性 + +#### 布局控制增强 + +- **容器样式透传**：支持通过 elem_style 和 elem_classes 进行容器级别的样式控制 +- **Flexbox 优化**：利用 Flexbox 布局提供更好的内容排列效果 +- **间距控制**：优化了图标、标题、描述之间的间距表现 + +```mermaid +graph LR +Styles["样式系统"] --> IconStyle["图标样式控制"] +Styles --> ContainerStyle["容器样式透传"] +Styles --> LayoutControl["布局控制增强"] +IconStyle --> FlexShrink["flexShrink: 0"] +IconStyle --> CustomStyling["自定义样式合并"] +ContainerStyle --> ElemStyle["elem_style 支持"] +ContainerStyle --> ElemClasses["elem_classes 支持"] +LayoutControl --> Responsive["响应式布局"] +LayoutControl --> Spacing["间距优化"] +``` + +**图表来源** + +- [frontend/antdx/welcome/welcome.tsx:23-29](file://frontend/antdx/welcome/welcome.tsx#L23-L29) +- [frontend/antdx/welcome/Index.svelte:52-53](file://frontend/antdx/welcome/Index.svelte#L52-L53) + +**章节来源** + +- [frontend/antdx/welcome/welcome.tsx:23-29](file://frontend/antdx/welcome/welcome.tsx#L23-L29) +- [frontend/antdx/welcome/Index.svelte:52-53](file://frontend/antdx/welcome/Index.svelte#L52-L53) + +## 依赖关系分析 + +- 后端依赖： + - 基础组件基类：提供通用的布局组件能力与上下文管理。 + - 前端目录解析：通过 resolve_frontend_dir 定位到前端实现。 +- 前端依赖： + - Ant Design X 的 React 组件库。 + - Gradio 客户端工具：用于静态资源 URL 解析。 + - Svelte 预处理工具链：实现 React 组件与 Svelte 的桥接。 + - **新增**：样式系统增强依赖，提供更好的布局控制能力。 +- 文档系统依赖： + - Docs 渲染器负责扫描与渲染 README 与 demos。 + +```mermaid +graph LR +PY["AntdXWelcome
__init__.py"] --> BASE["ModelScopeLayoutComponent
component.py"] +PY --> FE_DIR["resolve_frontend_dir('welcome','antdx')"] +SV["Index.svelte"] --> PREACT["@svelte-preprocess-react/*"] +SV --> CLS["classnames"] +SV --> RX["welcome.tsx"] +RX --> ADX["@ant-design/x"] +RX --> GRCL["@gradio/client"] +RX --> PREACT +RX --> STYLES["样式增强系统"] +DOC["Docs.py"] --> APP["app.py"] +DOC --> DEMO["demos/basic.py"] +DOC --> READ["README.md"] +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:55-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L55-L55) +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [frontend/antdx/welcome/Index.svelte:1-10](file://frontend/antdx/welcome/Index.svelte#L1-L10) +- [frontend/antdx/welcome/welcome.tsx:1-7](file://frontend/antdx/welcome/welcome.tsx#L1-L7) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) +- [docs/components/antdx/welcome/demos/basic.py:1-5](file://docs/components/antdx/welcome/demos/basic.py#L1-L5) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:55-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L55-L55) +- [frontend/antdx/welcome/Index.svelte:1-10](file://frontend/antdx/welcome/Index.svelte#L1-L10) +- [frontend/antdx/welcome/welcome.tsx:1-7](file://frontend/antdx/welcome/welcome.tsx#L1-L7) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) + +## 性能考量 + +- 条件渲染：仅当 visible 为真时才加载并渲染 React 组件，避免不必要的初始化与网络请求。 +- 动态导入：通过异步导入 React 组件，减少首屏负载。 +- 资源解析：在前端统一解析静态资源 URL，避免重复计算与跨域问题。 +- 插槽渲染：优先使用 slot 内容，减少字符串拼接与模板渲染成本。 +- **新增**：样式增强系统采用高效的样式合并算法，避免重复渲染和样式冲突。 + +## 故障排查指南 + +- 图标无法显示 + - 检查后端传入的 icon 是否为有效路径或 URL。 + - 确认 Gradio 共享的 rootUrl 与 apiPrefix 已正确传递至前端。 +- 插槽未生效 + - 确认插槽名称是否为 title、description、icon、extra。 + - 确保插槽内容在运行时已正确挂载。 +- 组件未渲染 + - 检查 visible 是否为真。 + - 确认 FRONTEND_DIR 指向的前端实现存在且可被构建。 +- 文档示例无法运行 + - 检查 demos/basic.py 中的组件嵌套与 Provider 使用是否正确。 + - 确认文档应用入口与 Docs 渲染器配置无误。 +- **新增**：样式显示异常 + - 检查 styles 参数格式是否正确。 + - 确认样式合并逻辑不会导致冲突。 + - 验证 flexShrink 属性是否影响了布局表现。 + +**章节来源** + +- [frontend/antdx/welcome/Index.svelte:49-64](file://frontend/antdx/welcome/Index.svelte#L49-L64) +- [frontend/antdx/welcome/welcome.tsx:16-41](file://frontend/antdx/welcome/welcome.tsx#L16-L41) +- [docs/components/antdx/welcome/demos/basic.py:6-36](file://docs/components/antdx/welcome/demos/basic.py#L6-L36) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) + +## 结论 + +Welcome 欢迎组件通过后端与前端的协同，提供了简洁而强大的欢迎页展示能力。其插槽化设计与资源解析机制，使得在不同场景下都能灵活地进行个性化定制与集成。配合文档系统的示例与渲染能力，开发者可以快速理解并使用该组件。 + +**更新** 本次样式增强进一步提升了组件的布局控制能力和响应式设计表现，为开发者提供了更精细的样式定制选项和更好的用户体验。 + +## 附录 + +### 使用示例（概述） + +- 创建一个基础欢迎页，设置图标、标题与描述。 +- 使用 borderless 变体以适配更轻量的界面风格。 +- 通过插槽注入额外操作按钮，增强用户引导。 +- **新增**：利用增强的样式系统进行更精细的布局控制。 + +参考示例脚本路径 + +- [docs/components/antdx/welcome/demos/basic.py:6-36](file://docs/components/antdx/welcome/demos/basic.py#L6-L36) + +**章节来源** + +- [docs/components/antdx/welcome/demos/basic.py:1-37](file://docs/components/antdx/welcome/demos/basic.py#L1-L37) + +### 属性与事件清单（概述） + +- 支持插槽：extra、icon、description、title。 +- 关键属性：icon、title、description、variant（filled/borderless）、样式与类名、可见性与 DOM 属性。 +- 事件：当前版本未定义事件。 +- 生命周期：skip_api 为真，不参与标准 API 流程。 +- **新增**：样式增强支持，提供更丰富的布局控制选项。 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:12-15](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L12-L15) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:31-37](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L31-L37) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\224\244\351\206\222\347\273\204\344\273\266/\345\224\244\351\206\222\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\224\244\351\206\222\347\273\204\344\273\266/\345\224\244\351\206\222\347\273\204\344\273\266.md" new file mode 100644 index 00000000..a8dbb822 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\224\244\351\206\222\347\273\204\344\273\266/\345\224\244\351\206\222\347\273\204\344\273\266.md" @@ -0,0 +1,293 @@ +# 唤醒组件 + + +**本文引用的文件** +- [backend/modelscope_studio/components/antdx/welcome/__init__.py](file://backend/modelscope_studio/components/antdx/welcome/__init__.py) +- [frontend/antdx/welcome/Index.svelte](file://frontend/antdx/welcome/Index.svelte) +- [frontend/antdx/welcome/welcome.tsx](file://frontend/antdx/welcome/welcome.tsx) +- [backend/modelscope_studio/components/antdx/prompts/__init__.py](file://backend/modelscope_studio/components/antdx/prompts/__init__.py) +- [frontend/antdx/prompts/Index.svelte](file://frontend/antdx/prompts/Index.svelte) +- [frontend/antdx/prompts/prompts.tsx](file://frontend/antdx/prompts/prompts.tsx) +- [frontend/antdx/prompts/item/Index.svelte](file://frontend/antdx/prompts/item/Index.svelte) +- [frontend/antdx/prompts/item/prompts.item.tsx](file://frontend/antdx/prompts/item/prompts.item.tsx) +- [frontend/pro/chatbot/chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py](file://docs/layout_templates/chatbot/demos/fine_grained_control.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向 Ant Design X 唤醒组件，系统性说明 Welcome 欢迎组件与 Prompts 提示集组件的设计与用法，帮助开发者快速构建高质量的初始用户体验：Welcome 负责欢迎页的展示与个性化；Prompts 负责提示模板的组织、预设指令与智能推荐的承载。文档包含组件职责、数据流、交互逻辑、可扩展点以及完整使用示例，便于在实际项目中落地。 + +## 项目结构 + +Ant Design X 唤醒组件由后端 Python 组件与前端 Svelte/React 层协同实现： + +- 后端组件负责参数解析、静态资源处理、事件绑定与渲染开关 +- 前端 Svelte 层负责属性透传、插槽解析与异步加载 React 组件 +- React 层直接对接 @ant-design/x 的原生组件，完成最终渲染 + +```mermaid +graph TB +subgraph "后端" +B_Wel["AntdXWelcome
Python 组件"] +B_Pro["AntdXPrompts
Python 组件"] +end +subgraph "前端" +F_SvWel["welcome/Index.svelte"] +F_SvPro["prompts/Index.svelte"] +F_RcWel["welcome/welcome.tsx"] +F_RcPro["prompts/prompts.tsx"] +F_Item["prompts/item/Index.svelte"] +end +subgraph "第三方" +X["@ant-design/x
React 组件库"] +end +B_Wel --> F_SvWel --> F_RcWel --> X +B_Pro --> F_SvPro --> F_RcPro --> X +F_Item --> F_RcPro +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L55) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-70](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L70) +- [frontend/antdx/welcome/Index.svelte:1-65](file://frontend/antdx/welcome/Index.svelte#L1-L65) +- [frontend/antdx/prompts/Index.svelte:1-70](file://frontend/antdx/prompts/Index.svelte#L1-L70) +- [frontend/antdx/welcome/welcome.tsx:1-44](file://frontend/antdx/welcome/welcome.tsx#L1-L44) +- [frontend/antdx/prompts/prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [frontend/antdx/prompts/item/Index.svelte:1-68](file://frontend/antdx/prompts/item/Index.svelte#L1-L68) + +章节来源 + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) +- [frontend/antdx/welcome/Index.svelte:1-65](file://frontend/antdx/welcome/Index.svelte#L1-L65) +- [frontend/antdx/prompts/Index.svelte:1-70](file://frontend/antdx/prompts/Index.svelte#L1-L70) + +## 核心组件 + +- Welcome 欢迎组件：用于首屏欢迎页展示，支持标题、描述、图标与额外内容的插槽化定制，并可设置样式与变体 +- Prompts 提示集组件：用于展示一组提示模板，支持标题插槽、条目插槽、垂直布局、渐入动画、换行等配置，并提供点击回调事件 + +章节来源 + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L55) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-70](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L70) + +## 架构总览 + +下图展示了从后端到前端再到第三方组件库的数据与控制流： + +```mermaid +sequenceDiagram +participant Py as "后端组件
Python" +participant S as "前端 Svelte
Index.svelte" +participant R as "前端 React 包装
welcome.tsx / prompts.tsx" +participant X as "@ant-design/x
React 组件" +Py->>S : 传递可见性/样式/附加属性 +S->>R : 透传属性与插槽 +R->>X : 渲染原生组件处理图标/标题/描述/条目 +X-->>R : 组件输出 +R-->>S : 返回渲染结果 +S-->>Py : 完成一次渲染 +``` + +图表来源 + +- [frontend/antdx/welcome/Index.svelte:49-64](file://frontend/antdx/welcome/Index.svelte#L49-L64) +- [frontend/antdx/welcome/welcome.tsx:16-41](file://frontend/antdx/welcome/welcome.tsx#L16-L41) +- [frontend/antdx/prompts/Index.svelte:56-69](file://frontend/antdx/prompts/Index.svelte#L56-L69) +- [frontend/antdx/prompts/prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) + +## 详细组件分析 + +### Welcome 欢迎组件 + +- 组件职责 + - 展示欢迎页，支持标题、描述、图标与额外内容的插槽化定制 + - 支持样式与类名注入，以及多种变体风格 + - 图标支持静态资源路径或文件对象，统一通过工具函数转换为可用 URL +- 关键属性 + - 插槽：extra、icon、description、title + - 变体：filled、borderless + - 样式：styles、class_names、root_class_name + - 元信息：elem_id、elem_classes、elem_style、visible、render +- 数据流 + - 后端接收参数并处理静态资源路径 + - 前端 Svelte 将属性与插槽透传给 React 包装层 + - React 层根据插槽优先策略决定渲染内容，并将图标转换为可访问的 URL +- 交互逻辑 + - 作为欢迎页入口，通常在应用初始化时显示 + - 可结合业务逻辑在用户选择提示后隐藏或切换到对话区域 + +```mermaid +flowchart TD +Start(["进入 Welcome 渲染"]) --> CheckIcon["是否提供插槽图标?"] +CheckIcon --> |是| RenderSlotIcon["渲染插槽图标"] +CheckIcon --> |否| ConvertIcon["转换图标为可访问 URL"] +RenderSlotIcon --> RenderTitle["渲染标题插槽/文本"] +ConvertIcon --> RenderTitle +RenderTitle --> RenderDesc["渲染描述插槽/文本"] +RenderDesc --> RenderExtra["渲染额外内容插槽/文本"] +RenderExtra --> ApplyStyles["应用样式与类名"] +ApplyStyles --> End(["完成渲染"]) +``` + +图表来源 + +- [frontend/antdx/welcome/welcome.tsx:16-41](file://frontend/antdx/welcome/welcome.tsx#L16-L41) +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:47-53](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L47-L53) + +章节来源 + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L73) +- [frontend/antdx/welcome/Index.svelte:1-65](file://frontend/antdx/welcome/Index.svelte#L1-L65) +- [frontend/antdx/welcome/welcome.tsx:1-44](file://frontend/antdx/welcome/welcome.tsx#L1-L44) + +### Prompts 提示集组件 + +- 组件职责 + - 展示一组提示模板，支持标题与条目插槽 + - 提供条目点击事件回调，便于触发后续交互 + - 支持垂直布局、渐入动画、换行等视觉配置 +- 关键属性 + - 插槽：title、items + - 列表配置：items、vertical、fade_in、fade_in_left、wrap + - 样式与类名：styles、class_names、root_class_name + - 元信息：elem_id、elem_classes、elem_style、visible、render +- 数据流 + - 后端定义事件监听器，将 item_click 映射为前端事件 + - 前端 Svelte 将属性与插槽透传给 React 包装层 + - React 层合并外部 items 与插槽 items，按需克隆以避免副作用 +- 交互逻辑 + - 用户点击提示项时触发回调，可在上层业务中绑定具体行为（如填充输入框、发起请求） + +```mermaid +sequenceDiagram +participant U as "用户" +participant P as "Prompts 组件" +participant Ctx as "条目上下文" +participant X as "@ant-design/x
Prompts" +U->>P : 点击某提示项 +P->>Ctx : 触发 item_click 事件 +Ctx-->>P : 回调通知 +P->>X : 渲染提示列表合并 items +X-->>U : 展示点击反馈 +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-23](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L23) +- [frontend/antdx/prompts/Index.svelte:48-49](file://frontend/antdx/prompts/Index.svelte#L48-L49) +- [frontend/antdx/prompts/prompts.tsx:13-40](file://frontend/antdx/prompts/prompts.tsx#L13-L40) + +章节来源 + +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-88](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L88) +- [frontend/antdx/prompts/Index.svelte:1-70](file://frontend/antdx/prompts/Index.svelte#L1-L70) +- [frontend/antdx/prompts/prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) +- [frontend/antdx/prompts/item/Index.svelte:1-68](file://frontend/antdx/prompts/item/Index.svelte#L1-L68) +- [frontend/antdx/prompts/item/prompts.item.tsx:1-21](file://frontend/antdx/prompts/item/prompts.item.tsx#L1-L21) + +## 依赖关系分析 + +- 组件耦合 + - 后端组件仅负责参数与静态资源处理，耦合度低 + - 前端 Svelte 层承担属性透传与插槽解析，耦合度低 + - React 包装层与 @ant-design/x 强耦合，但对上层透明 +- 外部依赖 + - @ant-design/x：提供 Welcome 与 Prompts 的原生实现 + - 工具函数：文件 URL 转换、插槽渲染、条目渲染等 +- 事件映射 + - 后端将 item_click 事件映射为前端事件名称，确保跨层一致 + +```mermaid +graph LR +Py["后端组件"] --> Svelte["前端 Svelte"] +Svelte --> ReactWrap["React 包装层"] +ReactWrap --> ADX["@ant-design/x"] +Py --> Utils["工具函数"] +Svelte --> Utils +ReactWrap --> Utils +``` + +图表来源 + +- [frontend/antdx/welcome/welcome.tsx:6-7](file://frontend/antdx/welcome/welcome.tsx#L6-L7) +- [frontend/antdx/prompts/prompts.tsx:9-11](file://frontend/antdx/prompts/prompts.tsx#L9-L11) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-23](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L23) + +章节来源 + +- [backend/modelscope_studio/components/antdx/welcome/**init**.py:8-55](file://backend/modelscope_studio/components/antdx/welcome/__init__.py#L8-L55) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:11-70](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L11-L70) +- [frontend/antdx/welcome/welcome.tsx:1-44](file://frontend/antdx/welcome/welcome.tsx#L1-L44) +- [frontend/antdx/prompts/prompts.tsx:1-43](file://frontend/antdx/prompts/prompts.tsx#L1-L43) + +## 性能考量 + +- 渲染优化 + - 使用异步导入组件，避免首屏阻塞 + - 插槽内容延迟渲染，减少不必要的计算 +- 资源优化 + - 图标统一走 URL 转换，避免重复下载 + - 条目渲染采用克隆策略，降低状态共享带来的重渲染 +- 事件处理 + - 事件映射在前端完成，减少后端负担 + +## 故障排查指南 + +- 图标不显示 + - 检查图标路径是否正确，确认已通过工具函数转换为可访问 URL + - 若使用插槽图标，请确认插槽内容是否正确渲染 +- 插槽内容未生效 + - 确认插槽名称与组件支持的插槽一致（Welcome：extra、icon、description、title；Prompts：title、items） + - 确认插槽内容是否在 React 包装层被正确包裹 +- 点击事件无效 + - 确认后端事件监听器已启用且前端事件映射正确 + - 检查上层业务是否正确绑定回调 + +章节来源 + +- [frontend/antdx/welcome/welcome.tsx:23-37](file://frontend/antdx/welcome/welcome.tsx#L23-L37) +- [frontend/antdx/prompts/Index.svelte:48-49](file://frontend/antdx/prompts/Index.svelte#L48-L49) +- [backend/modelscope_studio/components/antdx/prompts/**init**.py:18-23](file://backend/modelscope_studio/components/antdx/prompts/__init__.py#L18-L23) + +## 结论 + +Welcome 与 Prompts 组件通过清晰的职责划分与插槽化设计，为初始体验提供了高可定制性与良好扩展性。配合 @ant-design/x 的原生能力，既能满足基础展示需求，也能承载复杂的交互与推荐场景。建议在实际项目中结合业务目标，合理配置样式与事件，以获得更佳的用户体验。 + +## 附录 + +### 使用示例与最佳实践 + +- 欢迎页面设计 + - 使用 Welcome 组件作为首屏入口，通过插槽配置标题、描述与图标 + - 配置变体与样式，使其与整体设计风格一致 + - 在用户选择提示后，隐藏欢迎页并进入对话区域 +- 提示集配置 + - 使用 Prompts 组件展示一组提示模板，支持分组与层级 + - 通过插槽与外部 items 组合，灵活管理提示内容 + - 绑定 item_click 事件，实现点击即用的交互 +- 用户引导流程 + - 在应用初始化时显示欢迎页 + - 展示精选提示集，引导用户快速开始 + - 根据用户行为动态调整提示集内容与排序 + +章节来源 + +- [frontend/pro/chatbot/chatbot.tsx:108-115](file://frontend/pro/chatbot/chatbot.tsx#L108-L115) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py:603-619](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L603-L619) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\267\245\345\205\267\347\273\204\344\273\266/CodeHighlighter \344\273\243\347\240\201\351\253\230\344\272\256.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\267\245\345\205\267\347\273\204\344\273\266/CodeHighlighter \344\273\243\347\240\201\351\253\230\344\272\256.md" new file mode 100644 index 00000000..1ddb4635 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\267\245\345\205\267\347\273\204\344\273\266/CodeHighlighter \344\273\243\347\240\201\351\253\230\344\272\256.md" @@ -0,0 +1,335 @@ +# CodeHighlighter 代码高亮 + + +**本文档引用的文件** +- [backend/modelscope_studio/components/antdx/code_highlighter/__init__.py](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py) +- [frontend/antdx/code-highlighter/Index.svelte](file://frontend/antdx/code-highlighter/Index.svelte) +- [frontend/antdx/code-highlighter/code-highlighter.tsx](file://frontend/antdx/code-highlighter/code-highlighter.tsx) +- [frontend/antdx/code-highlighter/package.json](file://frontend/antdx/code-highlighter/package.json) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [docs/components/antdx/code_highlighter/README.md](file://docs/components/antdx/code_highlighter/README.md) +- [docs/components/antdx/code_highlighter/README-zh_CN.md](file://docs/components/antdx/code_highlighter/README-zh_CN.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构概览](#架构概览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) + +## 简介 + +CodeHighlighter 是一个基于 Ant Design X 的代码高亮组件，用于在模型空间工作室（ModelScope Studio）中提供语法高亮显示功能。该组件支持多种编程语言的语法高亮，包括暗色和亮色主题模式，并提供了灵活的配置选项来满足不同的使用场景。 + +该组件通过 Gradio 集成，实现了前后端的无缝连接，为用户提供了一个强大而易用的代码展示工具。组件支持自定义样式、语言选择、头部内容等高级功能。 + +## 项目结构 + +CodeHighlighter 组件在整个项目架构中的位置如下： + +```mermaid +graph TB +subgraph "后端 (Backend)" +A[ModelScope Studio Backend] +B[AntdX Components] +C[CodeHighlighter Component] +end +subgraph "前端 (Frontend)" +D[Svelte 组件] +E[React 包装器] +F[Ant Design X] +end +subgraph "文档 (Documentation)" +G[示例文档] +H[使用说明] +end +A --> B +B --> C +C --> D +D --> E +E --> F +A --> G +G --> H +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/code_highlighter/**init**.py:1-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L1-L71) +- [frontend/antdx/code-highlighter/Index.svelte:1-65](file://frontend/antdx/code-highlighter/Index.svelte#L1-L65) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:1-54](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L1-L54) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/code_highlighter/**init**.py:1-71](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L1-L71) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## 核心组件 + +### 后端组件类 + +CodeHighlighter 后端组件继承自 `ModelScopeLayoutComponent`，提供了完整的组件生命周期管理和属性处理机制。 + +**主要特性：** + +- 支持多种编程语言的语法高亮 +- 自动主题适配（暗色/亮色模式） +- 可定制的样式和类名 +- 插槽系统支持头部内容 +- API 跳过机制优化性能 + +**关键属性：** + +- `value`: 要高亮显示的代码内容 +- `lang`: 编程语言类型 +- `header`: 头部显示内容 +- `highlight_props`: 高亮配置属性 +- `prism_light_mode`: Prism 主题模式设置 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/code_highlighter/**init**.py:15-52](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L15-L52) + +### 前端组件实现 + +前端采用 Svelte + React 的混合架构，通过 `sveltify` 工具实现组件桥接。 + +**技术特点：** + +- 动态导入优化加载性能 +- 支持插槽系统 +- 主题自动检测和切换 +- 自定义样式覆盖 + +**章节来源** + +- [frontend/antdx/code-highlighter/Index.svelte:1-65](file://frontend/antdx/code-highlighter/Index.svelte#L1-L65) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:1-54](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L1-L54) + +## 架构概览 + +CodeHighlighter 采用了分层架构设计，实现了前后端的清晰分离： + +```mermaid +sequenceDiagram +participant Client as 客户端应用 +participant Backend as 后端组件 +participant Frontend as 前端组件 +participant AntDX as Ant Design X +participant Prism as Prism 语法高亮 +Client->>Backend : 创建 CodeHighlighter 实例 +Backend->>Frontend : 解析前端目录 +Frontend->>Frontend : 动态导入 React 组件 +Frontend->>AntDX : 包装为 Svelte 组件 +AntDX->>Prism : 应用语法高亮样式 +Prism-->>AntDX : 返回高亮后的代码 +AntDX-->>Frontend : 渲染最终结果 +Frontend-->>Client : 显示高亮代码块 +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/code_highlighter/**init**.py:53-53](file://backend/modelscope_studio/components/antdx/code_highlighter/__init__.py#L53-L53) +- [frontend/antdx/code-highlighter/Index.svelte:10-12](file://frontend/antdx/code-highlighter/Index.svelte#L10-L12) +- [frontend/antdx/code-highlighter/code-highlighter.tsx:29-51](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L29-L51) + +## 详细组件分析 + +### 组件类结构图 + +```mermaid +classDiagram +class AntdXCodeHighlighter { ++EVENTS : [] ++SLOTS : ["header"] ++additional_props : dict ++styles : dict|str ++class_names : dict|str ++root_class_name : str ++value : str|None ++lang : str|None ++header : str|bool|None ++highlight_props : dict|None ++prism_light_mode : bool|None ++FRONTEND_DIR : str ++skip_api : bool ++preprocess(payload) None ++postprocess(value) None ++example_payload() None ++example_value() None +} +class ModelScopeLayoutComponent { +<
过滤内部字段"] +GetProps --> MergeTheme["合并 theme 优先级
theme_config > restProps.theme > additionalProps.theme"] +MergeTheme --> SetMode["读取 Gradio 共享主题
确定 themeMode"] +SetMode --> ImportCP["异步导入 ConfigProvider"] +ImportCP --> Render["渲染 ConfigProvider 并注入上下文"] +Render --> End(["完成"]) +``` + +图示来源 + +- [XProvider.svelte:17-74](file://frontend/antdx/x-provider/XProvider.svelte#L17-L74) + +章节来源 + +- [XProvider.svelte:1-75](file://frontend/antdx/x-provider/XProvider.svelte#L1-L75) + +### ConfigProvider 实现（前端） + +职责与要点 + +- 主题算法：根据 themeMode 与 props.theme.algorithm 自动组合暗色与紧凑算法。 +- 国际化：支持 locale 字符串或自动识别浏览器语言，按需动态加载对应语言包与 dayjs 本地化。 +- 容器挂载：提供 getPopupContainer 与 getTargetContainer 的函数包装，便于弹层容器自定义。 +- 插槽整合：将 slots 中的嵌套键路径转换为对应的 React 组件树，支持 renderEmpty 等插槽。 + +```mermaid +flowchart TD +A["接收 props/themeMode/locale"] --> B["计算 algorithm 列表"] +B --> C["动态加载 locale 对应资源"] +C --> D["组合 props 与 slots"] +D --> E["渲染 StyleProvider + ConfigProvider"] +E --> F["向下提供主题/语言/容器策略"] +``` + +图示来源 + +- [config-provider.tsx:71-149](file://frontend/antd/config-provider/config-provider.tsx#L71-L149) +- [locales.ts:89-105](file://frontend/antd/config-provider/locales.ts#L89-L105) + +章节来源 + +- [config-provider.tsx:51-151](file://frontend/antd/config-provider/config-provider.tsx#L51-L151) +- [locales.ts:12-87](file://frontend/antd/config-provider/locales.ts#L12-L87) + +### 后端组件（AntdXXProvider） + +职责与要点 + +- 参数声明：包含组件禁用、尺寸、方向、前缀类、语言、主题、变体、虚拟化、警告等配置项。 +- 插槽声明：声明 renderEmpty 等可注入插槽。 +- 前端目录：指向前端 x-provider 组件目录。 +- API 跳过：skip_api=True，避免生成冗余 API。 + +章节来源 + +- [**init**.py:10-101](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L10-L101) + +## 依赖分析 + +- 前端依赖 + - @ant-design/x：XProvider React 组件源。 + - @ant-design/cssinjs：样式注入与哈希控制。 + - dayjs：日期本地化。 + - svelte-i18n：浏览器语言检测。 + - immer：不可变更新工具。 +- 后端依赖 + - ModelScopeLayoutComponent：布局组件基类。 + - resolve_frontend_dir：定位前端组件目录。 + +```mermaid +graph LR +XP["XProvider.svelte"] --> CP["config-provider.tsx"] +CP --> AD["@ant-design/x"] +CP --> CSS["@ant-design/cssinjs"] +CP --> DJ["dayjs"] +CP --> I18N["svelte-i18n"] +CP --> IM["immer"] +PY["AntdXXProvider(__init__.py)"] --> CI["Index.svelte"] +CI --> XP +``` + +图示来源 + +- [XProvider.svelte:1-14](file://frontend/antdx/x-provider/XProvider.svelte#L1-L14) +- [config-provider.tsx:1-11](file://frontend/antd/config-provider/config-provider.tsx#L1-L11) +- [**init**.py:6-8](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L6-L8) + +章节来源 + +- [XProvider.svelte:1-14](file://frontend/antdx/x-provider/XProvider.svelte#L1-L14) +- [config-provider.tsx:1-11](file://frontend/antd/config-provider/config-provider.tsx#L1-L11) +- [**init**.py:6-8](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L6-L8) + +## 性能考虑 + +- 异步加载：XProvider 通过动态导入 ConfigProvider，避免首屏阻塞，提升启动速度。 +- 主题算法：仅在 themeMode 或 props.theme.algorithm 变更时重组算法数组，降低重渲染成本。 +- 语言包：按需加载语言包与 dayjs 本地化，避免一次性引入所有语言资源。 +- 样式注入：使用高优先级哈希策略，减少样式冲突与回流。 + +## 故障排查指南 + +- 主题冲突告警 + - 现象：当同时设置 theme 与 Gradio 预设主题时触发告警。 + - 处理：统一使用 theme_config，避免与 Gradio 预设属性冲突。 + - 参考：[**init**.py:74-77](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L74-L77) +- 明暗模式不生效 + - 确认 Gradio 共享主题已正确设置 themeMode。 + - 参考：[XProvider.svelte](file://frontend/antdx/x-provider/XProvider.svelte#L69) +- 语言未按预期切换 + - 检查 locale 字符串格式是否符合映射规则（如 zh_CN、en_US），或依赖自动识别。 + - 参考：[locales.ts:12-87](file://frontend/antd/config-provider/locales.ts#L12-L87) +- 插槽未生效 + - 确保插槽键路径正确（如 renderEmpty），并在 slots 中提供对应内容。 + - 参考：[config-provider.tsx:29-49](file://frontend/antd/config-provider/config-provider.tsx#L29-L49) + +章节来源 + +- [**init**.py:74-77](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L74-L77) +- [XProvider.svelte](file://frontend/antdx/x-provider/XProvider.svelte#L69) +- [locales.ts:12-87](file://frontend/antd/config-provider/locales.ts#L12-L87) +- [config-provider.tsx:29-49](file://frontend/antd/config-provider/config-provider.tsx#L29-L49) + +## 结论 + +XProvider 通过“前端包装器 + 后端桥接”的设计，为应用提供了统一的主题与国际化上下文，具备良好的扩展性与性能表现。建议在应用入口处集中配置，避免各组件重复设置，从而获得一致的用户体验与更低的维护成本。 + +## 附录 + +### 配置选项说明（摘要） + +- 组件级配置 + - component_disabled：组件禁用开关 + - component_size：组件尺寸（small/middle/large） + - direction：文本方向（ltr/rtl） + - prefix_cls/icon_prefix_cls：前缀类名 + - variant：组件外观变体（outlined/filled/borderless） + - virtual：虚拟滚动 + - warning：警告配置 +- 容器与弹层 + - get_popup_container/get_target_container：弹层与目标容器函数 +- 国际化 + - locale：语言代码（如 zh_CN、en_US），支持自动识别 +- 主题 + - theme/theme_config：主题对象与配置，优先使用 theme_config + - themeMode：由 Gradio 共享主题提供（light/dark） +- 其他 + - render_empty：空状态渲染插槽 + - 元素属性：elem_id、elem_classes、elem_style + - 可见性：visible 控制渲染 + +章节来源 + +- [**init**.py:19-82](file://backend/modelscope_studio/components/antdx/x_provider/__init__.py#L19-L82) +- [config-provider.tsx:53-70](file://frontend/antd/config-provider/config-provider.tsx#L53-L70) +- [locales.ts:12-87](file://frontend/antd/config-provider/locales.ts#L12-L87) +- [XProvider.svelte:25-74](file://frontend/antdx/x-provider/XProvider.svelte#L25-L74) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\267\245\345\205\267\347\273\204\344\273\266/\345\267\245\345\205\267\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\267\245\345\205\267\347\273\204\344\273\266/\345\267\245\345\205\267\347\273\204\344\273\266.md" new file mode 100644 index 00000000..85a6e67e --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\345\267\245\345\205\267\347\273\204\344\273\266/\345\267\245\345\205\267\347\273\204\344\273\266.md" @@ -0,0 +1,374 @@ +# 工具组件 + + +**本文引用的文件** +- [XProvider.svelte](file://frontend/antdx/x-provider/XProvider.svelte) +- [Index.svelte（XProvider 导出包装）](file://frontend/antdx/x-provider/Index.svelte) +- [config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [code-highlighter.tsx](file://frontend/antdx/code-highlighter/code-highlighter.tsx) +- [mermaid.tsx](file://frontend/antdx/mermaid/mermaid.tsx) +- [notification.tsx](file://frontend/antdx/notification/notification.tsx) +- [actions/context.ts](file://frontend/antdx/actions/context.ts) +- [backend/__init__.py（antdx 汇总导出）](file://backend/modelscope_studio/components/antdx/__init__.py) +- [x_provider 文档](file://docs/components/antdx/x_provider/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：使用示例与最佳实践](#附录使用示例与最佳实践) + +## 简介 + +本文件面向 Ant Design X 工具组件，系统性梳理以下组件的设计与用法： + +- XProvider：全局配置与上下文提供器，扩展 antd 的 ConfigProvider，统一为 @ant-design/x 组件提供主题、语言、弹层容器等全局能力。 +- CodeHighlighter：代码高亮展示组件，支持主题定制、头部插槽、语法高亮样式覆盖。 +- Mermaid：流程图/思维导图组件，集成高亮与动作项渲染，支持深浅主题切换与自定义动作。 +- Notification：浏览器通知封装，提供权限请求、打开/关闭、可见性控制与回调。 + +## 项目结构 + +围绕工具组件的关键目录与文件如下： + +- 前端 Svelte 包装层：frontend/antdx 下的各组件包装文件，负责将 @ant-design/x 的组件以 Svelte 方式接入 Gradio 生态。 +- antd ConfigProvider 扩展：frontend/antd/config-provider 提供主题、语言、弹层容器等全局能力。 +- 动作项上下文：frontend/antdx/actions/context 提供动作项的上下文注入与渲染工具。 +- 后端汇总导出：backend/modelscope_studio/components/antdx/**init**.py 将 antdx 组件统一导出，便于 Python 层使用。 + +```mermaid +graph TB +subgraph "前端包装层" +XP["XProvider.svelte"] +CH["code-highlighter.tsx"] +MG["mermaid.tsx"] +NT["notification.tsx"] +end +subgraph "antd 扩展" +CP["config-provider.tsx"] +end +subgraph "动作项上下文" +ACT["actions/context.ts"] +end +subgraph "后端导出" +BE["backend/__init__.py"] +end +XP --> CP +MG --> ACT +BE --> XP +BE --> CH +BE --> MG +BE --> NT +``` + +**图表来源** + +- [XProvider.svelte:1-75](file://frontend/antdx/x-provider/XProvider.svelte#L1-L75) +- [config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [code-highlighter.tsx:1-54](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L1-L54) +- [mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [backend/**init**.py（antdx 汇总导出）:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) + +**章节来源** + +- [XProvider.svelte:1-75](file://frontend/antdx/x-provider/XProvider.svelte#L1-L75) +- [config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [code-highlighter.tsx:1-54](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L1-L54) +- [mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [backend/**init**.py（antdx 汇总导出）:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) + +## 核心组件 + +- XProvider：在 Svelte 中通过 importComponent 异步加载并注入 ConfigProvider，统一透传 theme、themeMode、slots、容器函数等属性，作为 @ant-design/x 组件的全局上下文根节点。 +- CodeHighlighter：对 @ant-design/x 的 CodeHighlighter 进行二次封装，支持 header 插槽、主题模式切换、highlightProps 覆盖。 +- Mermaid：对 @ant-design/x 的 Mermaid 进行二次封装，支持 header、actions.customActions 插槽与上下文注入，自动根据 themeMode 切换 mermaid 主题与高亮样式。 +- Notification：对 @ant-design/x 的 notification 进行二次封装，暴露 visible 控制、权限回调、标签化关闭等能力。 + +**后端导出入口说明** +以上工具组件均通过 [backend/modelscope_studio/components/antdx/**init**.py](file://backend/modelscope_studio/components/antdx/__init__.py) 统一导出，对应导出名称如下： + +- `XProvider`：`from modelscope_studio.components.antdx import XProvider` +- `CodeHighlighter`：`from modelscope_studio.components.antdx import CodeHighlighter` +- `Mermaid`：`from modelscope_studio.components.antdx import Mermaid` +- `Notification`：`from modelscope_studio.components.antdx import Notification` + +**章节来源** + +- [XProvider.svelte:12-74](file://frontend/antdx/x-provider/XProvider.svelte#L12-L74) +- [config-provider.tsx:53-151](file://frontend/antd/config-provider/config-provider.tsx#L53-L151) +- [code-highlighter.tsx:29-51](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L29-L51) +- [mermaid.tsx:33-84](file://frontend/antdx/mermaid/mermaid.tsx#L33-L84) +- [notification.tsx:6-50](file://frontend/antdx/notification/notification.tsx#L6-L50) + +## 架构总览 + +下图展示了 XProvider 如何将 antd 的 ConfigProvider 与 @ant-design/x 组件串联起来，并通过 Svelte 上下文与 slots 机制完成属性与内容的传递。 + +```mermaid +sequenceDiagram +participant App as "应用根节点" +participant XP as "XProvider.svelte" +participant CP as "config-provider.tsx" +participant X as "@ant-design/x 组件树" +App->>XP : 传入 propstheme/themeMode/slots/容器函数 +XP->>CP : 渲染 ConfigProvider 并注入 themeMode/locale/getPopupContainer 等 +CP-->>XP : 返回已注入全局样式的 Provider +XP->>X : 将 children 渲染到 Provider 内部 +X-->>App : 子组件按全局配置生效 +``` + +**图表来源** + +- [XProvider.svelte:56-74](file://frontend/antdx/x-provider/XProvider.svelte#L56-L74) +- [config-provider.tsx:108-149](file://frontend/antd/config-provider/config-provider.tsx#L108-L149) + +**章节来源** + +- [XProvider.svelte:1-75](file://frontend/antdx/x-provider/XProvider.svelte#L1-L75) +- [config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) + +## 组件详解 + +### XProvider 全局配置与上下文提供机制 + +- 设计要点 + - 使用 importComponent 异步加载 antd 的 ConfigProvider 包装组件，避免首屏阻塞。 + - 通过 getProps/processProps 抽取并合并 gradio 额外属性、主题配置与通用布局属性，形成最终透传 props。 + - setConfigType('antd') 明确配置类型，确保后续组件消费一致的上下文。 + - 支持 slots 注入，将 Svelte 插槽转换为 React 可识别的结构。 +- 关键行为 + - theme 与 themeMode：优先从 additionalProps 或 restProps 获取 theme；themeMode 来自共享主题状态。 + - 容器函数：getPopupContainer、getTargetContainer 通过 useFunction 包裹，保证在组件生命周期内稳定可用。 + - 可见性控制：仅当 visible 为真时渲染 Provider，便于按需挂载。 +- 最佳实践 + - 在应用根部放置 XProvider，确保子组件继承全局主题与语言设置。 + - 若已有 antd.ConfigProvider，请替换为 antdx.XProvider，保持配置一致性。 + +```mermaid +flowchart TD +Start(["进入 XProvider"]) --> GetProps["抽取 props 与附加属性"] +GetProps --> MergeTheme["合并 theme 与 themeMode"] +MergeTheme --> Slots["处理 slots 并注入组件"] +Slots --> Container["绑定容器函数与样式属性"] +Container --> Visible{"visible 为真？"} +Visible -- 否 --> End(["不渲染"]) +Visible -- 是 --> Render["渲染 ConfigProvider 包装器"] +Render --> End +``` + +**图表来源** + +- [XProvider.svelte:25-74](file://frontend/antdx/x-provider/XProvider.svelte#L25-L74) +- [config-provider.tsx:93-149](file://frontend/antd/config-provider/config-provider.tsx#L93-L149) + +**章节来源** + +- [XProvider.svelte:1-75](file://frontend/antdx/x-provider/XProvider.svelte#L1-L75) +- [Index.svelte（XProvider 导出包装）:1-20](file://frontend/antdx/x-provider/Index.svelte#L1-L20) +- [config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [x_provider 文档:1-19](file://docs/components/antdx/x_provider/README.md#L1-L19) + +### CodeHighlighter 代码高亮组件 + +- 设计要点 + - 对接 @ant-design/x 的 CodeHighlighter，支持 header 插槽与 highlightProps 自定义。 + - 主题定制：基于 materialDark/materialLight，统一去除代码块外边距，适配卡片/对话场景。 + - 值来源：支持通过 value 属性直接传入代码字符串，或通过 children 传入。 +- 使用建议 + - 在深色主题下使用 customDarkStyle，在浅色主题下使用 customLightStyle。 + - 通过 highlightProps.style 覆盖默认样式，或追加其他 react-syntax-highlighter 支持的属性。 + - 使用 header 插槽添加标题/操作区。 + +```mermaid +flowchart TD +Enter(["进入 CodeHighlighter"]) --> Theme{"themeMode 为深色？"} +Theme -- 是 --> Dark["使用 customDarkStyle"] +Theme -- 否 --> Light["使用 customLightStyle"] +Dark --> Render["渲染 XCodeHighlighter 并传入 header/value"] +Light --> Render +Render --> Exit(["完成"]) +``` + +**图表来源** + +- [code-highlighter.tsx:29-51](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L29-L51) + +**章节来源** + +- [code-highlighter.tsx:1-54](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L1-L54) + +### Mermaid 流程图组件 + +- 设计要点 + - 对接 @ant-design/x 的 Mermaid，支持 header、actions.customActions 插槽与上下文注入。 + - 主题与高亮：根据 themeMode 切换 mermaid 主题（dark/base），同时同步高亮样式。 + - 动作项：通过 withItemsContextProvider 注入动作项上下文，支持动态渲染自定义动作。 +- 使用建议 + - 在深色主题下启用 mermaid dark 主题，浅色主题下使用 base。 + - 通过 actions.customActions 传入自定义动作项，或使用插槽注入。 + - 通过 config 透传 mermaid 渲染配置（如方向、主题色等）。 + +```mermaid +sequenceDiagram +participant U as "调用方" +participant M as "mermaid.tsx" +participant Ctx as "actions/context.ts" +participant X as "@ant-design/x.Mermaid" +U->>M : 传入 value/config/actions/themeMode/header +M->>Ctx : 获取动作项上下文 +Ctx-->>M : 返回动作项列表 +M->>X : 传入 highlightProps/config/actions/header +X-->>U : 渲染流程图 +``` + +**图表来源** + +- [mermaid.tsx:40-84](file://frontend/antdx/mermaid/mermaid.tsx#L40-L84) +- [actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) + +**章节来源** + +- [mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) + +### Notification 通知组件 + +- 设计要点 + - 对接 @ant-design/x 的 notification.useNotification，暴露 visible 控制与权限回调。 + - 自动请求权限：当 visible 为真且权限未授予时，触发权限请求；若授予则打开通知。 + - 标签化管理：支持按 tag 关闭指定通知，便于多实例管理。 + - 生命周期：在 visible 变更与组件卸载时自动清理通知。 +- 使用建议 + - 将 visible 与 onVisible 与上层状态联动，实现受控显示/隐藏。 + - 通过 onPermission 监听权限变化，引导用户授权。 + - 使用 tag 区分不同通知实例，避免互相干扰。 + +```mermaid +flowchart TD +Start(["visible 变更"]) --> Check{"visible 为真？"} +Check -- 否 --> Close["按 tag 关闭通知或全部"] +Close --> End(["结束"]) +Check -- 是 --> Perm{"权限已授予？"} +Perm -- 否 --> Request["请求权限"] +Request --> Granted{"授予成功？"} +Granted -- 否 --> End +Granted -- 是 --> Open["open(...)"] +Perm -- 是 --> Open +Open --> BindClose["绑定 onClose 并更新 onVisible"] +BindClose --> End +``` + +**图表来源** + +- [notification.tsx:17-46](file://frontend/antdx/notification/notification.tsx#L17-L46) + +**章节来源** + +- [notification.tsx:1-51](file://frontend/antdx/notification/notification.tsx#L1-L51) + +## 依赖关系分析 + +- 组件耦合 + - XProvider 依赖 antd 的 ConfigProvider 包装，形成全局上下文根节点。 + - Mermaid 依赖 actions/context 提供的动作项上下文，实现动态动作渲染。 + - CodeHighlighter/Mermaid 共同依赖 react-syntax-highlighter 的主题样式，统一高亮风格。 +- 外部依赖 + - @ant-design/x：核心组件库，提供 CodeHighlighter、Mermaid、Notification 等能力。 + - antd：提供 ConfigProvider、主题算法、语言包与 dayjs 国际化支持。 + - svelte-preprocess-react：桥接 Svelte 与 React，支持 slots 与函数包裹。 + +```mermaid +graph LR +XP["XProvider.svelte"] --> CP["config-provider.tsx"] +MG["mermaid.tsx"] --> ACT["actions/context.ts"] +CH["code-highlighter.tsx"] --> RS["react-syntax-highlighter 主题"] +MG --> RS +XP --> ANTD["@ant-design/x"] +CH --> ANTD +MG --> ANTD +NT["notification.tsx"] --> ANTD +``` + +**图表来源** + +- [XProvider.svelte:12-14](file://frontend/antdx/x-provider/XProvider.svelte#L12-L14) +- [config-provider.tsx:1-11](file://frontend/antd/config-provider/config-provider.tsx#L1-L11) +- [code-highlighter.tsx:4-11](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L4-L11) +- [mermaid.tsx:4-15](file://frontend/antdx/mermaid/mermaid.tsx#L4-L15) +- [actions/context.ts:1-4](file://frontend/antdx/actions/context.ts#L1-L4) +- [notification.tsx:3-4](file://frontend/antdx/notification/notification.tsx#L3-L4) + +**章节来源** + +- [XProvider.svelte:1-75](file://frontend/antdx/x-provider/XProvider.svelte#L1-L75) +- [config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [code-highlighter.tsx:1-54](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L1-L54) +- [mermaid.tsx:1-87](file://frontend/antdx/mermaid/mermaid.tsx#L1-L87) +- [actions/context.ts:1-7](file://frontend/antdx/actions/context.ts#L1-L7) +- [notification.tsx:1-51](file://frontend/antdx/notification/notification.tsx#L1-L51) + +## 性能考量 + +- 异步加载：XProvider 使用 importComponent 异步加载 ConfigProvider 包装组件，减少首屏负担。 +- 函数稳定化：通过 useFunction 包裹容器函数，避免每次渲染导致的函数引用变化引发的重渲染。 +- 记忆化：Mermaid 中对 actions.customActions 与 config 使用 useMemo，降低不必要的重新计算与渲染。 +- 主题样式：统一高亮样式对象，避免重复构建样式对象带来的开销。 + +[本节为通用指导，无需列出具体文件来源] + +## 故障排查指南 + +- XProvider 未生效 + - 确认已在应用根部放置 XProvider，并确保 visible 为真。 + - 检查 theme 与 themeMode 是否正确传入，theme 与 Gradio 预设冲突时请使用 theme_config。 +- Mermaid 图表不显示 + - 确认 value 有效，且 themeMode 与 config 正确。 + - 检查 actions.customActions 是否正确注入上下文或通过插槽传入。 +- CodeHighlighter 样式异常 + - 确认 themeMode 与 highlightProps.style 的组合是否正确。 + - 检查 header 插槽是否被意外覆盖。 +- Notification 无法弹出 + - 检查浏览器权限状态，确认 onPermission 回调是否触发。 + - 确认 visible 与 tag 的使用是否符合预期。 + +**章节来源** + +- [XProvider.svelte:56-74](file://frontend/antdx/x-provider/XProvider.svelte#L56-L74) +- [mermaid.tsx:40-84](file://frontend/antdx/mermaid/mermaid.tsx#L40-L84) +- [code-highlighter.tsx:29-51](file://frontend/antdx/code-highlighter/code-highlighter.tsx#L29-L51) +- [notification.tsx:17-46](file://frontend/antdx/notification/notification.tsx#L17-L46) + +## 结论 + +本文档系统梳理了 XProvider、CodeHighlighter、Mermaid、Notification 四个工具组件的实现与使用方法。它们通过统一的全局配置（XProvider）、主题与高亮策略（CodeHighlighter/Mermaid）、以及浏览器通知能力（Notification），为 Ant Design X 在前端生态中的落地提供了稳定、可扩展的基础。建议在应用根部统一引入 XProvider，并结合主题与语言配置，确保子组件获得一致的全局体验。 + +[本节为总结性内容，无需列出具体文件来源] + +## 附录：使用示例与最佳实践 + +- XProvider + - 在应用根部放置 XProvider，传入 theme_config 或 theme 与 themeMode，确保子组件继承全局配置。 + - 如已使用 antd.ConfigProvider，请替换为 antdx.XProvider，保持配置一致性。 +- CodeHighlighter + - 通过 value 或 children 传入代码内容；通过 header 插槽添加标题/操作区。 + - 根据 themeMode 选择对应高亮样式，必要时通过 highlightProps.style 覆盖细节。 +- Mermaid + - 传入 value 作为 mermaid 语法文本；通过 config 调整渲染参数；通过 actions.customActions 注入自定义动作。 + - 根据 themeMode 切换 mermaid 主题（dark/base），保持与页面主题一致。 +- Notification + - 使用 visible 与 onVisible 实现受控显示；监听 onPermission 获取权限状态；通过 tag 管理多实例。 + +**章节来源** + +- [x_provider 文档:1-19](file://docs/components/antdx/x_provider/README.md#L1-L19) +- [backend/**init**.py（antdx 汇总导出）:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/FileCard \346\226\207\344\273\266\345\215\241\347\211\207\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/FileCard \346\226\207\344\273\266\345\215\241\347\211\207\347\273\204\344\273\266.md" new file mode 100644 index 00000000..29b2b5e9 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/FileCard \346\226\207\344\273\266\345\215\241\347\211\207\347\273\204\344\273\266.md" @@ -0,0 +1,441 @@ +# FileCard 文件卡片组件 + + +**本文档引用的文件** +- [frontend/antdx/file-card/file-card.tsx](file://frontend/antdx/file-card/file-card.tsx) +- [frontend/antdx/file-card/base.tsx](file://frontend/antdx/file-card/base.tsx) +- [frontend/antdx/file-card/Index.svelte](file://frontend/antdx/file-card/Index.svelte) +- [frontend/antdx/file-card/list/file-card.list.tsx](file://frontend/antdx/file-card/list/file-card.list.tsx) +- [frontend/antdx/file-card/list/context.ts](file://frontend/antdx/file-card/list/context.ts) +- [frontend/antdx/file-card/list/item/file-card.list.item.tsx](file://frontend/antdx/file-card/list/item/file-card.list.item.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构概览](#架构概览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) + +## 简介 + +FileCard 文件卡片组件是 ModelScope Studio 前端框架中的一个重要组件，基于 Ant Design X 的 FileCard 组件进行扩展和封装。该组件提供了文件展示、预览、上传等功能，支持多种文件类型和自定义配置选项。 + +组件主要包含三个核心部分： + +- **基础文件卡片组件**：提供核心的文件显示功能 +- **文件卡片列表组件**：用于展示多个文件卡片的列表视图 +- **文件卡片列表项组件**：单个文件卡片在列表中的具体实现 + +## 项目结构 + +FileCard 组件位于前端项目的 antdx 组件库中，采用模块化组织方式： + +```mermaid +graph TB +subgraph "FileCard 组件结构" +FC[FileCard 核心组件] +FCL[FileCard 列表组件] +FCListItem[FileCard 列表项组件] +Base[基础文件卡片组件] +FC --> Base +FCL --> FCListItem +FCListItem --> Base +end +subgraph "前端组件库" +Antdx[antdx 组件库] +Antd[antd 组件库] +Utils[工具函数] +end +FC -.-> Antdx +FCL -.-> Antdx +FCListItem -.-> Antdx +Base -.-> Antdx +Base -.-> Antd +FC -.-> Utils +FCL -.-> Utils +FCListItem -.-> Utils +``` + +**图表来源** + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/list/file-card.list.tsx:1-68](file://frontend/antdx/file-card/list/file-card.list.tsx#L1-L68) + +**章节来源** + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/list/file-card.list.tsx:1-68](file://frontend/antdx/file-card/list/file-card.list.tsx#L1-L68) + +## 核心组件 + +### 基础文件卡片组件 (BaseFileCard) + +基础文件卡片组件是整个 FileCard 系统的核心，负责处理文件源解析和基本的文件显示逻辑。 + +**主要特性：** + +- 支持字符串和 FileData 类型的文件源 +- 自动解析可访问的文件 URL +- 集成 Ant Design X 的 FileCard 组件 +- 提供根 URL 和 API 前缀配置 + +**关键方法：** + +- `resolveFileSrc()`: 解析文件源，支持本地文件和远程文件 +- `BaseFileCard`: 主要组件渲染逻辑 + +**章节来源** + +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) + +### 文件卡片组件 (FileCard) + +文件卡片组件是对基础组件的进一步封装，增加了 React Slot 支持和更丰富的配置选项。 + +**主要功能：** + +- 支持 React Slot 插槽系统 +- 图片预览功能增强 +- 加载状态指示器配置 +- 自定义图标和描述内容 + +**核心配置：** + +- `imageProps.placeholder`: 占位符配置 +- `imageProps.preview`: 预览功能配置 +- `spinProps`: 加载状态配置 +- `slots`: 插槽系统支持 + +**章节来源** + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) + +### 文件卡片列表组件 (FileCardList) + +文件卡片列表组件用于展示多个文件卡片，支持批量操作和统一配置。 + +**主要特性：** + +- 批量文件管理 +- 可移除功能 +- 插槽系统集成 +- 项目上下文管理 + +**章节来源** + +- [frontend/antdx/file-card/list/file-card.list.tsx:1-68](file://frontend/antdx/file-card/list/file-card.list.tsx#L1-L68) + +### 文件卡片列表项组件 (FileCardListItem) + +单个文件卡片在列表中的具体实现，继承了基础文件卡片的所有功能。 + +**关键功能：** + +- 列表项处理机制 +- 插槽参数传递 +- 预览功能配置 +- 项目上下文集成 + +**章节来源** + +- [frontend/antdx/file-card/list/item/file-card.list.item.tsx:1-83](file://frontend/antdx/file-card/list/item/file-card.list.item.tsx#L1-L83) + +## 架构概览 + +FileCard 组件采用了分层架构设计，从底层的基础组件到上层的应用组件，形成了清晰的层次结构： + +```mermaid +graph TD +subgraph "应用层" +App[应用程序] +Demo[演示应用] +end +subgraph "组件层" +SvelteIndex[Index.svelte 入口] +FileCard[FileCard 组件] +FileCardList[FileCardList 组件] +FileCardListItem[FileCardListItem 组件] +end +subgraph "基础层" +BaseFileCard[BaseFileCard 组件] +AntdX[Ant Design X] +Utils[工具函数] +end +subgraph "数据层" +FileData[文件数据模型] +Config[配置对象] +Slots[插槽系统] +end +App --> SvelteIndex +Demo --> SvelteIndex +SvelteIndex --> FileCard +SvelteIndex --> FileCardList +FileCardList --> FileCardListItem +FileCard --> BaseFileCard +FileCardList --> BaseFileCard +FileCardListItem --> BaseFileCard +BaseFileCard --> AntdX +FileCard --> Utils +FileCardList --> Utils +FileCardListItem --> Utils +BaseFileCard --> FileData +FileCard --> Config +FileCardList --> Config +FileCardListItem --> Config +FileCard --> Slots +FileCardList --> Slots +FileCardListItem --> Slots +``` + +**图表来源** + +- [frontend/antdx/file-card/Index.svelte:1-66](file://frontend/antdx/file-card/Index.svelte#L1-L66) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/list/file-card.list.tsx:1-68](file://frontend/antdx/file-card/list/file-card.list.tsx#L1-L68) + +## 详细组件分析 + +### 基础文件卡片组件类图 + +```mermaid +classDiagram +class BaseFileCardProps { ++string rootUrl ++string apiPrefix ++string|FileData src ++XFileCardProps props +} +class BaseFileCard { ++resolveFileSrc(src, rootUrl, apiPrefix) string ++render() ReactElement +} +class FileCardProps { ++BaseFileCardProps props ++React.ReactNode children ++object slots ++object imageProps ++object spinProps +} +class FileCard { ++getConfig(value) object ++render() ReactElement +} +class FileCardListProps { ++FileCardListProps props ++ItemType[] items ++React.ReactNode children ++string rootUrl ++string apiPrefix ++function removable +} +class FileCardList { ++render() ReactElement ++resolveItems() ItemType[] +} +class FileCardListItemProps { ++BaseFileCardProps props ++ItemHandlerProps props ++object slots ++object imageProps +} +class FileCardListItem { ++getConfig(value) object ++render() ReactElement +} +BaseFileCardProps <|-- FileCardProps +BaseFileCardProps <|-- FileCardListItemProps +FileCardProps <|-- FileCard +FileCardListProps <|-- FileCardList +FileCardListItemProps <|-- FileCardListItem +FileCard --> BaseFileCard +FileCardList --> FileCardListItem +FileCardListItem --> BaseFileCard +``` + +**图表来源** + +- [frontend/antdx/file-card/base.tsx:9-13](file://frontend/antdx/file-card/base.tsx#L9-L13) +- [frontend/antdx/file-card/file-card.tsx:17-34](file://frontend/antdx/file-card/file-card.tsx#L17-L34) +- [frontend/antdx/file-card/list/file-card.list.tsx:14-21](file://frontend/antdx/file-card/list/file-card.list.tsx#L14-L21) +- [frontend/antdx/file-card/list/item/file-card.list.item.tsx:16-31](file://frontend/antdx/file-card/list/item/file-card.list.item.tsx#L16-L31) + +### 文件源解析流程 + +```mermaid +flowchart TD +Start([开始解析文件源]) --> CheckSrc{检查 src 参数} +CheckSrc --> |为空| ReturnEmpty[返回空值] +CheckSrc --> |为字符串| CheckProtocol{检查协议} +CheckSrc --> |为对象| CheckObject{检查对象属性} +CheckProtocol --> |以 http 开头| ReturnString[直接返回字符串] +CheckProtocol --> |不以 http 开头| ResolveURL[调用 getFetchableUrl] +CheckObject --> CheckUrl{检查 url 属性} +CheckObject --> CheckPath{检查 path 属性} +CheckUrl --> |存在| ReturnUrl[返回 url] +CheckUrl --> |不存在| ResolvePath[调用 getFetchableUrl] +CheckPath --> |存在| ResolvePath +CheckPath --> |不存在| ReturnUndefined[返回 undefined] +ResolveURL --> ReturnResolved[返回解析后的 URL] +ResolvePath --> ReturnResolved +ReturnEmpty --> End([结束]) +ReturnString --> End +ReturnUrl --> End +ReturnResolved --> End +ReturnUndefined --> End +``` + +**图表来源** + +- [frontend/antdx/file-card/base.tsx:15-29](file://frontend/antdx/file-card/base.tsx#L15-L29) + +### 插槽系统工作流程 + +```mermaid +sequenceDiagram +participant App as 应用程序 +participant FileCard as FileCard 组件 +participant BaseFileCard as BaseFileCard 组件 +participant SlotSystem as 插槽系统 +participant Utils as 工具函数 +App->>FileCard : 渲染组件 +FileCard->>SlotSystem : 获取插槽配置 +SlotSystem-->>FileCard : 返回插槽数据 +FileCard->>Utils : 处理插槽参数 +Utils-->>FileCard : 返回处理结果 +FileCard->>BaseFileCard : 传递配置 +BaseFileCard->>BaseFileCard : 渲染文件卡片 +BaseFileCard-->>App : 输出最终组件 +``` + +**图表来源** + +- [frontend/antdx/file-card/file-card.tsx:34-124](file://frontend/antdx/file-card/file-card.tsx#L34-L124) +- [frontend/antdx/file-card/base.tsx:31-41](file://frontend/antdx/file-card/base.tsx#L31-L41) + +**章节来源** + +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/list/file-card.list.tsx:1-68](file://frontend/antdx/file-card/list/file-card.list.tsx#L1-L68) +- [frontend/antdx/file-card/list/item/file-card.list.item.tsx:1-83](file://frontend/antdx/file-card/list/item/file-card.list.item.tsx#L1-L83) + +## 依赖关系分析 + +FileCard 组件的依赖关系相对清晰，主要依赖于 Ant Design X 组件库和内部工具函数： + +```mermaid +graph LR +subgraph "外部依赖" +AntdX[Ant Design X] +React[React] +Svelte[Svelte] +end +subgraph "内部依赖" +Utils[工具函数] +Hooks[React Hooks] +Context[上下文系统] +end +subgraph "FileCard 组件" +BaseFileCard[BaseFileCard] +FileCard[FileCard] +FileCardList[FileCardList] +FileCardListItem[FileCardListItem] +end +FileCard --> BaseFileCard +FileCardList --> FileCardListItem +FileCardListItem --> BaseFileCard +BaseFileCard --> AntdX +FileCard --> Utils +FileCardList --> Utils +FileCardListItem --> Utils +FileCard --> Hooks +FileCardList --> Hooks +FileCardListItem --> Hooks +FileCard --> Context +FileCardList --> Context +FileCardListItem --> Context +BaseFileCard --> React +FileCard --> Svelte +FileCardList --> Svelte +FileCardListItem --> Svelte +``` + +**图表来源** + +- [frontend/antdx/file-card/file-card.tsx:1-7](file://frontend/antdx/file-card/file-card.tsx#L1-L7) +- [frontend/antdx/file-card/base.tsx:1-7](file://frontend/antdx/file-card/base.tsx#L1-L7) +- [frontend/antdx/file-card/list/file-card.list.tsx:1-8](file://frontend/antdx/file-card/list/file-card.list.tsx#L1-L8) + +**章节来源** + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) +- [frontend/antdx/file-card/list/file-card.list.tsx:1-68](file://frontend/antdx/file-card/list/file-card.list.tsx#L1-L68) + +## 性能考虑 + +FileCard 组件在设计时充分考虑了性能优化： + +### 内存管理 + +- 使用 `useMemo` 缓存文件源解析结果 +- 避免不必要的组件重渲染 +- 合理使用 React Slot 减少 DOM 操作 + +### 渲染优化 + +- 条件渲染插槽内容 +- 懒加载组件避免初始渲染压力 +- 优化图片预览功能的性能 + +### 数据流优化 + +- 单向数据流设计 +- 避免深层嵌套的对象传递 +- 合理的事件处理机制 + +## 故障排除指南 + +### 常见问题及解决方案 + +**文件无法显示** + +- 检查文件源 URL 是否正确 +- 确认网络连接和权限设置 +- 验证文件格式是否受支持 + +**预览功能异常** + +- 检查图片预览配置 +- 确认插槽系统正常工作 +- 验证容器元素是否存在 + +**组件渲染错误** + +- 检查 React Slot 的使用 +- 确认必要的依赖已正确安装 +- 验证组件的导入路径 + +**章节来源** + +- [frontend/antdx/file-card/base.tsx:15-29](file://frontend/antdx/file-card/base.tsx#L15-L29) +- [frontend/antdx/file-card/file-card.tsx:34-124](file://frontend/antdx/file-card/file-card.tsx#L34-L124) + +## 结论 + +FileCard 文件卡片组件是一个功能完整、设计合理的前端组件系统。它通过清晰的分层架构、灵活的插槽系统和完善的配置选项，为用户提供了强大的文件管理和展示能力。 + +组件的主要优势包括： + +- **模块化设计**：清晰的组件层次结构 +- **灵活配置**：丰富的配置选项和插槽系统 +- **性能优化**：合理的内存管理和渲染优化 +- **易于扩展**：标准化的接口设计便于功能扩展 + +该组件系统为 ModelScope Studio 提供了可靠的文件处理能力，能够满足各种文件展示和管理场景的需求。 diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/Folder \346\226\207\344\273\266\345\244\271\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/Folder \346\226\207\344\273\266\345\244\271\347\273\204\344\273\266.md" new file mode 100644 index 00000000..4042c0fe --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/Folder \346\226\207\344\273\266\345\244\271\347\273\204\344\273\266.md" @@ -0,0 +1,359 @@ +# Folder 文件夹组件 + + +**本文档引用的文件** +- [backend/modelscope_studio/components/antdx/folder/__init__.py](file://backend/modelscope_studio/components/antdx/folder/__init__.py) +- [frontend/antdx/folder/Index.svelte](file://frontend/antdx/folder/Index.svelte) +- [frontend/antdx/folder/folder.tsx](file://frontend/antdx/folder/folder.tsx) +- [frontend/antdx/folder/context.ts](file://frontend/antdx/folder/context.ts) +- [frontend/antdx/folder/package.json](file://frontend/antdx/folder/package.json) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [docs/components/antdx/folder/README-zh_CN.md](file://docs/components/antdx/folder/README-zh_CN.md) +- [docs/components/antdx/folder/README.md](file://docs/components/antdx/folder/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构概览](#架构概览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) + +## 简介 + +Folder 文件夹组件是 ModelScope Studio 中的一个重要文件树组件，基于 Ant Design X 的 Folder 组件构建。该组件主要用于展示文件系统结构，提供文件和文件夹的层次化浏览功能。它支持文件点击、文件夹点击、选中文件变化、展开路径变化等事件处理，并提供了丰富的自定义选项。 + +该组件在前端使用 Svelte 框架实现，通过 React 预处理机制与 Ant Design X 的原生组件进行桥接，实现了从 Python 后端到 React 前端的完整数据流和事件流。 + +## 项目结构 + +Folder 组件在整个项目中的位置和组织结构如下： + +```mermaid +graph TB +subgraph "后端 (Python)" +A[backend/modelscope_studio/components/antdx/] --> B[folder/] +B --> C[__init__.py
AntdXFolder 类] +B --> D[directory_icon/] +B --> E[tree_node/] +end +subgraph "前端 (TypeScript/Svelte)" +F[frontend/antdx/] --> G[folder/] +G --> H[Index.svelte
组件入口] +G --> I[folder.tsx
React 实现] +G --> J[context.ts
上下文管理] +G --> K[package.json
包配置] +end +subgraph "文档" +L[docs/components/antdx/folder/] +L --> M[README-zh_CN.md] +L --> N[README.md] +end +A --> F +F --> L +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:1-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L1-L114) +- [frontend/antdx/folder/Index.svelte:1-81](file://frontend/antdx/folder/Index.svelte#L1-L81) +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:1-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L1-L114) +- [frontend/antdx/folder/Index.svelte:1-81](file://frontend/antdx/folder/Index.svelte#L1-L81) +- [frontend/antdx/folder/folder.tsx:1-124](file://frontend/antdx/folder/folder.tsx#L1-L124) + +## 核心组件 + +### AntdXFolder 类 + +AntdXFolder 是后端的核心组件类，继承自 ModelScopeLayoutComponent。它定义了完整的组件接口和行为规范。 + +**主要特性：** + +- 支持多种事件监听器（file_click, folder_click, selected_file_change, expanded_paths_change） +- 提供丰富的配置属性（tree_data, selectable, selected_file, expanded_paths 等） +- 支持插槽系统（emptyRender, previewRender, directoryTitle 等） +- 集成 Gradio 生态系统的组件生命周期管理 + +**关键属性说明：** + +- `tree_data`: 文件树数据结构，定义文件和文件夹的层次关系 +- `selectable`: 是否允许选择文件 +- `selected_file`: 当前选中的文件路径列表 +- `expanded_paths`: 默认展开的路径列表 +- `directory_icons`: 自定义目录图标映射 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) + +### 前端组件架构 + +前端组件采用分层架构设计，通过 Svelte 和 React 的桥接实现： + +```mermaid +classDiagram +class AntdXFolder { ++TreeNode ++DirectoryIcon ++EVENTS ++SLOTS ++tree_data ++selectable ++selected_file ++expanded_paths ++directory_icons ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +class FolderComponent { ++slots ++children ++previewRender ++previewTitle ++fileContentService ++treeData ++directoryIcons ++emptyRender ++directoryTitle +} +class ContextProviders { ++withTreeNodeItemsContextProvider ++withDirectoryIconItemsContextProvider ++useTreeNodeItems ++useDirectoryIconItems +} +AntdXFolder --> FolderComponent : "前端渲染" +FolderComponent --> ContextProviders : "使用上下文" +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:12-114](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L12-L114) +- [frontend/antdx/folder/folder.tsx:16-124](file://frontend/antdx/folder/folder.tsx#L16-L124) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) + +**章节来源** + +- [frontend/antdx/folder/folder.tsx:16-124](file://frontend/antdx/folder/folder.tsx#L16-L124) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) + +## 架构概览 + +Folder 组件的整体架构采用分层设计，实现了从后端 Python 到前端 React 的完整数据流： + +```mermaid +sequenceDiagram +participant Backend as 后端组件 +participant Svelte as Svelte 层 +participant React as React 组件 +participant AntDX as Ant Design X +participant User as 用户 +User->>Backend : 创建 Folder 组件 +Backend->>Svelte : 渲染组件 +Svelte->>React : 加载 Folder 组件 +React->>AntDX : 初始化 AntdXFolder +AntDX->>User : 显示文件树界面 +User->>AntDX : 点击文件/文件夹 +AntDX->>React : 触发事件回调 +React->>Svelte : 转发事件 +Svelte->>Backend : 更新状态 +Backend->>User : 反馈结果 +Note over Backend,User : 数据绑定和事件处理 +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:19-35](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L19-L35) +- [frontend/antdx/folder/Index.svelte:10-81](file://frontend/antdx/folder/Index.svelte#L10-L81) +- [frontend/antdx/folder/folder.tsx:25-121](file://frontend/antdx/folder/folder.tsx#L25-L121) + +## 详细组件分析 + +### 事件处理机制 + +Folder 组件支持多种事件监听器，每种事件都有其特定的功能和触发条件： + +```mermaid +flowchart TD +A[用户交互] --> B{事件类型} +B --> |file_click| C[文件点击事件] +B --> |folder_click| D[文件夹点击事件] +B --> |selected_file_change| E[选中文件变化] +B --> |expanded_paths_change| F[展开路径变化] +B --> |file_content_service_load_file_content| G[文件内容加载] +C --> H[更新 bind_fileClick_event] +D --> I[更新 bind_folderClick_event] +E --> J[更新 bind_selectedFileChange_event] +F --> K[更新 bind_expandedPathsChange_event] +G --> L[更新 bind_fileContentService_loadFileContent_event] +H --> M[回调函数执行] +I --> M +J --> M +K --> M +L --> M +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:19-35](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L19-L35) + +### 插槽系统 + +组件提供了灵活的插槽系统，允许开发者自定义各种显示内容： + +| 插槽名称 | 功能描述 | 使用场景 | +| -------------- | ---------- | ---------------------------- | +| emptyRender | 空状态渲染 | 当文件树为空时显示自定义内容 | +| previewRender | 预览渲染 | 自定义文件预览内容 | +| directoryTitle | 目录标题 | 自定义目录显示标题 | +| previewTitle | 预览标题 | 自定义预览标题显示 | +| treeData | 树数据 | 自定义树形数据结构 | +| directoryIcons | 目录图标 | 自定义文件类型图标 | + +**章节来源** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:37-41](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L37-L41) + +### 数据流处理 + +组件的数据流处理采用了 React 的 useMemo 优化机制： + +```mermaid +flowchart LR +A[原始数据] --> B[useMemo 优化] +B --> C[数据转换] +C --> D[上下文提供者] +D --> E[子组件消费] +F[外部传入] --> G[props.treeData] +H[内部生成] --> I[renderItems] +G --> C +I --> C +J[目录图标] --> K[对象映射] +K --> L[extension -> ReactNode] +``` + +**图表来源** + +- [frontend/antdx/folder/folder.tsx:60-88](file://frontend/antdx/folder/folder.tsx#L60-L88) + +**章节来源** + +- [frontend/antdx/folder/folder.tsx:60-88](file://frontend/antdx/folder/folder.tsx#L60-L88) + +## 依赖关系分析 + +Folder 组件的依赖关系体现了清晰的分层架构： + +```mermaid +graph TB +subgraph "外部依赖" +A[@ant-design/x] --> B[AntdXFolder] +C[classnames] --> D[Svelte 样式处理] +E[react] --> F[React Slot] +end +subgraph "内部依赖" +G[createItemsContext] --> H[上下文提供者] +I[renderItems] --> J[项目渲染] +K[renderParamsSlot] --> L[参数化插槽] +M[useFunction] --> N[函数包装] +end +subgraph "组件层次" +O[AntdXFolder] --> P[Index.svelte] +P --> Q[folder.tsx] +Q --> R[React 组件] +R --> S[Ant Design X] +end +A --> R +G --> Q +I --> Q +K --> Q +M --> Q +``` + +**图表来源** + +- [frontend/antdx/folder/folder.tsx:1-15](file://frontend/antdx/folder/folder.tsx#L1-L15) +- [frontend/antdx/folder/Index.svelte:1-10](file://frontend/antdx/folder/Index.svelte#L1-L10) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) + +**章节来源** + +- [frontend/antdx/folder/package.json:1-15](file://frontend/antdx/folder/package.json#L1-L15) +- [frontend/antdx/folder/folder.tsx:1-15](file://frontend/antdx/folder/folder.tsx#L1-L15) + +## 性能考虑 + +### 渲染优化 + +组件采用了多项性能优化策略： + +1. **useMemo 优化**: 对 treeData 和 directoryIcons 进行记忆化处理，避免不必要的重新计算 +2. **条件渲染**: 仅在需要时渲染 children 内容，减少 DOM 节点数量 +3. **懒加载**: 通过 importComponent 实现组件的动态导入和懒加载 + +### 内存管理 + +- 上下文提供者使用了适当的清理机制 +- 事件处理器通过 useFunction 包装，确保正确的 this 绑定 +- 插槽内容按需渲染，避免内存泄漏 + +## 故障排除指南 + +### 常见问题及解决方案 + +**问题 1: 组件不显示** + +- 检查 tree_data 是否正确设置 +- 确认 FRONTEND_DIR 路径是否正确解析 +- 验证组件的 visible 属性 + +**问题 2: 事件不触发** + +- 确认事件监听器是否正确注册 +- 检查 bind\_\*\_event 属性是否设置 +- 验证回调函数的签名是否正确 + +**问题 3: 图标不显示** + +- 检查 directory_icons 配置 +- 确认扩展名映射是否正确 +- 验证图标组件的导入路径 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/folder/**init**.py:97-101](file://backend/modelscope_studio/components/antdx/folder/__init__.py#L97-L101) + +## 结论 + +Folder 文件夹组件是一个功能完整、架构清晰的文件树组件。它成功地将 Ant Design X 的强大功能与 ModelScope Studio 的生态系统相结合，为用户提供了优秀的文件浏览体验。 + +**主要优势：** + +- 完整的事件处理机制 +- 灵活的插槽系统 +- 优秀的性能表现 +- 清晰的代码结构 +- 良好的可扩展性 + +**适用场景：** + +- 文件管理系统 +- 代码编辑器 +- 资源管理工具 +- 文档浏览应用 + +该组件为 ModelScope Studio 提供了强大的文件树展示能力，是构建复杂前端应用的重要基础组件。 diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/Sources \346\225\260\346\215\256\346\272\220\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/Sources \346\225\260\346\215\256\346\272\220\347\273\204\344\273\266.md" new file mode 100644 index 00000000..f66d262b --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/Sources \346\225\260\346\215\256\346\272\220\347\273\204\344\273\266.md" @@ -0,0 +1,422 @@ +# Sources 数据源组件 + + +**本文档引用的文件** +- [backend/modelscope_studio/components/antdx/sources/__init__.py](file://backend/modelscope_studio/components/antdx/sources/__init__.py) +- [backend/modelscope_studio/components/antdx/sources/item/__init__.py](file://backend/modelscope_studio/components/antdx/sources/item/__init__.py) +- [frontend/antdx/sources/sources.tsx](file://frontend/antdx/sources/sources.tsx) +- [frontend/antdx/sources/item/sources.item.tsx](file://frontend/antdx/sources/item/sources.item.tsx) +- [frontend/antdx/sources/context.ts](file://frontend/antdx/sources/context.ts) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [docs/components/antdx/sources/README-zh_CN.md](file://docs/components/antdx/sources/README-zh_CN.md) +- [docs/components/antdx/sources/demos/basic.py](file://docs/components/antdx/sources/demos/basic.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构概览](#架构概览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) + +## 简介 + +Sources 数据源组件是 ModelScope Studio 中用于在 AI 聊天场景中显示信息来源列表的核心组件。该组件基于 Ant Design X 的 Sources 组件构建，专门设计用于展示参考文献、链接来源和其他相关信息。 + +该组件支持多种配置选项，包括标题设置、展开状态控制、内联显示模式等，并提供了完整的事件处理机制，包括点击事件和展开事件。 + +## 项目结构 + +Sources 组件采用前后端分离的架构设计，主要包含以下结构： + +```mermaid +graph TB +subgraph "后端组件层" +Backend[AntdXSources
主组件] +BackendItem[AntdXSourcesItem
子项组件] +end +subgraph "前端组件层" +Frontend[Sources
React 组件] +FrontendItem[SourcesItem
React 子项组件] +Context[Context
上下文管理] +end +subgraph "工具层" +Utils[ModelScopeLayoutComponent
基础组件类] +Resolver[resolve_frontend_dir
路径解析器] +end +Backend --> Utils +BackendItem --> Utils +Backend --> Frontend +BackendItem --> FrontendItem +Frontend --> Context +Backend --> Resolver +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) +- [frontend/antdx/sources/sources.tsx:1-41](file://frontend/antdx/sources/sources.tsx#L1-L41) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/sources/**init**.py:1-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L1-L92) +- [backend/modelscope_studio/components/antdx/sources/item/**init**.py:1-68](file://backend/modelscope_studio/components/antdx/sources/item/__init__.py#L1-L68) + +## 核心组件 + +### AntdXSources 主组件 + +AntdXSources 是 Sources 组件的主容器，负责管理整个数据源列表的显示和交互。 + +**主要特性：** + +- 支持标题显示和自定义 +- 可配置展开图标位置（开始/结束） +- 默认展开和受控展开状态 +- 内联显示模式支持 +- 活动键值管理 +- 弹出框覆盖宽度设置 + +**关键属性：** + +- `title`: 显示在组件顶部的标题文本 +- `items`: 数据源项目的数组配置 +- `expand_icon_position`: 展开图标的显示位置 +- `default_expanded`: 默认展开状态 +- `expanded`: 受控展开状态 +- `inline`: 是否启用内联显示模式 +- `active_key`: 当前激活的项目键值 +- `popover_overlay_width`: 弹出框覆盖宽度 + +### AntdXSourcesItem 子项组件 + +AntdXSourcesItem 代表单个数据源条目，用于显示具体的来源信息。 + +**主要特性：** + +- 支持标题、图标和描述的自定义 +- 链接地址配置 +- 唯一键值标识 +- 插槽系统支持 + +**关键属性：** + +- `key`: 项目的唯一标识符 +- `title`: 项目标题 +- `description`: 项目描述信息 +- `icon`: 自定义图标 +- `url`: 跳转链接地址 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/sources/**init**.py:30-73](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L30-L73) +- [backend/modelscope_studio/components/antdx/sources/item/**init**.py:18-48](file://backend/modelscope_studio/components/antdx/sources/item/__init__.py#L18-L48) + +## 架构概览 + +Sources 组件采用分层架构设计，实现了清晰的关注点分离： + +```mermaid +sequenceDiagram +participant App as 应用程序 +participant Backend as 后端组件 +participant Frontend as 前端组件 +participant AntDX as Ant Design X +participant Context as 上下文管理 +App->>Backend : 创建 Sources 组件 +Backend->>Backend : 解析前端目录 +Backend->>Frontend : 渲染 React 组件 +Frontend->>Context : 初始化上下文提供者 +Frontend->>AntDX : 使用原生 Sources 组件 +AntDX-->>Frontend : 返回渲染结果 +Frontend-->>App : 输出最终组件 +Note over Backend,Frontend : 事件绑定和数据传递 +Backend->>Backend : 绑定 expand/click 事件 +Backend->>Frontend : 传递事件回调 +``` + +**图表来源** + +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-16](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L16) +- [frontend/antdx/sources/sources.tsx:9-38](file://frontend/antdx/sources/sources.tsx#L9-L38) + +**章节来源** + +- [frontend/antdx/sources/sources.tsx:1-41](file://frontend/antdx/sources/sources.tsx#L1-L41) +- [frontend/antdx/sources/item/sources.item.tsx:1-14](file://frontend/antdx/sources/item/sources.item.tsx#L1-L14) + +## 详细组件分析 + +### 后端组件实现 + +#### ModelScopeLayoutComponent 基础类 + +所有 Sources 组件都继承自 ModelScopeLayoutComponent，这是一个专门为 ModelScope Studio 设计的布局组件基类。 + +**核心功能：** + +- 提供 Gradio 组件的基础框架 +- 处理组件的生命周期管理 +- 支持插槽系统的集成 +- 管理组件的内部状态 + +#### AntdXSources 组件实现 + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++EVENTS : list ++SLOTS : list ++skip_api : bool ++FRONTEND_DIR : str ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdXSources { ++title : str ++items : list ++expand_icon_position : str ++default_expanded : bool ++expanded : bool ++inline : bool ++active_key : str ++popover_overlay_width : str|int|float ++Item : class ++EVENTS : list ++SLOTS : list +} +class AntdXSourcesItem { ++key : str ++description : str ++icon : str ++title : str ++url : str ++EVENTS : list ++SLOTS : list +} +ModelScopeLayoutComponent <|-- AntdXSources +ModelScopeLayoutComponent <|-- AntdXSourcesItem +AntdXSources --> AntdXSourcesItem : contains +``` + +**图表来源** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/antdx/sources/**init**.py:11-92](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L11-L92) +- [backend/modelscope_studio/components/antdx/sources/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/sources/item/__init__.py#L8-L68) + +**前端组件实现** + +#### Sources React 组件 + +Sources 组件使用 React 实现，通过 sveltify 包装器与 Svelte 生态系统集成。 + +**核心功能：** + +- 使用 Ant Design X 的原生 Sources 组件 +- 支持插槽系统，允许自定义标题内容 +- 动态处理项目列表 +- 事件处理机制 + +#### SourcesItem React 子组件 + +SourcesItem 是单个数据源项目的 React 实现，通过 ItemHandler 处理项目逻辑。 + +**关键特性：** + +- 接受部分 SourcesProps 类型 +- 使用 ItemHandler 进行项目处理 +- 支持额外的项目处理器属性 + +**章节来源** + +- [frontend/antdx/sources/sources.tsx:1-41](file://frontend/antdx/sources/sources.tsx#L1-L41) +- [frontend/antdx/sources/item/sources.item.tsx:1-14](file://frontend/antdx/sources/item/sources.item.tsx#L1-L14) + +### 事件处理机制 + +Sources 组件支持两种主要事件： + +```mermaid +flowchart TD +Start([组件初始化]) --> BindEvents["绑定事件监听器"] +BindEvents --> ExpandEvent["展开事件监听"] +BindEvents --> ClickEvent["点击事件监听"] +ExpandEvent --> ExpandCallback["bind_expand_event 回调"] +ClickEvent --> ClickCallback["bind_click_event 回调"] +ExpandCallback --> UpdateInternal["更新内部状态"] +ClickCallback --> UpdateInternal +UpdateInternal --> End([事件处理完成]) +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/sources/**init**.py:18-25](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L18-L25) + +**事件类型：** + +- `expand`: 当用户展开或折叠数据源时触发 +- `click`: 当用户点击某个数据源项目时触发 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/sources/**init**.py:18-25](file://backend/modelscope_studio/components/antdx/sources/__init__.py#L18-L25) + +### 插槽系统 + +Sources 组件支持灵活的插槽系统，允许开发者自定义组件的不同部分： + +```mermaid +graph LR +subgraph "插槽系统" +Items[items 插槽
主要项目列表] +Default[default 插槽
默认项目内容] +Title[title 插槽
自定义标题] +end +subgraph "渲染逻辑" +Resolve[解析插槽内容] +Fallback[回退到默认内容] +Render[渲染最终结果] +end +Items --> Resolve +Default --> Resolve +Title --> Resolve +Resolve --> Fallback +Fallback --> Render +``` + +**图表来源** + +- [frontend/antdx/sources/sources.tsx:12-36](file://frontend/antdx/sources/sources.tsx#L12-L36) + +**支持的插槽：** + +- `items`: 主要的数据源项目列表 +- `default`: 默认的项目内容 +- `title`: 自定义的标题内容 + +**章节来源** + +- [frontend/antdx/sources/sources.tsx:12-36](file://frontend/antdx/sources/sources.tsx#L12-L36) + +## 依赖关系分析 + +Sources 组件的依赖关系相对简洁，主要依赖于 Ant Design X 和相关的工具库： + +```mermaid +graph TB +subgraph "外部依赖" +AntDX[@ant-design/x
Ant Design X 核心组件] +SveltePreprocess[@svelte-preprocess-react
Svelte-React 桥接] +Utils[@utils/*
工具函数库] +end +subgraph "内部依赖" +Component[ModelScopeLayoutComponent
基础组件类] +Context[createItemsContext
上下文管理] +ResolveDir[resolve_frontend_dir
路径解析] +end +subgraph "Sources 组件" +Sources[AntdXSources] +SourcesItem[AntdXSourcesItem] +end +Sources --> AntDX +Sources --> SveltePreprocess +Sources --> Utils +Sources --> Component +Sources --> Context +Sources --> ResolveDir +SourcesItem --> AntDX +SourcesItem --> SveltePreprocess +SourcesItem --> Context +``` + +**图表来源** + +- [frontend/antdx/sources/sources.tsx:1-5](file://frontend/antdx/sources/sources.tsx#L1-L5) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-16](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L16) + +**主要依赖说明：** + +- `@ant-design/x`: 提供核心的 Sources 组件实现 +- `@svelte-preprocess-react`: 实现 Svelte 和 React 之间的桥接 +- `@utils/*`: 提供通用的工具函数，如 renderItems、createItemsContext 等 + +**章节来源** + +- [frontend/antdx/sources/sources.tsx:1-5](file://frontend/antdx/sources/sources.tsx#L1-L5) +- [backend/modelscope_studio/components/antdx/components.py:30-31](file://backend/modelscope_studio/components/antdx/components.py#L30-L31) + +## 性能考虑 + +Sources 组件在设计时充分考虑了性能优化： + +### 渲染优化 + +1. **Memoization 优化**: 使用 React 的 useMemo 来缓存计算结果，避免不必要的重新渲染 +2. **条件渲染**: 仅在需要时渲染组件内容 +3. **懒加载**: 通过事件驱动的方式延迟加载内容 + +### 内存管理 + +1. **组件卸载**: 正确处理组件的挂载和卸载过程 +2. **事件清理**: 在组件销毁时清理事件监听器 +3. **状态管理**: 使用最小化的状态更新策略 + +### 数据处理优化 + +1. **批量更新**: 支持批量的数据源更新 +2. **增量渲染**: 仅更新发生变化的部分 +3. **虚拟化支持**: 对大量数据源提供虚拟化渲染能力 + +## 故障排除指南 + +### 常见问题及解决方案 + +**问题 1: 组件无法显示** + +- 检查 Ant Design X 依赖是否正确安装 +- 确认前端目录路径解析是否正确 +- 验证组件的可见性属性设置 + +**问题 2: 事件不响应** + +- 确认事件监听器是否正确绑定 +- 检查事件回调函数的参数传递 +- 验证组件的事件处理逻辑 + +**问题 3: 插槽内容不显示** + +- 检查插槽名称是否正确 +- 确认插槽内容的传递方式 +- 验证插槽的渲染优先级 + +**问题 4: 性能问题** + +- 检查数据源的数量和复杂度 +- 优化数据源的渲染逻辑 +- 考虑使用虚拟化渲染 + +**章节来源** + +- [docs/components/antdx/sources/demos/basic.py:1-46](file://docs/components/antdx/sources/demos/basic.py#L1-L46) + +## 结论 + +Sources 数据源组件是一个设计精良、功能完整的组件，它成功地将 Ant Design X 的强大功能与 ModelScope Studio 的生态系统相结合。该组件具有以下优势： + +1. **架构清晰**: 采用分层设计，职责明确 +2. **扩展性强**: 支持丰富的配置选项和插槽系统 +3. **性能优秀**: 通过多种优化技术确保良好的性能表现 +4. **易于使用**: 提供直观的 API 和完整的文档支持 + +该组件特别适用于 AI 聊天应用中的参考文献显示、链接来源管理等场景，为开发者提供了强大的数据源展示能力。通过合理的事件处理和插槽系统，开发者可以轻松地定制组件的行为和外观，满足各种复杂的业务需求。 diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/Think \346\200\235\350\200\203\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/Think \346\200\235\350\200\203\347\273\204\344\273\266.md" new file mode 100644 index 00000000..a642545c --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/Think \346\200\235\350\200\203\347\273\204\344\273\266.md" @@ -0,0 +1,457 @@ +# Think 思考组件 + + +**本文档引用的文件** +- [think/__init__.py](file://backend/modelscope_studio/components/antdx/think/__init__.py) +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [think.tsx](file://frontend/antdx/think/think.tsx) +- [Index.svelte](file://frontend/antdx/think/Index.svelte) +- [thought-chain.tsx](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [context.ts](file://frontend/antdx/thought-chain/context.ts) +- [__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构概览](#架构概览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) + +## 简介 + +Think 思考组件是 ModelScope Studio 中用于可视化和追踪 AI Agent 思考过程的核心组件。该组件基于 Ant Design X 的 Think 组件构建，专门设计用于在对话系统中展示智能体的推理过程、决策链路和中间思考结果。 + +该组件的主要设计理念是提供透明化的 AI 决策过程可视化，让用户能够理解 AI 智能体是如何进行思考、分析和做出决策的。通过详细的思考过程记录和展示，用户可以更好地信任和优化 AI 系统的行为。 + +## 项目结构 + +Think 组件在整个项目架构中位于 antdx 组件库中，采用前后端分离的设计模式： + +```mermaid +graph TB +subgraph "后端层" +Backend[ModelScope Studio 后端] +ThinkPy[Think Python 组件] +ComponentsPy[组件注册] +end +subgraph "前端层" +Frontend[ModelScope Studio 前端] +ThinkTSX[Think TypeScript 组件] +IndexSvelte[Think Svelte 包装器] +ThoughtChain[思考链组件] +end +subgraph "外部依赖" +AntDX[Ant Design X] +Gradio[Gradio 框架] +end +Backend --> ThinkPy +ThinkPy --> ComponentsPy +Frontend --> ThinkTSX +ThinkTSX --> IndexSvelte +IndexSvelte --> AntDX +ComponentsPy --> Frontend +Gradio --> Backend +``` + +**图表来源** + +- [think/**init**.py:1-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L1-L79) +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +**章节来源** + +- [think/**init**.py:1-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L1-L79) +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## 核心组件 + +### Think 组件类定义 + +Think 组件继承自 `ModelScopeLayoutComponent`，提供了完整的属性配置和事件处理机制： + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++visible : bool ++elem_id : str ++elem_classes : list[str] ++elem_style : dict ++render : bool ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class AntdXThink { ++additional_props : dict ++icon : str ++styles : dict ++class_names : dict ++loading : str|bool ++title : str ++root_class_name : str ++default_expanded : bool ++expanded : bool ++blink : bool ++EVENTS : list ++SLOTS : list ++FRONTEND_DIR : str ++skip_api : bool +} +class Think { ++slots : dict ++props : ThinkProps ++loading : ReactNode ++icon : ReactNode ++title : ReactNode +} +ModelScopeLayoutComponent <|-- AntdXThink +AntdXThink --> Think : "前端渲染" +``` + +**图表来源** + +- [think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +### 关键属性配置 + +Think 组件支持丰富的配置选项，包括： + +- **基础属性**: 图标、标题、样式类名 +- **状态属性**: 加载状态、展开状态、闪烁效果 +- **事件属性**: 展开事件绑定 +- **插槽系统**: 支持 loading、icon、title 三个插槽 + +**章节来源** + +- [think/**init**.py:21-60](file://backend/modelscope_studio/components/antdx/think/__init__.py#L21-L60) +- [think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +## 架构概览 + +Think 组件采用分层架构设计，实现了前后端的清晰分离： + +```mermaid +sequenceDiagram +participant User as 用户界面 +participant Backend as 后端 Think 组件 +participant Frontend as 前端包装器 +participant AntDX as Ant Design X +participant React as React 组件 +User->>Backend : 创建 Think 组件实例 +Backend->>Backend : 配置组件属性 +Backend->>Frontend : 渲染前端包装器 +Frontend->>AntDX : 加载 Ant Design X Think +AntDX->>React : 渲染 React 组件 +React->>React : 处理插槽内容 +React->>User : 显示思考过程 +Note over Backend,React : 完整的组件生命周期管理 +``` + +**图表来源** + +- [Index.svelte:10-67](file://frontend/antdx/think/Index.svelte#L10-L67) +- [think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +### 组件生命周期 + +```mermaid +flowchart TD +Start([组件初始化]) --> Config[配置属性] +Config --> Render[渲染前端包装器] +Render --> LoadAntDX[加载 Ant Design X] +LoadAntDX --> ProcessSlots[处理插槽内容] +ProcessSlots --> Display[显示思考过程] +Display --> EventBind[绑定事件监听] +EventBind --> Ready[组件就绪] +Ready --> UserInteraction[用户交互] +UserInteraction --> UpdateState[更新状态] +UpdateState --> ReRender[重新渲染] +ReRender --> Ready +Ready --> Cleanup[组件销毁] +Cleanup --> End([结束]) +``` + +**图表来源** + +- [think/**init**.py:12-16](file://backend/modelscope_studio/components/antdx/think/__init__.py#L12-L16) +- [Index.svelte:55-68](file://frontend/antdx/think/Index.svelte#L55-L68) + +## 详细组件分析 + +### 后端实现分析 + +后端 Think 组件实现了完整的 Gradio 组件接口： + +#### 事件系统 + +组件支持 expand 事件，用于处理展开状态的变化： + +```mermaid +stateDiagram-v2 +[*] --> Collapsed : 默认折叠状态 +Collapsed --> Expanded : 触发 expand 事件 +Expanded --> Collapsed : 用户点击折叠 +Collapsed --> Blinking : 设置 blink 属性 +Blinking --> Collapsed : blink 效果结束 +note right of Expanded +展开状态下的思考过程 +可以查看详细内容 +end note +note right of Blinking +闪烁效果用于吸引注意 +通常表示新思考过程 +end note +``` + +**图表来源** + +- [think/**init**.py:12-16](file://backend/modelscope_studio/components/antdx/think/__init__.py#L12-L16) + +#### 插槽系统 + +组件支持三种插槽，允许灵活的内容定制： + +| 插槽名称 | 类型 | 用途 | 默认值 | +| -------- | --------- | ---------------- | ------------- | +| loading | ReactNode | 自定义加载指示器 | props.loading | +| icon | ReactNode | 自定义图标 | props.icon | +| title | ReactNode | 自定义标题内容 | props.title | + +**章节来源** + +- [think/**init**.py:18-19](file://backend/modelscope_studio/components/antdx/think/__init__.py#L18-L19) +- [think.tsx:12-16](file://frontend/antdx/think/think.tsx#L12-L16) + +### 前端实现分析 + +前端采用 Svelte + React 的混合架构： + +#### Svelte 包装器 + +Index.svelte 提供了完整的组件包装功能： + +```mermaid +classDiagram +class IndexSvelte { ++props : ComponentProps ++slots : Slots ++proceedProps : ProcessedProps ++AwaitedThink : ComponentPromise ++getProps() ++getSlots() ++processProps() +} +class ThinkWrapper { ++style : CSSProperties ++className : string ++id : string ++slots : dict ++children : ReactNode +} +IndexSvelte --> ThinkWrapper : "渲染" +ThinkWrapper --> AntDThink : "包含" +``` + +**图表来源** + +- [Index.svelte:12-67](file://frontend/antdx/think/Index.svelte#L12-L67) + +#### React 组件桥接 + +think.tsx 实现了 Svelte 到 React 的桥接： + +- 使用 `sveltify` 将 React 组件转换为 Svelte 组件 +- 通过 `ReactSlot` 处理插槽内容 +- 直接调用 Ant Design X 的原生 Think 组件 + +**章节来源** + +- [Index.svelte:1-69](file://frontend/antdx/think/Index.svelte#L1-L69) +- [think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +### 思考链集成 + +Think 组件与 ThoughtChain 组件形成完整的思考过程可视化体系： + +```mermaid +graph LR +subgraph "思考过程" +Think[Think 组件] +ThoughtChain[ThoughtChain 组件] +end +subgraph "数据流" +Items[思考项列表] +Status[状态管理] +Timeline[时间线] +end +subgraph "UI 展示" +ChainView[链式视图] +DetailView[详情视图] +TimelineView[时间轴视图] +end +Think --> Items +ThoughtChain --> Items +Items --> Status +Status --> Timeline +Timeline --> ChainView +Timeline --> DetailView +Timeline --> TimelineView +``` + +**图表来源** + +- [thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [context.ts:1-7](file://frontend/antdx/thought-chain/context.ts#L1-L7) + +**章节来源** + +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [context.ts:1-7](file://frontend/antdx/thought-chain/context.ts#L1-L7) + +## 依赖关系分析 + +### 组件依赖图 + +```mermaid +graph TB +subgraph "核心依赖" +Gradio[Gradio 框架] +AntD[Ant Design X] +Svelte[Svelte 框架] +end +subgraph "内部依赖" +Utils[开发工具] +Layout[布局组件] +Slot[插槽系统] +end +subgraph "Think 组件" +ThinkPy[Python 组件] +ThinkTSX[TypeScript 组件] +ThinkSvelte[Svelte 包装器] +end +Gradio --> ThinkPy +AntD --> ThinkTSX +Svelte --> ThinkSvelte +Utils --> ThinkPy +Layout --> ThinkPy +Slot --> ThinkTSX +ThinkPy --> ThinkTSX +ThinkTSX --> ThinkSvelte +``` + +**图表来源** + +- [components.py:34-34](file://backend/modelscope_studio/components/antdx/components.py#L34-L34) +- [**init**.py:34-34](file://backend/modelscope_studio/components/antdx/__init__.py#L34-L34) + +### 版本兼容性 + +组件确保与以下版本的兼容性： + +- **Gradio**: >= 4.0.0 +- **Ant Design X**: >= 0.1.0 +- **Svelte**: >= 3.54.0 +- **React**: >= 18.0.0 + +**章节来源** + +- [components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## 性能考虑 + +### 渲染优化 + +1. **懒加载机制**: 前端采用动态导入，减少初始加载时间 +2. **条件渲染**: 仅在可见时渲染组件，避免不必要的计算 +3. **插槽优化**: 通过 ReactSlot 实现高效的插槽内容处理 + +### 内存管理 + +- 组件销毁时自动清理事件监听器 +- 合理的 props 处理避免内存泄漏 +- 使用 useMemo 优化复杂数据结构的渲染 + +## 故障排除指南 + +### 常见问题及解决方案 + +#### 组件不显示 + +**症状**: Think 组件创建成功但不显示在界面上 + +**可能原因**: + +1. `visible` 属性设置为 False +2. `render` 属性设置为 False +3. 父容器样式问题 + +**解决方案**: + +- 检查组件的 `visible` 和 `render` 属性 +- 验证父容器的 CSS 样式 +- 确认组件正确导入 + +#### 插槽内容不生效 + +**症状**: 自定义的 loading、icon、title 插槽内容没有显示 + +**可能原因**: + +1. 插槽名称错误 +2. 插槽内容类型不匹配 +3. 插槽传递方式错误 + +**解决方案**: + +- 确认插槽名称为 'loading'、'icon' 或 'title' +- 验证插槽内容为有效的 ReactNode +- 检查插槽的传递语法 + +#### 事件处理异常 + +**症状**: expand 事件无法正常触发 + +**可能原因**: + +1. 事件监听器未正确绑定 +2. 事件回调函数错误 +3. 组件状态问题 + +**解决方案**: + +- 检查 EVENTS 数组配置 +- 验证事件回调函数逻辑 +- 确认组件状态同步 + +**章节来源** + +- [think/**init**.py:12-16](file://backend/modelscope_studio/components/antdx/think/__init__.py#L12-L16) + +## 结论 + +Think 思考组件作为 ModelScope Studio 的核心可视化组件，成功实现了 AI 思考过程的透明化展示。通过精心设计的架构和丰富的配置选项，该组件为开发者和用户提供了强大的思考过程追踪能力。 + +### 主要优势 + +1. **完整的可视化**: 提供从简单到复杂的多种思考过程展示方式 +2. **灵活的配置**: 支持丰富的属性配置和插槽定制 +3. **良好的性能**: 采用现代前端技术栈，确保流畅的用户体验 +4. **易于集成**: 与 Gradio 生态系统无缝集成 + +### 应用场景 + +- **AI 助手**: 展示智能体的推理过程和决策链路 +- **数据分析**: 可视化数据探索和分析思路 +- **代码生成**: 展示代码生成的思考过程和逻辑 +- **多模态应用**: 支持文本、图像等多种输入类型的思考过程 + +该组件为构建可信、可解释的 AI 应用奠定了坚实的基础，是现代 AI 产品不可或缺的重要组成部分。 diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/\346\225\260\346\215\256\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/\346\225\260\346\215\256\347\273\204\344\273\266.md" new file mode 100644 index 00000000..0684d590 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\347\273\204\344\273\266/\346\225\260\346\215\256\347\273\204\344\273\266.md" @@ -0,0 +1,372 @@ +# 数据组件 + + +**本文引用的文件** +- [frontend/antdx/file-card/file-card.tsx](file://frontend/antdx/file-card/file-card.tsx) +- [frontend/antdx/file-card/base.tsx](file://frontend/antdx/file-card/base.tsx) +- [frontend/antdx/folder/folder.tsx](file://frontend/antdx/folder/folder.tsx) +- [frontend/antdx/folder/context.ts](file://frontend/antdx/folder/context.ts) +- [frontend/antdx/sources/sources.tsx](file://frontend/antdx/sources/sources.tsx) +- [frontend/antdx/sources/context.ts](file://frontend/antdx/sources/context.ts) +- [frontend/antdx/think/think.tsx](file://frontend/antdx/think/think.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向 Ant Design X 的数据组件，聚焦以下四个组件：FileCard（文件卡片）、Folder（文件夹）、Sources（数据源）、Think（思考）。文档从系统架构、组件职责、数据流与处理逻辑、集成点与错误处理等方面进行深入解析，并提供可直接落地的使用示例与最佳实践，帮助开发者快速理解并正确使用这些组件。 + +## 项目结构 + +Ant Design X 的前端组件位于 `frontend/antdx` 目录下，每个组件通常由三部分组成： + +- 组件入口文件：负责桥接 Svelte 与 React 生态，注入插槽与函数式回调。 +- 基础实现文件：封装与 @ant-design/x 的实际组件交互，处理数据解析与默认行为。 +- 上下文与工具：通过 createItemsContext 提供插槽项的上下文能力，支持动态渲染与扩展。 + +```mermaid +graph TB +subgraph "Ant Design X 数据组件" +FC["FileCard
文件卡片"] +F["Folder
文件夹"] +S["Sources
数据源"] +T["Think
思考"] +end +subgraph "基础实现" +BFC["BaseFileCard
基础文件卡片"] +CtxF["Folder 上下文
treeData/directoryIcons"] +CtxS["Sources 上下文
items/title"] +end +subgraph "外部依赖" +ADX["@ant-design/x
原生组件库"] +Utils["@utils/*
工具与钩子"] +end +FC --> BFC +F --> CtxF +S --> CtxS +FC --> ADX +F --> ADX +S --> ADX +T --> ADX +FC --> Utils +F --> Utils +S --> Utils +T --> Utils +``` + +图表来源 + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) +- [frontend/antdx/folder/folder.tsx:1-123](file://frontend/antdx/folder/folder.tsx#L1-L123) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) +- [frontend/antdx/sources/sources.tsx:1-42](file://frontend/antdx/sources/sources.tsx#L1-L42) +- [frontend/antdx/sources/context.ts:1-7](file://frontend/antdx/sources/context.ts#L1-L7) +- [frontend/antdx/think/think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +章节来源 + +- [frontend/antdx/file-card/file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [frontend/antdx/file-card/base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) +- [frontend/antdx/folder/folder.tsx:1-123](file://frontend/antdx/folder/folder.tsx#L1-L123) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) +- [frontend/antdx/sources/sources.tsx:1-42](file://frontend/antdx/sources/sources.tsx#L1-L42) +- [frontend/antdx/sources/context.ts:1-7](file://frontend/antdx/sources/context.ts#L1-L7) +- [frontend/antdx/think/think.tsx:1-24](file://frontend/antdx/think/think.tsx#L1-L24) + +## 核心组件 + +- FileCard：用于展示单个文件卡片，支持图片占位、预览配置、遮罩与加载指示器的插槽化定制；内部通过 BaseFileCard 解析文件资源地址，确保可访问性。 + - **子组件层级关系**：FileCard 为顶层单卡片组件；`FileCardList`（列表层）用于署列展示多个文件卡片；`FileCardListItem`（列表项层）封装单个列表项的渲染逻辑。三者层级关系为：FileCardList → FileCardListItem → FileCard。 + - **后端导出**：`FileCard`、`FileCardList`、`FileCardListItem` 均通过 [backend/modelscope_studio/components/antdx/**init**.py](file://backend/modelscope_studio/components/antdx/__init__.py) 导出。 +- Folder：用于展示文件夹树形结构，支持 treeData、directoryIcons、空态渲染、目录标题、预览标题与预览渲染等插槽；通过上下文提供节点与图标项的动态注入。 +- Sources：用于展示数据源列表，支持 items 与 title 插槽；通过上下文提供默认项集合，便于在父级容器中统一注入。 +- Think：用于展示“思考”记录与状态，支持 loading、icon、title 插槽，便于在不同状态下显示不同的视觉反馈。 + - **Think 与 ThoughtChain 的区别**：Think（`antdx.Think`）是轻量级单步骤“思考状态”展示组件，通常嵌入气泡流中用于指示“正在思考”的单一状态（属于数据组件）；ThoughtChain（`antdx.ThoughtChain`）则是多步骤思维链组件，用于展示完整的推理过程序列，内层支持子项渲染（属于确认组件）。两者使用场景不同：Think 适合单状态指示，ThoughtChain 适合多步骤推理展示。 + +章节来源 + +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/file-card/base.tsx:9-41](file://frontend/antdx/file-card/base.tsx#L9-L41) +- [frontend/antdx/folder/folder.tsx:16-120](file://frontend/antdx/folder/folder.tsx#L16-L120) +- [frontend/antdx/folder/context.ts:3-13](file://frontend/antdx/folder/context.ts#L3-L13) +- [frontend/antdx/sources/sources.tsx:9-39](file://frontend/antdx/sources/sources.tsx#L9-L39) +- [frontend/antdx/sources/context.ts:3-4](file://frontend/antdx/sources/context.ts#L3-L4) +- [frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +## 架构总览 + +四个组件均采用“入口层 + 基础实现/上下文”的分层设计： + +- 入口层：使用 sveltify 将 Svelte 组件桥接到 React 生态，统一处理 slots 与函数式回调，保证与 @ant-design/x 的属性对齐。 +- 基础实现/上下文：在入口层之上，进一步封装数据解析、默认值处理、插槽渲染与上下文注入，降低重复逻辑，提升可维护性。 + +```mermaid +sequenceDiagram +participant U as "调用方" +participant FC as "FileCard 入口" +participant BFC as "BaseFileCard" +participant ADX as "@ant-design/x" +U->>FC : 传入 props 与 slots +FC->>FC : 处理 slots 与函数式回调 +FC->>BFC : 传递解析后的 props +BFC->>ADX : 渲染 FileCard 并解析 src +ADX-->>U : 展示文件卡片 +``` + +图表来源 + +- [frontend/antdx/file-card/file-card.tsx:34-124](file://frontend/antdx/file-card/file-card.tsx#L34-L124) +- [frontend/antdx/file-card/base.tsx:31-41](file://frontend/antdx/file-card/base.tsx#L31-L41) + +章节来源 + +- [frontend/antdx/file-card/file-card.tsx:17-124](file://frontend/antdx/file-card/file-card.tsx#L17-L124) +- [frontend/antdx/file-card/base.tsx:9-41](file://frontend/antdx/file-card/base.tsx#L9-L41) + +## 详细组件分析 + +### FileCard 组件分析 + +- 职责与能力 + - 文件信息展示：支持文件名、描述、图标、占位图、加载指示器等。 + - 操作与预览：支持图片预览配置（容器、遮罩、关闭图标、工具栏、自定义图片渲染）。 + - 插槽化扩展：通过 slots 对 icon、description、mask、spinProps._、imageProps._ 进行灵活替换。 + - 资源解析：通过 BaseFileCard 的 src 解析逻辑，将相对路径或 FileData 转换为可访问的 URL。 +- 关键流程 + - 入口层解析 slots 与函数式回调，构造 preview 配置。 + - 将解析后的 imageProps 与 spinProps 传递给 BaseFileCard。 + - BaseFileCard 使用 rootUrl 与 apiPrefix 计算可访问的文件地址。 +- 使用建议 + - 在需要自定义预览工具栏或遮罩时，优先使用 slots 注入，避免直接覆盖复杂对象。 + - 对于大文件或网络不稳定场景，合理设置占位图与加载指示器以提升用户体验。 + +```mermaid +flowchart TD +Start(["进入 FileCard"]) --> ParseSlots["解析 slots 与函数式回调"] +ParseSlots --> BuildPreview["构建 imageProps.preview 配置"] +BuildPreview --> ResolveSrc["BaseFileCard 解析 src
rootUrl + apiPrefix"] +ResolveSrc --> Render["渲染 @ant-design/x FileCard"] +Render --> End(["完成"]) +``` + +图表来源 + +- [frontend/antdx/file-card/file-card.tsx:34-124](file://frontend/antdx/file-card/file-card.tsx#L34-L124) +- [frontend/antdx/file-card/base.tsx:15-41](file://frontend/antdx/file-card/base.tsx#L15-L41) + +章节来源 + +- [frontend/antdx/file-card/file-card.tsx:9-124](file://frontend/antdx/file-card/file-card.tsx#L9-L124) +- [frontend/antdx/file-card/base.tsx:9-41](file://frontend/antdx/file-card/base.tsx#L9-L41) + +### Folder 组件分析 + +- 职责与能力 + - 树形结构展示：支持 treeData 与目录图标映射 directoryIcons。 + - 动态内容服务：通过 fileContentService.onLoadFileContent 加载文件内容。 + - 插槽化扩展：支持 emptyRender、previewRender、directoryTitle、previewTitle。 + - 上下文注入：通过 useTreeNodeItems 与 useDirectoryIconItems 获取默认节点与图标集合。 +- 关键流程 + - 从上下文解析 treeData 或 default，优先使用显式传入的 treeData。 + - 将 directoryIcons 转换为按扩展名映射的图标字典。 + - 将 slots 与函数式回调转换为 @ant-design/x 所需的渲染函数。 +- 使用建议 + - 当目录结构复杂时，优先使用上下文注入默认节点，减少重复配置。 + - 预览渲染函数应尽量轻量，避免在渲染过程中执行重计算。 + +```mermaid +sequenceDiagram +participant U as "调用方" +participant F as "Folder 入口" +participant Ctx as "Folder 上下文" +participant ADX as "@ant-design/x Folder" +U->>F : 传入 treeData/directoryIcons/slots +F->>Ctx : 读取默认节点与图标 +F->>F : 解析 slots 与函数式回调 +F->>ADX : 渲染 treeData 与 directoryIcons +ADX-->>U : 展示文件夹树 +``` + +图表来源 + +- [frontend/antdx/folder/folder.tsx:25-119](file://frontend/antdx/folder/folder.tsx#L25-L119) +- [frontend/antdx/folder/context.ts:3-13](file://frontend/antdx/folder/context.ts#L3-L13) + +章节来源 + +- [frontend/antdx/folder/folder.tsx:16-120](file://frontend/antdx/folder/folder.tsx#L16-L120) +- [frontend/antdx/folder/context.ts:1-16](file://frontend/antdx/folder/context.ts#L1-L16) + +### Sources 组件分析 + +- 职责与能力 + - 数据源列表展示：支持 items 列表与标题 title 插槽。 + - 上下文注入：通过 useItems 获取默认 items 与 default，优先使用显式传入的 items。 + - 渲染增强：使用 renderItems 将上下文中的项集合克隆并渲染为 @ant-design/x 所需格式。 +- 关键流程 + - 从上下文解析 items 或 default，合并为最终列表。 + - 将 title 与 items 传递给 @ant-design/x Sources。 +- 使用建议 + - 在父级容器中集中注入默认 items，便于多处复用。 + - 对于大型列表，建议在上游进行分页或懒加载优化。 + +```mermaid +sequenceDiagram +participant U as "调用方" +participant S as "Sources 入口" +participant Ctx as "Sources 上下文" +participant ADX as "@ant-design/x Sources" +U->>S : 传入 items/slots +S->>Ctx : 读取默认 items/default +S->>ADX : 渲染 items 与 title +ADX-->>U : 展示数据源列表 +``` + +图表来源 + +- [frontend/antdx/sources/sources.tsx:9-39](file://frontend/antdx/sources/sources.tsx#L9-L39) +- [frontend/antdx/sources/context.ts:3-4](file://frontend/antdx/sources/context.ts#L3-L4) + +章节来源 + +- [frontend/antdx/sources/sources.tsx:9-39](file://frontend/antdx/sources/sources.tsx#L9-L39) +- [frontend/antdx/sources/context.ts:1-7](file://frontend/antdx/sources/context.ts#L1-L7) + +### Think 组件分析 + +- 职责与能力 + - 思考记录与状态展示：支持 loading、icon、title 插槽，便于在不同状态（如加载中、完成、失败）下切换显示内容。 + - 简洁桥接：作为 thin wrapper 直接转发到 @ant-design/x 的 Think 组件。 +- 使用建议 + - 在异步思考流程中，结合 loading 插槽提供更友好的用户反馈。 + - 将 icon 与 title 插槽用于区分思考阶段或结果类型。 + +```mermaid +sequenceDiagram +participant U as "调用方" +participant T as "Think 入口" +participant ADX as "@ant-design/x Think" +U->>T : 传入 loading/icon/title/slots +T->>ADX : 直接转发 props 与 slots +ADX-->>U : 展示思考状态 +``` + +图表来源 + +- [frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +章节来源 + +- [frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +## 依赖关系分析 + +- 组件间耦合 + - FileCard 与 BaseFileCard：低耦合，通过 props 传递与解析实现解耦。 + - Folder 与 Sources：均依赖各自的上下文模块，彼此独立，通过 @ant-design/x 组件进行渲染。 + - Think：无上下文依赖，直接桥接 @ant-design/x。 +- 外部依赖 + - @ant-design/x：所有组件最终渲染的基础库。 + - @utils/\*：提供插槽渲染、函数式回调包装、上下文创建等通用能力。 + +```mermaid +graph LR +FC["FileCard"] --> BFC["BaseFileCard"] +F["Folder"] --> CtxF["Folder 上下文"] +S["Sources"] --> CtxS["Sources 上下文"] +T["Think"] +BFC --> ADX["@ant-design/x"] +F --> ADX +S --> ADX +T --> ADX +FC --> Utils["@utils/*"] +F --> Utils +S --> Utils +T --> Utils +``` + +图表来源 + +- [frontend/antdx/file-card/file-card.tsx:1-7](file://frontend/antdx/file-card/file-card.tsx#L1-L7) +- [frontend/antdx/file-card/base.tsx:1-7](file://frontend/antdx/file-card/base.tsx#L1-L7) +- [frontend/antdx/folder/folder.tsx:1-7](file://frontend/antdx/folder/folder.tsx#L1-L7) +- [frontend/antdx/sources/sources.tsx:1-5](file://frontend/antdx/sources/sources.tsx#L1-L5) +- [frontend/antdx/think/think.tsx:1-4](file://frontend/antdx/think/think.tsx#L1-L4) + +章节来源 + +- [frontend/antdx/file-card/file-card.tsx:1-7](file://frontend/antdx/file-card/file-card.tsx#L1-L7) +- [frontend/antdx/file-card/base.tsx:1-7](file://frontend/antdx/file-card/base.tsx#L1-L7) +- [frontend/antdx/folder/folder.tsx:1-7](file://frontend/antdx/folder/folder.tsx#L1-L7) +- [frontend/antdx/sources/sources.tsx:1-5](file://frontend/antdx/sources/sources.tsx#L1-L5) +- [frontend/antdx/think/think.tsx:1-4](file://frontend/antdx/think/think.tsx#L1-L4) + +## 性能考量 + +- 插槽渲染成本控制 + - 尽量将 heavy 内容放入 slots，但注意在渲染函数中避免重复计算，必要时使用 useMemo 缓存。 +- 数据解析与传输 + - FileCard 的 src 解析仅在依赖变化时触发，避免不必要的 URL 计算。 +- 列表渲染优化 + - Sources 与 Folder 在解析 items 时使用 clone 与 memo 化策略，减少重复渲染。 +- 预览与图片 + - 合理设置占位图与加载指示器，避免大图导致的首屏阻塞。 + +## 故障排查指南 + +- 图片无法显示 + - 检查 src 是否为相对路径，确认 rootUrl 与 apiPrefix 配置是否正确。 + - 参考路径：[frontend/antdx/file-card/base.tsx:15-29](file://frontend/antdx/file-card/base.tsx#L15-L29) +- 预览功能异常 + - 确认 imageProps.preview 的 slots 是否正确注入，函数式回调是否被正确包装。 + - 参考路径：[frontend/antdx/file-card/file-card.tsx:34-124](file://frontend/antdx/file-card/file-card.tsx#L34-L124) +- 目录图标不生效 + - 确认 directoryIcons 是否按扩展名映射，且已通过上下文注入。 + - 参考路径：[frontend/antdx/folder/folder.tsx:71-87](file://frontend/antdx/folder/folder.tsx#L71-L87) +- 数据源列表为空 + - 检查 items 与 default 是否正确注入，或是否被显式覆盖。 + - 参考路径：[frontend/antdx/sources/sources.tsx:13-33](file://frontend/antdx/sources/sources.tsx#L13-L33) +- 思考状态未更新 + - 确认 loading/icon/title 插槽是否正确注入，或函数式回调是否被正确包装。 + - 参考路径：[frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +章节来源 + +- [frontend/antdx/file-card/base.tsx:15-29](file://frontend/antdx/file-card/base.tsx#L15-L29) +- [frontend/antdx/file-card/file-card.tsx:34-124](file://frontend/antdx/file-card/file-card.tsx#L34-L124) +- [frontend/antdx/folder/folder.tsx:71-87](file://frontend/antdx/folder/folder.tsx#L71-L87) +- [frontend/antdx/sources/sources.tsx:13-33](file://frontend/antdx/sources/sources.tsx#L13-L33) +- [frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) + +## 结论 + +本文档系统梳理了 Ant Design X 数据组件在前端侧的实现与使用方式，重点围绕 FileCard、Folder、Sources、Think 四个组件展开。通过入口层的插槽与函数式回调桥接、基础实现的数据解析与默认值处理、以及上下文驱动的动态注入机制，这些组件在保持与 @ant-design/x 一致的 API 语义的同时，提供了更强的可扩展性与可维护性。建议在实际项目中遵循本文的使用建议与最佳实践，以获得更稳定、高效的体验。 + +## 附录 + +- 使用示例（基于组件职责与接口） + - 文件卡片展示与预览 + - 步骤要点：准备文件数据 src，配置 imageProps.preview 的 slots（如遮罩、工具栏），必要时设置占位图与加载指示器。 + - 参考路径：[frontend/antdx/file-card/file-card.tsx:34-124](file://frontend/antdx/file-card/file-card.tsx#L34-L124)，[frontend/antdx/file-card/base.tsx:15-41](file://frontend/antdx/file-card/base.tsx#L15-L41) + - 文件夹树形结构与目录管理 + - 步骤要点：准备 treeData 或通过上下文注入默认节点；配置 directoryIcons 的扩展名映射；根据需要注入 emptyRender、previewRender、directoryTitle、previewTitle。 + - 参考路径：[frontend/antdx/folder/folder.tsx:25-119](file://frontend/antdx/folder/folder.tsx#L25-L119)，[frontend/antdx/folder/context.ts:3-13](file://frontend/antdx/folder/context.ts#L3-L13) + - 数据源管理与元数据展示 + - 步骤要点：在父级容器中注入默认 items 或 default；在需要时覆盖 items；通过 title 插槽自定义标题。 + - 参考路径：[frontend/antdx/sources/sources.tsx:9-39](file://frontend/antdx/sources/sources.tsx#L9-L39)，[frontend/antdx/sources/context.ts:3-4](file://frontend/antdx/sources/context.ts#L3-L4) + - 思考记录与状态管理 + - 步骤要点：在不同阶段注入 loading/icon/title 插槽；在异步流程中根据状态切换显示内容。 + - 参考路径：[frontend/antdx/think/think.tsx:6-21](file://frontend/antdx/think/think.tsx#L6-L21) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\347\241\256\350\256\244\347\273\204\344\273\266/ThoughtChain \346\200\235\350\200\203\351\223\276\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\347\241\256\350\256\244\347\273\204\344\273\266/ThoughtChain \346\200\235\350\200\203\351\223\276\347\273\204\344\273\266.md" new file mode 100644 index 00000000..ac9928fa --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\347\241\256\350\256\244\347\273\204\344\273\266/ThoughtChain \346\200\235\350\200\203\351\223\276\347\273\204\344\273\266.md" @@ -0,0 +1,380 @@ +# ThoughtChain 思考链组件 + + +**本文档引用的文件** +- [backend 模块导出](file://backend/modelscope_studio/components/antdx/__init__.py) +- [ThoughtChain 主组件定义](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py) +- [ThoughtChain 子项组件定义](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py) +- [ThoughtChain 高级子项组件定义](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py) +- [前端 ThoughtChain 实现](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [前端 ThoughtChain 子项实现](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx) +- [前端 ThoughtChain 高级子项实现](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx) +- [前端 ThoughtChain 上下文工具](file://frontend/antdx/thought-chain/context.ts) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构概览](#架构概览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) + +## 简介 + +ThoughtChain 思考链组件是 ModelScope Studio 提供的一个强大可视化工具，专门用于记录和展示 AI 的思考过程。该组件通过树形结构清晰地呈现复杂的推理路径，帮助用户理解 AI 决策的逻辑流程。 + +该组件的核心价值在于： + +- **透明性增强**：让用户能够看到 AI 的完整思考过程 +- **可解释性提升**：通过可视化的步骤展示提高 AI 行为的可理解性 +- **调试支持**：便于开发者和用户追踪和分析 AI 的决策路径 +- **用户体验优化**：提供直观的视觉反馈，增强人机交互体验 + +## 项目结构 + +ModelScope Studio 采用分层架构设计，ThoughtChain 组件位于 antdx 组件库中，与 Gradio 生态系统深度集成。 + +```mermaid +graph TB +subgraph "后端 Python 层" +A[Antdx 组件导出] --> B[ThoughtChain 主组件] +A --> C[ThoughtChain 子项组件] +A --> D[ThoughtChain 高级子项组件] +end +subgraph "前端 React 层" +E[ThoughtChain 前端实现] +F[ThoughtChain 子项前端实现] +G[ThoughtChain 高级子项前端实现] +H[上下文工具] +end +subgraph "第三方库" +I[@ant-design/x] +J[Gradio 生态] +end +B --> E +C --> F +D --> G +E --> I +F --> I +G --> I +H --> E +H --> G +E --> J +F --> J +G --> J +``` + +**图表来源** + +- [backend 模块导出:35-41](file://backend/modelscope_studio/components/antdx/__init__.py#L35-L41) +- [ThoughtChain 主组件定义:12-18](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L18) +- [ThoughtChain 子项组件定义:8-11](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L8-L11) +- [ThoughtChain 高级子项组件定义:8-11](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L8-L11) + +**章节来源** + +- [backend 模块导出:35-41](file://backend/modelscope_studio/components/antdx/__init__.py#L35-L41) +- [ThoughtChain 主组件定义:12-18](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L18) + +## 核心组件 + +### ThoughtChain 主组件 + +主组件负责整体布局和状态管理，支持多种配置选项： + +**核心配置选项：** + +- `expanded_keys`: 默认展开的节点键值列表 +- `default_expanded_keys`: 初始默认展开的节点键值列表 +- `items`: 思考步骤的数据数组 +- `line`: 连接线样式（实线、虚线、点线） +- `prefix_cls`: 自定义前缀类名 +- `styles`: 内联样式对象或字符串 +- `class_names`: 类名映射对象 + +**事件处理：** + +- `expand`: 展开/折叠键值变化时的回调函数 + +### ThoughtChainItem 子项组件 + +用于表示单个思考步骤，支持丰富的自定义选项： + +**核心属性：** + +- `description`: 步骤描述文本 +- `icon`: 自定义图标名称 +- `title`: 步骤标题 +- `status`: 状态值（pending/pending, success/success, error/错误, abort/中止） +- `variant`: 外观变体（solid/实体, outlined/描边, text/文字） +- `blink`: 是否启用闪烁效果 + +**插槽支持：** + +- `description`: 自定义描述内容 +- `icon`: 自定义图标内容 +- `title`: 自定义标题内容 + +### ThoughtChainThoughtChainItem 高级子项组件 + +提供更复杂的功能，支持嵌套结构： + +**扩展属性：** + +- `content`: 主要内容文本 +- `extra`: 额外信息 +- `footer`: 底部内容 +- `collapsible`: 是否可折叠 +- `key`: 唯一键标识符 + +**高级插槽：** + +- `content`: 主要内容区域 +- `description`: 描述内容 +- `footer`: 底部内容 +- `icon`: 图标内容 +- `title`: 标题内容 + +**章节来源** + +- [ThoughtChain 主组件定义:30-67](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L30-L67) +- [ThoughtChain 子项组件定义:18-58](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L18-L58) +- [ThoughtChain 高级子项组件定义:18-59](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L18-L59) + +## 架构概览 + +ThoughtChain 组件采用前后端分离的架构设计，通过 Gradio 生态系统实现无缝集成。 + +```mermaid +sequenceDiagram +participant User as 用户界面 +participant Backend as 后端组件 +participant Frontend as 前端实现 +participant AntDX as Ant Design X +participant Context as 上下文管理 +User->>Backend : 创建 ThoughtChain 组件 +Backend->>Frontend : 解析前端目录 +Frontend->>Context : 初始化上下文 +Context->>AntDX : 加载核心组件 +User->>Backend : 设置配置参数 +Backend->>Frontend : 传递组件属性 +Frontend->>AntDX : 渲染思考链 +AntDX->>User : 显示可视化结果 +Note over User,AntDX : 支持动态更新和交互 +``` + +**图表来源** + +- [ThoughtChain 主组件定义:68-68](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L68-L68) +- [前端 ThoughtChain 实现:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [前端 ThoughtChain 上下文工具:1-4](file://frontend/antdx/thought-chain/context.ts#L1-L4) + +## 详细组件分析 + +### 数据流处理 + +```mermaid +flowchart TD +Start([组件初始化]) --> ParseProps["解析组件属性"] +ParseProps --> InitContext["初始化上下文"] +InitContext --> LoadItems["加载思考步骤数据"] +LoadItems --> RenderChain["渲染思考链"] +RenderChain --> HandleEvents["处理用户交互"] +HandleEvents --> UpdateState["更新组件状态"] +UpdateState --> ReRender["重新渲染"] +ReRender --> End([完成]) +LoadItems --> CheckSlots{"检查插槽内容"} +CheckSlots --> |有插槽| ProcessSlots["处理插槽内容"] +CheckSlots --> |无插槽| UseProps["使用属性值"] +ProcessSlots --> RenderChain +UseProps --> RenderChain +``` + +**图表来源** + +- [前端 ThoughtChain 实现:14-35](file://frontend/antdx/thought-chain/thought-chain.tsx#L14-L35) +- [前端 ThoughtChain 子项实现:12-27](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L12-L27) + +### 状态管理系统 + +组件支持四种核心状态，每种状态都有特定的视觉表现： + +```mermaid +stateDiagram-v2 +[*] --> 未开始 +未开始 --> 进行中 : 开始执行 +进行中 --> 已完成 : 执行成功 +进行中 --> 失败 : 执行异常 +进行中 --> 中止 : 用户中断 +已完成 --> [*] +失败 --> [*] +中止 --> [*] +note right of 未开始 : 显示等待状态 +note right of 进行中 : 显示加载动画 +note right of 已完成 : 显示成功图标 +note right of 失败 : 显示错误状态 +note right of 中止 : 显示中止提示 +``` + +**图表来源** + +- [ThoughtChain 子项组件定义:24-25](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L24-L25) +- [ThoughtChain 高级子项组件定义:29-30](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L29-L30) + +### 插槽系统架构 + +```mermaid +classDiagram +class ThoughtChainItem { ++description : string ++icon : string ++title : string ++status : Status ++variant : Variant ++blink : boolean ++slots : Description|Icon|Title +} +class ThoughtChainThoughtChainItem { ++content : string ++extra : string ++footer : string ++collapsible : boolean ++key : string ++slots : Content|Description|Footer|Icon|Title +} +class SlotProcessor { ++processDescription() : ReactNode ++processIcon() : ReactNode ++processTitle() : ReactNode ++renderSlots() : JSX.Element +} +ThoughtChainItem --> SlotProcessor : 使用 +ThoughtChainThoughtChainItem --> SlotProcessor : 使用 +SlotProcessor --> ReactSlot : 处理插槽 +``` + +**图表来源** + +- [ThoughtChain 子项组件定义:15-16](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L15-L16) +- [ThoughtChain 高级子项组件定义:15-16](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L15-L16) +- [前端 ThoughtChain 子项实现:18-26](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L18-L26) + +**章节来源** + +- [前端 ThoughtChain 实现:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [前端 ThoughtChain 子项实现:9-30](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L9-L30) +- [前端 ThoughtChain 高级子项实现:7-11](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L7-L11) + +## 依赖关系分析 + +### 组件依赖图 + +```mermaid +graph TB +subgraph "核心依赖" +A[@ant-design/x] --> B[ThoughtChain 核心] +A --> C[ThoughtChain.Item] +A --> D[ThoughtChain.ThoughtChainItem] +end +subgraph "工具依赖" +E[@svelte-preprocess-react] --> F[sveltify 转换] +E --> G[ReactSlot 插槽处理] +H[@utils/renderItems] --> I[项目渲染] +J[@utils/createItemsContext] --> K[上下文管理] +end +subgraph "Gradio 集成" +L[Gradio 事件系统] --> M[EventListener] +N[Gradio 组件系统] --> O[ModelScopeLayoutComponent] +end +B --> E +C --> E +D --> E +B --> L +C --> N +D --> N +E --> H +E --> J +``` + +**图表来源** + +- [前端 ThoughtChain 实现:1-7](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L7) +- [前端 ThoughtChain 子项实现:1-7](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L1-L7) +- [前端 ThoughtChain 高级子项实现:1-3](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L1-L3) +- [ThoughtChain 主组件定义:5-8](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L5-L8) + +### 版本兼容性 + +组件设计遵循以下兼容性原则： + +- 支持 Gradio 最新版本特性 +- 兼容 TypeScript 4.0+ 类型系统 +- 适配 React 17+ 和 Svelte 3+ 生态 +- 向后兼容 Ant Design X 0.x 版本 + +**章节来源** + +- [ThoughtChain 主组件定义:1-8](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L1-L8) +- [前端 ThoughtChain 实现:1-7](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L7) + +## 性能考虑 + +### 渲染优化策略 + +1. **懒加载机制**：使用 `sveltify` 实现按需加载 +2. **内存管理**：合理使用 `useMemo` 缓存计算结果 +3. **事件处理**：通过 `EventListener` 优化事件绑定 +4. **插槽渲染**：延迟渲染插槽内容以减少初始负载 + +### 最佳实践建议 + +- **数据预处理**：在传入组件前对数据进行必要的格式化 +- **状态最小化**：避免频繁的状态更新触发不必要的重渲染 +- **资源管理**：及时清理不再使用的组件实例 +- **错误边界**：利用 Gradio 的错误边界机制处理异常情况 + +## 故障排除指南 + +### 常见问题及解决方案 + +**问题 1：组件不显示** + +- 检查 `visible` 属性设置 +- 确认 `render` 属性为 `true` +- 验证父容器的 CSS 样式 + +**问题 2：状态显示异常** + +- 确认状态值在允许范围内 +- 检查 `blink` 属性是否正确配置 +- 验证样式类名的正确性 + +**问题 3：插槽内容不生效** + +- 确认插槽名称拼写正确 +- 检查插槽内容的类型匹配 +- 验证插槽的渲染时机 + +**章节来源** + +- [ThoughtChain 主组件定义:74-85](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L74-L85) +- [前端 ThoughtChain 子项实现:12-27](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L12-L27) + +## 结论 + +ThoughtChain 思考链组件为 AI 应用提供了强大的可视化思考过程展示能力。通过精心设计的架构和丰富的配置选项，该组件不仅提升了 AI 的透明度和可信度，还为用户提供了直观的交互体验。 + +**核心优势总结：** + +- **完整的思考过程可视化**：从简单到复杂的多层级展示 +- **灵活的配置选项**：满足不同场景下的使用需求 +- **良好的性能表现**：优化的渲染机制确保流畅体验 +- **完善的错误处理**：健壮的异常处理机制保障稳定性 +- **优秀的扩展性**：模块化的架构便于功能扩展和定制 + +该组件特别适用于需要展示 AI 决策过程的应用场景，如智能客服、数据分析、内容创作等领域，能够显著提升用户对 AI 行为的理解和信任度。 diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\347\241\256\350\256\244\347\273\204\344\273\266/ThoughtChainItem \346\200\235\350\200\203\351\241\271\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\347\241\256\350\256\244\347\273\204\344\273\266/ThoughtChainItem \346\200\235\350\200\203\351\241\271\347\273\204\344\273\266.md" new file mode 100644 index 00000000..199761f0 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\347\241\256\350\256\244\347\273\204\344\273\266/ThoughtChainItem \346\200\235\350\200\203\351\241\271\347\273\204\344\273\266.md" @@ -0,0 +1,410 @@ +# ThoughtChainItem 思考项组件 + + +**本文档引用的文件** +- [thought-chain.tsx](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [thought-chain.thought-chain-item.tsx](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx) +- [thought-chain.item.tsx](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx) +- [context.ts](file://frontend/antdx/thought-chain/context.ts) +- [createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [thought-chain.Index.svelte](file://frontend/antdx/thought-chain/Index.svelte) +- [thought-chain.thought-chain-item.Index.svelte](file://frontend/antdx/thought-chain/thought-chain-item/Index.svelte) +- [thought-chain.item.Index.svelte](file://frontend/antdx/thought-chain/item/Index.svelte) +- [thought_chain_item/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py) +- [thought_chain/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构概览](#架构概览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) + +## 简介 + +ThoughtChainItem 是 ModelScope Studio 中 ThoughtChain 思考链组件系统的核心子组件，用于在复杂的思考流程中表示和管理单个思考步骤。该组件提供了完整的状态管理、事件处理和视觉呈现能力，支持多种状态（待处理、进行中、已完成、失败等）的可视化展示。 + +该组件基于 Ant Design X 的 ThoughtChain 实现，通过自定义的 Items Context 系统实现了灵活的组件间通信和状态同步。组件支持插槽（slots）机制，允许开发者自定义标题、描述、图标等内容区域。 + +## 项目结构 + +ThoughtChainItem 组件系统采用分层架构设计，包含前端 React 组件、Svelte 包装器和后端 Python 组件三部分： + +```mermaid +graph TB +subgraph "前端架构" +A[ThoughtChain 主容器] --> B[ThoughtChainItem 子项] +B --> C[React 组件层] +C --> D[Svelte 包装器层] +end +subgraph "后端架构" +E[Python 组件层] --> F[前端目录映射] +F --> G[静态资源生成] +end +subgraph "状态管理" +H[Items Context] --> I[ItemHandler] +I --> J[状态同步] +end +A --> H +B --> I +``` + +**图表来源** + +- [thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [thought-chain.thought-chain-item.tsx:7-11](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L7-L11) +- [context.ts:1-6](file://frontend/antdx/thought-chain/context.ts#L1-L6) + +**章节来源** + +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [thought-chain.thought-chain-item.tsx:1-14](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L1-L14) +- [thought-chain.item.tsx:1-33](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L1-L33) + +## 核心组件 + +### ThoughtChain 主容器 + +ThoughtChain 组件是整个思考链系统的根容器，负责协调所有子项的渲染和状态管理： + +```mermaid +classDiagram +class ThoughtChain { ++items : Array ++children : ReactNode ++useMemo() items ++withItemsContextProvider() wrapper ++renderItems() processor +} +class ItemsContext { ++items : Object ++setItem() method ++initial : boolean ++onChange() callback +} +class ItemHandler { ++itemIndex : number ++itemSlotKey : string ++itemProps : function ++itemChildren : function ++slots : Object ++children : ReactNode +} +ThoughtChain --> ItemsContext : "uses" +ItemsContext --> ItemHandler : "provides" +ItemHandler --> ThoughtChain : "updates" +``` + +**图表来源** + +- [thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [context.ts:3-4](file://frontend/antdx/thought-chain/context.ts#L3-L4) +- [createItemsContext.tsx:102-170](file://frontend/utils/createItemsContext.tsx#L102-L170) + +### ThoughtChainItem 子项组件 + +ThoughtChainItem 提供了两种实现方式：直接 React 实现和基于 ItemHandler 的包装实现。 + +**章节来源** + +- [thought-chain.thought-chain-item.tsx:7-11](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L7-L11) +- [thought-chain.item.tsx:9-27](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L9-L27) + +## 架构概览 + +ThoughtChainItem 采用分层架构设计，确保组件间的松耦合和高内聚： + +```mermaid +sequenceDiagram +participant App as 应用程序 +participant Chain as ThoughtChain +participant Handler as ItemHandler +participant Item as ThoughtChainItem +participant XChain as Ant Design X +App->>Chain : 渲染思考链 +Chain->>Handler : 创建项目处理器 +Handler->>Item : 处理子项数据 +Item->>XChain : 渲染实际组件 +XChain-->>Item : 返回渲染结果 +Item-->>Handler : 更新状态 +Handler-->>Chain : 同步状态 +Chain-->>App : 完成渲染 +``` + +**图表来源** + +- [thought-chain.tsx:14-34](file://frontend/antdx/thought-chain/thought-chain.tsx#L14-L34) +- [createItemsContext.tsx:190-261](file://frontend/utils/createItemsContext.tsx#L190-L261) + +### 状态管理系统 + +组件的状态管理基于 React Context 和自定义的 Items Context 系统： + +```mermaid +flowchart TD +A[用户操作] --> B[状态变更] +B --> C[ItemHandler 处理] +C --> D[更新 Items Context] +D --> E[触发重新渲染] +E --> F[Ant Design X 渲染] +F --> G[视觉反馈] +H[异步操作] --> I[状态切换] +I --> J[加载指示器] +J --> K[完成状态] +L[错误处理] --> M[错误状态] +M --> N[重试机制] +``` + +**图表来源** + +- [createItemsContext.tsx:124-153](file://frontend/utils/createItemsContext.tsx#L124-L153) +- [createItemsContext.tsx:234-237](file://frontend/utils/createItemsContext.tsx#L234-L237) + +**章节来源** + +- [createItemsContext.tsx:97-274](file://frontend/utils/createItemsContext.tsx#L97-L274) + +## 详细组件分析 + +### ThoughtChainItem 属性配置 + +组件支持丰富的属性配置，满足不同的使用场景： + +| 属性名称 | 类型 | 必需 | 描述 | +| ------------ | ------------------------------------------ | ---- | -------------------- | +| title | ReactNode \| string | 否 | 思考项标题内容 | +| description | ReactNode \| string | 否 | 思考项描述内容 | +| icon | ReactNode | 否 | 自定义图标组件 | +| status | 'wait' \| 'process' \| 'finish' \| 'error' | 否 | 当前状态 | +| key | string \| number | 否 | 唯一键标识 | +| itemIndex | number | 是 | 在父容器中的索引位置 | +| itemSlotKey | string | 否 | 插槽键值 | +| itemProps | function | 否 | 动态属性计算函数 | +| itemChildren | function | 否 | 子项生成函数 | + +### 状态管理机制 + +组件支持四种核心状态，每种状态都有相应的视觉表现： + +```mermaid +stateDiagram-v2 +[*] --> 待处理 +待处理 --> 进行中 : 开始执行 +进行中 --> 已完成 : 执行成功 +进行中 --> 失败 : 执行异常 +已完成 --> [*] +失败 --> 待处理 : 重试 +失败 --> [*] : 放弃 +``` + +**图表来源** + +- [thought-chain.item.tsx:16-27](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L16-L27) + +### 事件处理机制 + +组件提供完整的事件处理能力： + +| 事件类型 | 回调函数 | 触发时机 | 参数 | +| ---------------- | -------- | -------- | -------------------- | +| onClick | function | 用户点击 | event, itemData | +| onStatusChange | function | 状态变更 | oldStatus, newStatus | +| onRenderComplete | function | 渲染完成 | itemData | +| onError | function | 发生错误 | error, itemData | + +**章节来源** + +- [thought-chain.thought-chain-item.tsx:7-11](file://frontend/antdx/thought-chain/thought-chain-item/thought-chain.thought-chain-item.tsx#L7-L11) +- [thought-chain.item.tsx:9-27](file://frontend/antdx/thought-chain/item/thought-chain.item.tsx#L9-L27) + +### 使用示例 + +#### 基本使用 + +```javascript +// 简单的思考项配置 +
额外内容
+
+思考链容器"] +B["AntdXThoughtChainItem
节点项简版"] +C["AntdXThoughtChainThoughtChainItem
节点项完整版"] +end +subgraph "前端包装层" +D["thought-chain.tsx
React 包装 + 插槽解析"] +E["context.ts
items 上下文"] +end +subgraph "文档示例" +F["basic.py
基础用法"] +G["item_status.py
状态切换演示"] +H["nested_use.py
嵌套使用"] +end +A --> D +B --> D +C --> D +D --> E +F --> A +G --> A +H --> A +``` + +**图表来源** + +- [AntdXThoughtChain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [AntdXThoughtChainItem/**init**.py:8-78](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L8-L78) +- [AntdXThoughtChainThoughtChainItem/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L8-L81) +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [context.ts:1-7](file://frontend/antdx/thought-chain/context.ts#L1-L7) +- [basic.py:24-77](file://docs/components/antdx/thought_chain/demos/basic.py#L24-L77) +- [item_status.py:36-71](file://docs/components/antdx/thought_chain/demos/item_status.py#L36-L71) +- [nested_use.py:6-68](file://docs/components/antdx/thought_chain/demos/nested_use.py#L6-L68) + +**章节来源** + +- [AntdXThoughtChain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) + +## 核心组件 + +- 容器组件：AntdXThoughtChain + - 职责：作为思考链的根容器，负责接收节点列表、展开键、线条样式、前缀类名等配置；通过事件绑定实现展开状态变更通知 + - 关键能力：支持插槽 items；事件 expand；可配置默认展开键与当前展开键 +- 节点项组件（简版）：AntdXThoughtChainItem + - 职责：承载单个节点的基本信息与外观，支持标题、描述、图标、状态、变体与闪烁效果 + - 关键能力：支持 description、icon、title 插槽；状态枚举（pending/success/error/abort） +- 节点项组件（完整版）：AntdXThoughtChainThoughtChainItem + - 职责：承载更丰富的节点内容，支持 content、description、footer、icon、title 插槽，以及 key、collapsible、status 等属性 + - 关键能力：支持折叠/展开、状态切换、额外操作区 + +**章节来源** + +- [AntdXThoughtChain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [AntdXThoughtChainItem/**init**.py:8-78](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L8-L78) +- [AntdXThoughtChainThoughtChainItem/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L8-L81) + +## 架构总览 + +前端包装层将后端组件映射为 React 组件，统一解析插槽并传递给 @ant-design/x 的 ThoughtChain 实现，同时通过上下文机制收集 items 插槽内容。 + +```mermaid +sequenceDiagram +participant Py as "Python 后端组件" +participant Wrap as "React 包装 thought-chain.tsx" +participant Ctx as "items 上下文 context.ts" +participant X as "@ant-design/x ThoughtChain" +Py->>Wrap : 渲染 ThoughtChain 容器 +Wrap->>Ctx : 读取 items/default 插槽 +Ctx-->>Wrap : 返回 items 列表 +Wrap->>X : 传入 props 与解析后的 items +X-->>Wrap : 渲染节点树 +Wrap-->>Py : 输出最终 UI +``` + +**图表来源** + +- [thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [context.ts:1-7](file://frontend/antdx/thought-chain/context.ts#L1-L7) + +## 详细组件分析 + +### 容器组件：AntdXThoughtChain + +- 主要职责 + - 接收 items 列表与展开键配置，决定初始展开状态 + - 支持事件 expand，用于监听展开键变化 + - 提供插槽 items，便于以声明式方式组织节点 +- 关键属性 + - expanded_keys / default_expanded_keys：当前展开键与默认展开键 + - items：节点数据数组 + - line：连线样式（布尔或线型枚举） + - prefix_cls：前缀类名 + - styles / class_names / root_class_name：样式与类名定制 +- 事件 + - expand：展开键变更时触发 +- 生命周期 + - preprocess/postprocess/example\_\* 均返回空值，表明该组件不参与数据序列化 + +```mermaid +classDiagram +class AntdXThoughtChain { ++expanded_keys ++default_expanded_keys ++items ++line ++prefix_cls ++styles ++class_names ++root_class_name ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +``` + +**图表来源** + +- [AntdXThoughtChain/**init**.py:30-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L30-L86) + +**章节来源** + +- [AntdXThoughtChain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) + +### 节点项组件（简版）：AntdXThoughtChainItem + +- 主要职责 + - 表达单个思考节点的标题、描述、图标与状态 + - 支持多种外观变体与闪烁效果 +- 关键属性 + - description / icon / title：节点基本信息 + - status：节点状态（pending/success/error/abort） + - variant：外观变体（solid/outlined/text） + - blink：是否闪烁 + - 插槽：description、icon、title +- 生命周期 + - 与容器组件一致，不参与数据序列化 + +```mermaid +classDiagram +class AntdXThoughtChainItem { ++description ++icon ++title ++status ++variant ++blink ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +``` + +**图表来源** + +- [AntdXThoughtChainItem/**init**.py:18-78](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L18-L78) + +**章节来源** + +- [AntdXThoughtChainItem/**init**.py:8-78](file://backend/modelscope_studio/components/antdx/thought_chain/item/__init__.py#L8-L78) + +### 节点项组件（完整版）：AntdXThoughtChainThoughtChainItem + +- 主要职责 + - 承载更丰富的节点内容，支持 content、footer、extra 等插槽 + - 支持 key、collapsible、status 等属性，便于复杂交互与状态管理 +- 关键属性 + - content / description / footer / icon / title：内容与装饰 + - key：节点唯一标识 + - collapsible：是否可折叠 + - status：节点状态 + - 插槽：content、description、footer、icon、title +- 生命周期 + - 与容器组件一致，不参与数据序列化 + +```mermaid +classDiagram +class AntdXThoughtChainThoughtChainItem { ++content ++description ++extra ++footer ++icon ++title ++status ++key ++collapsible ++blink ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +``` + +**图表来源** + +- [AntdXThoughtChainThoughtChainItem/**init**.py:18-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L18-L81) + +**章节来源** + +- [AntdXThoughtChainThoughtChainItem/**init**.py:8-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L8-L81) + +### 前端包装与插槽解析 + +- thought-chain.tsx + - 将 @ant-design/x 的 ThoughtChain 以 sveltify 方式包装 + - 使用 withItemsContextProvider 与 useItems 解析 items/default 插槽 + - 通过 renderItems 将插槽内容转换为 props.items +- context.ts + - 提供 items 上下文，支持嵌套场景下的插槽收集 + +```mermaid +flowchart TD +Start(["渲染入口"]) --> ReadSlots["读取 items/default 插槽"] +ReadSlots --> Resolve["调用 renderItems 解析节点"] +Resolve --> RenderX["渲染 @ant-design/x ThoughtChain"] +RenderX --> End(["完成"]) +``` + +**图表来源** + +- [thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [context.ts:1-7](file://frontend/antdx/thought-chain/context.ts#L1-L7) + +**章节来源** + +- [thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [context.ts:1-7](file://frontend/antdx/thought-chain/context.ts#L1-L7) + +### 使用示例与场景 + +#### 基础用法与可折叠行为 + +- 示例要点 + - 在 XProvider 下创建 ThoughtChain 容器 + - 使用 Switch 控制 collapsible 属性，动态切换节点可折叠性 + - 通过 Slot 注入 extra/content/footer，实现丰富节点内容 +- 适用场景 + - 展示多步骤任务的执行流程与当前状态 + - 提供节点级操作按钮与补充信息 + +**章节来源** + +- [basic.py:24-77](file://docs/components/antdx/thought_chain/demos/basic.py#L24-L77) + +#### 节点状态切换（成功/错误/进行中） + +- 示例要点 + - 使用 Each 动态生成节点列表 + - 通过按钮点击逐步更新节点状态与图标，模拟真实运行状态 + - 支持 pending/error/success 三种状态的视觉反馈 +- 适用场景 + - 展示 AI 推理过程中的阶段性结果 + - 增强用户对执行进度与结果的信心 + +**章节来源** + +- [item_status.py:36-71](file://docs/components/antdx/thought_chain/demos/item_status.py#L36-L71) + +#### 嵌套使用（子思考链） + +- 示例要点 + - 在父级 ThoughtChain 的节点内容中嵌套另一个 ThoughtChain + - 子级节点同样支持 extra/content/footer 等插槽 +- 适用场景 + - 复杂任务拆分为多个子任务，逐层细化 + - 展示层级化的决策或推理链条 + +**章节来源** + +- [nested_use.py:6-68](file://docs/components/antdx/thought_chain/demos/nested_use.py#L6-L68) + +## 依赖分析 + +- 组件耦合 + - 容器与节点项均继承自 ModelScopeLayoutComponent，共享统一的生命周期与属性体系 + - 前端包装层仅负责插槽解析与属性透传，不引入业务逻辑 +- 外部依赖 + - @ant-design/x 的 ThoughtChain 提供实际渲染能力 + - Gradio 事件系统用于 expand 事件绑定 +- 潜在风险 + - 插槽名称与顺序需严格匹配，否则渲染异常 + - items 列表为空时，应确保 fallback 到 default 插槽 + +```mermaid +graph LR +Py["Python 组件"] --> Wrap["React 包装层"] +Wrap --> X["@ant-design/x ThoughtChain"] +Wrap --> Ctx["items 上下文"] +Py --> Gradio["Gradio 事件系统"] +``` + +**图表来源** + +- [AntdXThoughtChain/**init**.py:20-25](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L20-L25) +- [thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) + +**章节来源** + +- [AntdXThoughtChain/**init**.py:20-25](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L20-L25) +- [thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) + +## 性能考虑 + +- 渲染优化 + - 使用 useMemo 缓存 items 计算结果，避免不必要的重渲染 + - 通过插槽懒加载与条件渲染减少 DOM 数量 +- 数据流 + - items 列表建议保持稳定引用，配合 key 字段提升 diff 效率 +- 交互体验 + - 对于大量节点的场景，优先使用可折叠与分步加载策略 + +## 故障排查指南 + +- 症状：节点未显示或显示为空 + - 检查 items 是否正确传入或 default 插槽是否填充 + - 确认插槽名称大小写与文档一致 +- 症状：expand 事件无效 + - 确认事件绑定是否启用（bind_expand_event） + - 检查容器是否处于可交互状态 +- 症状：嵌套 ThoughtChain 不生效 + - 确保父级节点的 content 插槽内正确嵌套子级 ThoughtChain + - 检查子级 ThoughtChain 的插槽是否正确声明 + +## 结论 + +Ant Design X 的 ThoughtChain 组件通过“容器 + 节点项”的分层设计，结合前端插槽解析与 @ant-design/x 的渲染能力，实现了对 AI 思考过程的结构化记录与可视化展示。其状态驱动的节点外观、灵活的插槽扩展与可折叠交互，能够有效提升用户对复杂推理流程的理解与信任。配合文档示例，开发者可以快速搭建从基础流程到嵌套子链的多种应用场景。 + +## 附录 + +### API 速查表 + +- 容器组件 AntdXThoughtChain + - 属性：expanded_keys、default_expanded_keys、items、line、prefix_cls、styles、class_names、root_class_name + - 事件：expand + - 插槽：items +- 节点项组件（简版）AntdXThoughtChainItem + - 属性：description、icon、title、status、variant、blink + - 插槽：description、icon、title +- 节点项组件（完整版）AntdXThoughtChainThoughtChainItem + - 属性：content、description、extra、footer、icon、title、status、key、collapsible、blink + - 插槽：content、description、footer、icon、title + +### 使用建议 + +- 透明度与可信度 + - 通过清晰的状态与图标提示，帮助用户理解每一步的执行结果 + - 对关键决策点提供额外说明与可操作入口，增强可控感 +- 可访问性 + - 为图标与状态提供可读性替代文本 + - 保证键盘可访问与屏幕阅读器友好 diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\347\273\204\344\273\266\346\246\202\350\247\210.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\347\273\204\344\273\266\346\246\202\350\247\210.md" new file mode 100644 index 00000000..330997fc --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\347\273\204\344\273\266\346\246\202\350\247\210.md" @@ -0,0 +1,368 @@ +# 组件概览 + + +**本文引用的文件** +- [README-zh_CN.md](file://README-zh_CN.md) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/pro/__init__.py](file://backend/modelscope_studio/components/pro/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [frontend/antdx/package.json](file://frontend/antdx/package.json) +- [frontend/base/package.json](file://frontend/base/package.json) +- [frontend/pro/package.json](file://frontend/pro/package.json) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [frontend/pro/chatbot/chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Ant Design X 组件库是面向机器学习与大模型应用场景的增强型 UI 组件体系，基于 Gradio 构建，提供更灵活的布局能力、更丰富的交互形态以及针对对话、可视化、多模态输入等 AI 场景的专用组件。其核心目标是在保持易用性的同时，显著提升 AI 应用的用户体验与开发效率。 + +- 设计理念 + - 以“可组合、可扩展、可定制”为核心，覆盖从基础控件到专业场景组件的全栈能力。 + - 面向 AI 应用的交互范式（如对话气泡、思维链、提示词工程、文件卡片、思维导图等）进行深度优化。 + - 与 Ant Design 和 Ant Design X 生态无缝衔接，复用成熟的设计语言与交互规范。 + +- 价值定位 + - 提升 AI 应用界面的专业度与一致性，降低从原型到上线的成本。 + - 通过专用组件（如聊天气泡、思维链、代码高亮、Mermaid 图表等）直接解决典型业务痛点。 + - 与 Gradio 生态兼容，既可独立使用，也可与传统组件混合搭配。 + +**章节来源** + +- [README-zh_CN.md:17-32](file://README-zh_CN.md#L17-L32) + +## 项目结构 + +该项目采用前后端分离的多包组织方式，后端 Python 包负责组件导出与生态桥接，前端以 Svelte/React 混编方式封装 Ant Design/Ant Design X 组件，并通过统一的 sveltify 工具适配为 Gradio 可用的组件。 + +```mermaid +graph TB +subgraph "后端 Python 包" +A_init["components/__init__.py"] +A_antd["antd/__init__.py"] +A_antdx["antdx/__init__.py"] +A_pro["pro/__init__.py"] +A_base["base/__init__.py"] +end +subgraph "前端 NPM 包" +F_antd["@modelscope-studio/antd
版本: 2.0.0"] +F_antdx["@modelscope-studio/antdx
版本: 2.0.0"] +F_pro["@modelscope-studio/pro
版本: 2.0.0"] +F_base["@modelscope-studio/base
版本: 2.0.0"] +end +A_init --> A_antd +A_init --> A_antdx +A_init --> A_pro +A_init --> A_base +A_antd --> F_antd +A_antdx --> F_antdx +A_pro --> F_pro +A_base --> F_base +``` + +**图表来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) +- [frontend/base/package.json:1-6](file://frontend/base/package.json#L1-L6) + +**章节来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) +- [frontend/base/package.json:1-6](file://frontend/base/package.json#L1-L6) + +## 核心组件 + +- 基础层（Base） + - 提供通用容器、文本、插槽、循环、过滤等基础能力，支撑复杂布局与条件渲染。 + - 典型组件：Application、AutoLoading、Div、Each、Filter、Fragment、Markdown、Slot、Span、Text。 + +- Ant Design（Antd） + - 覆盖 Ant Design 的完整组件族，包括按钮、表单、布局、导航、反馈、展示、编辑器等。 + - 支持嵌套子组件（如 Button.Group、Form.Item、Tree.TreeNode 等），便于构建复杂表单与树形结构。 + +- Ant Design X（AntdX） + - 专为 AI 场景打造的高级组件，如对话气泡、思维链、提示词、文件卡片、Mermaid 图等。 + - 强调内容可编辑、可渲染、可交互，适合 LLM 应用的动态内容呈现与编辑。 + +- Pro（Pro） + - 面向专业场景的一体化组件集合，如 Chatbot、Monaco Editor、Multimodal Input、Web Sandbox。 + - 将多个子组件与上下文整合，提供开箱即用的 AI 应用骨架。 + +**章节来源** + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) + +## 架构总览 + +整体架构由“后端组件导出 + 前端适配层 + 生态集成”三部分组成。后端通过 Python 包聚合各子模块并统一导出；前端以 Svelte/React 混编方式封装原生组件，并通过 sveltify 将 React 组件桥接到 Svelte/Gradio 环境；同时提供工具函数与上下文，实现插槽、渲染函数、事件回调等高级能力。 + +```mermaid +graph TB +subgraph "后端" +Py_API["Python 导出 API
components/__init__.py"] +Py_antd["Antd 组件导出"] +Py_antdx["AntdX 组件导出"] +Py_pro["Pro 组件导出"] +Py_base["Base 组件导出"] +end +subgraph "前端" +FE_antd["antd/button.tsx
sveltify 适配"] +FE_antdx["antdx/bubble/bubble.tsx
插槽/渲染函数"] +FE_pro["pro/chatbot/chatbot.tsx
上下文+状态管理"] +end +subgraph "生态" +AD["Ant Design"] +ADX["Ant Design X"] +GR["Gradio"] +end +Py_API --> Py_antd +Py_API --> Py_antdx +Py_API --> Py_pro +Py_API --> Py_base +Py_antd --> FE_antd +Py_antdx --> FE_antdx +Py_pro --> FE_pro +FE_antd --> AD +FE_antdx --> ADX +FE_pro --> ADX +FE_antd --> GR +FE_antdx --> GR +FE_pro --> GR +``` + +**图表来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) + +## 详细组件分析 + +### Antd Button 组件（基础控件） + +- 设计要点 + - 使用 sveltify 将 Ant Design 的 Button 适配为 Svelte/Gradio 组件。 + - 支持插槽（如 icon、loading.icon）与值绑定（value），自动处理 children 与受控值的优先级。 + - 对 loading 的延迟配置进行兼容处理，确保与 slots 的组合使用。 + +```mermaid +flowchart TD +Start(["进入 Button 渲染"]) --> ParseSlots["解析插槽与属性"] +ParseSlots --> HasIcon{"存在 icon 插槽？"} +HasIcon --> |是| RenderIcon["使用 ReactSlot 渲染 icon 插槽"] +HasIcon --> |否| UsePropIcon["使用属性 icon"] +RenderIcon --> HasLoadingIcon{"存在 loading.icon 插槽？"} +UsePropIcon --> HasLoadingIcon +HasLoadingIcon --> |是| RenderLoadingIcon["使用 ReactSlot 渲染 loading.icon 插槽
并保留 delay 配置"] +HasLoadingIcon --> |否| UsePropLoading["使用属性 loading"] +RenderLoadingIcon --> RenderButton["渲染 Ant Design Button"] +UsePropLoading --> RenderButton +RenderButton --> End(["完成"]) +``` + +**图表来源** + +- [frontend/antd/button/button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) + +**章节来源** + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) + +### AntdX Bubble 组件（AI 场景） + +- 设计要点 + - 基于 Ant Design X 的 Bubble，提供头像、内容、底部、额外区域、加载渲染、内容渲染等多插槽。 + - 支持 editable 的 okText/cancelText 插槽与布尔开关，typing、header/footer/avatar/extra 等函数式配置。 + - 通过 useFunction 与 renderParamsSlot 将插槽转换为可执行函数，增强可编程性。 + +```mermaid +sequenceDiagram +participant C as "调用方" +participant B as "Bubble 组件" +participant R as "ReactSlot/renderParamsSlot" +participant F as "useFunction" +C->>B : 传入 props 与 slots +B->>F : 解析 header/footer/avatar/extra/typing/editable +F-->>B : 返回可执行函数或默认值 +B->>R : 若存在 content/header/footer/avatar/loadingRender/contentRender 插槽 +R-->>B : 渲染插槽内容 +B-->>C : 渲染最终 Bubble +``` + +**图表来源** + +- [frontend/antdx/bubble/bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) + +**章节来源** + +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) + +### Pro Chatbot 组件（对话场景） + +- 设计要点 + - 基于 Ant Design X 的 Bubble.List，结合自定义上下文与 hooks 实现滚动、编辑、复制、点赞、重试、欢迎语等能力。 + - 通过 useRole 将不同角色（用户、助手、内部欢迎）映射为对应的气泡样式与行为。 + - 内置 Markdown 渲染、主题模式、根路径传递等配置，满足多模态内容展示需求。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant CB as "Chatbot" +participant BL as "Bubble.List" +participant CTX as "角色上下文" +participant H as "hooks(滚动/编辑)" +U->>CB : 输入消息/操作 +CB->>CTX : 解析消息角色与配置 +CTX-->>CB : 返回对应气泡配置 +CB->>H : 触发滚动/编辑状态更新 +H-->>CB : 更新状态 +CB->>BL : 渲染消息列表 +BL-->>U : 展示对话气泡 +``` + +**图表来源** + +- [frontend/pro/chatbot/chatbot.tsx:76-472](file://frontend/pro/chatbot/chatbot.tsx#L76-L472) + +**章节来源** + +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) + +## 依赖关系分析 + +- 版本与命名空间 + - 所有前端包均使用统一的版本号（2.0.0），命名空间为 @modelscope-studio，便于发布与管理。 +- 组件导出与分组 + - 后端按功能域导出：antd、antdx、pro、base，分别对应 Ant Design 组件族、AI 专用组件、专业场景组件、基础能力。 +- 前后端映射 + - 每个后端导出模块对应一个前端包，形成稳定的映射关系，保证组件名与生态一致。 + +```mermaid +graph LR +Py_antd["后端 antd 导出"] --> FE_antd["前端 @modelscope-studio/antd"] +Py_antdx["后端 antdx 导出"] --> FE_antdx["前端 @modelscope-studio/antdx"] +Py_pro["后端 pro 导出"] --> FE_pro["前端 @modelscope-studio/pro"] +Py_base["后端 base 导出"] --> FE_base["前端 @modelscope-studio/base"] +``` + +**图表来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) +- [frontend/base/package.json:1-6](file://frontend/base/package.json#L1-L6) + +**章节来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) + +## 性能考虑 + +- 渲染与插槽 + - 通过插槽与渲染函数的组合，避免不必要的重复渲染；仅在插槽存在时才进行参数化渲染。 +- 状态与计算 + - 使用 useMemo 与 useMemoizedFn 缓存配置与回调，减少无效重渲染与对象创建。 +- 滚动与交互 + - 对滚动、编辑、点赞等高频交互使用局部状态与节流策略，保证流畅体验。 + +[本节为通用指导，无需特定文件引用] + +## 故障排查指南 + +- 页面未正确显示（Hugging Face Space） + - 在 demo.launch() 中添加 ssr_mode=False 参数，避免服务端渲染导致的显示问题。 +- 组件导入失败 + - 确认已安装 modelscope_studio 并正确引入 modelscope_studio.components.\* 命名空间。 +- 版本不匹配 + - 检查后端与前端包版本是否一致，避免因版本差异导致的运行时错误。 + +**章节来源** + +- [README-zh_CN.md:32-32](file://README-zh_CN.md#L32-L32) +- [README-zh_CN.md:38-42](file://README-zh_CN.md#L38-L42) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) + +## 结论 + +Ant Design X 组件库通过“基础控件 + AI 专用组件 + 专业场景组件”的三层架构，系统性提升了机器学习与大模型应用的界面表达力与交互效率。其以 Gradio 为入口、以 Ant Design/Ant Design X 为基石、以前端适配层为桥梁，形成了稳定、可扩展、易维护的组件体系。开发者可借助该库快速搭建高质量的 AI 应用界面，并在对话、可视化、多模态输入等场景中获得一致而专业的用户体验。 + +[本节为总结性内容，无需特定文件引用] + +## 附录 + +### 快速开始 + +- 安装 + - 使用 pip 安装 modelscope_studio。 +- 示例 + - 在 Blocks 中引入 modelscope_studio 的 Application、ConfigProvider、AutoLoading，并使用 antd 组件进行布局与交互。 + +**章节来源** + +- [README-zh_CN.md:38-57](file://README-zh_CN.md#L38-L57) + +### 组件分类与使用场景 + +- 基础层（Base） + - 场景：通用布局、条件渲染、文本与插槽管理。 + - 典型：Application、AutoLoading、Markdown、Slot、Text、Span、Div、Each、Filter、Fragment。 +- Ant Design（Antd） + - 场景：表单、导航、反馈、展示、布局等通用 UI。 + - 典型：Button、Form、Layout、Menu、Modal、Table、Tabs、Tree、Upload 等。 +- Ant Design X（AntdX） + - 场景：对话气泡、思维链、提示词、文件卡片、Mermaid 图等 AI 专属交互。 + - 典型：Bubble、Conversations、Sender、ThoughtChain、Prompts、Attachments、Mermaid、Notification、Welcome、XProvider。 +- Pro（Pro） + - 场景：一体化 AI 应用骨架，如聊天机器人、代码编辑器、多模态输入、Web 沙盒。 + - 典型：Chatbot、MonacoEditor、MultimodalInput、WebSandbox。 + +**章节来源** + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\350\241\250\350\276\276\347\273\204\344\273\266/Attachments \351\231\204\344\273\266\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\350\241\250\350\276\276\347\273\204\344\273\266/Attachments \351\231\204\344\273\266\347\273\204\344\273\266.md" new file mode 100644 index 00000000..9268c98c --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\350\241\250\350\276\276\347\273\204\344\273\266/Attachments \351\231\204\344\273\266\347\273\204\344\273\266.md" @@ -0,0 +1,731 @@ +# 附件组件（Attachments）文档 + + +**本文档引用的文件** +- [Index.svelte](file://frontend/antdx/attachments/Index.svelte) +- [attachments.tsx](file://frontend/antdx/attachments/attachments.tsx) +- [__init__.py](file://backend/modelscope_studio/components/antdx/attachments/__init__.py) +- [README-zh_CN.md](file://docs/components/antdx/attachments/README-zh_CN.md) +- [basic.py](file://docs/components/antdx/attachments/demos/basic.py) +- [combination.py](file://docs/components/antdx/attachments/demos/combination.py) +- [file_card.py](file://docs/components/antdx/attachments/demos/file_card.py) +- [multimodal-input.tsx](file://frontend/pro/multimodal-input/multimodal-input.tsx) +- [upload.ts](file://frontend/utils/upload.ts) +- [file-card.tsx](file://frontend/antdx/file-card/file-card.tsx) +- [base.tsx](file://frontend/antdx/file-card/base.tsx) +- [app.py](file://docs/components/antdx/attachments/app.py) +- [package.json](file://frontend/antdx/attachments/package.json) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构概览](#架构概览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Attachments 附件组件是 ModelScope Studio 提供的一个强大文件管理和上传解决方案。该组件基于 Ant Design X 的 Attachments 组件构建，提供了完整的文件上传、预览、管理和删除功能。 + +### 主要特性 + +- **多格式支持**：支持图片、文档、音频、视频等多种文件类型的上传和预览 +- **拖拽上传**：提供直观的拖拽式文件上传体验 +- **批量管理**：支持多文件同时上传和管理 +- **实时预览**：内置文件预览功能，支持缩略图和完整内容查看 +- **灵活配置**：丰富的配置选项和自定义能力 +- **响应式设计**：适配各种屏幕尺寸和设备 + +## 项目结构 + +Attachments 组件采用前后端分离的架构设计，主要由以下部分组成： + +```mermaid +graph TB +subgraph "前端层" +A[Index.svelte
组件入口] +B[attachments.tsx
核心实现] +C[file-card.tsx
文件卡片组件] +D[base.tsx
基础文件卡片] +E[multimodal-input.tsx
多模态输入集成] +end +subgraph "后端层" +F[__init__.py
Python组件封装] +end +subgraph "工具层" +G[upload.ts
文件URL处理] +H[package.json
包配置] +end +A --> B +B --> C +C --> D +B --> G +F --> A +E --> B +``` + +**图表来源** + +- [Index.svelte:1-98](file://frontend/antdx/attachments/Index.svelte#L1-L98) +- [attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [**init**.py:21-64](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L21-L64) + +**章节来源** + +- [Index.svelte:1-98](file://frontend/antdx/attachments/Index.svelte#L1-L98) +- [attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [**init**.py:21-64](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L21-L64) + +## 核心组件 + +### 组件架构 + +Attachments 组件采用分层架构设计，确保了良好的可维护性和扩展性： + +```mermaid +classDiagram +class Attachments { ++FileData[] items ++upload(files) Promise~FileData[]~ ++onValueChange(value) void ++onChange(value) void ++disabled boolean ++maxCount number ++imageProps ImageProps ++placeholder Function|Object ++showUploadList Object|boolean ++beforeUpload Function ++customRequest Function ++previewFile Function ++isImageUrl Function ++itemRender Function ++iconRender Function ++data Object|Function ++getDropContainer Function +} +class FileCard { ++BaseFileCardProps props ++imageProps ImageProps ++description ReactNode ++icon ReactNode ++mask ReactNode ++spinProps SpinProps ++children ReactNode +} +class BaseFileCard { ++string|FileData src ++string rootUrl ++string apiPrefix ++resolveFileSrc() string +} +class UploadUtils { ++getFetchableUrl() string ++getFileUrl() string|undefined ++isUrl() boolean +} +Attachments --> FileCard : "渲染" +FileCard --> BaseFileCard : "继承" +Attachments --> UploadUtils : "使用" +``` + +**图表来源** + +- [attachments.tsx:36-83](file://frontend/antdx/attachments/attachments.tsx#L36-L83) +- [file-card.tsx:17-34](file://frontend/antdx/file-card/file-card.tsx#L17-L34) +- [base.tsx:9-13](file://frontend/antdx/file-card/base.tsx#L9-L13) +- [upload.ts:12-44](file://frontend/utils/upload.ts#L12-L44) + +### 数据流处理 + +组件内部实现了复杂的数据流处理机制： + +```mermaid +sequenceDiagram +participant U as 用户 +participant A as Attachments组件 +participant P as 预览系统 +participant S as 服务器 +participant V as 验证器 +U->>A : 选择/拖拽文件 +A->>V : 调用beforeUpload验证 +V-->>A : 验证结果 +A->>A : 更新临时文件列表 +A->>S : 调用upload函数上传 +S-->>A : 返回FileData数组 +A->>A : 合并文件列表 +A->>P : 渲染预览 +P-->>U : 显示文件预览 +U->>A : 删除文件 +A->>S : 发送删除请求 +S-->>A : 确认删除 +A->>A : 更新状态 +``` + +**图表来源** + +- [attachments.tsx:275-354](file://frontend/antdx/attachments/attachments.tsx#L275-L354) + +**章节来源** + +- [attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [file-card.tsx:1-127](file://frontend/antdx/file-card/file-card.tsx#L1-L127) +- [base.tsx:1-44](file://frontend/antdx/file-card/base.tsx#L1-L44) + +## 架构概览 + +### 整体架构设计 + +Attachments 组件采用了现代化的前端架构模式，结合了 React 和 Svelte 的优势： + +```mermaid +graph TD +subgraph "用户界面层" +UI[用户界面] +SL[Svelte组件] +RC[React组件] +end +subgraph "业务逻辑层" +AM[附件管理器] +VM[视图模型] +CM[配置管理器] +end +subgraph "数据访问层" +FS[文件系统] +CS[云端存储] +LS[本地存储] +end +subgraph "工具服务层" +PU[预览服务] +US[上传服务] +VS[验证服务] +end +UI --> SL +SL --> RC +RC --> AM +AM --> VM +AM --> CM +AM --> FS +AM --> CS +AM --> LS +AM --> PU +AM --> US +AM --> VS +``` + +**图表来源** + +- [Index.svelte:1-98](file://frontend/antdx/attachments/Index.svelte#L1-L98) +- [attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) + +### 组件生命周期 + +```mermaid +stateDiagram-v2 +[*] --> 初始化 +初始化 --> 加载配置 +加载配置 --> 渲染界面 +渲染界面 --> 等待交互 +等待交互 --> 文件上传 +文件上传 --> 验证文件 +验证文件 --> 上传中 +上传中 --> 上传完成 +上传完成 --> 渲染预览 +渲染预览 --> 等待交互 +等待交互 --> 文件删除 +文件删除 --> 删除确认 +删除确认 --> 更新状态 +更新状态 --> 等待交互 +等待交互 --> 错误处理 +错误处理 --> 等待交互 +等待交互 --> [*] +``` + +**图表来源** + +- [attachments.tsx:132-354](file://frontend/antdx/attachments/attachments.tsx#L132-L354) + +## 详细组件分析 + +### 核心功能实现 + +#### 文件上传机制 + +组件实现了完整的文件上传流程，支持多种上传策略： + +```mermaid +flowchart TD +Start([开始上传]) --> Validate[验证文件] +Validate --> Valid{验证通过?} +Valid --> |否| Error[返回错误] +Valid --> |是| Prepare[准备上传] +Prepare --> Upload[执行上传] +Upload --> Progress[更新进度] +Progress --> Complete{上传完成?} +Complete --> |否| Progress +Complete --> |是| Process[处理响应] +Process --> Success[上传成功] +Success --> End([结束]) +Error --> End +``` + +**图表来源** + +- [attachments.tsx:292-354](file://frontend/antdx/attachments/attachments.tsx#L292-L354) + +#### 文件预览系统 + +组件集成了强大的文件预览功能，支持多种文件类型的可视化展示： + +| 文件类型 | 预览支持 | 特殊功能 | +| -------- | ------------- | ------------------ | +| 图片 | ✅ 完整预览 | 缩放、旋转、下载 | +| 文档 | ✅ 缩略图预览 | 在线查看、下载 | +| PDF | ✅ 分页预览 | 导航、搜索 | +| 音频 | ✅ 播放器 | 播放控制、音量调节 | +| 视频 | ✅ 播放器 | 播放控制、全屏 | +| 压缩包 | ✅ 缩略图 | 解压预览 | + +#### 批量管理功能 + +组件提供了高效的批量文件管理能力： + +```mermaid +graph LR +subgraph "批量操作" +BA[批量选择] +BM[批量删除] +BC[批量下载] +BR[批量重命名] +end +subgraph "状态管理" +FS[文件状态] +SS[选择状态] +PS[处理状态] +end +BA --> SS +BM --> FS +BC --> FS +BR --> FS +SS --> PS +FS --> PS +``` + +**图表来源** + +- [attachments.tsx:304-342](file://frontend/antdx/attachments/attachments.tsx#L304-L342) + +**章节来源** + +- [attachments.tsx:275-409](file://frontend/antdx/attachments/attachments.tsx#L275-L409) + +### 配置选项详解 + +#### 基础配置 + +| 配置项 | 类型 | 默认值 | 描述 | +| ---------------- | ----------------- | -------- | ------------------ | +| `disabled` | boolean | false | 是否禁用上传功能 | +| `maxCount` | number | Infinity | 最大文件数量限制 | +| `multiple` | boolean | true | 是否支持多文件上传 | +| `accept` | string | \* | 接受的文件类型 | +| `showUploadList` | boolean \| object | true | 是否显示上传列表 | + +#### 高级配置 + +| 配置项 | 类型 | 默认值 | 描述 | +| --------------- | -------- | ------ | ----------------- | +| `beforeUpload` | Function | - | 上传前的验证函数 | +| `customRequest` | Function | - | 自定义上传请求 | +| `previewFile` | Function | - | 自定义文件预览 | +| `isImageUrl` | Function | - | 判断是否为图片URL | +| `itemRender` | Function | - | 自定义文件项渲染 | +| `iconRender` | Function | - | 自定义图标渲染 | + +#### 预览配置 + +| 配置项 | 类型 | 默认值 | 描述 | +| ---------------------------------- | --------- | ------ | ---------------- | +| `imageProps.preview.mask` | ReactNode | - | 预览遮罩层 | +| `imageProps.preview.closeIcon` | ReactNode | - | 关闭按钮图标 | +| `imageProps.preview.toolbarRender` | Function | - | 工具栏自定义渲染 | +| `imageProps.preview.imageRender` | Function | - | 图片自定义渲染 | + +**章节来源** + +- [attachments.tsx:36-83](file://frontend/antdx/attachments/attachments.tsx#L36-L83) + +### 事件回调机制 + +组件提供了丰富的事件回调接口： + +```mermaid +sequenceDiagram +participant C as 调用者 +participant A as Attachments组件 +participant H as 回调处理器 +C->>A : 绑定事件监听 +A->>H : 注册回调函数 +Note over A,H : 用户交互触发事件 +A->>H : 触发onChange事件 +H-->>A : 返回处理结果 +A->>H : 触发onRemove事件 +H-->>A : 返回处理结果 +A->>H : 触发onValueChange事件 +H-->>A : 返回处理结果 +``` + +**图表来源** + +- [**init**.py:27-43](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L27-L43) + +#### 事件类型 + +| 事件名称 | 触发时机 | 参数 | 描述 | +| ---------- | ------------ | ---------- | ---------------------- | +| `change` | 文件状态变化 | FileData[] | 文件列表发生变化时触发 | +| `remove` | 文件删除 | FileData | 文件被删除时触发 | +| `preview` | 文件预览 | FileData | 文件开始预览时触发 | +| `download` | 文件下载 | FileData | 文件开始下载时触发 | +| `drop` | 文件拖拽 | FileData[] | 文件被拖拽到区域时触发 | + +**章节来源** + +- [**init**.py:27-43](file://backend/modelscope_studio/components/antdx/attachments/__init__.py#L27-L43) + +### 错误处理机制 + +组件实现了完善的错误处理体系： + +```mermaid +flowchart TD +Start([开始处理]) --> Try[执行操作] +Try --> Success{操作成功?} +Success --> |是| Complete[完成处理] +Success --> |否| Catch[捕获错误] +Catch --> Type{错误类型?} +Type --> |网络错误| Network[网络错误处理] +Type --> |权限错误| Auth[权限错误处理] +Type --> |格式错误| Format[格式错误处理] +Type --> |大小错误| Size[大小错误处理] +Type --> |其他错误| Other[其他错误处理] +Network --> Retry[重试机制] +Auth --> Login[重新登录] +Format --> Fix[修复格式] +Size --> Reduce[减小文件] +Other --> Report[报告问题] +Retry --> Try +Login --> Try +Fix --> Try +Reduce --> Try +Report --> End([结束]) +Complete --> End +``` + +**图表来源** + +- [attachments.tsx:350-354](file://frontend/antdx/attachments/attachments.tsx#L350-L354) + +**章节来源** + +- [attachments.tsx:350-354](file://frontend/antdx/attachments/attachments.tsx#L350-L354) + +## 依赖关系分析 + +### 外部依赖 + +组件依赖于多个关键的外部库： + +```mermaid +graph TB +subgraph "核心依赖" +AX[@ant-design/x
Ant Design X组件库] +ANTD[antd
Ant Design组件库] +GRADIO[@gradio/client
Gradio客户端] +REACT[react
React框架] +end +subgraph "工具库" +Lodash[lodash-es
工具函数库] +Classnames[classnames
类名处理] +SveltePreprocess[svelte-preprocess-react
Svelte预处理] +end +subgraph "组件依赖" +FileCard[FileCard组件] +Utils[工具函数] +Hooks[React Hooks] +end +Attachments --> AX +Attachments --> ANTD +Attachments --> GRADIO +Attachments --> REACT +Attachments --> Lodash +Attachments --> Classnames +Attachments --> SveltePreprocess +Attachments --> FileCard +Attachments --> Utils +Attachments --> Hooks +``` + +**图表来源** + +- [attachments.tsx:1-17](file://frontend/antdx/attachments/attachments.tsx#L1-L17) +- [package.json:1-15](file://frontend/antdx/attachments/package.json#L1-L15) + +### 内部模块依赖 + +```mermaid +graph TD +subgraph "前端模块" +A[Index.svelte] +B[attachments.tsx] +C[file-card.tsx] +D[base.tsx] +E[upload.ts] +F[multimodal-input.tsx] +end +subgraph "后端模块" +G[__init__.py] +end +A --> B +B --> C +C --> D +B --> E +F --> B +G --> A +``` + +**图表来源** + +- [Index.svelte:1-98](file://frontend/antdx/attachments/Index.svelte#L1-L98) +- [attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) + +**章节来源** + +- [package.json:1-15](file://frontend/antdx/attachments/package.json#L1-L15) +- [Index.svelte:1-98](file://frontend/antdx/attachments/Index.svelte#L1-L98) + +## 性能考虑 + +### 上传性能优化 + +组件在设计时充分考虑了性能优化： + +- **并发上传控制**：通过 `maxCount` 限制同时上传的文件数量 +- **进度条显示**：实时显示上传进度，提升用户体验 +- **内存管理**：及时清理临时文件数据，避免内存泄漏 +- **缓存策略**：对已上传文件进行缓存，减少重复上传 + +### 预览性能优化 + +```mermaid +graph LR +subgraph "预览优化策略" +A[懒加载预览] +B[缩略图生成] +C[虚拟滚动] +D[预加载机制] +end +subgraph "性能指标" +E[首屏加载时间] +F[内存占用] +G[CPU使用率] +H[网络带宽] +end +A --> E +B --> F +C --> G +D --> H +``` + +### 内存管理 + +组件实现了智能的内存管理机制： + +- **文件对象复用**：重用已存在的文件对象，避免重复创建 +- **垃圾回收**：及时释放不再使用的文件数据 +- **状态同步**：保持本地状态与服务器状态的一致性 + +## 故障排除指南 + +### 常见问题及解决方案 + +#### 上传失败 + +**问题描述**：文件上传过程中出现错误 + +**可能原因**： + +- 网络连接不稳定 +- 文件格式不支持 +- 文件大小超出限制 +- 权限不足 + +**解决方案**： + +1. 检查网络连接状态 +2. 验证文件格式是否在 `accept` 列表中 +3. 确认文件大小未超过 `maxSize` 限制 +4. 检查用户权限设置 + +#### 预览失败 + +**问题描述**：文件无法正常预览 + +**可能原因**： + +- 浏览器兼容性问题 +- 文件损坏 +- URL解析错误 + +**解决方案**： + +1. 尝试在不同浏览器中打开 +2. 重新上传文件 +3. 检查文件完整性 +4. 验证URL格式正确性 + +#### 性能问题 + +**问题描述**：组件运行缓慢或卡顿 + +**可能原因**： + +- 文件数量过多 +- 文件过大 +- 内存不足 + +**解决方案**： + +1. 减少同时上传的文件数量 +2. 优化文件大小 +3. 增加系统内存 +4. 使用 `maxCount` 限制文件数量 + +**章节来源** + +- [attachments.tsx:350-354](file://frontend/antdx/attachments/attachments.tsx#L350-L354) + +### 调试技巧 + +#### 开启调试模式 + +```javascript +// 在开发环境中启用详细日志 +const attachments = new Attachments({ + debug: true, + // 其他配置... +}); +``` + +#### 监控上传进度 + +```javascript +attachments.on('upload-progress', (progress) => { + console.log(`上传进度: ${progress}%`); +}); +``` + +## 结论 + +Attachments 附件组件是一个功能完整、性能优异的文件管理解决方案。它不仅提供了基本的文件上传和预览功能，还具备了高级的批量管理、自定义配置和错误处理能力。 + +### 主要优势 + +1. **功能全面**：涵盖文件上传、预览、管理的所有核心需求 +2. **易于使用**：简洁的API设计，快速集成 +3. **高度可定制**：丰富的配置选项满足各种使用场景 +4. **性能优秀**：优化的算法和架构确保流畅的用户体验 +5. **稳定可靠**：完善的错误处理和异常恢复机制 + +### 适用场景 + +- 在线文档管理系统 +- 即时通讯应用的文件传输 +- 内容创作平台的媒体管理 +- 企业协作平台的文件共享 +- 教育平台的作业提交系统 + +## 附录 + +### API参考 + +#### Props属性 + +| 属性名 | 类型 | 必填 | 默认值 | 描述 | +| ---------------- | ----------------- | ---- | -------- | ------------------------------------ | +| `items` | FileData[] | 是 | [] | 当前文件列表 | +| `upload` | Function | 是 | - | 上传函数，接收RcFile[]返回FileData[] | +| `onValueChange` | Function | 否 | - | 值变化回调 | +| `onChange` | Function | 否 | - | 字符串路径变化回调 | +| `disabled` | boolean | 否 | false | 是否禁用 | +| `maxCount` | number | 否 | Infinity | 最大文件数 | +| `accept` | string | 否 | \* | 接受的文件类型 | +| `multiple` | boolean | 否 | true | 是否多选 | +| `showUploadList` | boolean \| object | 否 | true | 是否显示上传列表 | +| `imageProps` | ImageProps | 否 | - | 图片预览配置 | + +#### 事件 + +| 事件名 | 参数 | 描述 | +| ---------- | ---------- | ------------ | +| `change` | FileData[] | 文件列表变化 | +| `remove` | FileData | 文件删除 | +| `preview` | FileData | 文件预览开始 | +| `download` | FileData | 文件下载开始 | +| `drop` | FileData[] | 文件拖拽 | + +#### 插槽 + +| 插槽名 | 参数 | 描述 | +| ---------------------------------- | ------------------------ | ---------------- | +| `placeholder` | type: 'drop' \| 'inline' | 占位符内容 | +| `placeholder.title` | type | 标题内容 | +| `placeholder.description` | type | 描述内容 | +| `placeholder.icon` | type | 图标内容 | +| `iconRender` | file, fileList | 自定义图标渲染 | +| `itemRender` | file, fileList | 自定义文件项渲染 | +| `showUploadList.previewIcon` | file, fileList | 预览图标 | +| `showUploadList.removeIcon` | file, fileList | 删除图标 | +| `showUploadList.downloadIcon` | file, fileList | 下载图标 | +| `showUploadList.extra` | file, fileList | 额外操作 | +| `imageProps.placeholder` | file, fileList | 图片占位符 | +| `imageProps.preview.mask` | file, fileList | 预览遮罩 | +| `imageProps.preview.closeIcon` | file, fileList | 关闭图标 | +| `imageProps.preview.toolbarRender` | file, fileList | 工具栏渲染 | +| `imageProps.preview.imageRender` | file, fileList | 图片渲染 | + +### 最佳实践 + +#### 性能优化建议 + +1. **合理设置 `maxCount`**：根据应用场景设置合适的最大文件数量 +2. **使用懒加载**：对于大量文件，考虑使用分页或虚拟滚动 +3. **优化文件大小**：在上传前压缩图片和视频文件 +4. **缓存策略**：对常用文件建立缓存机制 + +#### 安全考虑 + +1. **文件类型验证**：在服务端也进行文件类型检查 +2. **大小限制**：设置合理的文件大小上限 +3. **病毒扫描**：对上传文件进行安全扫描 +4. **权限控制**：确保只有授权用户可以访问文件 + +#### 用户体验优化 + +1. **进度反馈**：提供清晰的上传进度指示 +2. **错误提示**：友好的错误信息和解决方案 +3. **批量操作**：支持批量选择和操作 +4. **响应式设计**：适配各种设备和屏幕尺寸 + +**章节来源** + +- [README-zh_CN.md:1-10](file://docs/components/antdx/attachments/README-zh_CN.md#L1-L10) +- [basic.py:1-51](file://docs/components/antdx/attachments/demos/basic.py#L1-L51) +- [combination.py:1-75](file://docs/components/antdx/attachments/demos/combination.py#L1-L75) +- [file_card.py:1-72](file://docs/components/antdx/attachments/demos/file_card.py#L1-L72) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\350\241\250\350\276\276\347\273\204\344\273\266/Sender \345\217\221\351\200\201\345\231\250\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\350\241\250\350\276\276\347\273\204\344\273\266/Sender \345\217\221\351\200\201\345\231\250\347\273\204\344\273\266.md" new file mode 100644 index 00000000..737f212d --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\350\241\250\350\276\276\347\273\204\344\273\266/Sender \345\217\221\351\200\201\345\231\250\347\273\204\344\273\266.md" @@ -0,0 +1,315 @@ +# Sender 发送器组件 + + +**本文引用的文件** +- [frontend/antdx/sender/sender.tsx](file://frontend/antdx/sender/sender.tsx) +- [frontend/antdx/sender/header/sender.header.tsx](file://frontend/antdx/sender/header/sender.header.tsx) +- [frontend/antdx/sender/switch/sender.switch.tsx](file://frontend/antdx/sender/switch/sender.switch.tsx) +- [backend/modelscope_studio/components/antdx/sender/__init__.py](file://backend/modelscope_studio/components/antdx/sender/__init__.py) +- [backend/modelscope_studio/components/antdx/sender/header/__init__.py](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py) +- [backend/modelscope_studio/components/antdx/sender/switch/__init__.py](file://backend/modelscope_studio/components/antdx/sender/switch/__init__.py) +- [docs/components/antdx/sender/README.md](file://docs/components/antdx/sender/README.md) +- [docs/components/antdx/attachments/demos/combination.py](file://docs/components/antdx/attachments/demos/combination.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：配置与用法示例](#附录配置与用法示例) + +## 简介 + +Sender 发送器组件是面向聊天场景的输入组件，提供消息发送、输入处理、粘贴上传、提交类型控制、头部面板与开关控制等能力。它在前端基于 Ant Design X 的 Sender 实现，并通过 Gradio 适配层在后端提供 Python API，支持插槽化扩展（如前缀/后缀、头部、页脚、技能面板等）以及事件绑定。 + +## 项目结构 + +Sender 组件由“前端 Svelte 包装 + 后端 Python 组件”两部分构成，同时配套 Header 与 Switch 子组件，文档与示例位于 docs 目录中。 + +```mermaid +graph TB +subgraph "前端" +F_sender["frontend/antdx/sender/sender.tsx"] +F_header["frontend/antdx/sender/header/sender.header.tsx"] +F_switch["frontend/antdx/sender/switch/sender.switch.tsx"] +end +subgraph "后端" +B_sender["backend/.../antdx/sender/__init__.py"] +B_header["backend/.../antdx/sender/header/__init__.py"] +B_switch["backend/.../antdx/sender/switch/__init__.py"] +end +subgraph "文档与示例" +D_readme["docs/components/antdx/sender/README.md"] +D_demo["docs/components/antdx/attachments/demos/combination.py"] +end +F_sender --> B_sender +F_header --> B_header +F_switch --> B_switch +D_readme --> B_sender +D_demo --> B_sender +``` + +**图表来源** + +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) +- [frontend/antdx/sender/header/sender.header.tsx:1-21](file://frontend/antdx/sender/header/sender.header.tsx#L1-L21) +- [frontend/antdx/sender/switch/sender.switch.tsx:1-34](file://frontend/antdx/sender/switch/sender.switch.tsx#L1-L34) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:1-149](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L1-L149) +- [backend/modelscope_studio/components/antdx/sender/header/**init**.py:1-74](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py#L1-L74) +- [backend/modelscope_studio/components/antdx/sender/switch/**init**.py:1-81](file://backend/modelscope_studio/components/antdx/sender/switch/__init__.py#L1-L81) +- [docs/components/antdx/sender/README.md:1-10](file://docs/components/antdx/sender/README.md#L1-L10) +- [docs/components/antdx/attachments/demos/combination.py:1-75](file://docs/components/antdx/attachments/demos/combination.py#L1-L75) + +**章节来源** + +- [frontend/antdx/sender/sender.tsx:1-174](file://frontend/antdx/sender/sender.tsx#L1-L174) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:1-149](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L1-L149) + +## 核心组件 + +- Sender（主组件） + - 负责输入值管理、提交事件拦截、粘贴文件上传、插槽渲染、技能面板（含 Tooltip、可关闭）配置。 + - 对外暴露 value、onChange、onSubmit、onPasteFile 等回调与属性。 +- Sender.Header（头部面板） + - 支持标题插槽、可选展开/收起、可关闭等特性。 +- Sender.Switch（开关控件） + - 支持自定义“选中/未选中”文案与图标插槽。 + +**章节来源** + +- [frontend/antdx/sender/sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) +- [frontend/antdx/sender/header/sender.header.tsx:7-18](file://frontend/antdx/sender/header/sender.header.tsx#L7-L18) +- [frontend/antdx/sender/switch/sender.switch.tsx:7-31](file://frontend/antdx/sender/switch/sender.switch.tsx#L7-L31) + +## 架构总览 + +Sender 在前端以 Svelte 包装形式桥接 Ant Design X 的 Sender，并在后端通过 Python 组件暴露到 Gradio 生态。其数据流与事件流如下： + +```mermaid +sequenceDiagram +participant U as "用户" +participant FE as "前端 Sender(svelte)" +participant ADX as "Ant Design X Sender" +participant BK as "后端 Sender(Python)" +U->>FE : 输入/粘贴/点击发送 +FE->>FE : useValueChange(value/onValueChange) +FE->>ADX : 渲染并传递 props(含插槽/技能配置) +ADX-->>FE : onChange(value) +FE-->>BK : 变更事件(Gradio) +ADX-->>FE : onSubmit(args) +FE->>FE : 检查建议是否打开(阻止自动提交) +FE-->>BK : submit 事件(Gradio) +FE->>FE : onPasteFile(files) -> upload(files) -> onPasteFile(urls) +``` + +**图表来源** + +- [frontend/antdx/sender/sender.tsx:68-138](file://frontend/antdx/sender/sender.tsx#L68-L138) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:21-59](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L21-L59) + +## 详细组件分析 + +### 主组件 Sender（消息发送与输入处理） + +- 输入与状态 + - 使用受控 value 与 onChange，结合 useValueChange 管理外部传入 value 与内部变更。 +- 提交逻辑 + - onSubmit 会被拦截：若建议面板处于打开状态则不触发外部 submit，避免误触。 + - 外部 submit 事件通过 Gradio 事件系统上报。 +- 粘贴上传 + - onPasteFile 接收原生 File 列表，调用 upload 回调进行上传，再将返回的文件路径数组回传给 onPasteFile。 +- 插槽与高级功能 + - 支持 suffix/header/prefix/footer 插槽；支持 skill.title、skill.toolTip.title、skill.closable.closeIcon 插槽。 + - skill 配置支持 Tooltip 与可关闭行为，Tooltip 的 afterOpenChange、getPopupContainer 可通过函数包装。 +- 事件映射 + - change、submit、cancel、allow_speech_recording_change、key_down/key_press、focus/blur、paste、paste_file、skill_closable_close 等事件均映射到 Gradio 事件。 + +```mermaid +flowchart TD +Start(["进入 Sender 渲染"]) --> Slots["解析插槽与技能配置"] +Slots --> Render["渲染 Ant Design X Sender"] +Render --> OnChange["onChange(value) -> 更新本地 value"] +Render --> OnSubmit["onSubmit(args)"] +OnSubmit --> CheckOpen{"建议面板是否打开?"} +CheckOpen --> |是| BlockSubmit["阻止外部 submit"] +CheckOpen --> |否| FireSubmit["触发外部 submit(Gradio)"] +Render --> Paste["onPasteFile(files)"] +Paste --> Upload["upload(files) -> FileData[]"] +Upload --> OnPasteFile["onPasteFile(urls) 回调"] +OnChange --> End(["完成"]) +FireSubmit --> End +BlockSubmit --> End +OnPasteFile --> End +``` + +**图表来源** + +- [frontend/antdx/sender/sender.tsx:68-138](file://frontend/antdx/sender/sender.tsx#L68-L138) + +**章节来源** + +- [frontend/antdx/sender/sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:21-66](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L21-L66) + +### 子组件 Sender.Header（头部面板） + +- 功能要点 + - 支持 title 插槽，其余属性透传至 Ant Design X Header。 + - 事件 open_change 通过 Gradio 映射。 +- 使用场景 + - 与 Sender 结合用于插入附件或扩展输入区域。 + +**章节来源** + +- [frontend/antdx/sender/header/sender.header.tsx:7-18](file://frontend/antdx/sender/header/sender.header.tsx#L7-L18) +- [backend/modelscope_studio/components/antdx/sender/header/**init**.py:12-20](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py#L12-L20) + +### 子组件 Sender.Switch（开关控制） + +- 功能要点 + - 支持 checkedChildren、unCheckedChildren、icon 插槽，便于自定义文案与图标。 + - 事件 change 通过 Gradio 映射。 +- 使用场景 + - 控制语音输入、快捷提交模式等。 + +**章节来源** + +- [frontend/antdx/sender/switch/sender.switch.tsx:7-31](file://frontend/antdx/sender/switch/sender.switch.tsx#L7-L31) +- [backend/modelscope_studio/components/antdx/sender/switch/**init**.py:12-19](file://backend/modelscope_studio/components/antdx/sender/switch/__init__.py#L12-L19) + +### 类关系图（代码级） + +```mermaid +classDiagram +class AntdXSender { ++EVENTS ++SLOTS ++__init__(...) ++FRONTEND_DIR ++api_info() ++preprocess(payload) ++postprocess(value) +} +class AntdXSenderHeader { ++EVENTS ++SLOTS ++__init__(...) ++FRONTEND_DIR +} +class AntdXSenderSwitch { ++EVENTS ++SLOTS ++__init__(...) ++FRONTEND_DIR +} +AntdXSender --> AntdXSenderHeader : "包含" +AntdXSender --> AntdXSenderSwitch : "包含" +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/sender/**init**.py:14-128](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L14-L128) +- [backend/modelscope_studio/components/antdx/sender/header/**init**.py:8-56](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py#L8-L56) +- [backend/modelscope_studio/components/antdx/sender/switch/**init**.py:8-63](file://backend/modelscope_studio/components/antdx/sender/switch/__init__.py#L8-L63) + +## 依赖关系分析 + +- 前端依赖 + - 使用 @svelte-preprocess-react 将 React 组件桥接到 Svelte。 + - 使用 @ant-design/x 的 Sender/Header/Switch。 + - 使用 @gradio/client 的 FileData 类型与 Gradio 事件。 +- 后端依赖 + - 基于 Gradio 的 ModelScopeDataLayoutComponent/ModelScopeLayoutComponent 抽象，统一事件与插槽映射。 +- 文档与示例 + - README 提供基本示例入口；组合示例展示与 Attachments、Badge、Button 等组件协同。 + +```mermaid +graph LR +Svelte["Svelte 包装(Sender)"] --> ADX["Ant Design X Sender"] +Svelte --> Hooks["@utils/* hooks"] +Svelte --> Slot["ReactSlot 插槽"] +Backend["Python Sender 组件"] --> Gradio["Gradio 事件系统"] +Backend --> Frontend["前端组件映射"] +Docs["文档与示例"] --> Backend +Docs --> Frontend +``` + +**图表来源** + +- [frontend/antdx/sender/sender.tsx:1-10](file://frontend/antdx/sender/sender.tsx#L1-L10) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:14-128](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L14-L128) +- [docs/components/antdx/sender/README.md:1-10](file://docs/components/antdx/sender/README.md#L1-L10) + +**章节来源** + +- [frontend/antdx/sender/sender.tsx:1-10](file://frontend/antdx/sender/sender.tsx#L1-L10) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:14-128](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L14-L128) + +## 性能考虑 + +- 插槽与函数包装 + - 对 Tooltip 的回调与插槽采用函数包装与 ReactSlot 渲染，避免不必要的重渲染；建议在上层缓存或稳定化插槽内容。 +- 提交拦截 + - 建议在建议面板打开时禁用自动提交，减少无效请求。 +- 文件上传 + - onPasteFile 应尽量异步处理，避免阻塞 UI；对大文件建议分片或服务端直传策略。 + +## 故障排查指南 + +- 提交被意外拦截 + - 若建议面板未关闭导致 submit 未触发，请检查建议面板状态或临时关闭拦截逻辑。 +- 粘贴上传未生效 + - 确认 upload 回调已正确返回包含 path 字段的 FileData 数组；onPasteFile 回调应接收字符串数组。 +- 插槽内容不显示 + - 确认插槽名称与组件支持一致（如 skill.title、skill.toolTip.title、skill.closable.closeIcon）。 +- 事件未触发 + - 检查后端 EVENTS 列表是否包含对应事件名，前端是否正确绑定。 + +**章节来源** + +- [frontend/antdx/sender/sender.tsx:126-138](file://frontend/antdx/sender/sender.tsx#L126-L138) +- [backend/modelscope_studio/components/antdx/sender/**init**.py:21-59](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L21-L59) + +## 结论 + +Sender 发送器组件通过前后端一体化设计，提供了聊天场景下强大的输入与提交能力，配合 Header、Switch 与插槽系统，能够灵活扩展为多模态输入与复杂交互。建议在实际应用中关注事件拦截、插槽稳定性与上传流程的健壮性。 + +## 附录：配置与用法示例 + +### 配置项概览（后端） + +- 基础属性 + - value/default_value/placeholder/loading/disabled/read_only/auto_size/submit_type 等。 +- 插槽 + - suffix/header/prefix/footer/skill.title/skill.toolTip.title/skill.closable.closeIcon。 +- 事件 + - change、submit、cancel、allow_speech_recording_change、key_down/key_press、focus/blur、paste、paste_file、skill_closable_close。 +- 子组件 + - Header、Switch（分别支持相应插槽与事件）。 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/sender/**init**.py:61-127](file://backend/modelscope_studio/components/antdx/sender/__init__.py#L61-L127) +- [backend/modelscope_studio/components/antdx/sender/header/**init**.py:19-54](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py#L19-L54) +- [backend/modelscope_studio/components/antdx/sender/switch/**init**.py:18-61](file://backend/modelscope_studio/components/antdx/sender/switch/__init__.py#L18-L61) + +### 聊天机器人集成示例（概述） + +- 文本消息 + - 使用 Sender 作为输入，监听 submit 事件获取文本内容，结合后端模型推理返回结果。 +- 多模态内容 + - 与 Sender.Header/Attachents 协同，通过粘贴或拖拽上传图片/文件，onPasteFile 返回的路径列表可用于后续处理。 +- 特殊命令 + - 在 onChange 或 submit 中解析输入，识别“/reset”“/help”等命令，执行相应逻辑。 + +**章节来源** + +- [docs/components/antdx/attachments/demos/combination.py:26-71](file://docs/components/antdx/attachments/demos/combination.py#L26-L71) +- [docs/components/antdx/sender/README.md:5-10](file://docs/components/antdx/sender/README.md#L5-L10) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\350\241\250\350\276\276\347\273\204\344\273\266/Suggestion \345\277\253\346\215\267\346\214\207\344\273\244\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\350\241\250\350\276\276\347\273\204\344\273\266/Suggestion \345\277\253\346\215\267\346\214\207\344\273\244\347\273\204\344\273\266.md" new file mode 100644 index 00000000..b8d1f754 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\350\241\250\350\276\276\347\273\204\344\273\266/Suggestion \345\277\253\346\215\267\346\214\207\344\273\244\347\273\204\344\273\266.md" @@ -0,0 +1,338 @@ +# Suggestion 快捷指令组件 + + +**本文引用的文件** +- [backend/modelscope_studio/components/antdx/suggestion/__init__.py](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py) +- [backend/modelscope_studio/components/antdx/suggestion/item/__init__.py](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py) +- [frontend/antdx/suggestion/suggestion.tsx](file://frontend/antdx/suggestion/suggestion.tsx) +- [frontend/antdx/suggestion/item/suggestion.item.tsx](file://frontend/antdx/suggestion/item/suggestion.item.tsx) +- [frontend/antdx/suggestion/context.ts](file://frontend/antdx/suggestion/context.ts) +- [docs/components/antdx/suggestion/README.md](file://docs/components/antdx/suggestion/README.md) +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能与交互特性](#性能与交互特性) +8. [使用示例与最佳实践](#使用示例与最佳实践) +9. [故障排查](#故障排查) +10. [结论](#结论) + +## 简介 + +Suggestion 快捷指令组件用于在智能助手对话场景中提供“快捷指令”“智能补全”“上下文相关建议”“个性化推荐”等能力。它基于 Ant Design X 的 Suggestion 能力，通过 React 包装与 Gradio 布局组件桥接，实现： + +- 指令定义：以“建议项”形式组织，支持标签、图标、额外内容等多维信息。 +- 触发条件：可由输入框键盘事件或外部状态控制面板开合。 +- 执行逻辑：选择建议后触发回调，便于在 Python 侧进行后续处理。 +- 控制方式：支持受控/非受控两种模式；可通过 Python 侧直接设置 open 状态。 +- 动态更新：建议列表可由 slot 或函数动态生成，运行时可热更新。 + +本组件广泛应用于聊天机器人、代码助手、内容创作等需要“快速行动”的交互场景。 + +## 项目结构 + +Suggestion 组件由后端 Python 组件与前端 React 实现共同构成，并通过统一的上下文系统实现插槽渲染与动态数据注入。 + +```mermaid +graph TB +subgraph "后端 Python" +PY_SUG["AntdXSuggestion
组件类"] +PY_ITEM["AntdXSuggestionItem
建议项类"] +end +subgraph "前端 React" +FE_SUG["Suggestion
React 包装"] +FE_ITEM["SuggestionItem
建议项包装"] +CTX["context.ts
items 上下文"] +end +PY_SUG --> FE_SUG +PY_ITEM --> FE_ITEM +FE_SUG --> CTX +FE_ITEM --> CTX +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/suggestion/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py#L8-L68) +- [frontend/antdx/suggestion/suggestion.tsx:64-165](file://frontend/antdx/suggestion/suggestion.tsx#L64-L165) +- [frontend/antdx/suggestion/item/suggestion.item.tsx:7-22](file://frontend/antdx/suggestion/item/suggestion.item.tsx#L7-L22) +- [frontend/antdx/suggestion/context.ts:1-7](file://frontend/antdx/suggestion/context.ts#L1-L7) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/suggestion/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py#L8-L68) +- [frontend/antdx/suggestion/suggestion.tsx:64-165](file://frontend/antdx/suggestion/suggestion.tsx#L64-L165) +- [frontend/antdx/suggestion/item/suggestion.item.tsx:7-22](file://frontend/antdx/suggestion/item/suggestion.item.tsx#L7-L22) +- [frontend/antdx/suggestion/context.ts:1-7](file://frontend/antdx/suggestion/context.ts#L1-L7) + +## 核心组件 + +- AntdXSuggestion（后端组件） + - 支持事件：select（选中）、open_change（面板开合）。 + - 支持插槽：items、children。 + - 关键属性：items（建议列表）、block（块级显示）、open（受控开合）、should_trigger（自定义触发器）、根样式类名与内联样式等。 + - 前端映射：resolve_frontend_dir("suggestion", type="antdx")。 +- AntdXSuggestionItem（后端建议项） + - 支持插槽：label、icon、extra。 + - 关键属性：value、label、extra、icon、key。 + - 前端映射：resolve_frontend_dir("suggestion", "item", type="antdx")。 + +上述组件均声明 skip_api=True，表明其不参与标准 API 流程，而是通过事件与插槽完成交互。 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/suggestion/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py#L8-L68) + +## 架构总览 + +Suggestion 在前端通过 React 包装 Ant Design X 的 Suggestion 组件，结合插槽系统与上下文，实现“建议项”渲染与事件透传；在后端通过 Gradio 布局组件桥接，支持 Python 侧控制与事件绑定。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant FE as "前端 Suggestion" +participant ADX as "Ant Design X Suggestion" +participant CTX as "Items 上下文" +participant PY as "后端 AntdXSuggestion" +U->>FE : 输入文本/按键 +FE->>ADX : 渲染建议面板 +FE->>CTX : 解析 items 插槽 +CTX-->>FE : 返回建议项集合 +FE->>ADX : 注入 items 与回调 +U->>FE : 选择某建议项 +FE->>PY : 触发 select 事件 +PY-->>FE : 回调处理Python 侧 +FE-->>U : 更新界面/执行动作 +``` + +**图表来源** + +- [frontend/antdx/suggestion/suggestion.tsx:77-162](file://frontend/antdx/suggestion/suggestion.tsx#L77-L162) +- [frontend/antdx/suggestion/context.ts:1-7](file://frontend/antdx/suggestion/context.ts#L1-L7) +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:18-27](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L18-L27) + +## 组件详解 + +### 后端组件：AntdXSuggestion + +- 事件绑定 + - select：建议项被选中时触发，后端通过内部标记启用事件绑定。 + - open_change：面板开合状态变化时触发，便于受控/非受控切换。 +- 插槽支持 + - items：建议项集合，可由 slot 或函数动态生成。 + - children：用于包裹输入框等宿主元素，配合 should_trigger 自定义触发逻辑。 +- 属性要点 + - items：可为字符串、列表或函数，函数形式支持动态计算。 + - open：受控模式下由 Python 侧显式设置面板开合。 + - should_trigger：自定义键盘事件触发器，决定何时弹出建议面板。 + - 样式：支持 class_names、styles、root_class_name 等。 +- 生命周期 + - preprocess/postprocess/example_payload/example_value 均返回空值，表示该组件不参与数据序列化。 + +```mermaid +classDiagram +class AntdXSuggestion { ++EVENTS ++SLOTS ++items ++block ++open ++should_trigger ++root_class_name ++class_names ++styles ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +class AntdXSuggestionItem { ++EVENTS ++SLOTS ++value ++label ++extra ++icon ++key ++skip_api +} +AntdXSuggestion --> AntdXSuggestionItem : "使用" +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) +- [backend/modelscope_studio/components/antdx/suggestion/item/**init**.py:8-68](file://backend/modelscope_studio/components/antdx/suggestion/item/__init__.py#L8-L68) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-86](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L86) + +### 前端实现：Suggestion（React 包装） + +- 插槽与上下文 + - 使用 withItemsContextProvider 提供 items 上下文，支持 default 与 items 两套插槽。 + - 通过 renderItems 与 patchSlots 将插槽内容转换为建议项结构。 +- 动态建议列表 + - items 可为函数或插槽解析结果；若为空则回退到默认插槽。 + - 使用 useMemoizedEqualValue 与 useMemo 优化渲染与比较。 +- 触发与开合 + - shouldTrigger：在 onKeyDown 中按需触发 onTrigger，决定是否弹出面板。 + - open：支持 props.open 非受控模式与内部状态受控模式。 +- 事件透传 + - onOpenChange：根据 props.open 是否存在决定是否更新内部状态。 + - children：通过 SuggestionChildrenWrapper 注入上下文并透传事件。 + +```mermaid +flowchart TD +Start(["进入 Suggestion 渲染"]) --> ResolveItems["解析 items 插槽/函数"] +ResolveItems --> ItemsEmpty{"items 是否为空?"} +ItemsEmpty -- 是 --> Fallback["回退到 default 插槽"] +ItemsEmpty -- 否 --> UseProvided["使用提供的 items 函数/数组"] +Fallback --> BuildList["构建建议项列表"] +UseProvided --> BuildList +BuildList --> PatchSlots["patchSlots 渲染 label/icon/extra 子插槽"] +PatchSlots --> SetOpen["根据 props.open 设置/同步 open 状态"] +SetOpen --> Render["渲染 Ant Design X Suggestion 并透传事件"] +Render --> End(["完成"]) +``` + +**图表来源** + +- [frontend/antdx/suggestion/suggestion.tsx:77-162](file://frontend/antdx/suggestion/suggestion.tsx#L77-L162) +- [frontend/antdx/suggestion/context.ts:1-7](file://frontend/antdx/suggestion/context.ts#L1-L7) + +**章节来源** + +- [frontend/antdx/suggestion/suggestion.tsx:64-165](file://frontend/antdx/suggestion/suggestion.tsx#L64-L165) +- [frontend/antdx/suggestion/context.ts:1-7](file://frontend/antdx/suggestion/context.ts#L1-L7) + +### 前端实现：SuggestionItem（建议项包装） + +- 通过 ItemHandler 将插槽 default 渲染为建议项 children。 +- 仅允许 default 插槽，简化建议项内容组织。 + +**章节来源** + +- [frontend/antdx/suggestion/item/suggestion.item.tsx:7-22](file://frontend/antdx/suggestion/item/suggestion.item.tsx#L7-L22) + +## 依赖关系分析 + +- 组件耦合 + - AntdXSuggestion 依赖 AntdXSuggestionItem 作为建议项容器。 + - 前端 Suggestion 依赖 Ant Design X 的 Suggestion 组件与内部工具函数（如 patchSlots、renderItems）。 +- 数据流 + - 插槽 → 上下文解析 → 建议项结构 → 渲染 → 事件回调 → Python 处理。 +- 事件链路 + - 前端 onOpenChange/select → 后端事件监听器 → Python 回调。 + +```mermaid +graph LR +PY_SUG["后端 AntdXSuggestion"] --> FE_SUG["前端 Suggestion"] +PY_ITEM["后端 AntdXSuggestionItem"] --> FE_ITEM["前端 SuggestionItem"] +FE_SUG --> ADX["Ant Design X Suggestion"] +FE_SUG --> CTX["Items 上下文"] +FE_ITEM --> CTX +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-16](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L16) +- [frontend/antdx/suggestion/suggestion.tsx:64-86](file://frontend/antdx/suggestion/suggestion.tsx#L64-L86) +- [frontend/antdx/suggestion/item/suggestion.item.tsx:7-18](file://frontend/antdx/suggestion/item/suggestion.item.tsx#L7-L18) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:11-16](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L11-L16) +- [frontend/antdx/suggestion/suggestion.tsx:64-86](file://frontend/antdx/suggestion/suggestion.tsx#L64-L86) +- [frontend/antdx/suggestion/item/suggestion.item.tsx:7-18](file://frontend/antdx/suggestion/item/suggestion.item.tsx#L7-L18) + +## 性能与交互特性 + +- 渲染优化 + - 使用 useMemoizedEqualValue 与 useMemo 缓存 props 与 items，避免重复渲染。 + - 仅在 items 或插槽变化时重建建议项列表。 +- 事件节流 + - shouldTrigger 中使用 requestAnimationFrame 将键盘事件处理延后，降低主线程阻塞风险。 +- 开合控制 + - 非受控模式：onOpenChange 内部维护 open 状态。 + - 受控模式：由 props.open 决定，onOpenChange 仅回调不修改状态。 +- 插槽渲染 + - patchSlots 将 label/icon/extra 子插槽转换为对应字段，减少跨组件通信成本。 + +**章节来源** + +- [frontend/antdx/suggestion/suggestion.tsx:36-57](file://frontend/antdx/suggestion/suggestion.tsx#L36-L57) +- [frontend/antdx/suggestion/suggestion.tsx:94-121](file://frontend/antdx/suggestion/suggestion.tsx#L94-L121) +- [frontend/antdx/suggestion/suggestion.tsx:135-140](file://frontend/antdx/suggestion/suggestion.tsx#L135-L140) + +## 使用示例与最佳实践 + +### 基础用法（文档示例） + +- 文档提供了基础、块级展示、Python 受控三种示例，可参考： + - [docs/components/antdx/suggestion/README.md:5-10](file://docs/components/antdx/suggestion/README.md#L5-L10) + +### 智能助手场景示例（概念性说明） + +- 常用命令 + - 定义一组固定命令建议项，点击即执行，适合“快速开始”场景。 +- 上下文相关建议 + - 根据当前输入或历史消息动态生成建议列表，提升相关性。 +- 个性化推荐 + - 基于用户偏好或使用记录，优先展示高命中率的建议项。 +- Python 侧控制 + - 通过设置 open 属性实现面板显隐控制；通过 select 事件接收选中项并在 Python 侧执行相应逻辑。 + +### 指令定义与触发 + +- 指令定义 + - 使用 AntdXSuggestionItem 组织建议项，支持 label、icon、extra 等字段。 +- 触发条件 + - 可通过 should_trigger 自定义键盘事件触发；也可由 open 属性控制面板开合。 +- 执行逻辑 + - 选中建议项后触发 select 事件，Python 侧可在回调中处理业务逻辑。 + +### 样式与交互定制 + +- 样式 + - 通过 class*names、styles、root_class_name 与后端 elem*\* 属性进行样式定制。 +- 交互 + - children 插槽用于承载输入框等宿主组件，配合 should_trigger 实现更灵活的触发策略。 + +**章节来源** + +- [docs/components/antdx/suggestion/README.md:5-10](file://docs/components/antdx/suggestion/README.md#L5-L10) +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:32-67](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L32-L67) +- [frontend/antdx/suggestion/suggestion.tsx:77-86](file://frontend/antdx/suggestion/suggestion.tsx#L77-L86) + +## 故障排查 + +- 建议项不显示 + - 检查 items 是否为空；若为空，确认 default 插槽是否正确填充。 + - 确认插槽名称是否匹配（items/default）。 +- 面板无法打开 + - 若使用受控 open，请确保 Python 侧正确设置 open。 + - 检查 should_trigger 是否正确实现触发逻辑。 +- 事件未回调 + - 确认事件监听器已注册（select/open_change）。 + - 检查 Python 侧回调是否正确绑定。 + +**章节来源** + +- [frontend/antdx/suggestion/suggestion.tsx:87-121](file://frontend/antdx/suggestion/suggestion.tsx#L87-L121) +- [backend/modelscope_studio/components/antdx/suggestion/**init**.py:18-27](file://backend/modelscope_studio/components/antdx/suggestion/__init__.py#L18-L27) + +## 结论 + +Suggestion 快捷指令组件通过“后端布局组件 + 前端 React 包装 + 插槽上下文”的架构，实现了高性能、可扩展的快捷指令与智能补全能力。其支持受控/非受控开合、动态建议列表、自定义触发器与事件回调，适用于多种智能助手与创作场景。建议在实际应用中结合业务上下文动态生成建议项，并通过 Python 侧事件实现闭环交互。 diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\350\241\250\350\276\276\347\273\204\344\273\266/\350\241\250\350\276\276\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\350\241\250\350\276\276\347\273\204\344\273\266/\350\241\250\350\276\276\347\273\204\344\273\266.md" new file mode 100644 index 00000000..26dbfd63 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\350\241\250\350\276\276\347\273\204\344\273\266/\350\241\250\350\276\276\347\273\204\344\273\266.md" @@ -0,0 +1,322 @@ +# 表达组件 + + +**本文引用的文件** +- [frontend/antdx/attachments/attachments.tsx](file://frontend/antdx/attachments/attachments.tsx) +- [frontend/antdx/sender/sender.tsx](file://frontend/antdx/sender/sender.tsx) +- [frontend/antdx/suggestion/suggestion.tsx](file://frontend/antdx/suggestion/suggestion.tsx) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能与可用性建议](#性能与可用性建议) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：使用示例与最佳实践](#附录使用示例与最佳实践) + +## 简介 + +本文件面向 Ant Design X 的表达组件体系，聚焦三大组件： + +- 附件（Attachments）：负责文件上传、预览、列表管理与占位渲染 +- 发送器（Sender）：负责消息输入、粘贴附件上传、提交与输入状态同步 +- 快捷指令（Suggestion）：负责指令补全、触发策略、上下文传递与弹层容器配置 + +文档将从系统架构、数据流、处理逻辑、组件间协作机制到使用示例与排障建议进行完整说明，帮助开发者快速理解并正确集成。 + +## 项目结构 + +Ant Design X 的前端组件位于 frontend/antdx 下，分别以模块化方式组织；后端 Python 包装层在 backend/modelscope_studio/components/antdx 中导出统一别名，便于在 Python 生态中直接使用。 + +```mermaid +graph TB +subgraph "后端包装层" +PY_API["Python 导出别名
components.py / __init__.py"] +end +subgraph "前端 Ant Design X 组件" +ATT["Attachments
附件上传与管理"] +SND["Sender
消息输入与提交"] +SUG["Suggestion
快捷指令与补全"] +end +PY_API --> ATT +PY_API --> SND +PY_API --> SUG +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/components.py:7-32](file://backend/modelscope_studio/components/antdx/components.py#L7-L32) +- [backend/modelscope_studio/components/antdx/**init**.py:7-41](file://backend/modelscope_studio/components/antdx/__init__.py#L7-L41) + +章节来源 + +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) + +## 核心组件 + +- 附件（Attachments） + - 职责：封装 @ant-design/x 的 Attachments，提供上传钩子、占位图渲染、图片预览增强、图标自定义、最大数量控制、移除回调与值变更通知 + - 关键能力：上传前校验、并发上传状态、文件列表去重与合并、错误兜底 +- 发送器（Sender） + - 职责：封装 @ant-design/x 的 Sender，提供输入值双向绑定、粘贴文件上传、技能面板（skill）插槽化、提交事件在建议面板关闭时才触发 + - 关键能力：输入变更同步、粘贴文件上传、插槽化头部/尾部/前后缀、技能提示与可关闭配置 +- 快捷指令（Suggestion） + - 职责：封装 @ant-design/x 的 Suggestion，支持动态 items 渲染、插槽化标签/图标/额外区域、弹层容器定制、打开状态受控与非受控切换 + - 关键能力：触发策略钩子、上下文透传、键盘事件拦截与转发、弹层容器定位 + +章节来源 + +- [frontend/antdx/attachments/attachments.tsx:36-410](file://frontend/antdx/attachments/attachments.tsx#L36-L410) +- [frontend/antdx/sender/sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) +- [frontend/antdx/suggestion/suggestion.tsx:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) + +## 架构总览 + +三者协同工作：用户在 Sender 输入文本并粘贴文件，Sender 将文件交由上传函数生成可持久化的文件信息，再通过回调回传给上层；同时，Suggestion 提供指令补全，当其关闭时，Sender 才会真正提交内容，避免误触。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant S as "Sender" +participant A as "Attachments" +participant P as "上传函数(upload)" +participant C as "上层应用" +U->>S : "输入文本/粘贴文件" +S->>P : "粘贴文件上传" +P-->>S : "返回文件信息列表" +S-->>C : "onPasteFile(urls)" +S-->>C : "onChange(value)" +S->>C : "onSubmit(...)" +Note over S,C : "仅当 Suggestion 关闭时触发提交" +U->>A : "拖拽/选择文件" +A->>P : "调用上传钩子" +P-->>A : "返回文件信息" +A-->>C : "onValueChange(items)" +A-->>C : "onChange(paths)" +``` + +图表来源 + +- [frontend/antdx/sender/sender.tsx:135-138](file://frontend/antdx/sender/sender.tsx#L135-L138) +- [frontend/antdx/attachments/attachments.tsx:329-348](file://frontend/antdx/attachments/attachments.tsx#L329-L348) +- [frontend/antdx/suggestion/suggestion.tsx:135-140](file://frontend/antdx/suggestion/suggestion.tsx#L135-L140) + +## 组件详解 + +### 附件（Attachments）组件 + +- 功能要点 + - 文件上传：通过 upload 钩子接收原生文件对象数组，返回文件信息数组；支持 maxCount 控制单/多文件模式 + - 预览增强：imageProps.preview 支持 mask、closeIcon、toolbarRender、imageRender 插槽化与函数化配置 + - 列表管理：自动去重（基于 uid/url/path）、状态标记（done/uploading）、移除回调与值变更通知 + - 占位渲染：placeholder 支持标题/描述/图标插槽化与函数化 + - 交互保护：上传过程中禁用交互，防止重复提交 +- 数据流与关键路径 + - 变更处理：onChange 内区分新增/删除分支，新增时先注入临时“上传中”状态，再调用 upload，最后合并结果并触发回调 + - 图片预览：通过 imageProps.preview 的 getContainer、toolbarRender、imageRender 等插槽或函数实现高度定制 + - 显示列表：showUploadList 的图标与 extra 支持插槽化与函数化覆盖 +- 错误处理 + - 捕获上传异常并恢复上传状态，避免界面卡死 +- 复杂度与性能 + - 去重与状态合并为 O(n)，适合中等规模文件列表 + - 插槽化渲染按需计算，避免不必要的重渲染 + +```mermaid +flowchart TD +Start(["进入 onChange"]) --> IsRemove{"是否为删除操作？"} +IsRemove --> |是| RemoveFlow["执行 onRemove 回调
更新 fileList 并触发回调"] +IsRemove --> |否| AddFlow["进入新增流程"] +AddFlow --> BeforeUpload["beforeUpload 钩子可选"] +BeforeUpload --> BeforeUploadOk{"返回 true？"} +BeforeUploadOk --> |否| End(["结束"]) +BeforeUploadOk --> |是| SetUploading["设置上传中状态"] +SetUploading --> Filter["过滤未完成文件并按 maxCount 截断"] +Filter --> TempList["生成临时上传中条目"] +TempList --> CallUpload["调用 upload 钩子"] +CallUpload --> Merge["合并返回的文件信息到最终列表"] +Merge --> UpdateState["更新 fileList 并触发 onValueChange/onChange"] +UpdateState --> End +``` + +图表来源 + +- [frontend/antdx/attachments/attachments.tsx:275-354](file://frontend/antdx/attachments/attachments.tsx#L275-L354) + +章节来源 + +- [frontend/antdx/attachments/attachments.tsx:36-410](file://frontend/antdx/attachments/attachments.tsx#L36-L410) + +### 发送器（Sender）组件 + +- 功能要点 + - 输入绑定：value 与 onChange 双向同步，支持外部受控 + - 粘贴上传：onPasteFile 将粘贴的文件集合转交给 upload 钩子，并回传文件路径数组 + - 技能面板：skill.title/toolTip/closable 支持插槽化与函数化配置 + - 提交控制：只有当 Suggestion 关闭时，onSubmit 才会被触发，避免建议面板开启时误提交 + - 插槽化布局：header/footer/prefix/suffix 支持 ReactSlot 注入 +- 关键交互 + - 使用 useSuggestionOpenContext 获取建议面板开关状态，从而决定是否允许提交 + - slotConfig 中的 formatResult/customRender 通过 createFunction 进行函数化包装 +- 错误处理 + - 粘贴上传失败不影响输入框状态，仅记录日志 +- 性能与复杂度 + - 值变更与插槽渲染均为轻量级，适合高频输入场景 + +```mermaid +sequenceDiagram +participant U as "用户" +participant S as "Sender" +participant Ctx as "Suggestion 开关上下文" +participant P as "上传函数(upload)" +U->>S : "粘贴文件" +S->>P : "upload(files)" +P-->>S : "返回文件信息" +S-->>U : "onPasteFile(urls)" +U->>S : "点击提交/回车" +S->>Ctx : "读取建议面板开关" +alt 建议面板已关闭 +S-->>U : "onSubmit(...)" +else 建议面板已打开 +S-->>U : "忽略提交" +end +``` + +图表来源 + +- [frontend/antdx/sender/sender.tsx:126-130](file://frontend/antdx/sender/sender.tsx#L126-L130) +- [frontend/antdx/sender/sender.tsx:135-138](file://frontend/antdx/sender/sender.tsx#L135-L138) + +章节来源 + +- [frontend/antdx/sender/sender.tsx:18-171](file://frontend/antdx/sender/sender.tsx#L18-L171) + +### 快捷指令（Suggestion）组件 + +- 功能要点 + - 动态 items：支持 items 函数或插槽化 items/default 两种来源，优先使用插槽 items + - 插槽化渲染：label/icon/extra/children 支持 ReactSlot 注入与 patchSlots 处理 + - 触发策略：shouldTrigger 钩子可拦截键盘事件，实现自定义触发条件 + - 弹层容器：getPopupContainer 支持函数化与插槽化，便于在复杂布局中定位 + - 状态控制：open 可受控（undefined 时内部自管），onOpenChange 透传底层状态 +- 上下文与事件 + - 通过 SuggestionContext 与 SuggestionOpenContext 向子树传递当前激活项与键盘事件处理 + - children 渲染函数中隐藏真实 children，仅在存在插槽时显示 +- 性能与复杂度 + - items 渲染按需计算，插槽化 patch 仅对必要字段生效 + +```mermaid +flowchart TD +Init(["初始化 items 渲染"]) --> Resolve["解析 items/default 插槽"] +Resolve --> ItemsFn["items 函数可选"] +ItemsFn --> Merge["合并为最终 items 数组"] +Merge --> Render["渲染每个项的 label/icon/extra 子项"] +Render --> Patch["patchSlots 应用插槽化覆盖"] +Patch --> Open["根据 open 状态控制显示"] +Open --> Trigger["shouldTrigger 拦截键盘事件"] +Trigger --> Done(["完成"]) +``` + +图表来源 + +- [frontend/antdx/suggestion/suggestion.tsx:89-121](file://frontend/antdx/suggestion/suggestion.tsx#L89-L121) +- [frontend/antdx/suggestion/suggestion.tsx:135-140](file://frontend/antdx/suggestion/suggestion.tsx#L135-L140) + +章节来源 + +- [frontend/antdx/suggestion/suggestion.tsx:64-162](file://frontend/antdx/suggestion/suggestion.tsx#L64-L162) + +## 依赖关系分析 + +- 后端导出 + - components.py 与 **init**.py 将 AntdXAttachments/AntdXSender/AntdXSuggestion 等组件统一导出为 Attachments/Sender/Suggestion，便于 Python 端直接使用 +- 前端封装 + - 三个组件均通过 sveltify 将 @ant-design/x 的原生组件桥接为支持插槽与函数化配置的 React 组件 + - 通过 useFunction/useValueChange/useTargets 等工具钩子，实现参数函数化与值同步 +- 组件间耦合 + - Sender 与 Suggestion 通过上下文建立弱耦合：Sender 仅在 Suggestion 关闭时提交，避免交互冲突 + - Attachments 与 Sender 通过 upload 回调解耦：上传逻辑由上层提供，组件只负责 UI 与状态 + +```mermaid +graph LR +PY["Python 导出别名"] --> ATT["前端 Attachments"] +PY --> SND["前端 Sender"] +PY --> SUG["前端 Suggestion"] +ATT --> AX["@ant-design/x Attachments"] +SND --> AX2["@ant-design/x Sender"] +SUG --> AX3["@ant-design/x Suggestion"] +SND -- "建议面板开关" --> CTX["Suggestion 开关上下文"] +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/components.py:7-32](file://backend/modelscope_studio/components/antdx/components.py#L7-L32) +- [backend/modelscope_studio/components/antdx/**init**.py:7-41](file://backend/modelscope_studio/components/antdx/__init__.py#L7-L41) +- [frontend/antdx/sender/sender.tsx:72-72](file://frontend/antdx/sender/sender.tsx#L72-L72) + +章节来源 + +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) + +## 性能与可用性建议 + +- 附件上传 + - 合理设置 maxCount，避免一次性上传过多文件导致内存压力 + - beforeUpload 中进行格式/大小校验，减少无效请求 + - 使用 imageProps.preview 的 getContainer 将预览浮层挂载到合适容器，避免滚动穿透 +- 发送器 + - 对高频输入使用节流/防抖策略（可在上层实现），降低 onChange 频率 + - 在多插槽场景下，尽量复用函数化配置，减少插槽渲染开销 +- 快捷指令 + - items 渲染尽量保持稳定结构，避免频繁重建 DOM + - shouldTrigger 中仅做必要判断，避免阻塞键盘事件 +- 全局 + - 在复杂布局中，优先使用 getPopupContainer 定位建议面板，确保可见性 + - 对上传失败进行友好提示，避免用户困惑 + +## 故障排查指南 + +- 附件无法删除 + - 检查 onChange 分支中的删除逻辑是否被提前 return + - 确认 validFileList 中是否存在匹配 uid 的条目 +- 上传无响应 + - 确认 upload 钩子返回值是否为 Promise
导出 Bubble 组件"] +B["list/bubble.list.tsx
导出 BubbleList 组件"] +C["list/item/bubble.list.item.tsx
导出 BubbleListItem 组件"] +D["list/role/bubble.list.role.tsx
导出 BubbleListRole 组件"] +E["list/context.ts
Items/Role 上下文"] +F["list/utils.tsx
useRole 工具与插槽补丁"] +G["utils/patchSlots.ts
插槽补丁增强"] +H["utils/renderItems.tsx
插槽渲染与参数传递"] +end +A --> |"包装并转发属性/插槽"| X["@ant-design/x Bubble"] +B --> |"组合 Items/Role 上下文"| X +C --> |"注入 ItemHandler"| X +D --> |"注入 RoleItemHandler"| X +E --> |"提供 useItems/useRoleItems"| B +F --> |"计算角色映射/插槽补丁"| B +G --> |"增强插槽补丁功能"| F +H --> |"标准化插槽渲染"| B +``` + +**图示来源** + +- [frontend/antdx/bubble/bubble.tsx:1-120](file://frontend/antdx/bubble/bubble.tsx#L1-L120) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-50](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L50) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:1-14](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L1-L14) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:1-14](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L1-L14) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/antdx/bubble/list/utils.tsx:1-135](file://frontend/antdx/bubble/list/utils.tsx#L1-L135) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + +**章节来源** + +- [frontend/antdx/bubble/bubble.tsx:1-120](file://frontend/antdx/bubble/bubble.tsx#L1-L120) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-50](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L50) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:1-14](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L1-L14) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:1-14](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L1-L14) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/antdx/bubble/list/utils.tsx:1-135](file://frontend/antdx/bubble/list/utils.tsx#L1-L135) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + +## 核心组件 + +- Bubble：对 @ant-design/x 的 Bubble 进行 Svelte 包装，支持插槽与函数式属性的统一渲染，同时兼容可编辑态的文案插槽。 +- BubbleList：列表容器，负责合并外部 items 与插槽 items，注入角色上下文，将消息逐条交给 @ant-design/x 的 List 渲染。 +- BubbleListItem：消息项包装器，通过 ItemHandler 注入上下文，使单个 Bubble 能感知列表环境。 +- BubbleListRole：角色项包装器，通过 RoleItemHandler 注入角色上下文，使角色配置可被 useRole 解析。 +- useRole：核心角色解析工具，支持默认键、预处理、后处理与插槽补丁，将角色映射为 @ant-design/x 所需的 RoleType。 + +**章节来源** + +- [frontend/antdx/bubble/bubble.tsx:1-120](file://frontend/antdx/bubble/bubble.tsx#L1-L120) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-50](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L50) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:1-14](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L1-L14) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:1-14](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L1-L14) +- [frontend/antdx/bubble/list/utils.tsx:49-135](file://frontend/antdx/bubble/list/utils.tsx#L49-L135) + +## 架构总览 + +Bubble 体系通过"包装层 + 上下文 + 工具函数"的方式，将 @ant-design/x 的原生能力与 Gradio 风格的插槽/函数式属性打通，形成可扩展的角色化消息列表。 + +```mermaid +sequenceDiagram +participant U as "调用方" +participant BL as "BubbleList" +participant Ctx as "上下文(Items/Role)" +participant UR as "useRole 工具" +participant PS as "patchSlots 增强" +participant XBL as "@ant-design/x List" +participant BI as "BubbleListItem/BubbleListRole" +U->>BL : 提供 items 或插槽 items +BL->>Ctx : 注入 Items/Role 上下文 +BL->>UR : 计算角色映射与插槽补丁 +UR->>PS : 应用插槽补丁增强 +PS-->>UR : 返回增强后的补丁 +UR-->>BL : 返回 RoleType +BL->>XBL : 渲染列表并传入 role +loop 遍历每条消息 +XBL->>BI : 渲染消息项 +BI-->>XBL : 传递 Bubble 属性/插槽 +end +``` + +**图示来源** + +- [frontend/antdx/bubble/list/bubble.list.tsx:18-46](file://frontend/antdx/bubble/list/bubble.list.tsx#L18-L46) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/antdx/bubble/list/utils.tsx:84-134](file://frontend/antdx/bubble/list/utils.tsx#L84-L134) +- [frontend/utils/patchSlots.ts:4-31](file://frontend/utils/patchSlots.ts#L4-L31) + +## 组件详解 + +### Bubble 组件 + +- 功能定位：对 @ant-design/x 的 Bubble 进行 Svelte 包装，统一处理插槽与函数式属性，支持可编辑态文案插槽。 +- 关键点： + - 插槽优先：当存在对应插槽时，优先渲染插槽内容；否则回退到属性值或函数。 + - 可编辑态：通过 editable 配置与插槽组合，支持自定义"确定/取消"文案。 + - 函数式属性：通过 useFunction 将传入的函数转换为可渲染的 React 组件。 + - 隐藏子节点：将 children 放入不可见容器，避免重复渲染。 + +```mermaid +flowchart TD +Start(["进入 Bubble 渲染"]) --> CheckEditable["检测 editable 配置与插槽"] +CheckEditable --> BuildEditable{"是否启用可编辑？"} +BuildEditable --> |是| MergeEditable["合并插槽与配置"] +BuildEditable --> |否| PassEditable["透传 editable"] +MergeEditable --> ResolveSlots["解析 header/footer/avatar/extra/content/loadingRender/contentRender"] +PassEditable --> ResolveSlots +ResolveSlots --> RenderX["渲染 @ant-design/x Bubble"] +RenderX --> End(["完成"]) +``` + +**图示来源** + +- [frontend/antdx/bubble/bubble.tsx:27-117](file://frontend/antdx/bubble/bubble.tsx#L27-L117) + +**章节来源** + +- [frontend/antdx/bubble/bubble.tsx:1-120](file://frontend/antdx/bubble/bubble.tsx#L1-L120) + +### BubbleList 列表组件 + +- 功能定位：消息列表容器，负责： + - 合并外部 items 与插槽 items + - 注入 Items 与 Role 上下文 + - 使用 useRole 解析角色映射 + - 将最终 items 交由 @ant-design/x 的 List 渲染 +- 关键点： + - 优先使用 props.items；若无则使用插槽 items/default + - 通过 renderItems 将插槽内容标准化为数组 + - 通过 useMemo 缓存 items，减少重渲染 + +```mermaid +sequenceDiagram +participant BL as "BubbleList" +participant Ctx as "Items/Role 上下文" +participant UR as "useRole" +participant RI as "renderItems" +participant XBL as "@ant-design/x List" +BL->>Ctx : withItemsContextProvider / withRoleItemsContextProvider +BL->>UR : useRole({ role }) +UR-->>BL : 返回 RoleType +BL->>RI : renderItems(resolvedSlotItems) +RI-->>BL : 返回标准化 items +BL->>XBL : 渲染 List(items, role) +``` + +**图示来源** + +- [frontend/antdx/bubble/list/bubble.list.tsx:18-46](file://frontend/antdx/bubble/list/bubble.list.tsx#L18-L46) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/antdx/bubble/list/utils.tsx:84-134](file://frontend/antdx/bubble/list/utils.tsx#L84-L134) +- [frontend/utils/renderItems.tsx:8-114](file://frontend/utils/renderItems.tsx#L8-L114) + +**章节来源** + +- [frontend/antdx/bubble/list/bubble.list.tsx:1-50](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L50) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/antdx/bubble/list/utils.tsx:1-135](file://frontend/antdx/bubble/list/utils.tsx#L1-L135) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + +### BubbleListItem 与 BubbleListRole + +- BubbleListItem：将 ItemHandler 注入到 Bubble，使单个消息项具备列表上下文能力。 +- BubbleListRole：将 RoleItemHandler 注入到角色配置，使角色项可被 useRole 解析为 RoleType。 + +```mermaid +classDiagram +class BubbleListItem { ++props : BubbleProps & ItemHandlerProps ++render() : ReactNode +} +class BubbleListRole { ++props : BubbleProps & ItemHandlerProps ++render() : ReactNode +} +class ItemHandler +class RoleItemHandler +BubbleListItem --> ItemHandler : "注入" +BubbleListRole --> RoleItemHandler : "注入" +``` + +**图示来源** + +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:7-11](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L7-L11) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:7-11](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L7-L11) +- [frontend/antdx/bubble/list/context.ts:3-10](file://frontend/antdx/bubble/list/context.ts#L3-L10) + +**章节来源** + +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:1-14](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L1-L14) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:1-14](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L1-L14) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) + +### useRole 角色解析工具 + +- 功能定位：将角色配置（字符串函数或对象）转换为 @ant-design/x 所需的 RoleType，并进行插槽补丁与索引注入。 +- 关键点： + - 支持默认键 defaultRoleKeys + - 支持 preProcess 与 defaultRolePostProcess 钩子 + - 自动将角色配置中的 header/footer/avatar/extra/loadingRender/contentRender 等插槽与内容进行补丁合并 + - 默认 contentRender 会将对象序列化为字符串 + +**更新** 优化了插槽补丁处理逻辑，移除了未使用的 unshift 行为，提升了渲染性能 + +```mermaid +flowchart TD +A["输入: role/defaultRoleKeys/preProcess/postProcess"] --> B["读取 Role 上下文 items"] +B --> C{"是否有 Role 配置？"} +C --> |有| D["渲染 Role 插槽并聚合为映射"] +C --> |无| E["使用空映射"] +D --> F["合并默认键与映射键"] +E --> F +F --> G["遍历每个键"] +G --> H{"键值为函数？"} +H --> |是| I["编译为函数并缓存"] +H --> |否| J["生成默认处理器(含插槽补丁/索引注入/默认 contentRender)"] +I --> K["应用 patchBubbleSlots 增强"] +K --> L["返回 RoleType"] +J --> L +``` + +**图示来源** + +- [frontend/antdx/bubble/list/utils.tsx:49-135](file://frontend/antdx/bubble/list/utils.tsx#L49-L135) +- [frontend/utils/patchSlots.ts:4-31](file://frontend/utils/patchSlots.ts#L4-L31) + +**章节来源** + +- [frontend/antdx/bubble/list/utils.tsx:1-135](file://frontend/antdx/bubble/list/utils.tsx#L1-L135) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) + +### Divider 分割线组件 + +- 作用：在对话气泡之间插入分割线，用于视觉分段与节奏控制。 +- 使用场景：多轮对话、模块化展示、时间/主题切换提示等。 +- 注意：Divider 作为独立组件，通常与 BubbleList 协作，通过插槽或布局控制其出现位置与样式。 + +（本节为概念性说明，不直接分析具体源码） + +## 依赖关系分析 + +- 组件耦合： + - Bubble 仅作为包装层，依赖 @ant-design/x 的原生能力，耦合度低，便于升级替换。 + - BubbleList 依赖上下文与工具函数，职责清晰，耦合集中在 useRole 与 renderItems。 +- 上下文与工具： + - createItemsContext 提供 Items/Role 两套上下文，分别服务于列表项与角色项。 + - useRole 是角色解析的核心，承担了从配置到渲染参数的转换职责。 + - patchSlots 提供插槽补丁增强功能，支持参数传递与函数组合。 +- 外部依赖： + - @ant-design/x：提供 Bubble/List/Role 类型与渲染能力 + - @svelte-preprocess-react：桥接 Svelte 与 React 插槽 + - @utils/\*：提供渲染与函数封装工具 + +```mermaid +graph LR +Bubble["Bubble 组件"] --> ADX["@ant-design/x"] +BubbleList["BubbleList 组件"] --> ADX +BubbleList --> Ctx["上下文(Items/Role)"] +BubbleList --> UR["useRole 工具"] +BubbleList --> RI["renderItems 工具"] +UR --> PS["patchSlots 增强"] +UR --> Utils["@utils/* 工具集"] +Bubble --> Slots["插槽/函数式属性"] +PS --> PatchUtils["参数传递与函数组合"] +RI --> SlotRender["插槽渲染与标准化"] +``` + +**图示来源** + +- [frontend/antdx/bubble/bubble.tsx:1-120](file://frontend/antdx/bubble/bubble.tsx#L1-L120) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-50](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L50) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/antdx/bubble/list/utils.tsx:1-135](file://frontend/antdx/bubble/list/utils.tsx#L1-L135) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + +**章节来源** + +- [frontend/antdx/bubble/bubble.tsx:1-120](file://frontend/antdx/bubble/bubble.tsx#L1-L120) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-50](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L50) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/antdx/bubble/list/utils.tsx:1-135](file://frontend/antdx/bubble/list/utils.tsx#L1-L135) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + +## 性能与可维护性 + +- 性能优化建议： + - 使用 useMemo 缓存 BubbleList 的 items，避免不必要的重渲染。 + - 在 useRole 中合理设置依赖数组，避免重复计算角色映射。 + - 将大型插槽内容拆分为可复用组件，减少闭包与对象创建。 + - **优化** 移除了未使用的 unshift 行为，减少了不必要的参数重组开销。 +- 可维护性建议： + - 将角色配置集中管理，避免散落于多处。 + - 使用 preProcess/postProcess 钩子统一处理消息预处理与后处理，降低模板复杂度。 + - 保持 Bubble 的插槽命名一致性，便于团队协作与文档维护。 + +**更新** 通过移除未使用的 unshift 行为，进一步优化了插槽补丁处理的性能表现 + +（本节为通用建议，不直接分析具体源码） + +## 故障排查指南 + +- 插槽未生效 + - 检查插槽名称是否与组件约定一致（如 avatar/header/footer/extra/content 等） + - 确认 Bubble/BubbleList 是否正确包裹插槽 +- 角色配置无效 + - 确认 BubbleListRole 是否正确注入 RoleItemHandler + - 检查 useRole 的 defaultRoleKeys 与 preProcess/postProcess 是否按预期工作 +- 可编辑文案不显示 + - 确认 editable 配置与插槽是否同时存在，插槽优先级更高 + - 检查 editable.okText/editable.cancelText 的插槽是否正确传入 +- 列表渲染异常 + - 确认 BubbleListItem 是否正确注入 ItemHandler + - 检查 items 与插槽 items 的数据结构是否符合要求 +- **新增** 插槽参数传递问题 + - 检查 patchSlots 中的 unshift 配置是否正确设置 + - 确认插槽函数的参数顺序与预期一致 + +**章节来源** + +- [frontend/antdx/bubble/bubble.tsx:36-64](file://frontend/antdx/bubble/bubble.tsx#L36-L64) +- [frontend/antdx/bubble/list/bubble.list.tsx:18-46](file://frontend/antdx/bubble/list/bubble.list.tsx#L18-L46) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:7-11](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L7-L11) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:7-11](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L7-L11) +- [frontend/antdx/bubble/list/utils.tsx:84-134](file://frontend/antdx/bubble/list/utils.tsx#L84-L134) +- [frontend/utils/patchSlots.ts:16-29](file://frontend/utils/patchSlots.ts#L16-L29) + +## 结论 + +Bubble 对话气泡组件体系以"包装层 + 上下文 + 工具函数"为核心设计，既保留了 @ant-design/x 的强大能力，又提供了灵活的插槽与角色化扩展。通过 BubbleList、BubbleListItem、BubbleListRole 与 useRole 的协同，开发者可以快速构建复杂、可定制的对话界面，并在样式、交互与可维护性之间取得良好平衡。 + +**更新** 最新的性能优化通过移除未使用的 unshift 行为，进一步提升了插槽处理的效率，为大规模对话场景提供了更好的性能保障。 + +## 附录：使用示例与最佳实践 + +- 基本对话气泡 + - 使用 Bubble 组件承载消息内容，通过 content 插槽或属性传入文本/富文本 + - 通过 avatar/header/footer/extra 等插槽添加头像、标题、操作区与额外信息 +- 复杂消息格式 + - 使用 contentRender 对象/数组进行结构化渲染 + - 通过 preProcess/postProcess 钩子统一处理消息字段与样式 +- 自定义样式 + - 通过 role 映射为不同角色配置，结合插槽补丁实现差异化样式 + - 使用 Divider 在关键节点插入分割线，提升可读性 +- 最佳实践 + - 将角色配置集中管理，避免分散在模板中 + - 使用 useMemo 缓存 items 与角色映射，减少重渲染 + - 保持插槽命名规范，便于团队协作与文档维护 + - **优化建议** 在使用插槽参数传递时，合理利用 patchSlots 的增强功能，避免不必要的参数重组 + +（本节为概念性说明，不直接分析具体源码） diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble \347\273\204\344\273\266\346\246\202\350\247\210.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble \347\273\204\344\273\266\346\246\202\350\247\210.md" new file mode 100644 index 00000000..787a1d3f --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble \347\273\204\344\273\266\346\246\202\350\247\210.md" @@ -0,0 +1,359 @@ +# Bubble 组件概览 + + +**本文档引用的文件** +- [frontend/antdx/bubble/Index.svelte](file://frontend/antdx/bubble/Index.svelte) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [frontend/antdx/bubble/list/Index.svelte](file://frontend/antdx/bubble/list/Index.svelte) +- [frontend/antdx/bubble/list/bubble.list.tsx](file://frontend/antdx/bubble/list/bubble.list.tsx) +- [frontend/antdx/bubble/system/Index.svelte](file://frontend/antdx/bubble/system/Index.svelte) +- [frontend/antdx/bubble/system/bubble.system.tsx](file://frontend/antdx/bubble/system/bubble.system.tsx) +- [frontend/antdx/bubble/divider/Index.svelte](file://frontend/antdx/bubble/divider/Index.svelte) +- [frontend/antdx/bubble/divider/bubble.divider.tsx](file://frontend/antdx/bubble/divider/bubble.divider.tsx) +- [backend/modelscope_studio/components/antdx/bubble/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/__init__.py) +- [backend/modelscope_studio/components/antdx/bubble/list/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Bubble 是面向机器学习对话场景的可视化气泡组件，基于 Ant Design X 的 Bubble 能力构建，提供消息气泡的渲染、编辑、打字动画、内容分发等能力，并通过 Gradio/ModelScope 生态实现前后端一体化开发体验。该组件族包含单个气泡、气泡列表、系统消息分隔线以及系统型气泡等子组件，覆盖从基础展示到复杂交互的多种对话形态。 + +## 项目结构 + +Bubble 组件由前端 Svelte 包装层与后端 Python 组件层共同构成，采用“前端 React 组件 + 后端 Gradio 组件”的双层设计，确保在 Python 环境中以声明式方式使用 Ant Design X 的能力。 + +```mermaid +graph TB +subgraph "前端 Svelte 层" +A["Index.svelte
包装器入口"] +B["bubble.tsx
Sveltify 包装"] +C["list/Index.svelte
列表包装器"] +D["list/bubble.list.tsx
列表实现"] +E["system/Index.svelte
系统气泡包装器"] +F["system/bubble.system.tsx
系统气泡实现"] +G["divider/Index.svelte
分隔线包装器"] +H["divider/bubble.divider.tsx
分隔线实现"] +end +subgraph "后端 Python 层" +P1["antdx/bubble/__init__.py
主组件类"] +P2["antdx/bubble/list/__init__.py
列表组件类"] +end +A --> B +C --> D +E --> F +G --> H +P1 --> A +P2 --> C +``` + +图表来源 + +- [frontend/antdx/bubble/Index.svelte:1-78](file://frontend/antdx/bubble/Index.svelte#L1-L78) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/bubble/list/Index.svelte:1-66](file://frontend/antdx/bubble/list/Index.svelte#L1-L66) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-49](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L49) +- [frontend/antdx/bubble/system/Index.svelte:1-64](file://frontend/antdx/bubble/system/Index.svelte#L1-L64) +- [frontend/antdx/bubble/system/bubble.system.tsx:1-27](file://frontend/antdx/bubble/system/bubble.system.tsx#L1-L27) +- [frontend/antdx/bubble/divider/Index.svelte:1-66](file://frontend/antdx/bubble/divider/Index.svelte#L1-L66) +- [frontend/antdx/bubble/divider/bubble.divider.tsx:1-27](file://frontend/antdx/bubble/divider/bubble.divider.tsx#L1-L27) +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:1-135](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L1-L135) +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:1-84](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L1-L84) + +章节来源 + +- [frontend/antdx/bubble/Index.svelte:1-78](file://frontend/antdx/bubble/Index.svelte#L1-L78) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/bubble/list/Index.svelte:1-66](file://frontend/antdx/bubble/list/Index.svelte#L1-L66) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-49](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L49) +- [frontend/antdx/bubble/system/Index.svelte:1-64](file://frontend/antdx/bubble/system/Index.svelte#L1-L64) +- [frontend/antdx/bubble/system/bubble.system.tsx:1-27](file://frontend/antdx/bubble/system/bubble.system.tsx#L1-L27) +- [frontend/antdx/bubble/divider/Index.svelte:1-66](file://frontend/antdx/bubble/divider/Index.svelte#L1-L66) +- [frontend/antdx/bubble/divider/bubble.divider.tsx:1-27](file://frontend/antdx/bubble/divider/bubble.divider.tsx#L1-L27) +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:1-135](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L1-L135) +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:1-84](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L1-L84) + +## 核心组件 + +- 单个气泡组件：负责渲染一条消息气泡，支持头像、标题、内容、额外操作、底部栏、加载与内容自定义渲染、可编辑模式、打字动画等。 +- 气泡列表组件：用于承载多条气泡，支持角色分组、自动滚动、插槽注入 items/role 等。 +- 系统气泡组件：用于渲染系统提示或状态信息，强调语义化展示。 +- 分隔线组件：用于在对话中插入分隔提示，如时间分隔、会话切换提示等。 + +章节来源 + +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-49](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L49) +- [frontend/antdx/bubble/system/bubble.system.tsx:1-27](file://frontend/antdx/bubble/system/bubble.system.tsx#L1-L27) +- [frontend/antdx/bubble/divider/bubble.divider.tsx:1-27](file://frontend/antdx/bubble/divider/bubble.divider.tsx#L1-L27) + +## 架构总览 + +Bubble 组件采用“Svelte 包装 + Ant Design X React 组件 + Gradio/ModelScope 后端桥接”的三层架构。前端通过 Svelte 的 importComponent 实现按需加载，使用 sveltify 将 React 组件桥接到 Svelte；后端通过 ModelScopeLayoutComponent 抽象，统一处理事件绑定、插槽映射与属性透传。 + +```mermaid +sequenceDiagram +participant Py as "Python 后端组件" +participant Svelte as "Svelte 包装器" +participant React as "Ant Design X React 组件" +participant User as "调用方" +User->>Py : 初始化组件参数与事件 +Py->>Svelte : 渲染前端包装器 +Svelte->>Svelte : importComponent 动态导入 +Svelte->>React : 传递 props 与 slots +React-->>Svelte : 渲染结果 +Svelte-->>User : 输出最终 DOM +``` + +图表来源 + +- [frontend/antdx/bubble/Index.svelte:10-77](file://frontend/antdx/bubble/Index.svelte#L10-L77) +- [frontend/antdx/bubble/bubble.tsx:27-116](file://frontend/antdx/bubble/bubble.tsx#L27-L116) +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:13-54](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L13-L54) + +## 详细组件分析 + +### 单个气泡组件（Bubble） + +- 设计理念：以 Ant Design X 的 Bubble 为核心，提供丰富的插槽与回调扩展点，满足对话场景中对头像、标题、内容、操作区、加载态与编辑态的多样化需求。 +- 关键特性 + - 插槽体系：avatar、content、header、footer、extra、loadingRender、contentRender、editable.okText、editable.cancelText。 + - 编辑能力：支持 editable 布尔开关与配置对象，结合插槽实现自定义文案与渲染。 + - 打字动画：typing 支持布尔与配置对象，配合 typingComplete 事件完成动画生命周期管理。 + - 自定义渲染：loadingRender 与 contentRender 支持函数或插槽注入，灵活控制加载态与内容渲染。 + - 头像与额外区域：avatar、extra 支持函数或插槽，便于扩展图标、操作按钮等。 +- 数据流与渲染流程 + +```mermaid +flowchart TD +Start(["进入 Bubble 渲染"]) --> CheckEditable{"是否启用编辑?"} +CheckEditable --> |是| MergeEditable["合并 editable 配置与插槽"] +CheckEditable --> |否| PassEditable["直接透传 editable"] +MergeEditable --> RenderAvatar{"是否有 avatar 插槽?"} +PassEditable --> RenderAvatar +RenderAvatar --> |有| SlotAvatar["渲染 avatar 插槽"] +RenderAvatar --> |无| FuncAvatar["渲染 avatar 函数/属性"] +FuncAvatar --> RenderHeader{"是否有 header 插槽?"} +SlotAvatar --> RenderHeader +RenderHeader --> |有| SlotHeader["渲染 header 插槽"] +RenderHeader --> |无| FuncHeader["渲染 header 函数/属性"] +FuncHeader --> RenderContent{"是否有 content 插槽?"} +SlotHeader --> RenderContent +RenderContent --> |有| SlotContent["渲染 content 插槽"] +RenderContent --> |无| TextContent["渲染文本内容"] +TextContent --> RenderFooter{"是否有 footer 插槽?"} +SlotContent --> RenderFooter +RenderFooter --> |有| SlotFooter["渲染 footer 插槽"] +RenderFooter --> |无| FuncFooter["渲染 footer 函数/属性"] +FuncFooter --> RenderExtra{"是否有 extra 插槽?"} +SlotFooter --> RenderExtra +RenderExtra --> |有| SlotExtra["渲染 extra 插槽"] +RenderExtra --> |无| FuncExtra["渲染 extra 函数/属性"] +FuncExtra --> RenderLoading{"是否有 loadingRender 插槽?"} +SlotExtra --> RenderLoading +RenderLoading --> |有| SlotLoading["渲染 loadingRender 插槽"] +RenderLoading --> |无| FuncLoading["渲染 loadingRender 函数"] +FuncLoading --> RenderContentRender{"是否有 contentRender 插槽?"} +SlotLoading --> RenderContentRender +RenderContentRender --> |有| SlotContentRender["渲染 contentRender 插槽"] +RenderContentRender --> |无| FuncContentRender["渲染 contentRender 函数"] +FuncContentRender --> End(["完成渲染"]) +``` + +图表来源 + +- [frontend/antdx/bubble/bubble.tsx:27-116](file://frontend/antdx/bubble/bubble.tsx#L27-L116) + +章节来源 + +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:21-54](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L21-L54) + +### 气泡列表组件（BubbleList） + +- 设计理念：在单个气泡基础上，提供批量渲染与角色分组能力，适合多轮对话、历史消息列表等场景。 +- 关键特性 + - 角色分组：通过 role 插槽或属性定义不同角色（如用户、系统、助手）的展示策略。 + - 插槽 items/default：支持通过插槽注入列表项，或直接传入 items 数组。 + - 自动滚动：可配置自动滚动至最新消息，提升用户体验。 + - 上下文注入：通过 useItems 与 useRole 解析插槽与默认值，保证灵活性与一致性。 +- 列表渲染流程 + +```mermaid +sequenceDiagram +participant Caller as "调用方" +participant ListWrapper as "BubbleList 包装器" +participant ListImpl as "BubbleList 实现" +participant Items as "useItems/useRole" +participant XList as "Ant Design X List" +Caller->>ListWrapper : 传入 items/role 与属性 +ListWrapper->>ListImpl : 透传 props 与 slots +ListImpl->>Items : 解析 items/default 与 role +Items-->>ListImpl : 返回解析后的 items 与 role +ListImpl->>XList : 渲染列表并绑定自动滚动 +XList-->>Caller : 输出列表 DOM +``` + +图表来源 + +- [frontend/antdx/bubble/list/Index.svelte:10-65](file://frontend/antdx/bubble/list/Index.svelte#L10-L65) +- [frontend/antdx/bubble/list/bubble.list.tsx:13-46](file://frontend/antdx/bubble/list/bubble.list.tsx#L13-L46) + +章节来源 + +- [frontend/antdx/bubble/list/Index.svelte:1-66](file://frontend/antdx/bubble/list/Index.svelte#L1-L66) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-49](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L49) +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:12-30](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L12-L30) + +### 系统气泡组件（BubbleSystem） + +- 设计理念：用于展示系统级提示或状态信息，强调语义化与一致性，常用于“系统通知”“会话开始”“模型切换”等场景。 +- 关键特性 + - 内容插槽：content 插槽优先于属性 content，便于动态渲染。 + - 语义化展示：基于 Ant Design X 的 System 类型，统一风格与行为。 +- 渲染流程 + +```mermaid +flowchart TD +Enter(["进入 System 渲染"]) --> HasSlot{"是否存在 content 插槽?"} +HasSlot --> |是| RenderSlot["渲染插槽内容"] +HasSlot --> |否| RenderProp["渲染属性内容"] +RenderSlot --> Done(["完成渲染"]) +RenderProp --> Done +``` + +图表来源 + +- [frontend/antdx/bubble/system/Index.svelte:10-63](file://frontend/antdx/bubble/system/Index.svelte#L10-L63) +- [frontend/antdx/bubble/system/bubble.system.tsx:12-23](file://frontend/antdx/bubble/system/bubble.system.tsx#L12-L23) + +章节来源 + +- [frontend/antdx/bubble/system/Index.svelte:1-64](file://frontend/antdx/bubble/system/Index.svelte#L1-L64) +- [frontend/antdx/bubble/system/bubble.system.tsx:1-27](file://frontend/antdx/bubble/system/bubble.system.tsx#L1-L27) + +### 分隔线组件（BubbleDivider） + +- 设计理念：在对话中插入分隔提示，如时间戳、会话切换等，帮助用户理解对话结构。 +- 关键特性 + - 内容插槽：content 插槽优先于属性 content。 + - 语义化分隔：基于 Ant Design X 的 Divider 类型，保持一致的视觉与交互。 +- 渲染流程 + +```mermaid +flowchart TD +Enter(["进入 Divider 渲染"]) --> HasSlot{"是否存在 content 插槽?"} +HasSlot --> |是| RenderSlot["渲染插槽内容"] +HasSlot --> |否| RenderProp["渲染属性内容"] +RenderSlot --> Done(["完成渲染"]) +RenderProp --> Done +``` + +图表来源 + +- [frontend/antdx/bubble/divider/Index.svelte:10-65](file://frontend/antdx/bubble/divider/Index.svelte#L10-L65) +- [frontend/antdx/bubble/divider/bubble.divider.tsx:12-23](file://frontend/antdx/bubble/divider/bubble.divider.tsx#L12-L23) + +章节来源 + +- [frontend/antdx/bubble/divider/Index.svelte:1-66](file://frontend/antdx/bubble/divider/Index.svelte#L1-L66) +- [frontend/antdx/bubble/divider/bubble.divider.tsx:1-27](file://frontend/antdx/bubble/divider/bubble.divider.tsx#L1-L27) + +## 依赖关系分析 + +- 前端依赖 + - @svelte-preprocess-react：提供 importComponent、processProps、slot 上下文等能力，实现 Svelte 与 React 的桥接。 + - @ant-design/x：提供 Bubble、List、System、Divider 等核心组件与类型定义。 + - @utils/\*：提供 useFunction、renderParamsSlot、renderItems、上下文 Provider 等工具。 +- 后端依赖 + - ModelScopeLayoutComponent：统一抽象前端组件的渲染、事件绑定与属性透传。 + - Gradio 事件系统：typing、typing_complete、edit_confirm、edit_cancel 等事件绑定。 + +```mermaid +graph LR +Svelte["Svelte 包装器"] --> Utils["@utils/* 工具"] +Svelte --> ADX["@ant-design/x"] +Svelte --> Preprocess["@svelte-preprocess-react"] +Py["Python 组件"] --> Layout["ModelScopeLayoutComponent"] +Py --> Events["Gradio 事件系统"] +Py --> Svelte +``` + +图表来源 + +- [frontend/antdx/bubble/Index.svelte:1-78](file://frontend/antdx/bubble/Index.svelte#L1-L78) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:1-135](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L1-L135) + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:1-135](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L1-L135) +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:1-84](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L1-L84) + +## 性能考虑 + +- 按需加载：前端通过 importComponent 实现动态导入，避免初始包体过大，提升首屏性能。 +- 插槽与函数渲染：合理使用插槽与函数渲染，减少不必要的重复渲染；对 contentRender/loadingRender 使用稳定的函数引用，避免重渲染抖动。 +- 列表优化：BubbleList 使用 useMemo 与 renderItems，确保 items 变更时仅重新计算必要部分；auto_scroll 在大量数据时应谨慎开启，避免频繁滚动导致卡顿。 +- 事件绑定：typing_complete、edit_confirm、edit_cancel 等事件仅在需要时绑定，避免无意义的回调触发。 + +## 故障排查指南 + +- 插槽未生效 + - 检查插槽名称是否正确（如 avatar、content、header、footer、extra、loadingRender、contentRender、editable.okText、editable.cancelText）。 + - 确认插槽优先级高于属性，若同时设置属性与插槽，插槽优先。 +- 编辑功能不工作 + - 确认 editable 为布尔或配置对象，且存在 cancelText/okText 插槽或属性。 + - 检查 edit_confirm、edit_cancel 事件是否正确绑定。 +- 打字动画异常 + - 确认 typing 为布尔或配置对象；若未设置 typing，typing_complete 会在渲染完成后立即触发。 +- 列表滚动问题 + - 检查 auto_scroll 是否开启；在大量消息时建议延迟滚动或节流。 +- 样式与主题冲突 + - 使用 root_class_name 或 class_names/styles 注入自定义样式；注意与 Ant Design X 主题变量的兼容性。 + +章节来源 + +- [frontend/antdx/bubble/bubble.tsx:27-116](file://frontend/antdx/bubble/bubble.tsx#L27-L116) +- [frontend/antdx/bubble/list/bubble.list.tsx:13-46](file://frontend/antdx/bubble/list/bubble.list.tsx#L13-L46) +- [backend/modelscope_studio/components/antdx/bubble/**init**.py:21-54](file://backend/modelscope_studio/components/antdx/bubble/__init__.py#L21-L54) +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:19-30](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L19-L30) + +## 结论 + +Bubble 组件族以 Ant Design X 为基础，结合 Svelte 与 Gradio/ModelScope 的生态能力，提供了从单条消息到多轮对话列表的完整解决方案。其插槽化设计与事件系统使得在机器学习对话场景中能够灵活地呈现不同类型的提示与消息，同时保持良好的性能与可维护性。 + +## 附录 + +### 基本使用示例（步骤说明） + +- 单个气泡 + - 设置 content 文本或通过 content 插槽注入复杂内容。 + - 如需编辑，设置 editable 并提供 editable.okText/ editable.cancelText 插槽或属性。 + - 如需打字动画，设置 typing；监听 typing_complete 完成动画。 +- 气泡列表 + - 通过 items/default 插槽或 items 属性传入消息数组。 + - 使用 role 插槽或属性定义角色分组。 + - 开启 auto_scroll 以自动滚动至最新消息。 +- 系统气泡与分隔线 + - 使用 System 组件展示系统提示；使用 Divider 组件插入分隔提示。 + - 两者均支持 content 插槽优先策略。 + +### 最佳实践 + +- 优先使用插槽而非内联字符串，提升可维护性与可测试性。 +- 对频繁变化的内容使用 memo 化策略，减少重渲染。 +- 在对话密集场景中，合理控制自动滚动与动画效果，避免性能问题。 +- 使用 root_class_name/class_names/styles 进行主题定制，确保与整体设计一致。 diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.Divider \345\210\206\345\211\262\347\272\277\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.Divider \345\210\206\345\211\262\347\272\277\347\273\204\344\273\266.md" new file mode 100644 index 00000000..6d1e8336 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.Divider \345\210\206\345\211\262\347\272\277\347\273\204\344\273\266.md" @@ -0,0 +1,231 @@ +# Bubble.Divider 分割线组件 + + +**本文档引用的文件** +- [frontend/antdx/bubble/divider/Index.svelte](file://frontend/antdx/bubble/divider/Index.svelte) +- [frontend/antdx/bubble/divider/bubble.divider.tsx](file://frontend/antdx/bubble/divider/bubble.divider.tsx) +- [backend/modelscope_studio/components/antdx/bubble/divider/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/divider/__init__.py) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [docs/components/antdx/bubble/README.md](file://docs/components/antdx/bubble/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Bubble.Divider 是对话气泡中的时间分隔与内容分区组件，用于在长对话中清晰地划分不同时间段或逻辑区块，提升可读性与用户体验。它基于 Ant Design X 的 Bubble.Divider 能力，通过内容插槽支持自定义标题/标签，并具备可见性控制与样式透传能力。 + +## 项目结构 + +Bubble.Divider 位于 antdx 气泡体系下，采用“后端 Python 组件 + 前端 Svelte 包装 + React 组件桥接”的分层设计： + +- 后端组件：负责属性定义、可见性与样式透传、生命周期钩子（如预处理/后处理） +- 前端包装：Svelte 组件负责按需加载、属性合并、类名与样式注入、插槽渲染 +- React 组件桥接：将 Ant Design X 的 Bubble.Divider 能力以 Svelte 形式暴露 + +```mermaid +graph TB +subgraph "后端" +PY["Python 组件
antdx.bubble.divider.__init__.py"] +end +subgraph "前端包装层" +IDX["Svelte 包装
bubble.divider/Index.svelte"] +end +subgraph "React 桥接层" +BD["React 组件桥接
bubble.divider.tsx"] +XBD["Ant Design X Bubble.Divider"] +end +PY --> IDX +IDX --> BD +BD --> XBD +``` + +图表来源 + +- [frontend/antdx/bubble/divider/Index.svelte:1-66](file://frontend/antdx/bubble/divider/Index.svelte#L1-L66) +- [frontend/antdx/bubble/divider/bubble.divider.tsx:1-27](file://frontend/antdx/bubble/divider/bubble.divider.tsx#L1-L27) +- [backend/modelscope_studio/components/antdx/bubble/divider/**init**.py:1-95](file://backend/modelscope_studio/components/antdx/bubble/divider/__init__.py#L1-L95) + +章节来源 + +- [frontend/antdx/bubble/divider/Index.svelte:1-66](file://frontend/antdx/bubble/divider/Index.svelte#L1-L66) +- [frontend/antdx/bubble/divider/bubble.divider.tsx:1-27](file://frontend/antdx/bubble/divider/bubble.divider.tsx#L1-L27) +- [backend/modelscope_studio/components/antdx/bubble/divider/**init**.py:1-95](file://backend/modelscope_studio/components/antdx/bubble/divider/__init__.py#L1-L95) + +## 核心组件 + +- 后端 Python 组件：定义 Bubble.Divider 的属性集合（如可见性、元素 ID/类名/样式、额外属性等），并声明前端目录映射与渲染行为 +- 前端 Svelte 包装：按需导入 React 桥接组件，合并属性、处理可见性、注入类名与样式、透传插槽 +- React 桥接：将 Ant Design X 的 Bubble.Divider 能力以 Svelte 可用的形式封装，支持内容插槽 + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/divider/**init**.py:1-95](file://backend/modelscope_studio/components/antdx/bubble/divider/__init__.py#L1-L95) +- [frontend/antdx/bubble/divider/Index.svelte:1-66](file://frontend/antdx/bubble/divider/Index.svelte#L1-L66) +- [frontend/antdx/bubble/divider/bubble.divider.tsx:1-27](file://frontend/antdx/bubble/divider/bubble.divider.tsx#L1-L27) + +## 架构总览 + +Bubble.Divider 的调用链路如下： + +- 后端组件接收属性并决定是否渲染 +- 前端 Svelte 包装根据 visible 决定是否挂载 +- React 桥接组件将 props 透传给 Ant Design X 的 Bubble.Divider +- 插槽系统支持 content 内容与 children 渲染 + +```mermaid +sequenceDiagram +participant Py as "后端组件" +participant Svt as "Svelte 包装" +participant Rct as "React 桥接" +participant X as "Ant Design X Bubble.Divider" +Py->>Svt : 传递属性与可见性 +Svt->>Svt : 处理可见性(visible) +Svt->>Rct : 透传属性与样式 +Rct->>X : 渲染 Bubble.Divider +X-->>Rct : 组件输出 +Rct-->>Svt : 返回渲染结果 +Svt-->>Py : 完成一次渲染 +``` + +图表来源 + +- [frontend/antdx/bubble/divider/Index.svelte:49-65](file://frontend/antdx/bubble/divider/Index.svelte#L49-L65) +- [frontend/antdx/bubble/divider/bubble.divider.tsx:12-24](file://frontend/antdx/bubble/divider/bubble.divider.tsx#L12-L24) + +## 详细组件分析 + +### 属性与配置 + +- 可见性控制：visible 控制组件是否渲染 +- 元素标识：elem_id、elem_classes、elem_style 用于定位与样式定制 +- 额外属性：additionalProps 透传给底层组件 +- 内容插槽：content 插槽优先于 props.content +- 子节点：children 作为后备内容兜底 + +章节来源 + +- [frontend/antdx/bubble/divider/Index.svelte:14-44](file://frontend/antdx/bubble/divider/Index.svelte#L14-L44) +- [frontend/antdx/bubble/divider/bubble.divider.tsx:7-24](file://frontend/antdx/bubble/divider/bubble.divider.tsx#L7-L24) + +### 渲染机制与显示条件 + +- 可见性判断：仅当 visible 为真时才渲染 React 组件 +- 动态导入：使用 importComponent 实现按需加载，降低首屏负担 +- 类名与样式：通过 cls 与内联样式注入，确保与主题一致 +- 插槽渲染：优先使用 content 插槽，其次使用 props.content，最后为空字符串兜底 + +```mermaid +flowchart TD +Start(["进入渲染"]) --> CheckVisible{"visible 为真？"} +CheckVisible -- 否 --> Skip["跳过渲染"] +CheckVisible -- 是 --> Load["动态导入 React 组件"] +Load --> MergeProps["合并属性与样式"] +MergeProps --> Render["渲染 Bubble.Divider"] +Render --> End(["完成"]) +Skip --> End +``` + +图表来源 + +- [frontend/antdx/bubble/divider/Index.svelte:49-65](file://frontend/antdx/bubble/divider/Index.svelte#L49-L65) + +### 样式定制与布局影响 + +- 样式透传：elem_style 与 elem_classes 直接应用于根节点，便于覆盖默认主题 +- 主题一致性：通过 Ant Design X 的主题系统保证视觉统一 +- 布局影响：作为气泡列表中的分隔元素，建议保持紧凑间距与清晰的视觉层级，避免过度装饰 + +章节来源 + +- [frontend/antdx/bubble/divider/Index.svelte:52-53](file://frontend/antdx/bubble/divider/Index.svelte#L52-L53) + +### 与消息时间戳的关系与最佳使用场景 + +- 时间分隔：适合在长时间对话中插入“今日”“昨天”等时间分组提示 +- 内容分区：用于区分不同话题、角色切换或状态变更 +- 最佳实践： + - 避免过于频繁地插入分割线，以免打断阅读节奏 + - 将时间戳与分割线结合使用，增强可读性 + - 使用简洁明了的内容文本，避免冗长 + +章节来源 + +- [docs/components/antdx/bubble/README.md:1-13](file://docs/components/antdx/bubble/README.md#L1-L13) + +### 使用示例（路径指引） + +以下为常见使用场景的代码片段路径（请在对应文件中查看具体实现）： + +- 在气泡列表中插入时间分隔：[frontend/antdx/bubble/list/bubble.list.tsx:1-48](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L48) +- 在聊天机器人中使用分割线：[docs/components/antdx/bubble/README.md:1-13](file://docs/components/antdx/bubble/README.md#L1-L13) + +章节来源 + +- [frontend/antdx/bubble/list/bubble.list.tsx:1-48](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L48) +- [docs/components/antdx/bubble/README.md:1-13](file://docs/components/antdx/bubble/README.md#L1-L13) + +## 依赖关系分析 + +- 后端依赖：ModelScopeLayoutComponent 提供通用布局与渲染能力 +- 前端依赖：@svelte-preprocess-react 提供 Svelte 与 React 的桥接能力；classnames 用于类名拼接 +- React 依赖：Ant Design X 的 Bubble.Divider 提供核心渲染能力 + +```mermaid +graph LR +PY["Python 组件"] --> IDX["Svelte 包装"] +IDX --> BD["React 桥接"] +BD --> XBD["Ant Design X Bubble.Divider"] +IDX --> CLS["classnames"] +IDX --> PRE["svelte-preprocess-react"] +``` + +图表来源 + +- [frontend/antdx/bubble/divider/Index.svelte:1-8](file://frontend/antdx/bubble/divider/Index.svelte#L1-L8) +- [frontend/antdx/bubble/divider/bubble.divider.tsx:1-5](file://frontend/antdx/bubble/divider/bubble.divider.tsx#L1-L5) + +章节来源 + +- [frontend/antdx/bubble/divider/Index.svelte:1-8](file://frontend/antdx/bubble/divider/Index.svelte#L1-L8) +- [frontend/antdx/bubble/divider/bubble.divider.tsx:1-5](file://frontend/antdx/bubble/divider/bubble.divider.tsx#L1-L5) + +## 性能考虑 + +- 按需加载：通过动态导入减少初始包体体积 +- 条件渲染：visible 为假时不渲染，避免无意义的 DOM 占用 +- 属性最小化：仅透传必要属性，减少 React 层级开销 +- 插槽优化：优先使用插槽而非大对象 props，降低重渲染概率 + +## 故障排除指南 + +- 组件不显示：检查 visible 是否为真；确认 additionalProps 未覆盖关键样式 +- 样式异常：核对 elem_id/ elem_classes/ elem_style 是否正确传入；确认主题变量生效 +- 内容不显示：确认 content 插槽或 props.content 是否设置；children 仅作为兜底 +- 运行时错误：检查 Ant Design X 版本兼容性；确保 @svelte-preprocess-react 正常工作 + +章节来源 + +- [frontend/antdx/bubble/divider/Index.svelte:49-65](file://frontend/antdx/bubble/divider/Index.svelte#L49-L65) +- [frontend/antdx/bubble/divider/bubble.divider.tsx:12-24](file://frontend/antdx/bubble/divider/bubble.divider.tsx#L12-L24) + +## 结论 + +Bubble.Divider 通过简洁的属性与强大的插槽系统，在对话气泡中提供了高效的时间分隔与内容分区能力。其按需加载与条件渲染策略兼顾了性能与可用性，适合在长对话场景中提升用户阅读体验。建议与时间戳配合使用，并遵循适度原则，避免过度分割。 + +## 附录 + +- 相关组件参考 + - 气泡容器：[frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) + - 文档示例入口：[docs/components/antdx/bubble/README.md:1-13](file://docs/components/antdx/bubble/README.md#L1-L13) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.Item \346\266\210\346\201\257\351\241\271\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.Item \346\266\210\346\201\257\351\241\271\347\273\204\344\273\266.md" new file mode 100644 index 00000000..d13c052e --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.Item \346\266\210\346\201\257\351\241\271\347\273\204\344\273\266.md" @@ -0,0 +1,390 @@ +# Bubble.Item 消息项组件 + + +**本文档引用的文件** +- [frontend/antdx/bubble/list/item/Item.svelte](file://frontend/antdx/bubble/list/item/Item.svelte) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [frontend/antdx/bubble/list/bubble.list.tsx](file://frontend/antdx/bubble/list/bubble.list.tsx) +- [frontend/antdx/bubble/list/context.ts](file://frontend/antdx/bubble/list/context.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Bubble.Item 是 Modelscope Studio 前端组件体系中用于表示“单条消息”的基础单元，通常配合 Bubble.List 使用以渲染消息列表。它封装了 Ant Design X 的 Bubble 组件能力，并通过统一的上下文系统将消息项的属性、插槽、事件回调等进行标准化处理，支持文本、图片、代码块等多种内容格式，以及可编辑、加载态、头部/尾部/额外区域等扩展能力。 + +本组件的关键特性包括： + +- 作为消息项的最小渲染单元，负责将内容、头像、操作区等组合展示 +- 支持多种内容格式：文本、富文本、图片、代码块等 +- 提供消息状态：加载态、可编辑态、打字机态等 +- 与 Bubble.List 协作，基于上下文系统完成数据绑定与渲染 +- 支持插槽化扩展：avatar、header、footer、extra、content、contentRender、loadingRender 等 + +## 项目结构 + +Bubble.Item 所在的目录位于前端 antdx 组件库中，与 Bubble.List、上下文系统、渲染工具共同构成消息列表渲染链路。 + +```mermaid +graph TB +subgraph "Bubble 列表体系" +BL["Bubble.List
frontend/antdx/bubble/list/bubble.list.tsx"] +CTX["上下文系统
frontend/antdx/bubble/list/context.ts"] +RI["渲染工具
frontend/utils/renderItems.tsx"] +end +subgraph "消息项" +BI["Bubble.Item
frontend/antdx/bubble/list/item/Item.svelte"] +BLI["Bubble.List.Item 包装器
frontend/antdx/bubble/list/item/bubble.list.item.tsx"] +B["Bubble 容器
frontend/antdx/bubble/bubble.tsx"] +end +BL --> CTX +BL --> RI +BL --> BLI +BI --> BLI +BLI --> B +``` + +**图表来源** + +- [frontend/antdx/bubble/list/bubble.list.tsx:1-49](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L49) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/antdx/bubble/list/item/Item.svelte:1-150](file://frontend/antdx/bubble/list/item/Item.svelte#L1-L150) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:1-14](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L1-L14) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) + +**章节来源** + +- [frontend/antdx/bubble/list/bubble.list.tsx:1-49](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L49) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/antdx/bubble/list/item/Item.svelte:1-150](file://frontend/antdx/bubble/list/item/Item.svelte#L1-L150) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:1-14](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L1-L14) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) + +## 核心组件 + +- Bubble.Item（Svelte）：消息项的入口组件，负责收集属性、插槽与事件，转换为 Bubble.List.Item 可消费的结构，并注入上下文索引与插槽键值。 +- Bubble.List.Item（React 包装器）：将 Svelte 的消息项 props 与 slots 转换为 Ant Design X 的 Bubble.List.Item 所需的结构，并通过 ItemHandler 注入到上下文系统。 +- Bubble（React 容器）：对 Ant Design X 的 Bubble 进行二次封装，支持 slots 与函数型渲染器，统一 editable、typing、contentRender、loadingRender 等能力。 +- Bubble.List（React 容器）：对 Ant Design X 的 Bubble.List 进行二次封装，提供 items 与 roles 的上下文，负责将插槽中的消息项解析为最终渲染数据。 +- 上下文系统（createItemsContext）：提供 items 上下文、ItemHandler 与 withItemsContextProvider，支撑 Bubble.List 与 Bubble.Item 的数据绑定与子项递归构建。 +- 渲染工具（renderItems）：将 Item 结构数组渲染为 React 对象树，支持插槽克隆、参数传递、子项递归等。 + +**章节来源** + +- [frontend/antdx/bubble/list/item/Item.svelte:1-150](file://frontend/antdx/bubble/list/item/Item.svelte#L1-L150) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:1-14](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L1-L14) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-49](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L49) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + +## 架构总览 + +Bubble.Item 的工作流从 Bubble.List 开始，通过上下文系统收集各消息项，再由 Bubble.Item 将属性与插槽转换为 React 可渲染对象，最终由 Ant Design X 的 Bubble 渲染。 + +```mermaid +sequenceDiagram +participant List as "Bubble.List" +participant Ctx as "上下文系统" +participant Item as "Bubble.Item(Svelte)" +participant BLI as "Bubble.List.Item 包装器" +participant Bubble as "Bubble 容器" +List->>Ctx : "初始化 items 上下文" +List->>Ctx : "读取插槽 items/default" +List->>List : "调用 renderItems 解析项" +loop 遍历每个消息项 +List->>Item : "渲染 Item.svelte" +Item->>BLI : "生成 props 与 slots" +BLI->>Bubble : "透传 BubbleProps" +Bubble-->>List : "渲染单条消息" +end +List-->>List : "输出完整消息列表" +``` + +**图表来源** + +- [frontend/antdx/bubble/list/bubble.list.tsx:13-46](file://frontend/antdx/bubble/list/bubble.list.tsx#L13-L46) +- [frontend/utils/renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) +- [frontend/antdx/bubble/list/item/Item.svelte:69-135](file://frontend/antdx/bubble/list/item/Item.svelte#L69-L135) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:7-11](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L7-L11) +- [frontend/antdx/bubble/bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) + +## 详细组件分析 + +### Bubble.Item（消息项入口） + +职责与实现要点： + +- 属性与事件映射：将 gradio 传入的属性与额外属性合并，过滤掉内部可见性控制字段，保留样式、类名、id 等。 +- 插槽处理：支持 avatar、header、footer、extra、content、contentRender、loadingRender 等插槽；对带参数的插槽进行克隆与参数注入。 +- 编辑态支持：根据 editable 的布尔或对象形式，生成编辑态配置并传递给底层组件。 +- 子项递归：通过 ItemHandler 将当前项及其子项写入上下文，支持嵌套消息结构。 + +```mermaid +flowchart TD +Start(["进入 Item.svelte"]) --> GetProps["获取组件属性与附加属性"] +GetProps --> Filter["过滤内部字段
visible/_internal 等"] +Filter --> BuildEditable{"是否启用编辑态？"} +BuildEditable --> |是| EditObj["生成编辑态对象"] +BuildEditable --> |否| KeepEditable["保持原值"] +EditObj --> Slots["准备插槽集合"] +KeepEditable --> Slots +Slots --> Render["等待 Bubble.List.Item 包装器"] +Render --> End(["渲染完成"]) +``` + +**图表来源** + +- [frontend/antdx/bubble/list/item/Item.svelte:36-135](file://frontend/antdx/bubble/list/item/Item.svelte#L36-L135) + +**章节来源** + +- [frontend/antdx/bubble/list/item/Item.svelte:1-150](file://frontend/antdx/bubble/list/item/Item.svelte#L1-L150) + +### Bubble.List.Item 包装器 + +职责与实现要点： + +- 将 Svelte 的 props 与 slots 转换为 Ant Design X 的 BubbleProps。 +- 通过 ItemHandler 将消息项注册到上下文中，携带索引与插槽键值，便于 Bubble.List 统一消费。 + +```mermaid +sequenceDiagram +participant Item as "Item.svelte" +participant BLI as "Bubble.List.Item 包装器" +participant Handler as "ItemHandler" +participant XBubble as "Ant Design X Bubble" +Item->>BLI : "传递 props 与 slots" +BLI->>Handler : "包裹为 ItemHandler" +Handler->>Handler : "写入上下文 items[index]" +Handler->>XBubble : "渲染 Bubble" +XBubble-->>Handler : "渲染结果" +``` + +**图表来源** + +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:7-11](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L7-L11) +- [frontend/antdx/bubble/list/context.ts:3-4](file://frontend/antdx/bubble/list/context.ts#L3-L4) + +**章节来源** + +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:1-14](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L1-L14) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) + +### Bubble（容器与插槽桥接） + +职责与实现要点： + +- 将 editable、typing、content、avatar、extra、footer、header、loadingRender、contentRender 等属性与插槽统一为 Ant Design X 的 BubbleProps。 +- 支持函数型渲染器与 ReactSlot 插槽，确保插槽可带参数、可克隆。 + +```mermaid +classDiagram +class Bubble { ++props : BubbleProps ++slots : Record ++editable ++typing ++content ++avatar ++extra ++footer ++header ++loadingRender ++contentRender +} +class XBubble { ++props : BubbleProps +} +Bubble --> XBubble : "透传并增强" +``` + +**图表来源** + +- [frontend/antdx/bubble/bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) + +**章节来源** + +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) + +### Bubble.List（列表容器与上下文） + +职责与实现要点： + +- 提供 items 与 roles 的上下文，支持多插槽 items/default。 +- 通过 renderItems 将插槽中的消息项解析为最终渲染数据，交由 Ant Design X 的 Bubble.List 渲染。 + +```mermaid +flowchart TD +LStart["Bubble.List 初始化"] --> ReadSlots["读取 items/default 插槽"] +ReadSlots --> ResolveRole["解析角色 role"] +ResolveRole --> RenderItems["调用 renderItems 解析项"] +RenderItems --> XList["渲染 Ant Design X List"] +XList --> LEnd["完成"] +``` + +**图表来源** + +- [frontend/antdx/bubble/list/bubble.list.tsx:18-42](file://frontend/antdx/bubble/list/bubble.list.tsx#L18-L42) + +**章节来源** + +- [frontend/antdx/bubble/list/bubble.list.tsx:1-49](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L49) + +### 上下文系统与渲染工具 + +职责与实现要点： + +- createItemsContext：提供 useItems、withItemsContextProvider、ItemHandler，支持多插槽 items 管理与子项递归构建。 +- renderItems：将 Item 结构数组渲染为 React 对象树，支持插槽克隆、参数传递、子项递归。 + +```mermaid +classDiagram +class ItemsContext { ++items : Record ++setItem(slotKey, index, item) ++initial : boolean +} +class ItemHandler { ++itemIndex : number ++itemSlotKey : string ++itemProps(props, items) ++slots : Record ++children +} +class renderItems { ++items : Item[] ++options ++key +} +ItemsContext <.. ItemHandler : "使用" +ItemHandler <.. renderItems : "生成" +``` + +**图表来源** + +- [frontend/utils/createItemsContext.tsx:102-261](file://frontend/utils/createItemsContext.tsx#L102-L261) +- [frontend/utils/renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +**章节来源** + +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + +## 依赖关系分析 + +Bubble.Item 的依赖关系围绕“属性/插槽 -> 上下文 -> 渲染”展开，关键耦合点如下： + +```mermaid +graph TB +BI["Item.svelte"] --> BLI["bubble.list.item.tsx"] +BLI --> CTX["context.ts(ItemHandler)"] +CTX --> RI["renderItems.tsx"] +RI --> XList["Ant Design X List"] +BI --> B["bubble.tsx(Bubble)"] +B --> XBubble["Ant Design X Bubble"] +``` + +**图表来源** + +- [frontend/antdx/bubble/list/item/Item.svelte:14-16](file://frontend/antdx/bubble/list/item/Item.svelte#L14-L16) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:5-9](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L5-L9) +- [frontend/antdx/bubble/list/context.ts:3-4](file://frontend/antdx/bubble/list/context.ts#L3-L4) +- [frontend/utils/renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) +- [frontend/antdx/bubble/bubble.tsx:41-113](file://frontend/antdx/bubble/bubble.tsx#L41-L113) + +**章节来源** + +- [frontend/antdx/bubble/list/item/Item.svelte:1-150](file://frontend/antdx/bubble/list/item/Item.svelte#L1-L150) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:1-14](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L1-L14) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/antdx/bubble/bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) + +## 性能考虑 + +- 插槽克隆与参数传递：当插槽带有参数时，renderItems 会以函数形式注入参数，避免不必要的重复渲染。建议仅在必要时开启 withParams 与 clone，减少 DOM 克隆成本。 +- 上下文更新去重：createItemsContext 使用浅比较与记忆化函数，避免重复 setItem 导致的无意义重渲染。 +- 列表渲染优化：Bubble.List 在 items 变更时才重新计算渲染结果，尽量复用已渲染节点。 +- 编辑态与加载态：合理使用 editable 与 loadingRender，避免频繁切换导致的重排。 + +[本节为通用性能建议，不直接分析具体文件] + +## 故障排查指南 + +- 插槽未生效 + - 检查插槽键名是否正确（如 avatar、header、footer、extra、content、contentRender、loadingRender），并确认是否启用 withParams 与 clone。 + - 参考路径：[frontend/antdx/bubble/list/item/Item.svelte:101-133](file://frontend/antdx/bubble/list/item/Item.svelte#L101-L133) +- 编辑态不显示 + - 确认 editable 传入的是布尔值或包含 editing 字段的对象；若使用插槽，确保插槽键名正确。 + - 参考路径：[frontend/antdx/bubble/bubble.tsx:43-64](file://frontend/antdx/bubble/bubble.tsx#L43-L64) +- 内容为空或渲染异常 + - 检查 content、contentRender 是否正确传入；若使用插槽，确认插槽元素存在且可克隆。 + - 参考路径：[frontend/antdx/bubble/list/item/Item.svelte:88-99](file://frontend/antdx/bubble/list/item/Item.svelte#L88-L99) +- 列表不更新 + - 确认 Bubble.List 的 items/default 插槽是否正确填充；检查上下文 setItem 是否被调用。 + - 参考路径：[frontend/antdx/bubble/list/bubble.list.tsx:19-42](file://frontend/antdx/bubble/list/bubble.list.tsx#L19-L42)，[frontend/utils/createItemsContext.tsx:124-153](file://frontend/utils/createItemsContext.tsx#L124-L153) + +**章节来源** + +- [frontend/antdx/bubble/list/item/Item.svelte:88-133](file://frontend/antdx/bubble/list/item/Item.svelte#L88-L133) +- [frontend/antdx/bubble/bubble.tsx:43-64](file://frontend/antdx/bubble/bubble.tsx#L43-L64) +- [frontend/antdx/bubble/list/bubble.list.tsx:19-42](file://frontend/antdx/bubble/list/bubble.list.tsx#L19-L42) +- [frontend/utils/createItemsContext.tsx:124-153](file://frontend/utils/createItemsContext.tsx#L124-L153) + +## 结论 + +Bubble.Item 通过清晰的属性/插槽桥接、上下文驱动的数据绑定与 Ant Design X 的渲染能力，实现了灵活、可扩展的消息项渲染。其设计遵循“Svelte 入口 + React 包装 + 上下文系统”的模式，既保证了易用性，又兼顾了性能与可维护性。结合 Bubble.List 的上下文与渲染工具，开发者可以快速构建复杂的消息列表场景。 + +[本节为总结性内容，不直接分析具体文件] + +## 附录 + +### 使用示例（路径指引） + +- 文本消息 + - 在 Bubble.Item 中设置 content 或使用 content 插槽 + - 参考路径：[frontend/antdx/bubble/list/item/Item.svelte:88-99](file://frontend/antdx/bubble/list/item/Item.svelte#L88-L99) +- 图片消息 + - 使用 avatar 插槽或 avatar 属性传入头像 + - 参考路径：[frontend/antdx/bubble/bubble.tsx:69-75](file://frontend/antdx/bubble/bubble.tsx#L69-L75) +- 代码块消息 + - 使用 contentRender 插槽或属性，返回代码高亮组件 + - 参考路径：[frontend/antdx/bubble/bubble.tsx:105-112](file://frontend/antdx/bubble/bubble.tsx#L105-L112) +- 可编辑消息 + - 设置 editable 为布尔值或对象，支持编辑确认/取消回调 + - 参考路径：[frontend/antdx/bubble/bubble.tsx:43-64](file://frontend/antdx/bubble/bubble.tsx#L43-L64)，[frontend/antdx/bubble/list/item/Item.svelte:72-87](file://frontend/antdx/bubble/list/item/Item.svelte#L72-L87) +- 加载态消息 + - 使用 loadingRender 插槽或属性，返回加载组件 + - 参考路径：[frontend/antdx/bubble/bubble.tsx:97-104](file://frontend/antdx/bubble/bubble.tsx#L97-L104) +- 自定义头部/尾部/额外区域 + - 使用 header/footer/extra 插槽或属性 + - 参考路径：[frontend/antdx/bubble/bubble.tsx:83-96](file://frontend/antdx/bubble/bubble.tsx#L83-L96) + +### 与 Bubble.List 的上下文关系 + +- Bubble.List 通过 withItemsContextProvider 与 withRoleItemsContextProvider 提供上下文 +- renderItems 将插槽中的消息项解析为 React 对象树 +- ItemHandler 将每条消息项写入上下文，携带索引与插槽键值 +- 参考路径： + - [frontend/antdx/bubble/list/bubble.list.tsx:13-46](file://frontend/antdx/bubble/list/bubble.list.tsx#L13-L46) + - [frontend/utils/renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + - [frontend/antdx/bubble/list/context.ts:3-10](file://frontend/antdx/bubble/list/context.ts#L3-L10) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.List \345\210\227\350\241\250\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.List \345\210\227\350\241\250\347\273\204\344\273\266.md" new file mode 100644 index 00000000..736ca515 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.List \345\210\227\350\241\250\347\273\204\344\273\266.md" @@ -0,0 +1,335 @@ +# Bubble.List 列表组件 + + +**本文引用的文件** +- [frontend/antdx/bubble/list/bubble.list.tsx](file://frontend/antdx/bubble/list/bubble.list.tsx) +- [frontend/antdx/bubble/list/Index.svelte](file://frontend/antdx/bubble/list/Index.svelte) +- [frontend/antdx/bubble/list/context.ts](file://frontend/antdx/bubble/list/context.ts) +- [frontend/antdx/bubble/list/utils.tsx](file://frontend/antdx/bubble/list/utils.tsx) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx) +- [backend/modelscope_studio/components/antdx/bubble/list/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py) +- [backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py) +- [docs/components/antdx/bubble/README.md](file://docs/components/antdx/bubble/README.md) +- [docs/components/antdx/bubble/demos/bubble_list.py](file://docs/components/antdx/bubble/demos/bubble_list.py) +- [docs/components/antdx/bubble/demos/custom_list_content.py](file://docs/components/antdx/bubble/demos/custom_list_content.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Bubble.List 是一个基于 Ant Design X 的消息容器组件，用于在聊天或对话场景中展示一组 Bubble（气泡）消息。它通过统一的数据结构与渲染机制，支持消息项的排列、滚动行为控制、角色化样式与内容定制，并与 Bubble.Item 与 Bubble.Role 协作完成数据与样式的分发。 + +本组件面向前端 Svelte 与后端 Gradio 双端：前端负责渲染与交互，后端提供 Python API 以声明式地组织消息数据、角色与插槽。 + +## 项目结构 + +Bubble.List 所在的目录位于前端 antdx/bubble/list，包含以下关键文件： + +- bubble.list.tsx：Bubble.List 的 Svelte 化封装，对接 @ant-design/x 的 XBubble.List +- Index.svelte：Gradio 前端桥接入口，负责属性透传与插槽注入 +- context.ts：定义 items 与 roles 的上下文，供子组件读取 +- utils.tsx：角色解析与插槽补丁工具，支持函数式角色与默认回退 +- item/bubble.list.item.tsx：Bubble.Item 的桥接包装 +- role/bubble.list.role.tsx：Bubble.Role 的桥接包装 + +后端侧： + +- backend/modelscope_studio/components/antdx/bubble/list/**init**.py：AntdXBubbleList 组件类，声明事件、插槽与属性 +- backend/modelscope_studio/components/antdx/bubble/list/item/**init**.py：AntdXBubbleListItem 组件类，声明消息项的属性与事件 + +```mermaid +graph TB +subgraph "前端" +A["Index.svelte
桥接入口"] --> B["bubble.list.tsx
BubbleList 封装"] +B --> C["context.ts
items/roles 上下文"] +B --> D["utils.tsx
角色解析与插槽补丁"] +B --> E["bubble.list.item.tsx
BubbleListItem 包装"] +B --> F["bubble.list.role.tsx
BubbleListRole 包装"] +end +subgraph "后端" +G["AntdXBubbleList
组件类"] --> H["事件/插槽/属性定义"] +I["AntdXBubbleListItem
组件类"] --> J["消息项属性/事件定义"] +end +A --- G +E --- I +``` + +图表来源 + +- [frontend/antdx/bubble/list/Index.svelte:1-66](file://frontend/antdx/bubble/list/Index.svelte#L1-L66) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-49](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L49) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/antdx/bubble/list/utils.tsx:1-152](file://frontend/antdx/bubble/list/utils.tsx#L1-L152) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:1-14](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L1-L14) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:1-14](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L1-L14) +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:1-84](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L1-L84) +- [backend/modelscope_studio/components/antdx/bubble/list/item/**init**.py:1-129](file://backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py#L1-L129) + +章节来源 + +- [frontend/antdx/bubble/list/Index.svelte:1-66](file://frontend/antdx/bubble/list/Index.svelte#L1-L66) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-49](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L49) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/antdx/bubble/list/utils.tsx:1-152](file://frontend/antdx/bubble/list/utils.tsx#L1-L152) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:1-14](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L1-L14) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:1-14](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L1-L14) +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:1-84](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L1-L84) +- [backend/modelscope_studio/components/antdx/bubble/list/item/**init**.py:1-129](file://backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py#L1-L129) + +## 核心组件 + +- Bubble.List（前端）：负责接收 items 与 roles，解析并渲染消息列表；支持自动滚动绑定与滚动事件回调。 +- Bubble.Item（前端）：单条消息项的包装器，承载头像、内容、额外区域、加载态等插槽。 +- Bubble.Role（前端）：角色定义器，为不同角色（如 ai、user）提供默认样式与渲染策略。 +- 后端 AntdXBubbleList/AntdXBubbleListItem：Python 层组件类，声明属性、事件与插槽，驱动前端渲染。 + +章节来源 + +- [frontend/antdx/bubble/list/bubble.list.tsx:13-46](file://frontend/antdx/bubble/list/bubble.list.tsx#L13-L46) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:7-11](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L7-L11) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:7-11](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L7-L11) +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:12-31](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L12-L31) +- [backend/modelscope_studio/components/antdx/bubble/list/item/**init**.py:10-47](file://backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py#L10-L47) + +## 架构总览 + +Bubble.List 的运行时流程如下： + +- 前端 Index.svelte 接收来自后端的 props 与 slots，将 items 与 role 注入到 BubbleList。 +- BubbleList 从上下文中读取 items/default 与 role，解析为最终的 items 数组与角色映射。 +- 使用 utils.useRole 计算角色函数或对象，必要时对插槽进行补丁处理，确保角色优先级覆盖。 +- 最终调用 @ant-design/x 的 XBubble.List 渲染消息列表。 + +```mermaid +sequenceDiagram +participant Backend as "后端组件类" +participant FrontIndex as "Index.svelte" +participant FrontList as "BubbleList(bubble.list.tsx)" +participant Ctx as "上下文(context.ts)" +participant Util as "角色工具(utils.tsx)" +Backend->>FrontIndex : "传递 props 与 slots" +FrontIndex->>FrontList : "透传 items/role/附加属性" +FrontList->>Ctx : "读取 items/default 与 role" +FrontList->>Util : "useRole 解析角色与插槽补丁" +Util-->>FrontList : "返回角色映射与预/后处理结果" +FrontList-->>FrontIndex : "渲染 XBubble.List" +``` + +图表来源 + +- [frontend/antdx/bubble/list/Index.svelte:49-65](file://frontend/antdx/bubble/list/Index.svelte#L49-L65) +- [frontend/antdx/bubble/list/bubble.list.tsx:18-42](file://frontend/antdx/bubble/list/bubble.list.tsx#L18-L42) +- [frontend/antdx/bubble/list/context.ts:3-10](file://frontend/antdx/bubble/list/context.ts#L3-L10) +- [frontend/antdx/bubble/list/utils.tsx:51-151](file://frontend/antdx/bubble/list/utils.tsx#L51-L151) + +## 详细组件分析 + +### Bubble.List 实现机制 + +- 数据源解析 + - 优先使用外部传入的 items；若未提供，则从上下文读取 slotItems 中的 items 或 default。 + - 使用 renderItems 将插槽内容转换为可渲染的数组。 +- 角色解析 + - useRole 支持 role 为字符串函数或对象，支持 preProcess 与 defaultRolePostProcess 钩子。 + - 对插槽进行补丁处理，使角色的 avatar/header/footer/extra/loadingRender/contentRender 能前置覆盖。 +- 渲染与滚动 + - 通过 @ant-design/x 的 XBubble.List 渲染，支持自动滚动绑定与滚动事件回调。 + +```mermaid +flowchart TD +Start(["进入 BubbleList"]) --> CheckItems["检查 props.items 是否存在"] +CheckItems --> |存在| UseItems["使用外部 items"] +CheckItems --> |不存在| ReadSlot["读取上下文 slotItems.items 或 default"] +ReadSlot --> ResolveItems["使用 renderItems 解析为数组"] +UseItems --> ResolveItems +ResolveItems --> ParseRole["useRole 解析角色映射"] +ParseRole --> PatchSlots["对插槽进行补丁处理"] +PatchSlots --> RenderList["渲染 XBubble.List"] +RenderList --> End(["完成"]) +``` + +图表来源 + +- [frontend/antdx/bubble/list/bubble.list.tsx:18-42](file://frontend/antdx/bubble/list/bubble.list.tsx#L18-L42) +- [frontend/antdx/bubble/list/utils.tsx:51-151](file://frontend/antdx/bubble/list/utils.tsx#L51-L151) + +章节来源 + +- [frontend/antdx/bubble/list/bubble.list.tsx:13-46](file://frontend/antdx/bubble/list/bubble.list.tsx#L13-L46) +- [frontend/antdx/bubble/list/context.ts:3-10](file://frontend/antdx/bubble/list/context.ts#L3-L10) +- [frontend/antdx/bubble/list/utils.tsx:44-151](file://frontend/antdx/bubble/list/utils.tsx#L44-L151) + +### Bubble.Item 与 Bubble.Role 的协作 + +- Bubble.Item + - 作为 ItemHandler 的包装，将消息项的属性与插槽注入到上下文中，供 Bubble.List 在渲染时读取。 +- Bubble.Role + - 作为 RoleItemHandler 的包装，将角色定义注入到角色上下文中，供 useRole 解析。 +- 数据流转 + - Bubble.List 在渲染前从上下文读取 items/default 与 role，结合 useRole 的预/后处理钩子，生成最终的渲染配置。 + +```mermaid +classDiagram +class BubbleList { ++props : "items, role, children" ++useItems() : "读取 items/default" ++useRole() : "解析角色映射" ++render() : "渲染 XBubble.List" +} +class BubbleListItem { ++props : "BubbleProps + ItemHandlerProps" ++ItemHandler : "写入 items/default" +} +class BubbleListRole { ++props : "BubbleProps + ItemHandlerProps" ++RoleItemHandler : "写入 role" +} +BubbleList --> BubbleListItem : "消费 items/default" +BubbleList --> BubbleListRole : "消费 role" +``` + +图表来源 + +- [frontend/antdx/bubble/list/bubble.list.tsx:18-42](file://frontend/antdx/bubble/list/bubble.list.tsx#L18-L42) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:7-11](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L7-L11) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:7-11](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L7-L11) + +章节来源 + +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:7-11](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L7-L11) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:7-11](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L7-L11) + +### 消息渲染逻辑与排列方式 + +- 渲染回调 + - 通过 useFunction 与 renderParamsSlot 将插槽转换为可执行的渲染函数，支持带参渲染。 +- 排列方式 + - 由 @ant-design/x 的 XBubble.List 决定消息的排列与布局，Bubble.List 仅负责数据与角色的准备。 +- 插槽优先级 + - 角色插槽会前置覆盖消息项插槽，保证角色级别的统一风格。 + +章节来源 + +- [frontend/antdx/bubble/list/bubble.list.tsx:18-42](file://frontend/antdx/bubble/list/bubble.list.tsx#L18-L42) +- [frontend/antdx/bubble/list/utils.tsx:18-42](file://frontend/antdx/bubble/list/utils.tsx#L18-L42) + +### 滚动行为控制与性能优化策略 + +- 滚动控制 + - 后端事件定义包含滚动事件回调，前端可通过绑定实现滚动行为控制（例如自动滚动至底部）。 +- 性能优化 + - 使用 useMemo 缓存解析后的 items 与角色映射，避免重复计算。 + - 使用 useMemoizedFn 与 useMemoizedEqualValue 降低函数与值变更带来的重渲染。 + - 通过上下文按需注入 items/default 与 role，减少不必要的 props 传递。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:19-24](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L19-L24) +- [frontend/antdx/bubble/list/bubble.list.tsx:31-39](file://frontend/antdx/bubble/list/bubble.list.tsx#L31-L39) +- [frontend/antdx/bubble/list/utils.tsx:60-62](file://frontend/antdx/bubble/list/utils.tsx#L60-L62) + +### 属性配置与使用示例 + +- 基本消息列表 + - 使用 items 参数传入消息数组，配合 role 定义默认样式与行为。 +- 动态消息添加 + - 通过更新 items 或重新渲染 Bubble.List 触发增量渲染。 +- 消息过滤与排序 + - 在传入 items 前进行过滤与排序，再交由 Bubble.List 渲染。 +- 自定义内容渲染 + - 通过 role 的 contentRender 插槽自定义消息内容展示。 + +参考示例路径 + +- [docs/components/antdx/bubble/demos/bubble_list.py:28-52](file://docs/components/antdx/bubble/demos/bubble_list.py#L28-L52) +- [docs/components/antdx/bubble/demos/custom_list_content.py:65-89](file://docs/components/antdx/bubble/demos/custom_list_content.py#L65-L89) + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:32-64](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L32-L64) +- [backend/modelscope_studio/components/antdx/bubble/list/item/**init**.py:49-108](file://backend/modelscope_studio/components/antdx/bubble/list/item/__init__.py#L49-L108) +- [docs/components/antdx/bubble/demos/bubble_list.py:28-52](file://docs/components/antdx/bubble/demos/bubble_list.py#L28-L52) +- [docs/components/antdx/bubble/demos/custom_list_content.py:65-89](file://docs/components/antdx/bubble/demos/custom_list_content.py#L65-L89) + +## 依赖分析 + +- 组件耦合 + - BubbleList 依赖上下文读取 items/default 与 role，依赖 utils.useRole 进行角色解析。 + - BubbleListItem/BubbleListRole 通过 ItemHandler/RoleItemHandler 将自身注入上下文。 +- 外部依赖 + - @ant-design/x 的 XBubble.List 提供核心渲染能力。 + - @svelte-preprocess-react 工具链负责 Svelte 到 React 的桥接与插槽渲染。 + +```mermaid +graph LR +BL["BubbleList"] --> CTX["上下文(context.ts)"] +BL --> UT["角色工具(utils.tsx)"] +BL --> ADX["@ant-design/x XBubble.List"] +BLB["BubbleListItem"] --> CTX +BLR["BubbleListRole"] --> CTX +``` + +图表来源 + +- [frontend/antdx/bubble/list/bubble.list.tsx:18-42](file://frontend/antdx/bubble/list/bubble.list.tsx#L18-L42) +- [frontend/antdx/bubble/list/context.ts:3-10](file://frontend/antdx/bubble/list/context.ts#L3-L10) +- [frontend/antdx/bubble/list/utils.tsx:51-151](file://frontend/antdx/bubble/list/utils.tsx#L51-L151) + +章节来源 + +- [frontend/antdx/bubble/list/bubble.list.tsx:1-49](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L49) +- [frontend/antdx/bubble/list/context.ts:1-13](file://frontend/antdx/bubble/list/context.ts#L1-L13) +- [frontend/antdx/bubble/list/utils.tsx:1-152](file://frontend/antdx/bubble/list/utils.tsx#L1-L152) + +## 性能考虑 + +- 依赖缓存 + - 对 items 与角色映射使用 useMemo 缓存，避免每次渲染都重新计算。 +- 函数稳定化 + - 使用 useMemoizedFn 与 useMemoizedEqualValue 保持函数与默认值稳定，减少副作用。 +- 渲染粒度 + - 通过上下文按需注入数据，避免将大量无关 props 传递给子树。 + +[本节为通用性能建议，不直接分析具体文件] + +## 故障排查指南 + +- 滚动事件无效 + - 检查后端是否正确绑定滚动事件，前端是否启用滚动回调。 +- 消息内容未按预期渲染 + - 确认 role 的插槽是否被正确设置，以及插槽优先级是否覆盖了消息项插槽。 +- 角色函数未生效 + - 检查 role 的字符串函数是否可被正确解析，或对象形式的角色配置是否完整。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/list/**init**.py:19-24](file://backend/modelscope_studio/components/antdx/bubble/list/__init__.py#L19-L24) +- [frontend/antdx/bubble/list/utils.tsx:101-133](file://frontend/antdx/bubble/list/utils.tsx#L101-L133) + +## 结论 + +Bubble.List 通过清晰的上下文分发与角色解析机制，实现了消息列表的高扩展性与高性能渲染。结合 Bubble.Item 与 Bubble.Role，开发者可以灵活地定义消息样式与内容，满足多样化的聊天场景需求。后端组件类提供了稳定的 API 与事件绑定，便于在 Gradio 应用中集成。 + +[本节为总结性内容，不直接分析具体文件] + +## 附录 + +- 示例入口 + - [docs/components/antdx/bubble/README.md:1-13](file://docs/components/antdx/bubble/README.md#L1-L13) +- 基础示例 + - [docs/components/antdx/bubble/demos/bubble_list.py:28-52](file://docs/components/antdx/bubble/demos/bubble_list.py#L28-L52) +- 自定义内容示例 + - [docs/components/antdx/bubble/demos/custom_list_content.py:65-89](file://docs/components/antdx/bubble/demos/custom_list_content.py#L65-L89) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.Role \350\247\222\350\211\262\346\240\207\350\257\206\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.Role \350\247\222\350\211\262\346\240\207\350\257\206\347\273\204\344\273\266.md" new file mode 100644 index 00000000..7d2b9164 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.Role \350\247\222\350\211\262\346\240\207\350\257\206\347\273\204\344\273\266.md" @@ -0,0 +1,346 @@ +# Bubble.Role 角色标识组件 + + +**本文档引用的文件** +- [frontend/antdx/bubble/list/role/Role.svelte](file://frontend/antdx/bubble/list/role/Role.svelte) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx) +- [backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py) +- [frontend/antdx/bubble/list/role/Index.svelte](file://frontend/antdx/bubble/list/role/Index.svelte) +- [frontend/antdx/bubble/list/context.ts](file://frontend/antdx/bubble/list/context.ts) +- [frontend/antdx/bubble/list/utils.tsx](file://frontend/antdx/bubble/list/utils.tsx) +- [frontend/antdx/bubble/list/bubble.list.tsx](file://frontend/antdx/bubble/list/bubble.list.tsx) +- [frontend/antdx/bubble/list/item/Item.svelte](file://frontend/antdx/bubble/list/item/Item.svelte) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx) +- [docs/components/antdx/bubble/README-zh_CN.md](file://docs/components/antdx/bubble/README-zh_CN.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Bubble.Role 是消息气泡列表中的角色标识组件，用于在聊天界面中为每条消息或消息片段标注发送者角色（如用户、系统、助手等）。它通过统一的角色配置与 Bubble.Item 协同工作，实现角色头像、标题、副标题、额外信息、底部信息等区域的渲染，并支持可编辑、打字动画、流式渲染等高级特性。该组件既可在前端 Svelte 层直接使用，也可通过后端 Python 组件桥接，实现从服务端到前端的完整数据流转。 + +## 项目结构 + +Bubble.Role 所属的 Bubble 列表体系采用“前端 Svelte 包装层 + 后端 Python 组件桥接”的双层设计： + +- 前端层：Svelte 组件负责属性透传、插槽处理、事件绑定与渲染。 +- 后端层：Python 组件负责声明属性、事件、插槽与生命周期钩子，并将渲染结果传递给前端。 + +```mermaid +graph TB +subgraph "后端 Python 组件" +PY_ROLE["AntdXBubbleListRole
角色组件定义"] +end +subgraph "前端 Svelte 包装层" +IDX["Index.svelte
组件入口"] +WRAP["Role.svelte
属性与插槽包装"] +CORE["bubble.list.role.tsx
React 包装器"] +CTX["context.ts
上下文与处理器"] +UTIL["utils.tsx
useRole 工具"] +LIST["bubble.list.tsx
BubbleList 容器"] +end +PY_ROLE --> IDX +IDX --> WRAP +WRAP --> CORE +WRAP --> CTX +LIST --> CTX +LIST --> UTIL +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:10-128](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L10-L128) +- [frontend/antdx/bubble/list/role/Index.svelte:1-20](file://frontend/antdx/bubble/list/role/Index.svelte#L1-L20) +- [frontend/antdx/bubble/list/role/Role.svelte:1-148](file://frontend/antdx/bubble/list/role/Role.svelte#L1-L148) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:1-14](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L1-L14) +- [frontend/antdx/bubble/list/context.ts:1-12](file://frontend/antdx/bubble/list/context.ts#L1-L12) +- [frontend/antdx/bubble/list/utils.tsx:1-112](file://frontend/antdx/bubble/list/utils.tsx#L1-L112) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-48](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L48) + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:10-128](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L10-L128) +- [frontend/antdx/bubble/list/role/Index.svelte:1-20](file://frontend/antdx/bubble/list/role/Index.svelte#L1-L20) +- [frontend/antdx/bubble/list/role/Role.svelte:1-148](file://frontend/antdx/bubble/list/role/Role.svelte#L1-L148) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:1-14](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L1-L14) +- [frontend/antdx/bubble/list/context.ts:1-12](file://frontend/antdx/bubble/list/context.ts#L1-L12) +- [frontend/antdx/bubble/list/utils.tsx:1-112](file://frontend/antdx/bubble/list/utils.tsx#L1-L112) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-48](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L48) + +## 核心组件 + +- AntdXBubbleListRole（后端）：定义角色组件的属性、事件、插槽与生命周期行为，支持 typing、typing_complete、edit_confirm、edit_cancel 等事件绑定，以及 avatar、header、footer、extra、loadingRender、contentRender 等插槽。 +- Role.svelte（前端包装）：负责将后端传入的属性与插槽进行处理，生成 BubbleListRole 的 props 与 slots，并支持可见性控制与子节点渲染。 +- bubble.list.role.tsx（React 包装）：将 Svelte 组件映射为 React 可用的组件，内部委托给 RoleItemHandler 处理项级逻辑。 +- context.ts：提供 RoleItemHandler 上下文，供 Bubble.Role 与 Bubble.Item 共享状态与事件。 +- utils.tsx：提供 useRole 工具，用于根据角色键值解析并合并角色配置，支持默认角色键与预处理/后处理钩子。 +- bubble.list.tsx：BubbleList 容器，负责将角色配置注入到 Ant Design X 的 Bubble.List 中，并渲染最终的气泡列表。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:14-46](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L14-L46) +- [frontend/antdx/bubble/list/role/Role.svelte:35-133](file://frontend/antdx/bubble/list/role/Role.svelte#L35-L133) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:7-11](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L7-L11) +- [frontend/antdx/bubble/list/context.ts:6-10](file://frontend/antdx/bubble/list/context.ts#L6-L10) +- [frontend/antdx/bubble/list/utils.tsx:44-112](file://frontend/antdx/bubble/list/utils.tsx#L44-L112) +- [frontend/antdx/bubble/list/bubble.list.tsx:13-46](file://frontend/antdx/bubble/list/bubble.list.tsx#L13-L46) + +## 架构总览 + +Bubble.Role 的调用链路如下： + +- 后端 Python 组件接收开发者配置的角色参数与插槽，将其转换为前端可识别的数据结构。 +- 前端 Index.svelte 加载 Role.svelte，Role.svelte 解析属性与插槽，生成 BubbleListRole 的 props 与 slots。 +- bubble.list.role.tsx 将 props 交由 RoleItemHandler 处理，最终渲染为 Ant Design X 的 Bubble.List 子项。 +- BubbleList 容器通过 useRole 工具解析角色配置，结合 Bubble.Item 的通用项处理，完成整体布局与交互。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Py as "后端组件
AntdXBubbleListRole" +participant Idx as "前端入口
Index.svelte" +participant Wrap as "包装层
Role.svelte" +participant Core as "React 包装
bubble.list.role.tsx" +participant Ctx as "上下文处理器
RoleItemHandler" +participant List as "容器
BubbleList" +Dev->>Py : 配置角色属性与插槽 +Py-->>Idx : 渲染前端组件 +Idx->>Wrap : 传递 props 与 children +Wrap->>Wrap : 解析属性/插槽/事件 +Wrap->>Core : 生成 BubbleListRole props 与 slots +Core->>Ctx : 调用 RoleItemHandler +List->>Ctx : 注入角色配置与项处理 +Ctx-->>Dev : 渲染完成的消息气泡 +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:109-110](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L109-L110) +- [frontend/antdx/bubble/list/role/Index.svelte:5-19](file://frontend/antdx/bubble/list/role/Index.svelte#L5-L19) +- [frontend/antdx/bubble/list/role/Role.svelte:136-147](file://frontend/antdx/bubble/list/role/Role.svelte#L136-L147) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:7-11](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L7-L11) +- [frontend/antdx/bubble/list/context.ts:6-10](file://frontend/antdx/bubble/list/context.ts#L6-L10) +- [frontend/antdx/bubble/list/bubble.list.tsx:13-46](file://frontend/antdx/bubble/list/bubble.list.tsx#L13-L46) + +## 详细组件分析 + +### 组件职责与属性配置 + +- 角色标识属性 + - role：角色键名，用于在 useRole 中匹配对应的角色配置。 + - avatar：角色头像资源路径或内容。 + - header/footer/extra：顶部、底部与额外区域的内容。 + - placement：角色区域的起始/结束位置控制。 + - shape：气泡形状（圆润/角形/默认）。 + - variant：外观变体（填充/无边框/描边/阴影）。 + - typing/streaming：打字动画与流式渲染开关。 + - editable：是否允许编辑，支持布尔或对象形式。 + - class_names/styles/root_class_name：样式类名与内联样式的扩展。 + - additional_props/as_item/\_internal：附加属性、作为项标识与内部索引。 + - 可见性与 DOM 属性：visible、elem_id、elem_classes、elem_style、render。 + +- 插槽 + - avatar、header、footer、extra、loadingRender、contentRender。 + - 可选编辑插槽：editable.okText、editable.cancelText。 + +- 事件 + - typing、typing_complete、edit_confirm、edit_cancel。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:48-107](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L48-L107) +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:14-46](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L14-L46) +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:14-34](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L14-L34) + +### 显示逻辑与角色类型 + +- 角色解析流程 + - useRole 接收 role、defaultRoleKeys、preProcess、defaultRolePostProcess 等参数。 + - 通过 useRoleItems 获取角色项集合，构建角色映射表。 + - 合并默认角色键与用户自定义角色键，按顺序解析为函数或对象。 + - 对于每个消息项，先执行 preProcess，再将角色插槽通过 patchSlots 合并到消息项上，最后应用 defaultRolePostProcess 进行最终调整。 + +```mermaid +flowchart TD +Start(["开始"]) --> GetRoleItems["获取角色项集合"] +GetRoleItems --> BuildMap["构建角色映射表"] +BuildMap --> MergeKeys["合并默认键与自定义键"] +MergeKeys --> ResolveEach["逐个解析角色键"] +ResolveEach --> PreProcess["执行 preProcess 钩子"] +PreProcess --> PatchSlots["合并角色插槽到消息项"] +PatchSlots --> PostProcess["执行 defaultRolePostProcess 钩子"] +PostProcess --> End(["结束"]) +``` + +图表来源 + +- [frontend/antdx/bubble/list/utils.tsx:44-112](file://frontend/antdx/bubble/list/utils.tsx#L44-L112) + +章节来源 + +- [frontend/antdx/bubble/list/utils.tsx:44-112](file://frontend/antdx/bubble/list/utils.tsx#L44-L112) + +### 样式定制与位置控制 + +- 样式定制 + - class_names：支持为根元素、头像、内容等区域分别设置类名。 + - styles：支持为根元素、内容等区域设置内联样式。 + - root_class_name：根元素的额外类名。 + - shape/variant/placement：通过 Ant Design X 的 Bubble.List 传入，控制外观与对齐。 + +- 位置控制 + - placement 控制角色区域位于起始或结束侧。 + - footer_placement 支持外侧起始/结束与内侧起始/结束的底部区域定位。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:62-66](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L62-L66) +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:57-66](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L57-L66) + +### 与 Bubble.Item 的配合使用 + +- Bubble.Item 提供通用的消息项能力，包括内容、头像、标题、副标题、底部信息、额外信息、加载与内容渲染插槽等。 +- Bubble.Role 通过 RoleItemHandler 与 Bubble.Item 的 ItemHandler 共享上下文，使角色信息能够无缝融入消息项的渲染流程。 +- BubbleList 容器同时管理 items 与 roles 的上下文，确保角色配置与消息项正确关联。 + +```mermaid +classDiagram +class RoleItemHandler { ++处理角色项 ++接收 props 与 slots +} +class ItemHandler { ++处理通用项 ++接收 props 与 slots +} +class BubbleListItem { ++React 包装 ++委托 ItemHandler +} +class BubbleListRole { ++React 包装 ++委托 RoleItemHandler +} +RoleItemHandler <.. BubbleListRole : "委托" +ItemHandler <.. BubbleListItem : "委托" +``` + +图表来源 + +- [frontend/antdx/bubble/list/context.ts:6-10](file://frontend/antdx/bubble/list/context.ts#L6-L10) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:7-11](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L7-L11) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:7-11](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L7-L11) + +章节来源 + +- [frontend/antdx/bubble/list/context.ts:1-12](file://frontend/antdx/bubble/list/context.ts#L1-L12) +- [frontend/antdx/bubble/list/item/bubble.list.item.tsx:1-14](file://frontend/antdx/bubble/list/item/bubble.list.item.tsx#L1-L14) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:1-14](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L1-L14) + +### 使用示例与最佳实践 + +- 基础角色标识 + - 设置 role、avatar、header、footer 等基础属性，即可快速渲染角色头像与标题区域。 +- 自定义角色样式 + - 通过 class_names 与 styles 为不同区域设置类名与内联样式；利用 shape 与 variant 控制外观。 +- 动态角色信息 + - 结合 useRole 的 preProcess 与 defaultRolePostProcess，实现根据消息索引或上下文动态调整角色配置。 +- 与 Bubble.Item 的组合 + - 在 BubbleList 中同时提供 items 与 roles，确保角色信息与消息内容协同渲染。 + +章节来源 + +- [frontend/antdx/bubble/list/utils.tsx:44-112](file://frontend/antdx/bubble/list/utils.tsx#L44-L112) +- [frontend/antdx/bubble/list/bubble.list.tsx:13-46](file://frontend/antdx/bubble/list/bubble.list.tsx#L13-L46) + +## 依赖关系分析 + +- 组件耦合 + - Role.svelte 依赖 context.ts 提供的 RoleItemHandler，通过 bubble.list.role.tsx 与 Ant Design X 的 Bubble.List 对接。 + - utils.tsx 通过 useRoleItems 获取角色上下文，与 BubbleList 容器形成松耦合的配置注入机制。 +- 外部依赖 + - Ant Design X 的 Bubble.List 作为渲染核心，Bubble.Role 仅负责角色维度的配置与插槽处理。 + - Gradio 事件系统用于 typing、typing_complete、edit_confirm、edit_cancel 等回调绑定。 + +```mermaid +graph TB +ROLE["Role.svelte"] --> CTX["context.ts"] +ROLE --> CORE["bubble.list.role.tsx"] +CORE --> ADX["Ant Design X Bubble.List"] +LIST["bubble.list.tsx"] --> CTX +LIST --> UTIL["utils.tsx"] +UTIL --> CTX +``` + +图表来源 + +- [frontend/antdx/bubble/list/role/Role.svelte:14-16](file://frontend/antdx/bubble/list/role/Role.svelte#L14-L16) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:7-11](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L7-L11) +- [frontend/antdx/bubble/list/context.ts:6-10](file://frontend/antdx/bubble/list/context.ts#L6-L10) +- [frontend/antdx/bubble/list/bubble.list.tsx:13-46](file://frontend/antdx/bubble/list/bubble.list.tsx#L13-L46) +- [frontend/antdx/bubble/list/utils.tsx:64-90](file://frontend/antdx/bubble/list/utils.tsx#L64-L90) + +章节来源 + +- [frontend/antdx/bubble/list/role/Role.svelte:1-148](file://frontend/antdx/bubble/list/role/Role.svelte#L1-L148) +- [frontend/antdx/bubble/list/role/bubble.list.role.tsx:1-14](file://frontend/antdx/bubble/list/role/bubble.list.role.tsx#L1-L14) +- [frontend/antdx/bubble/list/context.ts:1-12](file://frontend/antdx/bubble/list/context.ts#L1-L12) +- [frontend/antdx/bubble/list/bubble.list.tsx:1-48](file://frontend/antdx/bubble/list/bubble.list.tsx#L1-L48) +- [frontend/antdx/bubble/list/utils.tsx:1-112](file://frontend/antdx/bubble/list/utils.tsx#L1-L112) + +## 性能考虑 + +- 按需渲染 + - 通过 visible 控制组件可见性，避免不必要的渲染与 DOM 更新。 +- 插槽克隆与参数传递 + - 插槽采用克隆与带参渲染策略，减少重复计算与副作用。 +- 事件绑定优化 + - 事件回调通过 Gradio 内部更新绑定标志位，避免频繁重绑导致的性能损耗。 +- 计算缓存 + - useRole 通过 useMemoizedFn 与 useMemoizedEqualValue 缓存函数与默认键，降低重复解析成本。 + +## 故障排除指南 + +- 角色未生效 + - 检查 role 键是否存在于 useRole 的角色映射中；确认 defaultRoleKeys 是否包含该键。 + - 确认 BubbleList 已注入 roles 上下文。 +- 插槽不显示 + - 确认插槽名称拼写正确（avatar/header/footer/extra/loadingRender/contentRender）。 + - 检查插槽是否被父级容器覆盖或未正确传递至 BubbleListRole。 +- 事件无效 + - 确认事件监听器已启用（bind_typing_event/bind_typingComplete_event 等）。 + - 检查事件回调是否正确绑定到组件实例。 +- 样式不生效 + - 检查 class_names 与 styles 的键名是否与目标区域一致。 + - 确认 root_class_name 与 elem_classes 的优先级关系。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/list/role/**init**.py:14-34](file://backend/modelscope_studio/components/antdx/bubble/list/role/__init__.py#L14-L34) +- [frontend/antdx/bubble/list/role/Role.svelte:66-133](file://frontend/antdx/bubble/list/role/Role.svelte#L66-L133) +- [frontend/antdx/bubble/list/utils.tsx:91-112](file://frontend/antdx/bubble/list/utils.tsx#L91-L112) + +## 结论 + +Bubble.Role 通过清晰的前后端分层设计与灵活的角色配置机制，实现了在消息气泡中对发送者角色的高效标识与渲染。其与 Bubble.Item 的紧密协作、与 Ant Design X 的无缝对接，以及对插槽、事件与样式的全面支持，使其成为构建复杂聊天界面的理想选择。建议在实际项目中结合 useRole 的钩子与 BubbleList 的上下文能力，实现更丰富的角色化体验。 + +## 附录 + +- 相关文档与示例 + - Bubble 组件文档与示例页面，包含基础气泡、打字效果、外观变体、气泡列表与自定义列表内容等演示。 + +章节来源 + +- [docs/components/antdx/bubble/README-zh_CN.md:1-13](file://docs/components/antdx/bubble/README-zh_CN.md#L1-L13) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.System \347\263\273\347\273\237\346\266\210\346\201\257\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.System \347\263\273\347\273\237\346\266\210\346\201\257\347\273\204\344\273\266.md" new file mode 100644 index 00000000..25178160 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Bubble \345\257\271\350\257\235\346\260\224\346\263\241/Bubble.System \347\263\273\347\273\237\346\266\210\346\201\257\347\273\204\344\273\266.md" @@ -0,0 +1,331 @@ +# Bubble.System 系统消息组件 + + +**本文档引用的文件** +- [frontend/antdx/bubble/system/bubble.system.tsx](file://frontend/antdx/bubble/system/bubble.system.tsx) +- [frontend/antdx/bubble/system/Index.svelte](file://frontend/antdx/bubble/system/Index.svelte) +- [backend/modelscope_studio/components/antdx/bubble/system/__init__.py](file://backend/modelscope_studio/components/antdx/bubble/system/__init__.py) +- [frontend/antdx/bubble/bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [frontend/antdx/bubble/system/package.json](file://frontend/antdx/bubble/system/package.json) +- [frontend/antdx/bubble/system/gradio.config.js](file://frontend/antdx/bubble/system/gradio.config.js) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Bubble.System 是专用于渲染“系统消息”的组件，区别于普通用户或机器人消息，系统消息通常用于呈现系统提示、状态通知、操作反馈等非对话型信息。该组件基于 Ant Design X 的系统气泡能力进行封装，提供统一的渲染入口与属性配置，确保在聊天界面中以一致的视觉风格和交互行为展示系统类内容。 + +## 项目结构 + +Bubble.System 组件由前端 Svelte 包装层与后端 Python 组件两部分组成： + +- 前端包装层：负责将 Ant Design X 的系统气泡组件桥接到 Gradio/Svelte 生态，并支持插槽（slot）与额外属性透传。 +- 后端组件：作为 ModelScope Studio 的布局组件，定义可选插槽、属性集合以及渲染控制策略。 + +```mermaid +graph TB +subgraph "前端" +A["Index.svelte
组件包装器"] +B["bubble.system.tsx
系统气泡包装"] +C["bubble.tsx
普通气泡包装"] +end +subgraph "后端" +D["__init__.py
AntdXBubbleSystem"] +end +E["@ant-design/x
系统气泡组件"] --> B +A --> B +A --> C +D --> A +``` + +图表来源 + +- [frontend/antdx/bubble/system/Index.svelte:10-63](file://frontend/antdx/bubble/system/Index.svelte#L10-L63) +- [frontend/antdx/bubble/system/bubble.system.tsx:12-24](file://frontend/antdx/bubble/system/bubble.system.tsx#L12-L24) +- [backend/modelscope_studio/components/antdx/bubble/system/**init**.py:8-55](file://backend/modelscope_studio/components/antdx/bubble/system/__init__.py#L8-L55) + +章节来源 + +- [frontend/antdx/bubble/system/Index.svelte:1-64](file://frontend/antdx/bubble/system/Index.svelte#L1-L64) +- [frontend/antdx/bubble/system/bubble.system.tsx:1-27](file://frontend/antdx/bubble/system/bubble.system.tsx#L1-L27) +- [backend/modelscope_studio/components/antdx/bubble/system/**init**.py:1-73](file://backend/modelscope_studio/components/antdx/bubble/system/__init__.py#L1-L73) + +## 核心组件 + +- 前端系统气泡包装（bubble.system.tsx） + - 将 Ant Design X 的系统气泡组件桥接为 Svelte 可用形态，支持 content 插槽与普通属性透传。 + - 使用 ReactSlot 渲染插槽内容，确保与 Gradio/Svelte 的插槽机制兼容。 +- 前端组件包装器（Index.svelte） + - 动态导入系统气泡包装组件，按需渲染。 + - 提供可见性控制、样式与 ID 注入、附加属性透传等通用能力。 +- 后端组件（AntdXBubbleSystem） + - 定义系统消息可用的属性集合（如 shape、variant、content 等）。 + - 支持 content 插槽，声明式地注入系统消息内容。 + - 控制渲染可见性与元素级样式/类名注入。 + +章节来源 + +- [frontend/antdx/bubble/system/bubble.system.tsx:7-24](file://frontend/antdx/bubble/system/bubble.system.tsx#L7-L24) +- [frontend/antdx/bubble/system/Index.svelte:13-63](file://frontend/antdx/bubble/system/Index.svelte#L13-L63) +- [backend/modelscope_studio/components/antdx/bubble/system/**init**.py:20-55](file://backend/modelscope_studio/components/antdx/bubble/system/__init__.py#L20-L55) + +## 架构总览 + +Bubble.System 的调用链路如下： + +- 后端 AntdXBubbleSystem 接收属性与插槽，决定是否渲染。 +- 前端 Index.svelte 在可见时动态加载 bubble.system.tsx。 +- bubble.system.tsx 将 Ant Design X 的系统气泡组件与插槽内容对接，完成最终渲染。 + +```mermaid +sequenceDiagram +participant Backend as "后端组件
AntdXBubbleSystem" +participant FrontIndex as "前端包装器
Index.svelte" +participant Wrapper as "系统气泡包装
bubble.system.tsx" +participant XSys as "Ant Design X 系统气泡" +Backend->>FrontIndex : "传递属性与可见性" +FrontIndex->>FrontIndex : "解析附加属性/样式/类名" +FrontIndex->>Wrapper : "动态导入并传入属性" +Wrapper->>XSys : "渲染系统气泡
注入 content 插槽" +XSys-->>Wrapper : "系统消息渲染结果" +Wrapper-->>FrontIndex : "返回渲染节点" +FrontIndex-->>Backend : "完成一次渲染" +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/bubble/system/**init**.py:40-55](file://backend/modelscope_studio/components/antdx/bubble/system/__init__.py#L40-L55) +- [frontend/antdx/bubble/system/Index.svelte:47-63](file://frontend/antdx/bubble/system/Index.svelte#L47-L63) +- [frontend/antdx/bubble/system/bubble.system.tsx:12-24](file://frontend/antdx/bubble/system/bubble.system.tsx#L12-L24) + +## 详细组件分析 + +### 前端系统气泡包装（bubble.system.tsx） + +- 设计要点 + - 使用 sveltify 将原生 React 组件桥接为 Svelte 形态，保留 slot 能力。 + - content 插槽优先级高于直接属性，便于灵活定制系统消息内容。 + - 隐藏 children，避免重复渲染与样式冲突。 +- 关键流程 + - 判断是否存在 content 插槽，若存在则通过 ReactSlot 渲染；否则回退到 props.content。 + - 将除 content 外的属性透传给 Ant Design X 的系统气泡组件。 + +```mermaid +flowchart TD +Start(["进入 bubble.system.tsx"]) --> CheckSlot["检查是否存在 content 插槽"] +CheckSlot --> |是| RenderSlot["通过 ReactSlot 渲染插槽内容"] +CheckSlot --> |否| UseProp["使用 props.content"] +RenderSlot --> PassThrough["透传其余属性给 Ant Design X 系统气泡"] +UseProp --> PassThrough +PassThrough --> End(["完成渲染"]) +``` + +图表来源 + +- [frontend/antdx/bubble/system/bubble.system.tsx:12-24](file://frontend/antdx/bubble/system/bubble.system.tsx#L12-L24) + +章节来源 + +- [frontend/antdx/bubble/system/bubble.system.tsx:1-27](file://frontend/antdx/bubble/system/bubble.system.tsx#L1-L27) + +### 前端组件包装器（Index.svelte） + +- 设计要点 + - 动态导入系统气泡包装组件，避免不必要的初始加载。 + - 对可见性、样式、类名、元素 ID 进行统一处理，保证与 Gradio 生态一致。 + - 将 content 优先从附加属性或组件属性中获取，确保灵活性。 +- 关键流程 + - 解析组件属性与附加属性，过滤掉内部字段。 + - 计算最终样式与类名，注入到系统气泡包装组件。 + - 传入 slots 与 children，交由包装层完成渲染。 + +```mermaid +flowchart TD +AStart(["进入 Index.svelte"]) --> ParseProps["解析组件属性与附加属性"] +ParseProps --> FilterInternal["过滤内部字段
保留可见性/样式/类名/ID"] +FilterInternal --> ComputeStyle["计算最终样式与类名"] +ComputeStyle --> ResolveContent["解析 content 来源优先级"] +ResolveContent --> ImportWrapper["动态导入系统气泡包装"] +ImportWrapper --> Render["渲染系统气泡包装并传入属性"] +Render --> AEnd(["完成渲染"]) +``` + +图表来源 + +- [frontend/antdx/bubble/system/Index.svelte:20-63](file://frontend/antdx/bubble/system/Index.svelte#L20-L63) + +章节来源 + +- [frontend/antdx/bubble/system/Index.svelte:1-64](file://frontend/antdx/bubble/system/Index.svelte#L1-L64) + +### 后端组件（AntdXBubbleSystem） + +- 设计要点 + - 继承 ModelScope Studio 的布局组件基类，具备统一的生命周期与渲染策略。 + - 显式声明支持的插槽（content），确保前端包装层正确对接。 + - 属性集合覆盖系统消息常见需求：内容、形状、变体、样式与类名等。 +- 关键流程 + - 初始化阶段设置可见性、元素 ID/类名/样式、附加属性等。 + - 指定前端目录映射，确保前端资源正确加载。 + - 标记为跳过 API 调用，避免冗余的前后端通信。 + +```mermaid +classDiagram +class AntdXBubbleSystem { ++EVENTS ++SLOTS ++content ++shape ++variant ++styles ++class_names ++root_class_name ++additional_props ++visible ++elem_id ++elem_classes ++elem_style ++render ++skip_api ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/bubble/system/**init**.py:8-73](file://backend/modelscope_studio/components/antdx/bubble/system/__init__.py#L8-L73) + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/system/**init**.py:1-73](file://backend/modelscope_studio/components/antdx/bubble/system/__init__.py#L1-L73) + +### 与普通气泡组件的差异 + +- 角色定位 + - 普通气泡（Bubble）用于用户/机器人对话内容渲染，支持头像、标题、底部操作等丰富插槽。 + - 系统气泡（Bubble.System）专注于系统提示、状态通知、操作反馈等非对话型内容。 +- 插槽与属性 + - 普通气泡支持更多插槽（如 avatar、header、footer、extra、contentRender 等）。 + - 系统气泡仅聚焦 content 插槽与基础属性，保持简洁与一致性。 +- 渲染目标 + - 普通气泡面向“人”与“角色”的交互内容。 + - 系统气泡面向“系统”向用户传达的信息。 + +章节来源 + +- [frontend/antdx/bubble/bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) +- [frontend/antdx/bubble/system/bubble.system.tsx:7-24](file://frontend/antdx/bubble/system/bubble.system.tsx#L7-L24) + +## 依赖关系分析 + +- 前端依赖 + - @svelte-preprocess-react：提供 sveltify 与 ReactSlot 能力，实现 React 组件与 Svelte 的桥接。 + - @ant-design/x：系统气泡组件的实际实现来源。 + - 前端包导出配置与 Gradio 集成：通过 package.json 的 exports 字段与 gradio.config.js 实现。 +- 后端依赖 + - ModelScopeLayoutComponent：统一的布局组件基类，提供可见性、样式、类名等通用能力。 + - resolve_frontend_dir：根据组件类型与名称解析前端目录，确保资源正确加载。 + +```mermaid +graph LR +Pkg["package.json
exports 映射"] --> GradioCfg["gradio.config.js"] +GradioCfg --> FrontIndex["Index.svelte"] +FrontIndex --> Wrapper["bubble.system.tsx"] +Wrapper --> XSys["@ant-design/x 系统气泡"] +Back["AntdXBubbleSystem
后端组件"] --> FrontIndex +``` + +图表来源 + +- [frontend/antdx/bubble/system/package.json:1-15](file://frontend/antdx/bubble/system/package.json#L1-L15) +- [frontend/antdx/bubble/system/gradio.config.js:1-4](file://frontend/antdx/bubble/system/gradio.config.js#L1-L4) +- [frontend/antdx/bubble/system/Index.svelte:10-10](file://frontend/antdx/bubble/system/Index.svelte#L10-L10) +- [frontend/antdx/bubble/system/bubble.system.tsx:4-4](file://frontend/antdx/bubble/system/bubble.system.tsx#L4-L4) +- [backend/modelscope_studio/components/antdx/bubble/system/**init**.py:55-55](file://backend/modelscope_studio/components/antdx/bubble/system/__init__.py#L55-L55) + +章节来源 + +- [frontend/antdx/bubble/system/package.json:1-15](file://frontend/antdx/bubble/system/package.json#L1-L15) +- [frontend/antdx/bubble/system/gradio.config.js:1-4](file://frontend/antdx/bubble/system/gradio.config.js#L1-L4) +- [backend/modelscope_studio/components/antdx/bubble/system/**init**.py:55-55](file://backend/modelscope_studio/components/antdx/bubble/system/__init__.py#L55-L55) + +## 性能考虑 + +- 按需加载 + - Index.svelte 采用动态导入，仅在可见时加载系统气泡包装组件，降低初始渲染开销。 +- 插槽渲染优化 + - ReactSlot 仅在插槽存在时才渲染，避免空内容造成的不必要计算。 +- 属性透传最小化 + - 仅传递必要属性与插槽，减少不必要的重渲染与样式计算。 + +## 故障排除指南 + +- 内容未显示 + - 检查 content 是否通过插槽或属性正确传入；插槽优先级高于属性。 + - 确认组件可见性（visible）为真值。 +- 样式异常 + - 检查 elem_id、elem_classes、elem_style 是否按预期注入。 + - 确认附加属性（additional_props）未覆盖关键样式。 +- 插槽无效 + - 确保插槽名称与后端声明一致（当前仅支持 content 插槽）。 + - 避免同时使用插槽与属性导致的优先级混淆。 + +章节来源 + +- [frontend/antdx/bubble/system/Index.svelte:47-63](file://frontend/antdx/bubble/system/Index.svelte#L47-L63) +- [frontend/antdx/bubble/system/bubble.system.tsx:12-24](file://frontend/antdx/bubble/system/bubble.system.tsx#L12-L24) +- [backend/modelscope_studio/components/antdx/bubble/system/**init**.py:16-18](file://backend/modelscope_studio/components/antdx/bubble/system/__init__.py#L16-L18) + +## 结论 + +Bubble.System 通过清晰的前后端分层设计，将 Ant Design X 的系统气泡能力无缝集成到 ModelScope Studio 的组件生态中。其简洁的属性集与插槽机制，使其非常适合用于系统提示、状态通知与操作反馈等场景。配合按需加载与插槽渲染优化，能够在保证功能完整性的同时兼顾性能表现。 + +## 附录 + +### 使用示例（场景化） + +- 欢迎消息 + - 场景：用户首次进入页面时展示欢迎语。 + - 方案：通过 content 插槽注入欢迎文案，设置合适的 shape/variant 以突出系统提示风格。 +- 错误提示 + - 场景：网络异常或服务错误时向用户提示。 + - 方案：使用 content 插槽承载错误描述，结合样式与类名注入统一视觉风格。 +- 进度通知 + - 场景：后台任务执行中的阶段性提示。 + - 方案：通过 content 插槽动态更新进度文本，保持系统消息的一致性与可读性。 + +### 配置选项与最佳实践 + +- 常用属性 + - content：系统消息内容（字符串或插槽）。 + - shape：气泡形状（round/corner/default）。 + - variant：外观变体（filled/borderless/outlined/shadow）。 + - styles/elem_style：内联样式。 + - elem_id/elem_classes：元素 ID 与类名。 + - additional_props：附加属性集合。 + - visible：是否渲染。 +- 最佳实践 + - 优先使用 content 插槽以获得更高的灵活性。 + - 保持系统消息的简洁与一致性，避免过度装饰影响可读性。 + - 合理使用 shape 与 variant，确保在不同主题下具有良好的对比度与可识别性。 + - 通过 elem_id/elem_classes 精准控制样式，避免全局污染。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/bubble/system/**init**.py:20-55](file://backend/modelscope_studio/components/antdx/bubble/system/__init__.py#L20-L55) +- [frontend/antdx/bubble/system/Index.svelte:20-63](file://frontend/antdx/bubble/system/Index.svelte#L20-L63) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/API \345\217\202\350\200\203.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/API \345\217\202\350\200\203.md" new file mode 100644 index 00000000..c622691d --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/API \345\217\202\350\200\203.md" @@ -0,0 +1,376 @@ +# API 参考 + + +**本文引用的文件** +- [conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [context.ts](file://frontend/antdx/conversations/context.ts) +- [Index.svelte](file://frontend/antdx/conversations/Index.svelte) +- [conversations.item.tsx](file://frontend/antdx/conversations/item/conversations.item.tsx) +- [basic.py](file://docs/components/antdx/conversations/demos/basic.py) +- [operations.py](file://docs/components/antdx/conversations/demos/operations.py) +- [group.py](file://docs/components/antdx/conversations/demos/group.py) +- [package.json](file://frontend/package.json) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件为 Conversations 组件的详细 API 参考文档，覆盖以下方面： + +- 所有属性参数：active_key、default_active_key、items、menu、groupable、shortcut_keys、creation、styles、class_names 等 +- 事件监听器：active_change、menu_open_change、menu_click、menu_select 等 +- 插槽（slots）：menu.expandIcon、menu.overflowedIndicator、menu.trigger、groupable.label、items、creation.icon 等 +- 参数类型、默认值、使用场景与配置示例 +- 内部数据流与渲染机制说明 + +## 项目结构 + +Conversations 组件由前端 Svelte 包装层与 Ant Design X 的真实组件组合而成，并通过 Gradio 前端桥接层进行事件映射与插槽透传。 + +```mermaid +graph TB +subgraph "前端包装层" +A["Index.svelte
属性处理与事件重命名"] +B["conversations.tsx
菜单与分组逻辑、插槽渲染"] +C["context.ts
items 上下文提供者"] +D["item/conversations.item.tsx
子项包装"] +end +subgraph "外部依赖" +E["@ant-design/x
Conversations 组件"] +F["antd
Menu 接口与事件"] +end +A --> B +B --> E +B --> F +B --> C +D --> C +``` + +图表来源 + +- [Index.svelte:1-70](file://frontend/antdx/conversations/Index.svelte#L1-L70) +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [conversations.item.tsx:1-13](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L13) + +章节来源 + +- [Index.svelte:1-70](file://frontend/antdx/conversations/Index.svelte#L1-L70) +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [conversations.item.tsx:1-13](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L13) + +## 核心组件 + +- 组件名称：Conversations +- 包装来源：@ant-design/x 的 Conversations 组件 +- 作用：管理与展示会话列表，支持菜单、分组、快捷键等高级能力 +- 事件映射：active_change、menu_open_change 在前端桥接层中被重命名为 activeChange、menu_openChange + +章节来源 + +- [Index.svelte:24-51](file://frontend/antdx/conversations/Index.svelte#L24-L51) +- [conversations.tsx:59-178](file://frontend/antdx/conversations/conversations.tsx#L59-L178) + +## 架构总览 + +下图展示了从调用到渲染的关键流程，包括菜单事件增强、插槽渲染与分组配置。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant S as "Index.svelte" +participant W as "conversations.tsx" +participant X as "@ant-design/x
Conversations" +participant M as "antd Menu" +U->>S : 触发 active_change / menu_open_change +S->>S : 属性重命名 active_change->activeChange
menu_open_change->menuOpenChange +S->>W : 传递 props 与 slots +W->>W : 解析 menu 配置与插槽 +W->>M : 渲染菜单项与触发器 +W->>X : 透传 items、groupable、class_names 等 +X-->>U : 渲染会话列表 +M-->>W : 菜单事件增强后 +W-->>S : 回调事件带 conversation 上下文 +``` + +图表来源 + +- [Index.svelte:24-51](file://frontend/antdx/conversations/Index.svelte#L24-L51) +- [conversations.tsx:35-122](file://frontend/antdx/conversations/conversations.tsx#L35-L122) +- [conversations.tsx:142-170](file://frontend/antdx/conversations/conversations.tsx#L142-L170) + +## 详细组件分析 + +### 属性参数（Props） + +- active_key + - 类型：string | number + - 默认值：未设置时由内部状态管理决定 + - 使用场景：受控激活项键值 + - 注意：在桥接层中对应 activeChange 事件，事件回调参数包含 payload + - 示例路径：[basic.py:14-28](file://docs/components/antdx/conversations/demos/basic.py#L14-L28) + +- default_active_key + - 类型：string | number + - 默认值：无 + - 使用场景：初始化默认激活项 + - 示例路径：[basic.py:32-45](file://docs/components/antdx/conversations/demos/basic.py#L32-L45) + +- items + - 类型：数组，元素为对象或通过插槽提供的子项 + - 默认值：空数组 + - 使用场景：直接传入会话项列表；也可通过插槽 items/default 提供 + - 渲染机制：优先使用传入的 items，否则使用插槽解析后的结果 + - 示例路径：[basic.py:14-28](file://docs/components/antdx/conversations/demos/basic.py#L14-L28) + +- menu + - 类型：对象或函数；对象包含 items、trigger、expandIcon、overflowedIndicator 等字段 + - 默认值：undefined + - 使用场景：为每个会话项提供操作菜单 + - 行为说明： + - 若传入字符串，则作为函数使用 + - 若传入对象且存在 items 或插槽 items，则生成菜单 + - onClick 事件会自动阻止 DOM 事件冒泡，并将当前 conversation 作为第一个参数传递给原始回调 + - 示例路径：[operations.py:29-43](file://docs/components/antdx/conversations/demos/operations.py#L29-L43) + +- groupable + - 类型：boolean 或对象；对象可包含 label、collapsible 等 + - 默认值：false + - 使用场景：启用分组显示与可折叠行为 + - 行为说明：当传入对象或存在 groupable.label 插槽时生效；collapsible 支持函数或布尔值 + - 示例路径：[group.py:8-27](file://docs/components/antdx/conversations/demos/group.py#L8-L27) + +- shortcut_keys + - 类型：boolean + - 默认值：未显式设置时遵循 @ant-design/x 默认行为 + - 使用场景：启用键盘快捷键导航 + - 注意：具体可用性取决于底层 @ant-design/x 实现 + +- creation + - 类型：对象或函数 + - 默认值：未设置 + - 使用场景：自定义“新建”入口或行为 + - 注意：具体字段与行为以 @ant-design/x 文档为准 + +- styles / class_names + - 类型：对象；class_names 支持额外类名拼接 + - 默认值：无 + - 使用场景：自定义样式与主题类名 + - 行为说明：内部会为 item 自动拼接特定类名，同时保留用户传入的 classNames + +章节来源 + +- [conversations.tsx:72-170](file://frontend/antdx/conversations/conversations.tsx#L72-L170) +- [Index.svelte:24-51](file://frontend/antdx/conversations/Index.svelte#L24-L51) +- [basic.py:14-45](file://docs/components/antdx/conversations/demos/basic.py#L14-L45) +- [operations.py:29-43](file://docs/components/antdx/conversations/demos/operations.py#L29-L43) +- [group.py:8-27](file://docs/components/antdx/conversations/demos/group.py#L8-L27) + +### 事件监听器（Events） + +- active_change + - 说明：激活项变更事件 + - 桥接层重命名：activeChange + - 回调参数：包含 payload，可用于获取当前激活项信息 + - 示例路径：[basic.py:7-8](file://docs/components/antdx/conversations/demos/basic.py#L7-L8) + +- menu_open_change + - 说明：菜单打开状态变化事件 + - 桥接层重命名：menuOpenChange + - 回调参数：事件数据对象 + - 示例路径：[Index.svelte:20-21](file://frontend/antdx/conversations/Index.svelte#L20-L21) + +- menu_click + - 说明：菜单点击事件 + - 回调参数：事件数据对象，包含 payload + - 行为说明：onClick 事件会被增强，确保 DOM 事件不冒泡，并将 conversation 作为首个参数传递 + - 示例路径：[operations.py:7-8](file://docs/components/antdx/conversations/demos/operations.py#L7-L8) + +- menu_select + - 说明：菜单选择事件 + - 回调参数：事件数据对象 + - 行为说明：与 menu_click 类似，但触发时机为选择菜单项 + +章节来源 + +- [Index.svelte:20-21](file://frontend/antdx/conversations/Index.svelte#L20-L21) +- [conversations.tsx:35-57](file://frontend/antdx/conversations/conversations.tsx#L35-L57) +- [operations.py:7-8](file://docs/components/antdx/conversations/demos/operations.py#L7-L8) + +### 插槽（Slots） + +- menu.expandIcon + - 说明：自定义菜单展开图标 + - 位置：menu 分组 + - 用法：通过插槽渲染，支持参数化渲染 + - 示例路径：[operations.py:30-42](file://docs/components/antdx/conversations/demos/operations.py#L30-L42) + +- menu.overflowedIndicator + - 说明：菜单溢出指示器 + - 位置：menu 分组 + - 用法：通过插槽渲染，支持 ReactSlot 透传 + - 示例路径：[operations.py:30-42](file://docs/components/antdx/conversations/demos/operations.py#L30-L42) + +- menu.trigger + - 说明：自定义菜单触发器 + - 位置：menu 分组 + - 用法：通过插槽渲染，支持参数化渲染 + - 示例路径：[operations.py:30-42](file://docs/components/antdx/conversations/demos/operations.py#L30-L42) + +- groupable.label + - 说明：自定义分组标签 + - 位置：groupable 分组 + - 用法：通过插槽渲染，支持参数化渲染 + - 示例路径：[group.py:8-27](file://docs/components/antdx/conversations/demos/group.py#L8-L27) + +- items / default + - 说明：会话项内容插槽 + - 位置：Conversations 容器 + - 用法：通过子级 Conversations.Item 提供 label、icon 等内容 + - 示例路径：[basic.py:32-45](file://docs/components/antdx/conversations/demos/basic.py#L32-L45) + +- creation.icon + - 说明：自定义“新建”入口图标 + - 位置：creation 分组 + - 用法：通过插槽渲染 + - 注意：具体支持以 @ant-design/x 文档为准 + +章节来源 + +- [conversations.tsx:103-120](file://frontend/antdx/conversations/conversations.tsx#L103-L120) +- [conversations.tsx:157-162](file://frontend/antdx/conversations/conversations.tsx#L157-L162) +- [conversations.tsx:123-137](file://frontend/antdx/conversations/conversations.tsx#L123-L137) +- [basic.py:32-45](file://docs/components/antdx/conversations/demos/basic.py#L32-L45) +- [operations.py:29-43](file://docs/components/antdx/conversations/demos/operations.py#L29-L43) +- [group.py:8-27](file://docs/components/antdx/conversations/demos/group.py#L8-L27) + +### 数据流与渲染机制 + +```mermaid +flowchart TD +Start(["进入 Conversations 包装"]) --> ParseMenu["解析 menu 配置与插槽"] +ParseMenu --> HasMenu{"是否存在菜单？"} +HasMenu --> |是| BuildMenu["构建菜单对象
合并 items/trigger/expandIcon/overflowedIndicator"] +HasMenu --> |否| SkipMenu["跳过菜单"] +BuildMenu --> GroupableCheck{"是否启用分组？"} +SkipMenu --> GroupableCheck +GroupableCheck --> |是| ApplyGroup["应用 groupable.label 与 collapsible"] +GroupableCheck --> |否| SkipGroup["跳过分组"] +ApplyGroup --> ResolveItems["解析 items 列表"] +SkipGroup --> ResolveItems +ResolveItems --> Render["渲染 @ant-design/x Conversations"] +Render --> End(["完成"]) +``` + +图表来源 + +- [conversations.tsx:72-170](file://frontend/antdx/conversations/conversations.tsx#L72-L170) + +章节来源 + +- [conversations.tsx:72-170](file://frontend/antdx/conversations/conversations.tsx#L72-L170) + +## 依赖分析 + +- 外部依赖 + - @ant-design/x：提供 Conversations 与相关类型 + - antd：提供 Menu 接口与事件类型 +- 内部工具 + - createFunction/useFunction：将字符串或函数转换为可执行函数 + - renderItems/renderParamsSlot/ReactSlot：插槽渲染与克隆 + - classNames：类名拼接 + +```mermaid +graph LR +P["package.json
依赖声明"] --> ADX["@ant-design/x"] +P --> ANT["antd"] +W["conversations.tsx"] --> ADX +W --> ANT +W --> Utils["工具函数与渲染器"] +``` + +图表来源 + +- [package.json:8-39](file://frontend/package.json#L8-L39) +- [conversations.tsx:1-26](file://frontend/antdx/conversations/conversations.tsx#L1-L26) + +章节来源 + +- [package.json:8-39](file://frontend/package.json#L8-L39) +- [conversations.tsx:1-26](file://frontend/antdx/conversations/conversations.tsx#L1-L26) + +## 性能考虑 + +- 插槽渲染采用克隆策略，避免重复创建节点，提升渲染效率 +- 菜单事件增强仅在存在 on 前缀的回调时进行，减少不必要的包裹 +- items 与 groupable 的解析在 useMemo 中进行，避免不必要的重算 +- 建议： + - 尽量复用菜单项与分组配置，避免频繁重建 + - 对于大量会话项，优先使用受控 items 并按需更新 + +章节来源 + +- [conversations.tsx:127-137](file://frontend/antdx/conversations/conversations.tsx#L127-L137) +- [conversations.tsx:153-168](file://frontend/antdx/conversations/conversations.tsx#L153-L168) + +## 故障排查指南 + +- 菜单点击事件未触发 + - 检查是否正确使用 menu.items 插槽或传入 menu 对象 + - 确认 onClick 是否为函数且未被错误地覆盖 + - 参考：[operations.py:29-43](file://docs/components/antdx/conversations/demos/operations.py#L29-L43) +- 激活项变更事件未收到 payload + - 确认事件绑定方式与桥接层重命名一致（activeChange） + - 参考：[Index.svelte:48-49](file://frontend/antdx/conversations/Index.svelte#L48-L49) +- 分组标签未生效 + - 确认 groupable 为对象或存在 groupable.label 插槽 + - 参考：[group.py:8-27](file://docs/components/antdx/conversations/demos/group.py#L8-L27) +- 子项内容未渲染 + - 确认通过 Conversations.Item 提供 label/icon 等插槽 + - 参考：[basic.py:32-45](file://docs/components/antdx/conversations/demos/basic.py#L32-L45) + +章节来源 + +- [operations.py:29-43](file://docs/components/antdx/conversations/demos/operations.py#L29-L43) +- [Index.svelte:48-49](file://frontend/antdx/conversations/Index.svelte#L48-L49) +- [group.py:8-27](file://docs/components/antdx/conversations/demos/group.py#L8-L27) +- [basic.py:32-45](file://docs/components/antdx/conversations/demos/basic.py#L32-L45) + +## 结论 + +Conversations 组件通过包装层实现了对 @ant-design/x 的增强，提供了灵活的菜单、分组与插槽能力，并在桥接层中完成了事件命名与参数增强。合理使用 items、menu、groupable 与各类插槽，可快速构建功能完备的会话列表界面。 + +## 附录 + +### 事件回调参数与返回值约定 + +- active_change / activeChange + - 参数：包含 payload 的事件对象 + - 返回：无（副作用处理） +- menu_open_change / menuOpenChange + - 参数：事件对象 + - 返回：无 +- menu_click + - 参数：事件对象（onClick 增强后，首参为 conversation） + - 返回：无 +- menu_select + - 参数：事件对象 + - 返回：无 + +章节来源 + +- [Index.svelte:20-21](file://frontend/antdx/conversations/Index.svelte#L20-L21) +- [conversations.tsx:35-57](file://frontend/antdx/conversations/conversations.tsx#L35-L57) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/Conversations \345\257\271\350\257\235\347\256\241\347\220\206.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/Conversations \345\257\271\350\257\235\347\256\241\347\220\206.md" new file mode 100644 index 00000000..ff31a623 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/Conversations \345\257\271\350\257\235\347\256\241\347\220\206.md" @@ -0,0 +1,345 @@ +# Conversations 对话管理 + + +**本文引用的文件** +- [frontend/antdx/conversations/Index.svelte](file://frontend/antdx/conversations/Index.svelte) +- [frontend/antdx/conversations/conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [frontend/antdx/conversations/context.ts](file://frontend/antdx/conversations/context.ts) +- [frontend/antdx/conversations/item/Index.svelte](file://frontend/antdx/conversations/item/Index.svelte) +- [frontend/antdx/conversations/item/conversations.item.tsx](file://frontend/antdx/conversations/item/conversations.item.tsx) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/antdx/conversations/index.less](file://frontend/antdx/conversations/index.less) +- [frontend/antdx/conversations/gradio.config.js](file://frontend/antdx/conversations/gradio.config.js) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件系统性阐述 Conversations 对话管理组件的设计与实现，覆盖以下方面： + +- 对话列表管理：添加、删除、排序、状态管理 +- Conversations.Item 对话项组件的渲染逻辑、交互行为、状态控制 +- 组件上下文（Context）的作用与对话状态共享机制 +- 属性配置、事件回调、样式定制与最佳实践 +- 完整使用示例：基本用法、动态增删、状态同步 + +## 项目结构 + +Conversations 组件由“容器层 + 项处理器 + 上下文”三层构成，并通过 Gradio 配置桥接运行时环境。 + +```mermaid +graph TB +subgraph "前端组件层" +A["Index.svelte
容器入口"] +B["conversations.tsx
对话容器实现"] +C["context.ts
项上下文导出"] +D["item/Index.svelte
项入口"] +E["item/conversations.item.tsx
项处理器"] +F["index.less
样式"] +end +subgraph "通用工具层" +G["createItemsContext.tsx
项上下文工厂"] +end +subgraph "构建配置" +H["gradio.config.js
统一配置"] +end +A --> B +D --> E +B --> C +C --> G +E --> C +B --> F +A --> H +D --> H +``` + +图表来源 + +- [frontend/antdx/conversations/Index.svelte:1-71](file://frontend/antdx/conversations/Index.svelte#L1-L71) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/antdx/conversations/item/Index.svelte:1-73](file://frontend/antdx/conversations/item/Index.svelte#L1-L73) +- [frontend/antdx/conversations/item/conversations.item.tsx:1-14](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L14) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/antdx/conversations/index.less:1-4](file://frontend/antdx/conversations/index.less#L1-L4) +- [frontend/antdx/conversations/gradio.config.js:1-4](file://frontend/antdx/conversations/gradio.config.js#L1-L4) + +章节来源 + +- [frontend/antdx/conversations/Index.svelte:1-71](file://frontend/antdx/conversations/Index.svelte#L1-L71) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/antdx/conversations/item/Index.svelte:1-73](file://frontend/antdx/conversations/item/Index.svelte#L1-L73) +- [frontend/antdx/conversations/item/conversations.item.tsx:1-14](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L14) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/antdx/conversations/index.less:1-4](file://frontend/antdx/conversations/index.less#L1-L4) +- [frontend/antdx/conversations/gradio.config.js:1-4](file://frontend/antdx/conversations/gradio.config.js#L1-L4) + +## 核心组件 + +- Conversations 容器：负责接收 items、菜单配置、分组配置与插槽，最终渲染 antd-x 的 Conversations。 +- Conversations.Item 项处理器：通过 ItemHandler 将 Svelte 插槽与 React 侧的项数据打通，支持动态收集子项、计算 props、克隆/透传插槽。 +- 项上下文（Items Context）：提供 setItem、useItems、withItemsContextProvider 等能力，支撑对话项的声明式收集与变更通知。 +- 样式与配置：统一类名前缀与样式表；通过 gradio.config.js 汇聚构建配置。 + +章节来源 + +- [frontend/antdx/conversations/conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) +- [frontend/antdx/conversations/item/conversations.item.tsx:7-11](file://frontend/antdx/conversations/item/conversations.item.tsx#L7-L11) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:97-273](file://frontend/utils/createItemsContext.tsx#L97-L273) +- [frontend/antdx/conversations/index.less:1-4](file://frontend/antdx/conversations/index.less#L1-L4) +- [frontend/antdx/conversations/gradio.config.js:1-4](file://frontend/antdx/conversations/gradio.config.js#L1-L4) + +## 架构总览 + +Conversations 的运行时架构如下： + +```mermaid +sequenceDiagram +participant SvelteEntry as "Index.svelte" +participant ReactConv as "conversations.tsx" +participant AntDX as "@ant-design/x.Conversations" +participant ItemEntry as "item/Index.svelte" +participant ItemHandler as "ItemHandler(conversations.tsx)" +participant Ctx as "createItemsContext" +SvelteEntry->>ReactConv : 传递 props/children/slots +ReactConv->>Ctx : withItemsContextProvider 包裹 +ReactConv->>AntDX : 渲染并注入 items/menu/groupable +ItemEntry->>ItemHandler : 传入 itemIndex/itemSlotKey +ItemHandler->>Ctx : useItems 获取上下文 +ItemHandler->>Ctx : setItem(index, item) 写入项 +Ctx-->>ReactConv : onChange 回调触发 +ReactConv-->>AntDX : 更新 items 列表 +``` + +图表来源 + +- [frontend/antdx/conversations/Index.svelte:57-70](file://frontend/antdx/conversations/Index.svelte#L57-L70) +- [frontend/antdx/conversations/conversations.tsx:68-175](file://frontend/antdx/conversations/conversations.tsx#L68-L175) +- [frontend/antdx/conversations/item/Index.svelte:54-72](file://frontend/antdx/conversations/item/Index.svelte#L54-L72) +- [frontend/antdx/conversations/item/conversations.item.tsx:9-11](file://frontend/antdx/conversations/item/conversations.item.tsx#L9-L11) +- [frontend/utils/createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) + +## 详细组件分析 + +### Conversations 容器组件 + +- 职责 + - 解析容器级 props（visible、elem\_\*、额外属性），拼装到最终渲染参数 + - 处理菜单配置：支持字符串或对象形式；自动合并插槽与静态 items；对菜单事件进行包裹以透传当前对话项 + - 处理分组配置：支持 groupable.label 插槽与可折叠回调 + - 支持插槽：menu.trigger、menu.expandIcon、menu.overflowedIndicator、groupable.label + - 将 items 从插槽或外部 props 解析为数组，交由 antd-x 渲染 +- 关键点 + - 使用 useMemo 缓存 menu 与 resolvedItems，避免重复渲染 + - 通过 classNames 合并自定义类名，保证项元素具备统一类名前缀 + - 通过 renderItems 与 renderParamsSlot 统一处理插槽与参数化渲染 + +章节来源 + +- [frontend/antdx/conversations/conversations.tsx:28-57](file://frontend/antdx/conversations/conversations.tsx#L28-L57) +- [frontend/antdx/conversations/conversations.tsx:72-175](file://frontend/antdx/conversations/conversations.tsx#L72-L175) + +### Conversations.Item 项处理器 + +- 职责 + - 将 Svelte 插槽与 React 侧的项数据打通 + - 通过 ItemHandler 注入 itemIndex、itemSlotKey、slots 等信息 + - 支持 itemProps、itemChildren、allowedSlots 等扩展能力 +- 渲染流程 + - 在 useEffect 中根据 props、slots、子项上下文生成项值 + - 通过 setItem 写入上下文，驱动容器更新 + - 子树再次被包裹于 ItemsContextProvider，形成递归收集 + +章节来源 + +- [frontend/antdx/conversations/item/conversations.item.tsx:7-11](file://frontend/antdx/conversations/item/conversations.item.tsx#L7-L11) +- [frontend/utils/createItemsContext.tsx:190-261](file://frontend/utils/createItemsContext.tsx#L190-L261) + +### 项上下文（Items Context） + +- 设计要点 + - 提供 withItemsContextProvider、useItems、ItemHandler 三件套 + - setItem 支持显式 slotKey 与默认 default slot，内部深拷贝避免意外修改 + - onChange 回调在 items 变更时触发，便于上层感知 + - ItemHandler 内部 memo 化 props 与 children，减少重渲染 +- 数据结构 + - items：按 slotKey 分组的项数组 + - setItem：写入指定索引的项 + - initial：标记初始状态，用于首次渲染优化 + +章节来源 + +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:97-273](file://frontend/utils/createItemsContext.tsx#L97-L273) + +### Svelte 入口与属性透传 + +- Index.svelte + - 延迟加载容器组件，避免首屏阻塞 + - 仅在 visible 为真时渲染 + - 透传 elem\_\*、additionalProps、slots 等到 React 容器 +- item/Index.svelte + - 透传 itemIndex、itemSlotKey 等到项处理器 + - 保持可见性控制与样式类名 + +章节来源 + +- [frontend/antdx/conversations/Index.svelte:57-70](file://frontend/antdx/conversations/Index.svelte#L57-L70) +- [frontend/antdx/conversations/item/Index.svelte:54-72](file://frontend/antdx/conversations/item/Index.svelte#L54-L72) + +### 类图：组件与上下文关系 + +```mermaid +classDiagram +class ConversationsContainer { ++props : "items, menu, groupable, classNames" ++slots : "menu.trigger, menu.expandIcon, menu.overflowedIndicator, groupable.label" ++render() : "XConversations" +} +class ConversationsItemHandler { ++props : "itemIndex, itemSlotKey, slots, itemProps, itemChildren" ++setItem() : "写入上下文" ++render() : "子项上下文Provider" +} +class ItemsContext { ++items : "{[slotKey] : Item[]}" ++setItem(slotKey, index, item) ++useItems() : "获取items/setItem" +} +ConversationsContainer --> ItemsContext : "消费/订阅" +ConversationsItemHandler --> ItemsContext : "写入项" +ConversationsContainer --> ConversationsItemHandler : "渲染项" +``` + +图表来源 + +- [frontend/antdx/conversations/conversations.tsx:68-175](file://frontend/antdx/conversations/conversations.tsx#L68-L175) +- [frontend/antdx/conversations/item/conversations.item.tsx:9-11](file://frontend/antdx/conversations/item/conversations.item.tsx#L9-L11) +- [frontend/utils/createItemsContext.tsx:102-170](file://frontend/utils/createItemsContext.tsx#L102-L170) + +## 依赖关系分析 + +- 容器依赖 + - @ant-design/x：实际渲染对话列表与菜单 + - @utils/\*：渲染工具（renderItems、renderParamsSlot）、函数包装（useFunction） + - 本地 context：与 antd menu 的 ItemsContext 协作，复用菜单插槽体系 +- 项处理器依赖 + - createItemsContext：提供 setItem/useItems/ItemHandler +- 样式与构建 + - index.less：统一类名前缀 + - gradio.config.js：统一构建配置 + +```mermaid +graph LR +ConvTSX["conversations.tsx"] --> AntDX["@ant-design/x"] +ConvTSX --> Utils["@utils/*"] +ConvTSX --> Ctx["context.ts"] +ItemTSX["item/conversations.item.tsx"] --> Ctx +Ctx --> CreateCtx["createItemsContext.tsx"] +ConvTSX --> Less["index.less"] +ConvSvelte["Index.svelte"] --> ConvTSX +ItemSvelte["item/Index.svelte"] --> ItemTSX +``` + +图表来源 + +- [frontend/antdx/conversations/conversations.tsx:1-26](file://frontend/antdx/conversations/conversations.tsx#L1-L26) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/antdx/conversations/item/conversations.item.tsx:1-14](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L14) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/antdx/conversations/index.less:1-4](file://frontend/antdx/conversations/index.less#L1-L4) +- [frontend/antdx/conversations/Index.svelte:1-71](file://frontend/antdx/conversations/Index.svelte#L1-L71) +- [frontend/antdx/conversations/item/Index.svelte:1-73](file://frontend/antdx/conversations/item/Index.svelte#L1-L73) + +章节来源 + +- [frontend/antdx/conversations/conversations.tsx:1-26](file://frontend/antdx/conversations/conversations.tsx#L1-L26) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/antdx/conversations/item/conversations.item.tsx:1-14](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L14) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/antdx/conversations/index.less:1-4](file://frontend/antdx/conversations/index.less#L1-L4) +- [frontend/antdx/conversations/Index.svelte:1-71](file://frontend/antdx/conversations/Index.svelte#L1-L71) +- [frontend/antdx/conversations/item/Index.svelte:1-73](file://frontend/antdx/conversations/item/Index.svelte#L1-L73) + +## 性能考量 + +- 渲染缓存 + - 使用 useMemo 缓存 menu 与 resolvedItems，避免不必要的重渲染 +- 事件包裹 + - 菜单事件通过 patchMenuEvents 包裹，确保点击冒泡被阻止且原事件仍可访问当前对话项 +- 上下文写入 + - setItem 采用浅拷贝数组并在必要时替换索引位置，避免深层不可变导致的昂贵操作 +- 插槽渲染 + - renderItems 与 renderParamsSlot 支持 clone 与 withParams，减少重复创建 DOM + +章节来源 + +- [frontend/antdx/conversations/conversations.tsx:83-122](file://frontend/antdx/conversations/conversations.tsx#L83-L122) +- [frontend/antdx/conversations/conversations.tsx:35-57](file://frontend/antdx/conversations/conversations.tsx#L35-L57) +- [frontend/utils/createItemsContext.tsx:124-153](file://frontend/utils/createItemsContext.tsx#L124-L153) + +## 故障排查指南 + +- 问题：菜单项不显示 + - 检查是否提供 menu.items 或通过插槽注入菜单项 + - 确认 menu.trigger、menu.expandIcon、menu.overflowedIndicator 插槽是否正确传入 +- 问题：对话项未生效 + - 确保 Conversations.Item 正确包裹在 Conversations 内部 + - 检查 itemIndex 与 itemSlotKey 是否正确传递 +- 问题：分组标签不显示 + - 确认 groupable.label 插槽或配置已提供 +- 问题：样式异常 + - 检查是否应用了统一类名前缀 ms-gr-antdx-conversations 与 ms-gr-antdx-conversations-item +- 问题：事件未触发或冒泡异常 + - 确认菜单事件是否通过 onClick 包裹，确保 domEvent.stopPropagation 已生效 + +章节来源 + +- [frontend/antdx/conversations/conversations.tsx:95-121](file://frontend/antdx/conversations/conversations.tsx#L95-L121) +- [frontend/antdx/conversations/conversations.tsx:153-168](file://frontend/antdx/conversations/conversations.tsx#L153-L168) +- [frontend/antdx/conversations/index.less:1-4](file://frontend/antdx/conversations/index.less#L1-L4) + +## 结论 + +Conversations 通过“容器 + 项处理器 + 上下文”的组合，实现了对话列表的声明式管理与高效渲染。其设计强调： + +- 明确的职责分离：容器负责布局与配置，项处理器负责数据收集与渲染 +- 强大的插槽与事件系统：菜单、分组、触发器均可灵活定制 +- 高性能的缓存与变更通知：减少重渲染，提升交互流畅度 + +## 附录 + +### 使用示例与最佳实践 + +- 基本用法 + - 在 Conversations 下放置多个 Conversations.Item，每个项通过 itemIndex 标识顺序 + - 通过插槽提供菜单项与分组标签 +- 动态增删 + - 通过 setItem 动态写入或删除某索引处的项，容器会自动响应 + - 删除后建议同步调整后续项的 itemIndex，避免索引错位 +- 状态同步 + - 使用 onChange 订阅 items 变化，实现与外部状态的双向绑定 +- 样式定制 + - 通过 classNames.item 自定义项样式，或覆盖 index.less 中的类名前缀 +- 事件回调 + - 菜单事件通过 onClick 包裹，确保可访问当前对话项与原始事件 + +章节来源 + +- [frontend/antdx/conversations/conversations.tsx:139-171](file://frontend/antdx/conversations/conversations.tsx#L139-L171) +- [frontend/antdx/conversations/item/Index.svelte:66-67](file://frontend/antdx/conversations/item/Index.svelte#L66-L67) +- [frontend/utils/createItemsContext.tsx:154-156](file://frontend/utils/createItemsContext.tsx#L154-L156) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/\344\275\277\347\224\250\347\244\272\344\276\213.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/\344\275\277\347\224\250\347\244\272\344\276\213.md" new file mode 100644 index 00000000..937be504 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/\344\275\277\347\224\250\347\244\272\344\276\213.md" @@ -0,0 +1,361 @@ +# 使用示例 + + +**本文引用的文件** +- [conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [context.ts](file://frontend/antdx/conversations/context.ts) +- [index.less](file://frontend/antdx/conversations/index.less) +- [__init__.py](file://backend/modelscope_studio/components/antdx/conversations/__init__.py) +- [item/__init__.py](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py) +- [README.md](file://docs/components/antdx/conversations/README.md) +- [README-zh_CN.md](file://docs/components/antdx/conversations/README-zh_CN.md) +- [demos/basic.py](file://docs/components/antdx/conversations/demos/basic.py) +- [demos/operations.py](file://docs/components/antdx/conversations/demos/operations.py) +- [demos/group.py](file://docs/components/antdx/conversations/demos/group.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件围绕 Conversations 组件提供从基础到高级的完整使用示例，涵盖： + +- 基础对话列表创建与默认选中项设置 +- 对话分组显示与可折叠配置 +- 对话项菜单操作（添加、删除、重命名） +- 对话状态管理（选中项变更、菜单点击事件） +- 与 Gradio 应用集成的实际案例（聊天应用、任务管理应用等场景） + +所有示例均基于仓库中的真实实现与演示脚本，确保可直接运行与复用。 + +## 项目结构 + +Conversations 组件由前端 Svelte 包装层与后端 Gradio 组件两部分组成： + +- 前端：通过 React 包装器桥接 Ant Design X 的 Conversations，并提供上下文与插槽能力 +- 后端：Gradio 组件封装，暴露事件与插槽，支持在 Blocks 中直接使用 + +```mermaid +graph TB +subgraph "前端" +CTSX["conversations.tsx
React 包装器"] +CTX["context.ts
Items 上下文"] +LESS["index.less
样式"] +end +subgraph "后端" +PY["__init__.py
Conversations 组件"] +ITEM["item/__init__.py
Conversations.Item 组件"] +end +subgraph "文档与示例" +DEMO_BASIC["demos/basic.py
基础示例"] +DEMO_OPS["demos/operations.py
菜单操作示例"] +DEMO_GROUP["demos/group.py
分组示例"] +DOC_README["README.md / README-zh_CN.md
示例入口"] +end +CTSX --> CTX +CTSX --> LESS +CTSX --> PY +PY --> ITEM +DEMO_BASIC --> PY +DEMO_OPS --> PY +DEMO_GROUP --> PY +DOC_README --> DEMO_BASIC +DOC_README --> DEMO_OPS +DOC_README --> DEMO_GROUP +``` + +图表来源 + +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [index.less:1-4](file://frontend/antdx/conversations/index.less#L1-L4) +- [**init**.py:1-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L1-L109) +- [item/**init**.py:1-75](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L1-L75) +- [README.md:1-10](file://docs/components/antdx/conversations/README.md#L1-L10) +- [README-zh_CN.md:1-10](file://docs/components/antdx/conversations/README-zh_CN.md#L1-L10) +- [demos/basic.py:1-50](file://docs/components/antdx/conversations/demos/basic.py#L1-L50) +- [demos/operations.py:1-47](file://docs/components/antdx/conversations/demos/operations.py#L1-L47) +- [demos/group.py:1-31](file://docs/components/antdx/conversations/demos/group.py#L1-L31) + +章节来源 + +- [README.md:1-10](file://docs/components/antdx/conversations/README.md#L1-L10) +- [README-zh_CN.md:1-10](file://docs/components/antdx/conversations/README-zh_CN.md#L1-L10) + +## 核心组件 + +- 前端包装器：负责将 Ant Design X 的 Conversations 能力以 Gradio 可用的方式呈现，支持菜单插槽、分组标签插槽、事件透传与样式扩展 +- 后端组件：定义事件、插槽、属性与渲染行为，适配 Gradio Blocks 的数据流 +- 插槽系统：支持菜单项、触发器、溢出指示器、图标、标签等自定义内容注入 + +章节来源 + +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) +- [item/**init**.py:8-75](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L8-L75) + +## 架构总览 + +前端包装器通过上下文与插槽机制，将 Ant Design X 的 Conversations 与 Gradio 组件桥接起来；后端组件负责事件绑定与插槽声明，最终在 Blocks 中以声明式方式组合使用。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant G as "Gradio Blocks" +participant PY as "后端组件(__init__.py)" +participant C as "前端包装(conversations.tsx)" +participant X as "Ant Design X Conversations" +U->>G : 触发事件如选择变更/菜单点击 +G->>PY : 分发事件回调 +PY-->>C : 事件绑定与插槽解析 +C->>X : 渲染对话列表/菜单/分组 +X-->>C : 返回交互结果 +C-->>G : 回传事件负载 +G-->>U : 更新界面 +``` + +图表来源 + +- [**init**.py:18-41](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L18-L41) +- [conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) + +## 详细组件分析 + +### 基础对话列表 + +- 功能要点 + - 通过 items 属性直接传入对话项数组 + - 设置 default_active_key 指定初始选中项 + - 支持禁用项（disabled） +- 运行效果 + - 列表按顺序渲染，初始高亮指定项 + - 选中项变化时触发 active_change 事件 +- 示例参考 + - [demos/basic.py:11-46](file://docs/components/antdx/conversations/demos/basic.py#L11-L46) + +章节来源 + +- [demos/basic.py:11-46](file://docs/components/antdx/conversations/demos/basic.py#L11-L46) +- [**init**.py:49-90](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L49-L90) + +### 自定义对话项与图标 + +- 功能要点 + - 使用 Conversations.Item 定义项 + - 通过 Slot 注入 label 与 icon 内容 + - 结合 Typography 与 Icon 实现富文本与图标 +- 运行效果 + - 每个对话项显示自定义标签与图标 +- 示例参考 + - [demos/basic.py:32-44](file://docs/components/antdx/conversations/demos/basic.py#L32-L44) + +章节来源 + +- [demos/basic.py:32-44](file://docs/components/antdx/conversations/demos/basic.py#L32-L44) +- [item/**init**.py:21-55](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L21-L55) + +### 菜单操作（添加、删除、重命名） + +- 功能要点 + - 通过 Slot 注入菜单项（menu.items），支持图标、禁用、危险样式 + - 事件回调 menu_click 获取当前点击项与菜单信息 +- 运行效果 + - 右侧触发器打开菜单，点击菜单项触发回调 +- 示例参考 + - [demos/operations.py:29-43](file://docs/components/antdx/conversations/demos/operations.py#L29-L43) + +章节来源 + +- [demos/operations.py:29-43](file://docs/components/antdx/conversations/demos/operations.py#L29-L43) +- [**init**.py:18-41](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L18-L41) + +### 对话分组显示与可折叠 + +- 功能要点 + - 通过 groupable=True 开启分组 + - 每个对话项设置 group 字段进行分组 + - 支持分组标签插槽与可折叠函数 +- 运行效果 + - 相同 group 的项被归为一组，支持展开/折叠 +- 示例参考 + - [demos/group.py:8-27](file://docs/components/antdx/conversations/demos/group.py#L8-L27) + +章节来源 + +- [demos/group.py:8-27](file://docs/components/antdx/conversations/demos/group.py#L8-L27) +- [**init**.py:49-90](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L49-L90) + +### 事件与状态管理 + +- 关键事件 + - active_change：选中项变更 + - menu_click/menu_select/menu_deselect/menu_open_change：菜单交互 + - groupable_expand：分组展开/收起 + - creation_click：创建按钮点击 +- 使用建议 + - 在回调中读取事件负载，更新应用状态或发起后续请求 +- 示例参考 + - [demos/basic.py:7-8](file://docs/components/antdx/conversations/demos/basic.py#L7-L8) + - [demos/operations.py:7-8](file://docs/components/antdx/conversations/demos/operations.py#L7-L8) + +章节来源 + +- [**init**.py:18-41](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L18-L41) +- [demos/basic.py:7-8](file://docs/components/antdx/conversations/demos/basic.py#L7-L8) +- [demos/operations.py:7-8](file://docs/components/antdx/conversations/demos/operations.py#L7-L8) + +### 插槽与样式定制 + +- 支持的插槽 + - menu.items、menu.trigger、menu.expandIcon、menu.overflowedIndicator + - groupable.label + - creation.icon、creation.label + - item 的 label、icon +- 样式 + - 默认样式类名与自定义类名合并 +- 示例参考 + - [conversations.tsx:68-175](file://frontend/antdx/conversations/conversations.tsx#L68-L175) + - [index.less:1-4](file://frontend/antdx/conversations/index.less#L1-L4) + +章节来源 + +- [conversations.tsx:68-175](file://frontend/antdx/conversations/conversations.tsx#L68-L175) +- [index.less:1-4](file://frontend/antdx/conversations/index.less#L1-L4) + +### 与 Gradio 应用集成（聊天应用） + +- 场景描述 + - 使用 Conversations 列表承载历史会话，结合 Chatbot 组件实现对话展示与输入 +- 实现思路 + - 将 Conversations 的选中项作为 Chatbot 的会话标识 + - 通过 active_change 事件加载对应会话消息 + - 通过菜单操作实现“新建”、“删除”、“重命名”等动作 +- 示例参考 + - [demos/basic.py:11-46](file://docs/components/antdx/conversations/demos/basic.py#L11-L46) + - [demos/operations.py:11-43](file://docs/components/antdx/conversations/demos/operations.py#L11-L43) + +章节来源 + +- [demos/basic.py:11-46](file://docs/components/antdx/conversations/demos/basic.py#L11-L46) +- [demos/operations.py:11-43](file://docs/components/antdx/conversations/demos/operations.py#L11-L43) + +### 与 Gradio 应用集成（任务管理应用） + +- 场景描述 + - 将对话项映射为任务条目，分组表示不同优先级或状态 +- 实现思路 + - group 字段用于分组（如“进行中/已完成”） + - 菜单操作实现任务编辑、删除、状态切换 + - 通过 active_change 事件联动任务详情面板 +- 示例参考 + - [demos/group.py:8-27](file://docs/components/antdx/conversations/demos/group.py#L8-L27) + +章节来源 + +- [demos/group.py:8-27](file://docs/components/antdx/conversations/demos/group.py#L8-L27) + +## 依赖关系分析 + +前端包装器与后端组件之间的依赖关系如下： + +```mermaid +classDiagram +class ConversationsWrapper { ++props : ConversationsProps ++slots : 插槽集合 ++useItems() : Items上下文 ++useMenuItems() : 菜单上下文 ++render() : 渲染 Ant Design X Conversations +} +class ConversationsBackend { ++EVENTS : 事件列表 ++SLOTS : 插槽列表 ++FRONTEND_DIR : 前端目录 ++skip_api : True +} +class ConversationsItemBackend { ++EVENTS : 事件列表 ++SLOTS : 插槽列表 ++FRONTEND_DIR : 前端目录 ++skip_api : True +} +ConversationsWrapper --> ConversationsBackend : "调用/传递" +ConversationsWrapper --> ConversationsItemBackend : "嵌套项" +``` + +图表来源 + +- [conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) +- [**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) +- [item/**init**.py:8-75](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L8-L75) + +章节来源 + +- [conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) +- [**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) +- [item/**init**.py:8-75](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L8-L75) + +## 性能考虑 + +- 列表渲染优化 + - 使用 useMemo 缓存菜单与分组配置，避免重复计算 + - 仅在 items 或插槽变化时重新解析渲染 +- 事件处理 + - 通过 useFunction 包装函数型 props，减少不必要的重渲染 +- 样式与插槽 + - 合理使用 classNames 合并类名，避免过度 DOM 操作 +- 大列表场景 + - 建议分页或虚拟化策略（若 Ant Design X 提供）以降低内存占用 + +章节来源 + +- [conversations.tsx:83-137](file://frontend/antdx/conversations/conversations.tsx#L83-L137) + +## 故障排查指南 + +- 无法显示菜单 + - 检查是否正确注入 menu.items 插槽，或是否传入了有效的 menu 配置 + - 确认菜单项的 key 与 label 是否正确 +- 事件未触发 + - 确认已为组件绑定相应事件（如 menu_click、active_change） + - 检查事件回调函数是否正确接收并处理事件负载 +- 分组不生效 + - 确认 groupable 是否开启，且每个项的 group 字段一致 +- 插槽内容未渲染 + - 确认插槽名称拼写正确（如 menu.trigger、groupable.label） + +章节来源 + +- [**init**.py:44-47](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L44-L47) +- [demos/operations.py:29-43](file://docs/components/antdx/conversations/demos/operations.py#L29-L43) +- [demos/group.py:8-27](file://docs/components/antdx/conversations/demos/group.py#L8-L27) + +## 结论 + +Conversations 组件提供了在 Gradio 中管理与查看对话列表的完整能力，配合菜单插槽、事件系统与分组功能，能够覆盖聊天应用、任务管理等多种场景。通过本文示例与最佳实践，开发者可以快速搭建具备良好交互体验的应用界面。 + +## 附录 + +- 示例入口 + - [README.md:5-9](file://docs/components/antdx/conversations/README.md#L5-L9) + - [README-zh_CN.md:5-9](file://docs/components/antdx/conversations/README-zh_CN.md#L5-L9) +- 相关文件 + - [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) + - [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) + - [index.less:1-4](file://frontend/antdx/conversations/index.less#L1-L4) + - [**init**.py:1-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L1-L109) + - [item/**init**.py:1-75](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L1-L75) + - [demos/basic.py:1-50](file://docs/components/antdx/conversations/demos/basic.py#L1-L50) + - [demos/operations.py:1-47](file://docs/components/antdx/conversations/demos/operations.py#L1-L47) + - [demos/group.py:1-31](file://docs/components/antdx/conversations/demos/group.py#L1-L31) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/\345\257\271\350\257\235\351\241\271\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/\345\257\271\350\257\235\351\241\271\347\273\204\344\273\266.md" new file mode 100644 index 00000000..93cfe110 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/\345\257\271\350\257\235\351\241\271\347\273\204\344\273\266.md" @@ -0,0 +1,382 @@ +# 对话项组件 + + +**本文引用的文件** +- [frontend/antdx/conversations/item/conversations.item.tsx](file://frontend/antdx/conversations/item/conversations.item.tsx) +- [frontend/antdx/conversations/item/Index.svelte](file://frontend/antdx/conversations/item/Index.svelte) +- [frontend/antdx/conversations/context.ts](file://frontend/antdx/conversations/context.ts) +- [frontend/antdx/conversations/conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [frontend/antdx/conversations/index.less](file://frontend/antdx/conversations/index.less) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [backend/modelscope_studio/components/antdx/conversations/__init__.py](file://backend/modelscope_studio/components/antdx/conversations/__init__.py) +- [backend/modelscope_studio/components/antdx/conversations/item/__init__.py](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py) +- [docs/components/antdx/conversations/demos/basic.py](file://docs/components/antdx/conversations/demos/basic.py) +- [docs/components/antdx/conversations/demos/operations.py](file://docs/components/antdx/conversations/demos/operations.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件聚焦于 Conversations.Item 对话项组件的实现与使用，涵盖其数据结构、渲染逻辑、交互行为、状态管理（激活、选中、右键菜单等），并提供多种配置示例与父组件 Conversations 的通信机制及数据绑定方式说明。目标是帮助开发者快速理解并正确使用该组件。 + +## 项目结构 + +Conversations.Item 属于 antdx 前端组件体系中的子项，由后端 Python 组件包装并在前端以 Svelte + React 混合模式渲染。其核心文件分布如下： + +- 前端入口与桥接：Index.svelte 负责属性处理与懒加载；conversations.item.tsx 将 React 组件桥接到 Svelte。 +- 上下文与子项收集：context.ts 导出 ItemHandler，并通过 createItemsContext.tsx 提供统一的“子项上下文”能力。 +- 父组件集成：conversations.tsx 负责将 items 与菜单等配置传递给 @ant-design/x 的 Conversations，并注入样式与事件。 +- 后端封装：backend 中的 Conversations 与 Conversations.Item 作为 Gradio 组件，负责声明事件、插槽与渲染桥接。 + +```mermaid +graph TB +subgraph "前端" +A["Index.svelte
属性处理与懒加载"] +B["conversations.item.tsx
桥接至 ItemHandler"] +C["context.ts
导出 ItemHandler"] +D["createItemsContext.tsx
子项上下文实现"] +E["conversations.tsx
父组件集成与样式注入"] +F["index.less
样式占位"] +end +subgraph "后端" +G["conversations/__init__.py
AntdXConversations"] +H["conversations/item/__init__.py
AntdXConversationsItem"] +end +A --> B --> C --> D +E --> C +E --> F +G --> E +H --> G +``` + +图表来源 + +- [frontend/antdx/conversations/item/Index.svelte:1-73](file://frontend/antdx/conversations/item/Index.svelte#L1-L73) +- [frontend/antdx/conversations/item/conversations.item.tsx:1-14](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L14) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/conversations/index.less:1-4](file://frontend/antdx/conversations/index.less#L1-L4) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:1-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L1-L109) +- [backend/modelscope_studio/components/antdx/conversations/item/**init**.py:1-75](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L1-L75) + +章节来源 + +- [frontend/antdx/conversations/item/Index.svelte:1-73](file://frontend/antdx/conversations/item/Index.svelte#L1-L73) +- [frontend/antdx/conversations/item/conversations.item.tsx:1-14](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L14) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/conversations/index.less:1-4](file://frontend/antdx/conversations/index.less#L1-L4) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:1-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L1-L109) +- [backend/modelscope_studio/components/antdx/conversations/item/**init**.py:1-75](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L1-L75) + +## 核心组件 + +- Conversations.Item（前端桥接）：将 React 版本的 ItemHandler 注入到 Svelte 环境，负责把属性与插槽透传给 ItemHandler。 +- ItemHandler（上下文子项处理器）：从 createItemsContext.tsx 导出，负责收集子项数据、处理 props 与 slots、维护子项树，并写入父级 ItemsContext。 +- Conversations（父组件）：负责将 items、菜单、分组等配置传递给 @ant-design/x 的 Conversations，并注入样式类名与事件。 +- 后端组件：AntdXConversations 与 AntdXConversationsItem 作为 Gradio 组件，声明事件、插槽与渲染桥接。 + +章节来源 + +- [frontend/antdx/conversations/item/conversations.item.tsx:1-14](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L14) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:190-261](file://frontend/utils/createItemsContext.tsx#L190-L261) +- [frontend/antdx/conversations/conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:11-47](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L47) +- [backend/modelscope_studio/components/antdx/conversations/item/**init**.py:8-20](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L8-L20) + +## 架构总览 + +下图展示了从父组件到子项的调用链路与数据流： + +```mermaid +sequenceDiagram +participant Parent as "Conversations(父)" +participant Provider as "ItemsContextProvider" +participant ItemBridge as "Conversations.Item(桥接)" +participant Handler as "ItemHandler(上下文)" +participant XConv as "@ant-design/x Conversations" +Parent->>Parent : 解析 items 与菜单配置 +Parent->>XConv : 传入 items、menu、groupable 等 +Parent->>Provider : 包裹子项渲染上下文 +Provider->>ItemBridge : 逐个渲染子项 +ItemBridge->>Handler : 透传 props 与 slots +Handler->>Handler : 收集 props/slots/children +Handler->>Provider : 写入 ItemsContext +Provider-->>Parent : 子项集合可用 +Parent->>XConv : 渲染最终列表 +``` + +图表来源 + +- [frontend/antdx/conversations/conversations.tsx:68-175](file://frontend/antdx/conversations/conversations.tsx#L68-L175) +- [frontend/antdx/conversations/item/conversations.item.tsx:7-11](file://frontend/antdx/conversations/item/conversations.item.tsx#L7-L11) +- [frontend/antdx/conversations/context.ts:3-4](file://frontend/antdx/conversations/context.ts#L3-L4) +- [frontend/utils/createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) +- [frontend/utils/createItemsContext.tsx:190-261](file://frontend/utils/createItemsContext.tsx#L190-L261) + +## 详细组件分析 + +### 数据结构与状态 + +- 子项数据模型（来自上下文）： + - props：子项的属性对象 + - slots：具名插槽映射（如 label、icon） + - el：DOM 元素引用（可选） + - ctx：上下文参数（包含 forceClone 等） + - itemChildrenKey：默认 children，支持自定义键 +- 状态来源： + - 激活/选中：由父组件 Conversations 控制，通过 active_key/default_active_key 驱动 + - 右键菜单：由父组件注入的 menu 配置决定，支持触发器、展开图标、溢出指示器等 + - 分组与折叠：groupable 配置控制分组标题与可折叠行为 + - 禁用/禁用态：disabled 字段影响交互与视觉 + +章节来源 + +- [frontend/utils/createItemsContext.tsx:20-48](file://frontend/utils/createItemsContext.tsx#L20-L48) +- [frontend/antdx/conversations/conversations.tsx:77-168](file://frontend/antdx/conversations/conversations.tsx#L77-L168) +- [backend/modelscope_studio/components/antdx/conversations/item/**init**.py:21-55](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L21-L55) + +### 渲染逻辑 + +- Index.svelte + - 使用 importComponent 懒加载 Conversations.Item + - processProps 提取 visible、_internal.index、as_item、elem_\* 等通用属性 + - 条件渲染：仅当 visible 为真时渲染 + - 透传 restProps、additionalProps、slots、itemIndex、itemSlotKey +- conversations.item.tsx + - 将 props 透传给 ItemHandler，实现 React 到 Svelte 的桥接 +- ItemHandler（createItemsContext.tsx） + - 在 useEffect 中根据 props/slots/children 构造子项值 + - 通过 setItem 将当前子项写入 ItemsContext，触发父级更新 + - 支持 itemProps 与 itemChildren 的动态计算 + +```mermaid +flowchart TD +Start(["进入 Index.svelte"]) --> CheckVisible{"visible 为真？"} +CheckVisible --> |否| End(["不渲染"]) +CheckVisible --> |是| LazyLoad["懒加载 Conversations.Item"] +LazyLoad --> ProcessProps["processProps 提取通用属性"] +ProcessProps --> RenderItem["渲染 Conversations.Item 并透传 props/slots"] +RenderItem --> Bridge["conversations.item.tsx 桥接至 ItemHandler"] +Bridge --> Collect["ItemHandler 收集 props/slots/children"] +Collect --> WriteCtx["写入 ItemsContext.setItem"] +WriteCtx --> End +``` + +图表来源 + +- [frontend/antdx/conversations/item/Index.svelte:13-72](file://frontend/antdx/conversations/item/Index.svelte#L13-L72) +- [frontend/antdx/conversations/item/conversations.item.tsx:7-11](file://frontend/antdx/conversations/item/conversations.item.tsx#L7-L11) +- [frontend/utils/createItemsContext.tsx:190-261](file://frontend/utils/createItemsContext.tsx#L190-L261) + +章节来源 + +- [frontend/antdx/conversations/item/Index.svelte:1-73](file://frontend/antdx/conversations/item/Index.svelte#L1-L73) +- [frontend/antdx/conversations/item/conversations.item.tsx:1-14](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L14) +- [frontend/utils/createItemsContext.tsx:190-261](file://frontend/utils/createItemsContext.tsx#L190-L261) + +### 交互行为与事件 + +- 选择变更：父组件通过 active_change 事件回调通知当前激活项变化 +- 菜单交互：menu_click、menu_select、menu_deselect、menu_open_change 等事件由父组件绑定 +- 分组扩展：groupable_expand 事件用于分组展开/收起 +- 创建按钮：creation_click 事件用于“新建”按钮点击 +- 右键菜单：通过父组件的 menu 配置注入，支持触发器、展开图标、溢出指示器等插槽 + +章节来源 + +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:18-41](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L18-L41) +- [frontend/antdx/conversations/conversations.tsx:35-57](file://frontend/antdx/conversations/conversations.tsx#L35-L57) + +### 状态管理 + +- 激活状态（激活/选中） + - 由父组件 Conversations 的 active_key/default_active_key 控制 + - 子项本身不直接维护激活状态，而是由父组件统一管理 +- 选中状态（菜单选中） + - 通过 menu_select/menu_deselect 事件与父组件联动 +- 右键菜单状态 + - 由父组件注入的 menu 配置决定是否显示菜单、如何触发 + - 菜单项的 disabled、danger 等状态由父组件统一处理 +- 分组状态 + - groupable.label/groupable.collapsible 由父组件注入，支持插槽与函数式配置 + +章节来源 + +- [frontend/antdx/conversations/conversations.tsx:77-168](file://frontend/antdx/conversations/conversations.tsx#L77-L168) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:44-47](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L44-L47) + +### 配置示例与使用方法 + +以下示例基于文档中的演示脚本，展示不同类型的对话项配置与交互。 + +- 基本对话项 + - 使用 items 数组直接传入键值与标签 + - 示例路径：[docs/components/antdx/conversations/demos/basic.py:14-28](file://docs/components/antdx/conversations/demos/basic.py#L14-L28) +- 带图标和标签的对话项 + - 通过 Slots 定义 label/icon 插槽，实现自定义渲染 + - 示例路径：[docs/components/antdx/conversations/demos/basic.py:32-44](file://docs/components/antdx/conversations/demos/basic.py#L32-L44) +- 带操作菜单的对话项 + - 通过 Slot("menu.items") 注入菜单项，支持 icon、disabled、danger 等属性 + - 示例路径：[docs/components/antdx/conversations/demos/operations.py:29-43](file://docs/components/antdx/conversations/demos/operations.py#L29-L43) + +章节来源 + +- [docs/components/antdx/conversations/demos/basic.py:1-50](file://docs/components/antdx/conversations/demos/basic.py#L1-L50) +- [docs/components/antdx/conversations/demos/operations.py:1-47](file://docs/components/antdx/conversations/demos/operations.py#L1-L47) + +### 与父组件的通信机制与数据绑定 + +- 父组件 Conversations + - 解析 items 与菜单配置，注入到 @ant-design/x 的 Conversations + - 通过 withItemsContextProvider 与 withMenuItemsContextProvider 包裹，提供 ItemsContext 与菜单上下文 + - 统一注入样式类名（如 item 类名），保证与主题一致 +- 子项 Conversations.Item + - 通过 ItemHandler 将自身 props/slots/children 写入 ItemsContext + - 由父组件统一消费并渲染 +- 后端桥接 + - AntdXConversations/AntdXConversationsItem 声明事件与插槽，确保前后端一致 + +```mermaid +classDiagram +class Conversations { ++props : items, menu, groupable, active_key ++events : active_change, menu_click, ... +} +class ConversationsItem { ++props : key, label, icon, disabled, ... ++slots : label, icon +} +class ItemHandler { ++setItem() ++collectProps() ++collectSlots() +} +class ItemsContext { ++items : map[] ++setItem() +} +Conversations --> ItemsContext : "提供上下文" +ConversationsItem --> ItemHandler : "桥接渲染" +ItemHandler --> ItemsContext : "写入子项" +``` + +图表来源 + +- [frontend/antdx/conversations/conversations.tsx:68-175](file://frontend/antdx/conversations/conversations.tsx#L68-L175) +- [frontend/antdx/conversations/context.ts:3-4](file://frontend/antdx/conversations/context.ts#L3-L4) +- [frontend/utils/createItemsContext.tsx:108-170](file://frontend/utils/createItemsContext.tsx#L108-L170) +- [frontend/utils/createItemsContext.tsx:190-261](file://frontend/utils/createItemsContext.tsx#L190-L261) + +章节来源 + +- [frontend/antdx/conversations/conversations.tsx:68-175](file://frontend/antdx/conversations/conversations.tsx#L68-L175) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:108-170](file://frontend/utils/createItemsContext.tsx#L108-L170) + +## 依赖关系分析 + +- 组件耦合 + - Conversations.Item 依赖 ItemHandler 与 ItemsContext，耦合度低，便于复用 + - 父组件 Conversations 通过上下文与工具函数集中处理 items、菜单与分组 +- 外部依赖 + - @ant-design/x：提供核心 Conversations 组件 + - Gradio 组件系统：后端 AntdXConversations/AntdXConversationsItem 作为桥接层 +- 潜在循环依赖 + - 无直接循环依赖；上下文通过 Provider 与 Context 解耦 + +```mermaid +graph LR +ConvTSX["conversations.tsx"] --> Ctx["context.ts"] +Ctx --> CIC["createItemsContext.tsx"] +ConvTSX --> X["@ant-design/x Conversations"] +ItemSvelte["Index.svelte"] --> ItemBridge["conversations.item.tsx"] +ItemBridge --> Ctx +Backend["AntdXConversations*"] --> ConvTSX +``` + +图表来源 + +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/antdx/conversations/item/Index.svelte:1-73](file://frontend/antdx/conversations/item/Index.svelte#L1-L73) +- [frontend/antdx/conversations/item/conversations.item.tsx:1-14](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L14) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:1-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L1-L109) +- [backend/modelscope_studio/components/antdx/conversations/item/**init**.py:1-75](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L1-L75) + +章节来源 + +- [frontend/antdx/conversations/conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/antdx/conversations/item/Index.svelte:1-73](file://frontend/antdx/conversations/item/Index.svelte#L1-L73) +- [frontend/antdx/conversations/item/conversations.item.tsx:1-14](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L14) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:1-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L1-L109) +- [backend/modelscope_studio/components/antdx/conversations/item/**init**.py:1-75](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L1-L75) + +## 性能考虑 + +- 懒加载与条件渲染：Index.svelte 仅在 visible 为真时渲染子项，避免不必要的初始化开销 +- 上下文更新最小化：ItemHandler 使用 useMemoizedFn 与 useMemoizedEqualValue，减少重复计算与无效更新 +- 批量写入：ItemsContextProvider 通过一次 setItem 更新整个子项数组，降低重渲染频率 +- 样式注入：父组件统一注入样式类名，避免子项重复设置样式带来的抖动 + +章节来源 + +- [frontend/antdx/conversations/item/Index.svelte:54-72](file://frontend/antdx/conversations/item/Index.svelte#L54-L72) +- [frontend/utils/createItemsContext.tsx:113-156](file://frontend/utils/createItemsContext.tsx#L113-L156) +- [frontend/utils/createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) +- [frontend/antdx/conversations/conversations.tsx:145-151](file://frontend/antdx/conversations/conversations.tsx#L145-L151) + +## 故障排查指南 + +- 子项未显示 + - 检查 visible 是否为真；Index.svelte 会在 visible 为假时不渲染 + - 确认父组件是否正确包裹 withItemsContextProvider +- 子项内容不更新 + - 确认 props 是否稳定；ItemHandler 会比较前值，若相等则不会写入 + - 检查 itemProps 与 itemChildren 的返回值是否随输入变化 +- 菜单不生效 + - 确认父组件是否正确注入 menu 配置或通过 Slot 注入菜单项 + - 检查菜单项的 onClick 等事件是否被正确拦截与转发 +- 样式异常 + - 父组件已注入 item 类名，确认未被外部覆盖 + - 检查 index.less 是否被正确引入 + +章节来源 + +- [frontend/antdx/conversations/item/Index.svelte:54-72](file://frontend/antdx/conversations/item/Index.svelte#L54-L72) +- [frontend/utils/createItemsContext.tsx:234-237](file://frontend/utils/createItemsContext.tsx#L234-L237) +- [frontend/antdx/conversations/conversations.tsx:83-122](file://frontend/antdx/conversations/conversations.tsx#L83-L122) +- [frontend/antdx/conversations/conversations.tsx:145-151](file://frontend/antdx/conversations/conversations.tsx#L145-L151) + +## 结论 + +Conversations.Item 通过 ItemHandler 与 ItemsContext 实现了灵活的子项收集与渲染，配合父组件 Conversations 的统一配置与事件管理，能够高效地构建复杂的对话列表场景。其设计强调解耦与可扩展性，适合在多插槽、多菜单、多分组的复杂界面中使用。 + +## 附录 + +- 后端组件事件与插槽清单 + - 事件：active_change、menu_click、menu_deselect、menu_open_change、menu_select、groupable_expand、creation_click + - 插槽：menu.expandIcon、menu.overflowedIndicator、menu.trigger、groupable.label、items、creation.icon、creation.label +- 关键实现参考 + - 子项上下文与处理器：[frontend/utils/createItemsContext.tsx:97-274](file://frontend/utils/createItemsContext.tsx#L97-L274) + - 父组件集成与样式注入：[frontend/antdx/conversations/conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) + - 前端桥接与懒加载：[frontend/antdx/conversations/item/Index.svelte:13-72](file://frontend/antdx/conversations/item/Index.svelte#L13-L72)、[frontend/antdx/conversations/item/conversations.item.tsx:7-11](file://frontend/antdx/conversations/item/conversations.item.tsx#L7-L11) + - 后端桥接与事件声明：[backend/modelscope_studio/components/antdx/conversations/**init**.py:18-41](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L18-L41)、[backend/modelscope_studio/components/antdx/conversations/item/**init**.py:13-19](file://backend/modelscope_studio/components/antdx/conversations/item/__init__.py#L13-L19) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/\347\273\204\344\273\266\346\246\202\350\247\210.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/\347\273\204\344\273\266\346\246\202\350\247\210.md" new file mode 100644 index 00000000..da082692 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Conversations \345\257\271\350\257\235\347\256\241\347\220\206/\347\273\204\344\273\266\346\246\202\350\247\210.md" @@ -0,0 +1,294 @@ +# 组件概览 + + +**本文引用的文件** +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/antdx/conversations/__init__.py](file://backend/modelscope_studio/components/antdx/conversations/__init__.py) +- [frontend/antdx/conversations/conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [frontend/antdx/conversations/context.ts](file://frontend/antdx/conversations/context.ts) +- [frontend/antdx/conversations/item/conversations.item.tsx](file://frontend/antdx/conversations/item/conversations.item.tsx) +- [docs/components/antdx/conversations/README.md](file://docs/components/antdx/conversations/README.md) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本概览面向 Conversations 对话管理组件，系统性介绍其整体架构、核心功能与设计理念，并说明其与 Ant Design X 组件库的关系以及在机器学习与对话式应用中的典型用法。文档同时提供基本使用路径与核心概念，帮助开发者快速理解与集成该组件。 + +## 项目结构 + +Conversations 组件位于 Ant Design X 前端生态中，后端通过 Python 包装器桥接到 Gradio 生态；前端以 React 组件形式对接 Ant Design X 的 Conversations 实现，并通过上下文与插槽机制扩展菜单、分组等能力。 + +```mermaid +graph TB +subgraph "后端" +PY_API["Python 包装器
AntdXConversations"] +BASE_COMP["基础组件基类
ModelScopeLayoutComponent"] +end +subgraph "前端" +REACT_COMP["React 组件
@ant-design/x Conversations"] +CTX["上下文与插槽
context.ts / conversations.tsx"] +ITEM["子项包装
conversations.item.tsx"] +end +PY_API --> |"调用/渲染"| REACT_COMP +BASE_COMP --> PY_API +CTX --> REACT_COMP +ITEM --> CTX +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) +- [frontend/antdx/conversations/conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/antdx/conversations/item/conversations.item.tsx:1-14](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L14) + +章节来源 + +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) +- [frontend/antdx/conversations/conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/antdx/conversations/item/conversations.item.tsx:1-14](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L14) + +## 核心组件 + +- AntdXConversations（后端包装器） + - 负责将前端组件注册到 Gradio 生态，暴露属性、事件与插槽，屏蔽底层实现细节。 + - 支持事件绑定：选中变化、菜单点击、展开/收起、新建等。 + - 支持插槽：菜单图标、溢出指示器、触发器、分组标签等。 +- Conversations（前端 React 组件） + - 基于 Ant Design X 的 Conversations，封装菜单、分组、插槽与上下文逻辑。 + - 提供对菜单事件的增强处理，确保与对话项绑定正确。 +- ConversationsItem（子项包装） + - 将子项数据与上下文结合，作为 Conversations 的 items 子项使用。 +- 上下文与工具 + - 使用 createItemsContext 管理 items 上下文，支持插槽渲染与参数化插槽。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) +- [frontend/antdx/conversations/conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) +- [frontend/antdx/conversations/item/conversations.item.tsx:7-11](file://frontend/antdx/conversations/item/conversations.item.tsx#L7-L11) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) + +## 架构总览 + +下图展示从后端包装器到前端渲染、再到 Ant Design X 组件的完整链路，以及事件与插槽如何贯穿其中。 + +```mermaid +sequenceDiagram +participant Py as "后端包装器
AntdXConversations" +participant Ctx as "上下文/插槽
context.ts / conversations.tsx" +participant R as "前端组件
@ant-design/x Conversations" +participant X as "Ant Design X
Conversations" +Py->>Ctx : 初始化并注入属性/事件/插槽 +Ctx->>R : 渲染 React 组件并传递 props +R->>X : 传入 items、menu、groupable 等配置 +X-->>R : 触发事件回调选中/菜单/分组 +R-->>Ctx : 处理事件并回传数据 +Ctx-->>Py : 暴露给上层应用使用 +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:18-47](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L18-L47) +- [frontend/antdx/conversations/conversations.tsx:72-171](file://frontend/antdx/conversations/conversations.tsx#L72-L171) + +章节来源 + +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:18-47](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L18-L47) +- [frontend/antdx/conversations/conversations.tsx:72-171](file://frontend/antdx/conversations/conversations.tsx#L72-L171) + +## 详细组件分析 + +### 后端包装器：AntdXConversations + +- 设计要点 + - 继承自 ModelScopeLayoutComponent，具备布局上下文能力与事件声明机制。 + - 显式声明支持的事件与插槽，便于前端按需绑定与渲染。 + - 前端目录解析通过 resolve_frontend_dir("conversations", type="antdx") 完成。 + - API 跳过策略（skip_api）用于避免不必要的数据传输，聚焦事件驱动。 +- 关键行为 + - preprocess/postprocess/example\_\* 返回空值或占位，表明该组件主要通过事件与插槽交互。 + - 通过内部状态更新（\_internal.update）参与布局渲染流程。 + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__enter__() ++__exit__() +} +class AntdXConversations { ++Item ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +AntdXConversations --|> ModelScopeLayoutComponent : "继承" +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-53](file://backend/modelscope_studio/utils/dev/component.py#L11-L53) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-53](file://backend/modelscope_studio/utils/dev/component.py#L11-L53) +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:11-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L11-L109) + +### 前端组件：Conversations（React） + +- 设计要点 + - 通过 sveltify 包装 Ant Design X 的 Conversations，统一与 Svelte/React 预处理体系协作。 + - 使用 useFunction 与 createFunction 将字符串或函数转换为可执行回调，提升灵活性。 + - 通过 renderItems 与 renderParamsSlot 渲染插槽与菜单项，支持克隆与参数化。 + - 对菜单事件进行增强：阻止冒泡并注入当前对话项上下文，保证事件回调签名一致。 + - 支持 groupable 的动态配置与插槽覆盖，满足分组标题与可折叠逻辑定制。 +- 数据流 + - 接收 items、menu、groupable、slots 等输入，计算最终传给 Ant Design X 的 props。 + - 通过 classNames 注入额外样式类名，保持与主题/布局的一致性。 + +```mermaid +flowchart TD +Start(["进入 Conversations 渲染"]) --> ReadProps["读取 props 与 slots"] +ReadProps --> BuildMenu["构建 menu 配置
合并事件/插槽/触发器"] +ReadProps --> BuildItems["解析 items 插槽与外部 items"] +ReadProps --> Groupable["解析 groupable 配置与插槽"] +BuildMenu --> RenderX["渲染 Ant Design X Conversations"] +BuildItems --> RenderX +Groupable --> RenderX +RenderX --> End(["完成渲染"]) +``` + +图表来源 + +- [frontend/antdx/conversations/conversations.tsx:72-171](file://frontend/antdx/conversations/conversations.tsx#L72-L171) + +章节来源 + +- [frontend/antdx/conversations/conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) + +### 子项包装：ConversationsItem + +- 设计要点 + - 作为子项的轻量包装，直接复用 ItemHandler 上下文，简化子项配置。 + - 通过 sveltify 将 Ant Design X 的子项类型与上下文结合，形成统一的子项接口。 + +章节来源 + +- [frontend/antdx/conversations/item/conversations.item.tsx:7-11](file://frontend/antdx/conversations/item/conversations.item.tsx#L7-L11) + +### 事件与插槽 + +- 事件 + - active_change、menu_click、menu_deselect、menu_open_change、menu_select、groupable_expand、creation_click。 +- 插槽 + - menu.expandIcon、menu.overflowedIndicator、menu.trigger、groupable.label、items、creation.icon、creation.label。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:18-47](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L18-L47) + +## 依赖关系分析 + +- 后端依赖 + - 继承自 ModelScopeLayoutComponent，获得布局上下文与事件声明能力。 + - 通过 resolve_frontend_dir 解析前端目录，确保组件正确加载。 +- 前端依赖 + - @ant-design/x 提供核心 Conversations 实现。 + - @svelte-preprocess-react 提供 React 与 Svelte 的互操作能力。 + - @utils/\* 工具函数与 hooks 提供事件处理、插槽渲染与上下文管理。 +- 组件间耦合 + - AntdXConversations 与前端 Conversations 通过 props 与事件解耦。 + - 上下文与插槽机制降低耦合度，提高可扩展性。 + +```mermaid +graph LR +PY["AntdXConversations"] --> FE["conversations.tsx"] +FE --> ADX["@ant-design/x"] +FE --> UTIL["@utils/*"] +FE --> CTX["context.ts"] +CTX --> FE +ITEM["conversations.item.tsx"] --> CTX +``` + +图表来源 + +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:91-91](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L91-L91) +- [frontend/antdx/conversations/conversations.tsx:1-26](file://frontend/antdx/conversations/conversations.tsx#L1-L26) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/antdx/conversations/item/conversations.item.tsx:1-14](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L14) + +章节来源 + +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:91-91](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L91-L91) +- [frontend/antdx/conversations/conversations.tsx:1-26](file://frontend/antdx/conversations/conversations.tsx#L1-L26) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [frontend/antdx/conversations/item/conversations.item.tsx:1-14](file://frontend/antdx/conversations/item/conversations.item.tsx#L1-L14) + +## 性能考量 + +- 事件驱动优先：组件默认跳过 API 层数据传输，仅通过事件与插槽交互，减少不必要的网络往返。 +- 插槽与上下文：通过上下文与插槽减少重复渲染，提升复杂列表的渲染效率。 +- 菜单事件增强：在前端对菜单事件进行增强处理，避免事件冒泡带来的重复触发风险。 +- 建议 + - 控制 items 数量与层级，避免一次性渲染过多节点。 + - 合理使用 groupable 与插槽，避免过度嵌套导致的重排与重绘。 + +## 故障排查指南 + +- 组件不显示或无响应 + - 检查 FRONTEND_DIR 是否正确解析，确认前端包已安装且版本匹配。 + - 确认事件绑定是否生效（如 active_change、menu_click），必要时检查回调函数签名。 +- 菜单不出现或点击无效 + - 确认 menu 配置或插槽是否正确设置，检查 menu.items 或 slots 中的触发器与图标。 + - 若使用字符串函数，请确认字符串可被安全解析为可执行函数。 +- 分组标签不显示 + - 确认 groupable 配置或 groupable.label 插槽是否正确传入。 +- 子项渲染异常 + - 检查 ConversationsItem 的上下文是否正确注入，确保 ItemHandler 正常工作。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/conversations/**init**.py:91-109](file://backend/modelscope_studio/components/antdx/conversations/__init__.py#L91-L109) +- [frontend/antdx/conversations/conversations.tsx:83-122](file://frontend/antdx/conversations/conversations.tsx#L83-L122) +- [frontend/antdx/conversations/context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) + +## 结论 + +Conversations 组件通过“后端包装器 + 前端 React 组件 + 上下文/插槽”的架构，实现了与 Ant Design X 的深度集成与灵活扩展。其事件驱动与插槽机制使其在对话列表管理、菜单操作与分组展示方面具备良好的可维护性与可扩展性，适合在机器学习与对话式应用中作为核心交互组件使用。 + +## 附录 + +- 快速使用路径 + - 在后端引入 AntdXConversations 并配置 items、menu、groupable 等属性。 + - 在前端通过插槽配置菜单图标、触发器与分组标签。 + - 通过事件监听实现选中切换、菜单操作与分组展开/收起。 +- 参考示例 + - 文档示例页面提供了基础、操作与分组三类示例，可作为集成起点。 + +章节来源 + +- [docs/components/antdx/conversations/README.md:1-10](file://docs/components/antdx/conversations/README.md#L1-L10) diff --git "a/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/\351\200\232\347\224\250\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/\351\200\232\347\224\250\347\273\204\344\273\266.md" new file mode 100644 index 00000000..44ba0d37 --- /dev/null +++ "b/.wiki/zh/Ant Design X \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/\351\200\232\347\224\250\347\273\204\344\273\266.md" @@ -0,0 +1,310 @@ +# 通用组件 + + +**本文引用的文件** +- [bubble.tsx](file://frontend/antdx/bubble/bubble.tsx) +- [conversations.tsx](file://frontend/antdx/conversations/conversations.tsx) +- [context.ts](file://frontend/antdx/conversations/context.ts) +- [index.less](file://frontend/antdx/conversations/index.less) +- [__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [README-zh_CN.md](file://README-zh_CN.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向 Ant Design X 通用组件，聚焦于 Bubble 对话气泡组件与 Conversations 对话管理组件的实现与使用。内容涵盖： + +- Bubble 的对话展示能力、消息类型区分、样式与内容定制 +- Conversations 的对话列表管理、状态控制、菜单与分组操作接口 +- 组件间协作关系与最佳实践 +- 完整使用示例（基础用法、高级配置、样式定制） + +## 项目结构 + +Ant Design X 通用组件位于前端目录的 antdx 分类下，采用 Svelte + React 预处理桥接方案，通过 sveltify 将 @ant-design/x 的原生组件包装为可在 Svelte 中使用的组件。后端 Python 包提供统一导出入口。 + +```mermaid +graph TB +subgraph "前端 antdx" +B["bubble.tsx"] +C["conversations.tsx"] +CTX["context.ts"] +L["index.less"] +end +subgraph "后端" +PY_INIT["__init__.py"] +PY_COMP["components.py"] +end +subgraph "第三方" +ADX["@ant-design/x"] +SveltePreprocess["@svelte-preprocess-react"] +Utils["@utils/*"] +end +B --> ADX +C --> ADX +B --> SveltePreprocess +C --> SveltePreprocess +B --> Utils +C --> Utils +PY_COMP --> B +PY_COMP --> C +PY_INIT --> PY_COMP +``` + +图表来源 + +- [bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [**init**.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) + +章节来源 + +- [bubble.tsx:1-119](file://frontend/antdx/bubble/bubble.tsx#L1-L119) +- [conversations.tsx:1-178](file://frontend/antdx/conversations/conversations.tsx#L1-L178) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [**init**.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) + +## 核心组件 + +- Bubble：对话气泡展示组件，支持头像、标题、内容、底部栏、额外区域、可编辑文案、加载态渲染、内容渲染等插槽化扩展。 +- Conversations：对话列表管理组件，支持菜单注入、分组配置、项渲染、样式类名合并、事件透传等。 + +章节来源 + +- [bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) +- [conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) + +## 架构总览 + +Bubble 与 Conversations 均通过 sveltify 桥接到 @ant-design/x 的原生组件，并在桥接层中完成： + +- 插槽到 ReactSlot 的映射 +- 函数型属性的 useFunction 包装 +- 菜单与分组配置的上下文与渲染工具集成 +- 样式类名的合并与覆盖 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Conv as "Conversations(桥接)" +participant XConv as "@ant-design/x.Conversations" +participant Ctx as "上下文(菜单/项)" +participant Bubble as "Bubble(桥接)" +participant XBubble as "@ant-design/x.Bubble" +Dev->>Conv : 传入 items/menu/groupable 等属性 +Conv->>Ctx : 解析菜单/项上下文 +Conv->>XConv : 渲染对话列表(含菜单/分组) +XConv-->>Dev : 列表渲染结果 +Dev->>Bubble : 传入 avatar/content/footer/header 等 +Bubble->>XBubble : 渲染对话气泡(插槽/函数包装) +XBubble-->>Dev : 气泡渲染结果 +``` + +图表来源 + +- [conversations.tsx:68-175](file://frontend/antdx/conversations/conversations.tsx#L68-L175) +- [bubble.tsx:27-116](file://frontend/antdx/bubble/bubble.tsx#L27-L116) + +## 详细组件分析 + +### Bubble 组件分析 + +- 功能要点 + - 支持头像、标题、内容、底部栏、额外区域等插槽化扩展 + - 支持可编辑模式（布尔或配置对象），并允许通过插槽自定义“确定/取消”文本 + - 支持 typing 回调与 loadingRender/contentRender 的函数化配置 + - 内部对 editable、avatar、header、footer、extra、loadingRender、contentRender 等进行统一处理与回退 +- 数据流与处理逻辑 + - 使用 useFunction 包装函数型属性，确保在 Svelte 环境中正确执行 + - 通过 ReactSlot 渲染插槽内容，renderParamsSlot 支持带参数的插槽 + - 对 editable 进行配置合并与条件渲染，兼容布尔值与对象配置 +- 复杂度与性能 + - 主要为属性映射与渲染开销，复杂度与插槽数量和嵌套深度相关 + - 通过函数包装避免重复渲染，提升交互响应性 + +```mermaid +flowchart TD +Start(["进入 Bubble 渲染"]) --> CheckEditable["检测 editable 配置"] +CheckEditable --> EditableSupport{"是否支持编辑?"} +EditableSupport --> |是| MergeEditable["合并编辑配置
并处理插槽文本"] +EditableSupport --> |否| PassEditable["直接传递 editable"] +MergeEditable --> RenderAvatar["处理头像插槽/函数"] +PassEditable --> RenderAvatar +RenderAvatar --> RenderHeader["处理头部插槽/函数"] +RenderHeader --> RenderFooter["处理底部插槽/函数"] +RenderFooter --> RenderExtra["处理额外区域插槽/函数"] +RenderExtra --> RenderContent["处理内容插槽/函数"] +RenderContent --> RenderLoading["处理 loadingRender 插槽/函数"] +RenderLoading --> RenderContentRender["处理 contentRender 插槽/函数"] +RenderContentRender --> End(["完成渲染"]) +``` + +图表来源 + +- [bubble.tsx:27-116](file://frontend/antdx/bubble/bubble.tsx#L27-L116) + +章节来源 + +- [bubble.tsx:8-116](file://frontend/antdx/bubble/bubble.tsx#L8-L116) + +### Conversations 组件分析 + +- 功能要点 + - 对接 @ant-design/x 的 Conversations，提供菜单注入、分组配置、项渲染与样式类名合并 + - 通过 useMenuItems 与 useItems 上下文解析菜单与项插槽 + - 支持字符串形式的 menu 属性与对象配置，自动合并事件并阻止冒泡 + - 支持 groupable 的 label 插槽与 collapsible 函数配置 +- 数据流与处理逻辑 + - patchMenuEvents：对菜单事件进行包装，注入 conversation 参数并阻止 DOM 事件冒泡 + - renderItems：将插槽项转换为实际渲染项，支持克隆与深拷贝 + - useMemo：对 menu 与 items 进行记忆化，减少不必要的重渲染 +- 复杂度与性能 + - 记忆化与上下文解析带来稳定性能；插槽项越多，renderItems 开销越大 + - 菜单事件包装仅在存在菜单时生效，避免无谓开销 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Conv as "Conversations(桥接)" +participant Ctx as "useMenuItems/useItems" +participant XConv as "@ant-design/x.Conversations" +Dev->>Conv : 传入 menu/items/groupable/classNames +Conv->>Ctx : 获取菜单/项上下文 +Conv->>Conv : patchMenuEvents 包装菜单事件 +Conv->>Conv : renderItems 解析插槽项 +Conv->>XConv : 合并样式类名并渲染 +XConv-->>Dev : 返回对话列表 +``` + +图表来源 + +- [conversations.tsx:35-175](file://frontend/antdx/conversations/conversations.tsx#L35-L175) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) + +章节来源 + +- [conversations.tsx:28-175](file://frontend/antdx/conversations/conversations.tsx#L28-L175) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) + +### 组件协作关系 + +- Conversations 作为容器，负责对话列表的渲染与菜单/分组配置 +- Bubble 作为子元素，负责单个对话气泡的展示与交互 +- 两者通过 @ant-design/x 的原生组件协同工作，桥接层提供插槽与函数包装能力 + +```mermaid +graph LR +Conv["Conversations(桥接)"] --> XB["@ant-design/x.Conversations"] +XB --> Item["对话项(由 items/menu/groupable 驱动)"] +Item --> BB["Bubble(桥接)"] +BB --> XBb["@ant-design/x.Bubble"] +``` + +图表来源 + +- [conversations.tsx:139-171](file://frontend/antdx/conversations/conversations.tsx#L139-L171) +- [bubble.tsx:38-115](file://frontend/antdx/bubble/bubble.tsx#L38-L115) + +## 依赖分析 + +- 第三方依赖 + - @ant-design/x：提供原生对话与气泡组件 + - @svelte-preprocess-react：提供 sveltify 与 ReactSlot 能力 + - @utils/\*：提供 useFunction、renderItems、renderParamsSlot、createFunction 等工具 + - classnames：用于类名合并 +- 后端导出 + - Python 包通过 **init**.py 与 components.py 暴露 antdx 组件，便于在 Python 环境中使用 + +```mermaid +graph TB +B["bubble.tsx"] --> ADX["@ant-design/x"] +B --> SPR["@svelte-preprocess-react"] +B --> U["@utils/*"] +C["conversations.tsx"] --> ADX +C --> SPR +C --> U +C --> CTX["context.ts"] +PY["components.py"] --> B +PY --> C +``` + +图表来源 + +- [bubble.tsx:1-7](file://frontend/antdx/bubble/bubble.tsx#L1-L7) +- [conversations.tsx:1-17](file://frontend/antdx/conversations/conversations.tsx#L1-L17) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) + +章节来源 + +- [bubble.tsx:1-7](file://frontend/antdx/bubble/bubble.tsx#L1-L7) +- [conversations.tsx:1-17](file://frontend/antdx/conversations/conversations.tsx#L1-L17) +- [context.ts:1-7](file://frontend/antdx/conversations/context.ts#L1-L7) +- [components.py](file://backend/modelscope_studio/components/antdx/components.py) + +## 性能考虑 + +- 使用 useMemo 对菜单与项进行记忆化，避免不必要的重渲染 +- 通过 useFunction 包装函数型属性，减少闭包创建与渲染抖动 +- 插槽项通过 renderItems 克隆渲染，避免共享状态导致的副作用 +- 在大量对话场景下，建议按需加载与虚拟滚动（如 @ant-design/x 提供的能力）以降低内存占用 + +## 故障排查指南 + +- 插槽未生效 + - 确认插槽名称与桥接层声明一致（如 editable.okText、editable.cancelText、content、footer、header、extra、loadingRender、contentRender） + - 确认插槽内容通过 ReactSlot 正确渲染 +- 菜单事件异常 + - 检查是否正确使用 useMenuItems 上下文 + - 确认 patchMenuEvents 是否正确包裹 onClick 等事件并阻止冒泡 +- 样式类名冲突 + - 通过 classNames 合并自定义类名，避免覆盖默认样式 +- 编辑模式不显示 + - 确认 editable 为对象且包含 editing 字段，或通过插槽提供自定义文案 + +章节来源 + +- [bubble.tsx:36-64](file://frontend/antdx/bubble/bubble.tsx#L36-L64) +- [conversations.tsx:35-57](file://frontend/antdx/conversations/conversations.tsx#L35-L57) +- [conversations.tsx:145-151](file://frontend/antdx/conversations/conversations.tsx#L145-L151) + +## 结论 + +Bubble 与 Conversations 通过桥接层实现了对 @ant-design/x 的完整能力封装，提供了灵活的插槽化与函数化配置，满足从基础对话展示到复杂对话管理的多种场景。建议在实际项目中结合上下文与工具函数，合理组织插槽与事件，以获得更佳的开发体验与运行性能。 + +## 附录 + +- 使用示例（基于仓库现有文件与组件能力） + - 基础用法 + - 使用 Bubble 展示一条消息，设置头像、内容与底部栏 + - 使用 Conversations 渲染对话列表，传入 items 与 menu 配置 + - 高级配置 + - 在 Bubble 中启用编辑模式，通过插槽自定义“确定/取消”文本 + - 在 Conversations 中使用 groupable 实现分组与折叠，通过插槽自定义分组标签 + - 样式定制 + - 通过 classNames 合并自定义类名，覆盖默认样式 + - 引入 index.less 进行主题化定制（如需要） + +章节来源 + +- [bubble.tsx:14-116](file://frontend/antdx/bubble/bubble.tsx#L14-L116) +- [conversations.tsx:59-175](file://frontend/antdx/conversations/conversations.tsx#L59-L175) +- [index.less](file://frontend/antdx/conversations/index.less) +- [README-zh_CN.md](file://README-zh_CN.md) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/Ant Design \347\273\204\344\273\266\345\272\223.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/Ant Design \347\273\204\344\273\266\345\272\223.md" new file mode 100644 index 00000000..731bfee3 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/Ant Design \347\273\204\344\273\266\345\272\223.md" @@ -0,0 +1,531 @@ +# Ant Design 组件库 + + +**本文引用的文件** +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antdx/__init__.py](file://backend/modelscope_studio/components/antdx/__init__.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [frontend/antdx/package.json](file://frontend/antdx/package.json) +- [docs/app.py](file://docs/app.py) +- [docs/helper/Docs.py](file://docs/helper/Docs.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [README-zh_CN.md](file://README-zh_CN.md) +- [.changeset/pink-sails-itch.md](file://.changeset/pink-sails-itch.md) +- [.changeset/eleven-aliens-sell.md](file://.changeset/eleven-aliens-sell.md) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py) +- [backend/modelscope_studio/components/antdx/folder/directory_icon/__init__.py](file://backend/modelscope_studio/components/antdx/folder/directory_icon/__init__.py) +- [backend/modelscope_studio/components/antdx/sender/header/__init__.py](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py) + + +## 更新摘要 + +**所做更改** + +- 更新了版本信息，反映从 Gradio 5.x 到 6.0、Ant Design 5.x 到 6.0、Ant Design X 1.x 到 2.0 的重大升级 +- 新增了 Ant Design X 组件库的完整功能介绍，包括思维链、文件夹、发送者等新组件 +- 扩展了组件分类，增加了新的组件组别和功能特性 +- 更新了架构说明，反映新的组件组织结构 + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [Ant Design X 组件库](#ant-design-x-组件库) +7. [依赖关系分析](#依赖关系分析) +8. [性能考量](#性能考量) +9. [故障排查指南](#故障排查指南) +10. [结论](#结论) +11. [附录](#附录) + +## 简介 + +本文件面向 ModelScope Studio 的 Ant Design 组件库，系统梳理其组件分类、功能特性与使用方式，覆盖通用组件、布局组件、导航组件、数据录入组件、数据展示组件、反馈组件六大类别。随着 Gradio 6.0、Ant Design 6.0 和 Ant Design X 2.0 的重大升级，组件库现已支持更丰富的交互能力和更现代化的设计系统。文档同时提供属性说明、事件处理、样式定制、响应式与国际化支持、性能优化与最佳实践，辅以丰富的示例与场景化说明，帮助开发者快速上手并高质量落地。 + +## 项目结构 + +ModelScope Studio 将 Ant Design 组件以 Python 包的形式导出，并通过前端 Svelte 包桥接至 Ant Design React 组件，形成"Python 层组件定义 + 前端渲染桥接"的双层架构。现在还集成了 Ant Design X 组件库，提供更丰富的交互组件。文档站点通过统一入口聚合各组件的文档与示例，便于浏览与对比。 + +```mermaid +graph TB +subgraph "后端 Python" +A["backend/modelscope_studio/components/antd/__init__.py
导出所有 Ant Design 组件类"] +B["backend/modelscope_studio/components/antd/components.py
集中导入与导出"] +C["backend/modelscope_studio/components/antdx/__init__.py
导出所有 Ant Design X 组件类"] +D["backend/modelscope_studio/components/antdx/components.py
集中导入与导出"] +E["backend/modelscope_studio/utils/dev/component.py
组件基类与上下文"] +end +subgraph "前端 Svelte" +F["frontend/antd/package.json
Ant Design 包元信息"] +G["frontend/antdx/package.json
Ant Design X 包元信息"] +H["frontend/antd/button/Index.svelte
按钮组件桥接示例"] +end +subgraph "文档与站点" +I["docs/app.py
组件分类与菜单生成"] +J["docs/helper/Docs.py
文档解析与示例渲染"] +end +A --> H +C --> H +B --> H +D --> H +E --> A +F --> H +G --> H +I --> J +``` + +**图示来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-147](file://backend/modelscope_studio/components/antd/components.py#L1-L147) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [docs/app.py:19-438](file://docs/app.py#L19-L438) +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) + +**章节来源** + +- [docs/app.py:19-438](file://docs/app.py#L19-L438) +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-147](file://backend/modelscope_studio/components/antd/components.py#L1-L147) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +## 核心组件 + +- 组件导出与命名：后端通过 **init**.py 与 components.py 将 Ant Design 组件类统一导出，现在还包括 Ant Design X 组件，便于按需导入与批量使用。 +- 组件基类：ModelScopeComponent/ModelScopeLayoutComponent/ModelScopeDataLayoutComponent 提供统一的可见性、元素 ID、类名、内联样式、插槽与生命周期行为。 +- 前端桥接：Svelte 组件通过 importComponent 动态加载 Ant Design React 组件，统一处理 props、slots 与样式注入。 +- 版本升级：从 Gradio 5.x 升级到 6.0，支持更强大的事件系统和组件生命周期管理。 + +**章节来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-147](file://backend/modelscope_studio/components/antd/components.py#L1-L147) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/utils/dev/component.py:54-169](file://backend/modelscope_studio/utils/dev/component.py#L54-L169) +- [frontend/antd/button/Index.svelte:10-74](file://frontend/antd/button/Index.svelte#L10-L74) + +## 架构总览 + +下图展示了从 Python 组件调用到前端渲染的关键流程，以及文档站点如何组织与呈现组件示例。现在包含了 Ant Design X 组件的支持。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Py as "Python 组件层
antd/__init__.py + antdx/__init__.py" +participant Bridge as "Svelte 桥接层
Index.svelte" +participant Antd as "Ant Design React 组件" +participant Antdx as "Ant Design X 组件" +participant Docs as "文档站点
docs/app.py + Docs" +Dev->>Py : 导入并实例化组件 +Py->>Bridge : 传递组件属性与插槽 +Bridge->>Bridge : processProps/className/id/style 处理 +Bridge->>Antd : 动态加载并渲染 Ant Design 组件 +Bridge->>Antdx : 动态加载并渲染 Ant Design X 组件 +Antd-->>Dev : 渲染结果 +Antdx-->>Dev : 渲染结果 +Docs->>Py : 聚合组件文档与示例 +Docs->>Bridge : 渲染示例与代码块 +``` + +**图示来源** + +- [docs/app.py:19-438](file://docs/app.py#L19-L438) +- [docs/helper/Docs.py:82-178](file://docs/helper/Docs.py#L82-L178) +- [frontend/antd/button/Index.svelte:24-74](file://frontend/antd/button/Index.svelte#L24-L74) + +## 组件详解 + +### 通用组件 + +- 按钮 Button：支持链接跳转、图标、尺寸与主题变体；通过 href_target 控制 target 行为；支持插槽与样式定制。 +- 悬浮按钮 FloatButton：支持返回顶部、分组与图标；可组合多个悬浮动作。 +- 图标 Icon：支持图标字体提供者；可与其它组件配合使用。 +- 排版 Typography：支持标题、文本、段落、链接等语义化排版元素。 + +使用要点 + +- 属性映射：前端通过 processProps 将 visible、elem_id、elem_classes、elem_style、value 等统一透传。 +- 插槽：Svelte 侧通过 getSlots 获取默认插槽，用于渲染子节点。 +- 示例：按钮组件的桥接示例展示了动态加载与样式拼接。 + +**章节来源** + +- [frontend/antd/button/Index.svelte:24-74](file://frontend/antd/button/Index.svelte#L24-L74) +- [docs/app.py:198-209](file://docs/app.py#L198-L209) + +### 布局组件 + +- 分割线 Divider：支持水平/垂直与虚线样式。 +- 弹性布局 Flex：提供灵活的弹性容器能力。 +- 栅格 Grid：行 Row 与列 Col 支持响应式断点与间距。 +- 布局 Layout：包含 Header、Sider、Content、Footer 子组件，适合构建页面骨架。 +- 间距 Space：支持紧凑模式与包裹子项。 +- 分割面板 Splitter：支持面板与拖拽分割。 +- 瀑布流布局 Masonry：支持响应式列数与项目高度自动调整。 + +使用要点 + +- 响应式：栅格与 Flex 提供多断点配置，适配移动端与桌面端。 +- 样式：elem_style 可直接作用于容器，实现定位、宽高与边距控制。 + +**章节来源** + +- [docs/app.py:216-233](file://docs/app.py#L216-L233) + +### 导航组件 + +- 锚点 Anchor：支持滚动定位与锚点项。 +- 面包屑 Breadcrumb：支持自定义分隔符与路由项。 +- 下拉菜单 Dropdown：支持按钮下拉与菜单项。 +- 导航菜单 Menu：支持多级菜单与选中态。 +- 分页 Pagination：支持页码切换与尺寸。 +- 步骤条 Steps：支持步骤状态与描述。 + +使用要点 + +- 事件：导航组件通常通过回调或状态变更触发页面跳转或内容更新。 +- 国际化：可通过 ConfigProvider 统一设置语言环境（见"国际化支持"）。 + +**章节来源** + +- [docs/app.py:240-257](file://docs/app.py#L240-L257) + +### 数据录入组件 + +- 自动完成 AutoComplete：支持选项与回填。 +- 级联选择 Cascader：支持多级联动与懒加载。 +- 多选框 Checkbox：支持组与选项。 +- 颜色选择器 ColorPicker：支持预设与格式化。 +- 日期选择 DatePicker：支持范围选择与预设快捷项。 +- 表单 Form：支持字段校验规则、动态增减与 Provider。 +- 输入框 Input：支持密码、搜索、多行与 OTP。 +- 数字输入 InputNumber：支持步长与精度。 +- 提及 Mentions：支持关键词提及与选项。 +- 单选框 Radio：支持按钮与组。 +- 评分 Rate：支持只读与半星。 +- 选择器 Select：支持多选与搜索。 +- 滑动输入条 Slider：支持标记与范围。 +- 开关 Switch：支持禁用与加载。 +- 时间选择器 TimePicker：支持范围选择。 +- 穿梭框 Transfer：支持源与目标列表。 +- 树选择 TreeSelect：支持目录树与节点。 +- 上传 Upload：支持拖拽与自定义请求。 + +使用要点 + +- 校验：FormItemRule 提供校验规则定义；动态表单支持条件渲染与字段增删。 +- 事件：onChange/onFocus/onBlur 等常见事件可用于联动与状态管理。 +- 样式：elem_style/elem_classes 用于微调外观与布局。 + +**章节来源** + +- [docs/app.py:264-317](file://docs/app.py#L264-L317) + +### 数据展示组件 + +- 头像 Avatar：支持头像组与徽标。 +- 徽标数 Badge：支持徽章与缎带。 +- 日历 Calendar：支持月份视图与事件标注。 +- 卡片 Card：支持网格与元信息。 +- 走马灯 Carousel：支持自动轮播与指示器。 +- 折叠面板 Collapse：支持手风琴与面板项。 +- 描述列表 Descriptions：支持键值对展示。 +- 空状态 Empty：支持自定义图片与操作。 +- 图片 Image：支持预览组与懒加载。 +- 列表 List：支持项与元信息。 +- 气泡卡片 Popover：支持触发与内容。 +- 二维码 QRCode：支持颜色与尺寸。 +- 分段控制器 Segmented：支持选项与禁用。 +- 统计数值 Statistic：支持计数与定时器。 +- 表格 Table：支持列、展开、选择与排序。 +- 标签页 Tabs：支持标签项与类型。 +- 标签 Tag：支持可勾选标签。 +- 时间轴 Timeline：支持节点与方向。 +- 文字提示 Tooltip：支持触发与位置。 +- 漫游式引导 Tour：支持步骤与高亮。 +- 树 Tree：支持目录树与节点。 + +使用要点 + +- 表格：支持固定列、排序、筛选与分页；可结合分段控制器进行维度切换。 +- 图片：ImagePreviewGroup 提供多图预览能力。 +- 交互：Popover/Tooltip/Tour 提升信息密度与引导效率。 + +**章节来源** + +- [docs/app.py:324-386](file://docs/app.py#L324-L386) + +### 反馈组件 + +- 警告提示 Alert：支持多种类型与关闭。 +- 抽屉 Drawer：支持位置与嵌套内容。 +- 全局提示 Message：支持全局消息与持续时间。 +- 对话框 Modal：支持静态对话框与遮罩层。 +- 通知提醒框 Notification：支持多条通知与关闭。 +- 气泡确认框 Popconfirm：支持确认与取消回调。 +- 进度条 Progress：支持圆形与百分比。 +- 结果 Result：支持成功/失败/等待等状态页。 +- 骨架屏 Skeleton：支持头像、按钮、输入与图片。 +- 加载中 Spin：支持全屏与内联。 +- 水印 Watermark：支持文本与图片水印。 + +使用要点 + +- 全局组件：Message/Notification/Modal/Drawer 等通常通过 API 调用而非直接渲染。 +- 动画与过渡：Progress/Spin/Skeleton 提升加载体验与占位效果。 +- 可访问性：建议为交互组件提供键盘可达与屏幕阅读器友好提示。 + +**章节来源** + +- [docs/app.py:393-425](file://docs/app.py#L393-L425) + +### 其他组件 + +- 固钉 Affix：支持吸附与偏移。 +- 全局化配置 ConfigProvider：提供主题、语言与全局样式覆盖。 + +使用要点 + +- 国际化：ConfigProvider 支持 locales 注入，实现中英文切换。 +- 主题：通过 ConfigProvider 覆盖全局主题变量，统一风格。 + +**章节来源** + +- [docs/app.py:432-437](file://docs/app.py#L432-L437) + +## Ant Design X 组件库 + +### 新增组件概览 + +Ant Design X 是 Ant Design 的扩展组件库，提供了更丰富的交互组件和专业应用场景的解决方案。本次升级包含了以下主要组件： + +#### 思维链组件 (Thought Chain) + +- ThoughtChain：思维链容器组件，支持多步骤思维过程展示 +- ThoughtChainItem：思维链项组件，支持状态管理、可折叠和闪烁效果 +- 支持 pending、success、error、abort 状态 +- 可配置内容、描述、页脚、图标和标题 + +#### 文件管理组件 + +- Folder：文件夹组件，支持目录树和文件管理 +- FolderDirectoryIcon：目录图标组件，支持不同文件类型的图标显示 +- FileCard：文件卡片组件，支持文件列表展示 +- FileCardList：文件列表组件，支持文件项管理 + +#### 会话交互组件 + +- Bubble：消息气泡组件，支持用户和系统消息展示 +- BubbleList：消息列表组件，支持消息项和角色管理 +- Conversations：对话组件，支持历史对话管理 +- Sender：发送者组件，支持消息发送和头部管理 +- SenderHeader：发送者头部组件，支持展开状态控制 + +#### 内容展示组件 + +- CodeHighlighter：代码高亮组件，支持多种编程语言语法高亮 +- Mermaid：图表组件，支持 Mermaid 语法图表渲染 +- Prompts：提示词组件，支持提示词管理和展示 +- Sources：来源组件，支持内容来源展示 +- Suggestion：建议组件，支持智能建议展示 + +#### 交互工具组件 + +- Actions：操作组件，支持多种操作按钮 +- Attachments：附件组件，支持文件附件管理 +- Notification：通知组件，支持系统通知展示 +- Welcome：欢迎组件，支持欢迎页面展示 +- XProvider：提供者组件，支持上下文提供 + +使用要点 + +- 插槽系统：大部分组件支持具名插槽，如 content、description、footer、icon、title 等 +- 事件系统：支持 open_change 等事件监听 +- 状态管理：支持状态属性如 open、closable、collapsible 等 +- 样式定制：支持 styles 和 class_names 属性进行样式定制 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:1-81](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L1-L81) +- [backend/modelscope_studio/components/antdx/folder/directory_icon/**init**.py:1-61](file://backend/modelscope_studio/components/antdx/folder/directory_icon/__init__.py#L1-L61) +- [backend/modelscope_studio/components/antdx/sender/header/**init**.py:1-74](file://backend/modelscope_studio/components/antdx/sender/header/__init__.py#L1-L74) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +## 依赖关系分析 + +- Python 层导出：**init**.py 与 components.py 将 Ant Design 和 Ant Design X 组件类集中导出，便于统一导入。 +- 前端桥接：Svelte 组件通过 importComponent 动态加载 Ant Design React 和 Ant Design X 组件，processProps 统一处理属性与样式。 +- 文档站点：docs/app.py 聚合各组件文档与示例，Docs.py 解析 Markdown 并渲染示例与代码块。 + +```mermaid +graph LR +PyInit["backend/.../antd/__init__.py"] --> PyComp["backend/.../antd/components.py"] +PyInitX["backend/.../antdx/__init__.py"] --> PyCompX["backend/.../antdx/components.py"] +PyComp --> SvelteBtn["frontend/antd/button/Index.svelte"] +PyCompX --> SvelteBtn +DocsApp["docs/app.py"] --> DocsHelper["docs/helper/Docs.py"] +DocsHelper --> SvelteBtn +``` + +**图示来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-147](file://backend/modelscope_studio/components/antd/components.py#L1-L147) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [frontend/antd/button/Index.svelte:10-74](file://frontend/antd/button/Index.svelte#L10-L74) +- [docs/app.py:19-438](file://docs/app.py#L19-L438) +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) + +**章节来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-147](file://backend/modelscope_studio/components/antd/components.py#L1-L147) +- [backend/modelscope_studio/components/antdx/**init**.py:1-42](file://backend/modelscope_studio/components/antdx/__init__.py#L1-L42) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [frontend/antd/button/Index.svelte:10-74](file://frontend/antd/button/Index.svelte#L10-L74) +- [docs/app.py:19-438](file://docs/app.py#L19-L438) +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) + +## 性能考量 + +- 动态加载：前端通过 importComponent 实现按需加载，减少初始包体积与首屏阻塞。 +- 属性透传：processProps 统一处理属性与样式，避免重复计算与冗余渲染。 +- 表格与列表：合理使用虚拟化与分页，避免一次性渲染大量节点。 +- 图片与骨架：使用 Skeleton 与 Image.lazy 降低资源压力与白屏时间。 +- 全局组件：Message/Notification/Modal 等建议限制并发数量，避免频繁弹窗造成卡顿。 +- 样式：elem_style/elem_classes 应尽量复用，避免内联样式过多导致重绘。 +- 组件懒加载：Ant Design X 组件支持懒加载，提升应用启动性能。 + +## 故障排查指南 + +- 页面空白或组件不显示 + - 确认已在外层包裹 Application 与 ConfigProvider。 + - 在 Hugging Face Space 中启动时启用 ssr_mode=False。 + - 检查 Ant Design X 组件的依赖版本兼容性。 +- 组件样式异常 + - 使用 elem_style/elem_classes 调整容器样式；避免与全局样式冲突。 + - 检查是否正确引入主题与字体资源。 + - 确认 Ant Design X 组件的样式文件已正确加载。 +- 国际化未生效 + - 通过 ConfigProvider 注入 locales；确保语言键值与 Ant Design 语言包一致。 +- 示例无法运行 + - 确认 docs/app.py 中组件文档路径与示例文件存在；检查 Docs.py 的示例模块加载逻辑。 + - 检查新组件的导入路径是否正确。 +- 版本兼容性问题 + - 确保 Gradio、Ant Design 和 Ant Design X 版本匹配。 + - 检查组件属性是否与新版本兼容。 + +**章节来源** + +- [README-zh_CN.md:32-32](file://README-zh_CN.md#L32-L32) +- [docs/app.py:577-595](file://docs/app.py#L577-L595) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) + +## 结论 + +ModelScope Studio 的 Ant Design 组件库通过清晰的 Python 导出层与前端桥接层，实现了 Ant Design 组件在 Gradio 生态中的无缝集成。随着 Gradio 6.0、Ant Design 6.0 和 Ant Design X 2.0 的重大升级，组件库现在提供了更丰富的交互能力和更现代化的设计系统。借助统一的基类体系、插槽机制、事件系统与文档站点，开发者可以高效地构建美观、易维护的界面。建议在实际项目中结合响应式与国际化策略，遵循性能优化与最佳实践，以获得更佳的用户体验。 + +## 附录 + +### 组件属性与事件通用说明 + +- 通用属性 + - visible：控制组件可见性 + - elem_id：元素 ID + - elem_classes：类名数组或字符串 + - elem_style：内联样式对象 + - value：组件值（如适用） +- 事件 + - onChange/onFocus/onBlur：常用于输入类组件 + - onClick/onContextMenu：常用于按钮与交互组件 + - onConfirm/onCancel：常用于确认类组件 + - open_change：用于可展开组件的状态变更 +- 插槽 + - 默认插槽用于渲染子节点；部分组件支持具名插槽如 content、description、footer、icon、title 等 + +**章节来源** + +- [backend/modelscope_studio/utils/dev/component.py:54-169](file://backend/modelscope_studio/utils/dev/component.py#L54-L169) +- [frontend/antd/button/Index.svelte:24-74](file://frontend/antd/button/Index.svelte#L24-L74) + +### 响应式设计与国际化支持 + +- 响应式 + - 栅格 Grid 与 Flex 提供多断点配置，建议针对移动端与桌面端分别设置断点与间距。 +- 国际化 + - 通过 ConfigProvider 注入 locales，实现中英文切换；注意语言包与组件文案的对应关系。 + +**章节来源** + +- [docs/app.py:435-437](file://docs/app.py#L435-L437) + +### 代码示例与场景化应用 + +- 示例组织 + - 文档站点通过 Docs.py 自动扫描 demos 目录，渲染示例与代码块；支持折叠显示与标题标注。 +- 场景化建议 + - 表单：使用 Form + FormItem + 校验规则，结合动态表单实现条件渲染。 + - 数据表格：结合 Pagination 与虚拟滚动，提升大数据量下的交互流畅度。 + - 导航：使用 Menu + Breadcrumb + Steps 构建清晰的层级与流程指引。 + - 反馈：使用 Message/Notification/Modal/Drawer 提供及时的用户反馈与操作确认。 + - 思维链：使用 ThoughtChain + ThoughtChainItem 构建 AI 应用的思维过程展示。 + - 文件管理：使用 Folder + FileCard + Attachments 实现文件管理系统。 + +**章节来源** + +- [docs/helper/Docs.py:82-178](file://docs/helper/Docs.py#L82-L178) +- [docs/app.py:19-438](file://docs/app.py#L19-L438) + +### 参数映射补充说明 + +- Collapse 折叠面板属性 + - active_key：当前展开的面板 key + - default_active_key：默认展开的面板 key + - accordion：手风琴模式 + - bordered：是否有边框 + - collapsible：可折叠触发区域 + - destroy_inactive_panel：销毁折叠隐藏的面板 + - expand_icon：自定义切换图标 + - expand_icon_placement：切换图标位置，可选 `start` 或 `end` + - ghost：透明无边框 + - size：尺寸大小 + +### 版本升级说明 + +- Gradio 6.0 升级 + - 支持新的事件系统和组件生命周期管理 + - 改进的组件状态管理和数据流 +- Ant Design 6.0 升级 + - 更现代化的设计系统和视觉规范 + - 增强的无障碍访问支持 + - 改进的主题定制能力 +- Ant Design X 2.0 升级 + - 新增丰富的交互组件 + - 改进的组件 API 和插槽系统 + - 增强的 TypeScript 类型支持 + +**章节来源** + +- [.changeset/pink-sails-itch.md:12-12](file://.changeset/pink-sails-itch.md#L12-L12) +- [.changeset/eleven-aliens-sell.md:12-12](file://.changeset/eleven-aliens-sell.md#L12-L12) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\205\266\344\273\226\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\205\266\344\273\226\347\273\204\344\273\266.md" new file mode 100644 index 00000000..f749dce9 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\205\266\344\273\226\347\273\204\344\273\266.md" @@ -0,0 +1,325 @@ +# 其他组件 + + +**本文引用的文件** +- [frontend/antd/affix/affix.tsx](file://frontend/antd/affix/affix.tsx) +- [frontend/antd/affix/Index.svelte](file://frontend/antd/affix/Index.svelte) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) +- [frontend/antd/config-provider/Index.svelte](file://frontend/antd/config-provider/Index.svelte) +- [frontend/antd/float-button/float-button.tsx](file://frontend/antd/float-button/float-button.tsx) +- [frontend/antd/layout/layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) +- [frontend/antd/float-button/group/float-button.group.less](file://frontend/antd/float-button/group/float-button.group.less) +- [frontend/antd/menu/menu.less](file://frontend/antd/menu/menu.less) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) + + +## 目录 + +1. [引言](#引言) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 引言 + +本章节面向 Ant Design Studio 的“其他组件”场景，重点覆盖两类辅助性组件：固钉（Affix）与全局化配置（ConfigProvider）。我们将从定位机制、滚动监听与边界处理，到主题定制、语言切换与组件默认配置进行系统讲解，并结合仓库中的真实实现，给出可操作的应用场景、性能优化与内存管理建议，以及组件间协作的最佳实践。 + +## 项目结构 + +- 前端采用 Svelte + React 混合封装模式：Svelte 层负责属性/插槽透传与条件渲染，React 层负责具体 UI 行为（如 Affix、ConfigProvider 等）。 +- 工具层提供通用能力，例如将外部函数转换为可在 React 中安全使用的函数包装器。 +- 样式层通过 CSS-in-JS 的 StyleProvider 保证主题与前缀隔离，避免全局污染。 + +```mermaid +graph TB +subgraph "Svelte 层" +A_Index["Affix/Index.svelte"] +C_Index["ConfigProvider/Index.svelte"] +end +subgraph "React 层" +A_Impl["affix.tsx
封装 Ant Design Affix"] +C_Impl["config-provider.tsx
封装 Ant Design ConfigProvider"] +FBT["float-button.tsx
浮层按钮"] +LBase["layout.base.tsx
布局基元"] +end +subgraph "工具与资源" +UF["useFunction.ts
函数包装"] +LOC["locales.ts
多语言映射与按需加载"] +FBGroupLess["float-button.group.less
分组样式"] +MenuLess["menu.less
菜单样式"] +end +A_Index --> A_Impl +C_Index --> C_Impl +A_Impl --> UF +C_Impl --> UF +C_Impl --> LOC +FBT --> UF +LBase --> |"布局组合"| A_Impl +LBase --> |"布局组合"| C_Impl +FBGroupLess --> FBT +MenuLess --> C_Impl +``` + +图表来源 + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/antd/float-button/group/float-button.group.less:1-31](file://frontend/antd/float-button/group/float-button.group.less#L1-L31) +- [frontend/antd/menu/menu.less:1-45](file://frontend/antd/menu/menu.less#L1-L45) + +章节来源 + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/antd/float-button/group/float-button.group.less:1-31](file://frontend/antd/float-button/group/float-button.group.less#L1-L31) +- [frontend/antd/menu/menu.less:1-45](file://frontend/antd/menu/menu.less#L1-L45) + +## 核心组件 + +- 固钉（Affix） + - 定位机制：基于目标容器滚动位置计算元素固定状态；支持自定义目标容器（如页面或某个滚动区域）。 + - 边界处理：通过阈值控制固定/解绑时机，避免元素被错误固定或提前解绑。 + - 滚动监听：通过函数包装器将外部传入的容器选择器转换为 React 可用的回调。 +- 全局化配置（ConfigProvider） + - 主题定制：支持明暗模式与紧凑算法开关，动态组合算法列表，实现主题切换。 + - 语言切换：根据浏览器或指定语言，按需异步加载 Antd 语言包与 dayjs 语言包。 + - 组件默认配置：统一封装 getPopupContainer、getTargetContainer、renderEmpty 等全局行为。 + - 样式隔离：通过 CSS-in-JS 的 StyleProvider 高优先级注入，避免样式冲突。 + +章节来源 + +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) + +## 架构总览 + +下图展示了 Svelte 与 React 层之间的交互关系，以及 ConfigProvider 在主题与语言层面的扩展点。 + +```mermaid +sequenceDiagram +participant S as "Svelte 层" +participant R as "React 层" +participant U as "工具层" +participant L as "语言资源" +S->>R : 透传属性/插槽 +R->>U : useFunction 包装容器选择器/回调 +R->>L : 按需加载语言包与 dayjs 语言 +L-->>R : 返回语言包对象 +R-->>S : 渲染结果含主题与语言 +``` + +图表来源 + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) + +## 详细组件分析 + +### 固钉（Affix）组件 + +- 设计要点 + - Svelte 层负责条件渲染与属性透传，支持 visible 控制显示。 + - React 层通过 useFunction 将外部传入的容器选择器转换为 React 可执行的函数，确保滚动监听稳定可靠。 + - 支持插槽与子节点渲染，便于在固定状态下承载复杂内容。 +- 关键流程 + - 属性处理：将 get_target 映射为 target，交由 Affix 组件内部处理。 + - 渲染：仅在 visible 为真时渲染，减少不必要的 DOM 开销。 +- 使用建议 + - 对于非窗口滚动容器，务必显式传入 target 函数以指向正确容器。 + - 合理设置阈值，避免频繁切换固定/解绑状态导致的抖动。 + +```mermaid +sequenceDiagram +participant UI as "调用方" +participant S as "Affix/Index.svelte" +participant R as "affix.tsx" +participant A as "Antd Affix" +UI->>S : 传入 visible/get_target/属性 +S->>R : 透传属性与插槽 +R->>R : useFunction 包装 target +R->>A : 渲染 Affix 并传入 target +A-->>UI : 固定/解绑状态更新 +``` + +图表来源 + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) + +章节来源 + +- [frontend/antd/affix/Index.svelte:1-72](file://frontend/antd/affix/Index.svelte#L1-L72) +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) + +### 全局化配置（ConfigProvider）组件 + +- 设计要点 + - 主题：通过 themeMode 与 theme.algorithm 动态组合算法，支持暗色与紧凑模式。 + - 语言：根据 locale 自动映射到可用语言集，按需异步加载 Antd 语言包与 dayjs 语言包。 + - 容器：统一提供 getPopupContainer 与 getTargetContainer 的函数包装，确保弹窗与浮层渲染到正确容器。 + - 插槽：支持 renderEmpty 等插槽参数，通过 renderParamsSlot 实现灵活扩展。 + - 样式：通过 StyleProvider 高优先级注入，避免样式冲突。 +- 关键流程 + - 语言初始化：根据浏览器语言或传入 locale，解析为标准格式并加载对应语言包。 + - 主题初始化：根据 themeMode 与用户配置生成算法数组，传递给 Ant Design。 + - 容器回调：使用 useFunction 包装回调，确保在 React 生命周期内稳定工作。 + - 插槽渲染：将插槽内容包裹为 ReactSlot 或 renderParamsSlot，保持类型安全。 + +```mermaid +sequenceDiagram +participant UI as "调用方" +participant S as "ConfigProvider/Index.svelte" +participant R as "config-provider.tsx" +participant U as "useFunction.ts" +participant LOC as "locales.ts" +participant SP as "StyleProvider" +UI->>S : 传入 theme_mode/locale/theme 等 +S->>R : 透传属性与插槽 +R->>U : useFunction 包装 getPopupContainer/getTargetContainer/renderEmpty +R->>LOC : 解析 locale 并按需加载语言包 +LOC-->>R : 返回语言包对象 +R->>SP : 注入高优先级样式 +SP-->>UI : 渲染子树带主题与语言 +``` + +图表来源 + +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) + +章节来源 + +- [frontend/antd/config-provider/Index.svelte:1-72](file://frontend/antd/config-provider/Index.svelte#L1-L72) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) + +### 浮层按钮（FloatButton）与布局基元（Layout.Base） + +- 浮层按钮（FloatButton） + - 支持 icon/description/tooltip/badge 等插槽，通过 ReactSlot 实现灵活渲染。 + - tooltip 支持对象配置与回调包装，确保弹出容器与回调稳定。 +- 布局基元（Layout.Base） + - 通过组件类型选择器动态选择 Header/Footer/Content/Layout，统一类名前缀，便于样式控制。 + +章节来源 + +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +## 依赖关系分析 + +- 组件耦合 + - Affix 与 ConfigProvider 均依赖 useFunction 进行函数包装，降低跨层调用风险。 + - ConfigProvider 依赖 locales.ts 提供的语言映射与按需加载能力。 +- 外部依赖 + - Ant Design 组件库与 dayjs 语言包。 + - CSS-in-JS 的 StyleProvider 用于样式隔离与优先级控制。 +- 潜在循环依赖 + - 当前实现未见直接循环依赖；若业务侧在插槽中再次引入 ConfigProvider/Affix，请谨慎控制渲染层级。 + +```mermaid +graph LR +A["affix.tsx"] --> UF["useFunction.ts"] +C["config-provider.tsx"] --> UF +C --> LOC["locales.ts"] +C --> SP["StyleProvider"] +F["float-button.tsx"] --> UF +L["layout.base.tsx"] --> |"组合"| A +L --> |"组合"| C +``` + +图表来源 + +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) + +章节来源 + +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) +- [frontend/antd/float-button/float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) + +## 性能考量 + +- 滚动监听与重绘 + - Affix 的 target 应尽量指向最小化滚动容器，避免对整页滚动造成压力。 + - 合理设置阈值与固定高度，减少频繁切换导致的重排与重绘。 +- 语言包按需加载 + - ConfigProvider 仅在 locale 变更时触发语言包加载，避免重复请求。 + - dayjs 语言包与 Antd 语言包异步加载，注意网络与缓存策略。 +- 函数包装与稳定性 + - 使用 useFunction 包装回调，避免每次渲染产生新函数导致子组件不必要更新。 +- 样式注入 + - StyleProvider 高优先级注入，减少样式覆盖成本；避免在热路径中频繁切换主题。 + +## 故障排查指南 + +- 固钉不生效 + - 检查是否正确传入 target 函数，或在容器滚动时未触发更新。 + - 确认 visible 条件满足，且容器具备滚动条。 +- 语言切换无效 + - 检查 locale 是否在 locales.ts 中存在映射；确认异步加载成功。 + - 确保 dayjs.locale 切换成功。 +- 主题切换异常 + - 检查 themeMode 与 theme.algorithm 的组合是否符合预期。 + - 注意算法数组的拼接顺序与空值过滤。 +- 插槽渲染问题 + - 确认插槽 key 与 renderParamsSlot 的映射一致。 + - ReactSlot 的 clone 参数应按需启用，避免重复挂载。 + +章节来源 + +- [frontend/antd/affix/affix.tsx:1-14](file://frontend/antd/affix/affix.tsx#L1-L14) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) + +## 结论 + +- Affix 与 ConfigProvider 作为辅助性组件，在 Ant Design Studio 中承担了“定位与滚动”“主题与语言”的关键职责。 +- 通过 Svelte 与 React 的分层封装，既保证了易用性，又提供了强大的可扩展性。 +- 在实际项目中，建议优先使用 ConfigProvider 进行全局统一配置，再在需要的页面局部使用 Affix 实现固定布局或工具栏。 + +## 附录 + +- 组件间协作最佳实践 + - 在应用根部放置 ConfigProvider，集中管理主题与语言；在需要固定元素的页面局部使用 Affix。 + - 使用 Layout.Base 统一布局结构，配合 FloatButton 提升交互效率。 + - 对于复杂插槽场景，优先使用 ReactSlot 与 renderParamsSlot，确保类型安全与渲染可控。 +- 样式与主题 + - 通过 StyleProvider 与前缀类名（如 ms-gr-ant）避免样式冲突。 + - 菜单与浮层按钮的样式文件可作为参考，按需调整圆角、间距与过渡效果。 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Alert \350\255\246\345\221\212\346\217\220\347\244\272.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Alert \350\255\246\345\221\212\346\217\220\347\244\272.md" new file mode 100644 index 00000000..0548ba38 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Alert \350\255\246\345\221\212\346\217\220\347\244\272.md" @@ -0,0 +1,287 @@ +# Alert 警告提示 + + +**本文引用的文件** +- [frontend/antd/alert/alert.tsx](file://frontend/antd/alert/alert.tsx) +- [frontend/antd/alert/Index.svelte](file://frontend/antd/alert/Index.svelte) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx) +- [frontend/antd/alert/error-boundary/Index.svelte](file://frontend/antd/alert/error-boundary/Index.svelte) +- [backend/modelscope_studio/components/antd/alert/__init__.py](file://backend/modelscope_studio/components/antd/alert/__init__.py) +- [backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py) +- [frontend/antd/alert/package.json](file://frontend/antd/alert/package.json) +- [docs/components/antd/alert/README-zh_CN.md](file://docs/components/antd/alert/README-zh_CN.md) +- [docs/components/antd/alert/README.md](file://docs/components/antd/alert/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Alert 警告提示用于向用户传达需要关注的信息或状态反馈，常用于表单验证提示、操作结果反馈、系统通知等场景。本组件基于 Ant Design 的 Alert 组件进行封装，提供类型化（成功、信息、警告、错误）、可关闭、图标与描述插槽、以及错误边界包装能力，确保在复杂渲染场景下仍能稳定呈现。 + +## 项目结构 + +Alert 组件由前端 Svelte 包装层与后端 Gradio 组件层共同构成，并提供独立的错误边界版本以增强稳定性。 + +```mermaid +graph TB +subgraph "前端" +A_Index["frontend/antd/alert/Index.svelte"] +A_Alert["frontend/antd/alert/alert.tsx"] +EB_Index["frontend/antd/alert/error-boundary/Index.svelte"] +EB_Boundary["frontend/antd/alert/error-boundary/alert.error-boundary.tsx"] +Pkg["frontend/antd/alert/package.json"] +end +subgraph "后端" +Py_Component["backend/modelscope_studio/components/antd/alert/__init__.py"] +Py_EB["backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py"] +end +A_Index --> A_Alert +EB_Index --> EB_Boundary +A_Index --> Py_Component +EB_Index --> Py_EB +Pkg --> A_Index +Pkg --> EB_Index +``` + +图表来源 + +- [frontend/antd/alert/Index.svelte:10-47](file://frontend/antd/alert/Index.svelte#L10-L47) +- [frontend/antd/alert/alert.tsx:7-43](file://frontend/antd/alert/alert.tsx#L7-L43) +- [frontend/antd/alert/error-boundary/Index.svelte:10-47](file://frontend/antd/alert/error-boundary/Index.svelte#L10-L47) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:6-32](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L6-L32) +- [backend/modelscope_studio/components/antd/alert/**init**.py:11-71](file://backend/modelscope_studio/components/antd/alert/__init__.py#L11-L71) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:10-55](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L10-L55) +- [frontend/antd/alert/package.json:1-15](file://frontend/antd/alert/package.json#L1-L15) + +章节来源 + +- [frontend/antd/alert/Index.svelte:1-66](file://frontend/antd/alert/Index.svelte#L1-L66) +- [frontend/antd/alert/alert.tsx:1-46](file://frontend/antd/alert/alert.tsx#L1-L46) +- [frontend/antd/alert/error-boundary/Index.svelte:1-70](file://frontend/antd/alert/error-boundary/Index.svelte#L1-L70) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-35](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L35) +- [backend/modelscope_studio/components/antd/alert/**init**.py:1-89](file://backend/modelscope_studio/components/antd/alert/__init__.py#L1-L89) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:1-73](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L1-L73) +- [frontend/antd/alert/package.json:1-15](file://frontend/antd/alert/package.json#L1-L15) + +## 核心组件 + +- 前端主组件：负责将 Ant Design 的 Alert 包装为 Svelte 可消费的形式，支持 slots 插槽（action、closable.closeIcon、description、icon、message），并透传属性与事件回调。 +- 错误边界组件：对 Alert 进行错误边界包裹，保证子树异常不会导致整个界面崩溃，同时保留消息与描述的插槽能力。 +- 后端 Gradio 组件：提供类型化参数（type）、插槽映射、事件绑定（close）与样式/类名注入能力；错误边界版本同样提供对应事件与插槽。 + +章节来源 + +- [frontend/antd/alert/alert.tsx:7-43](file://frontend/antd/alert/alert.tsx#L7-L43) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:6-32](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L6-L32) +- [backend/modelscope_studio/components/antd/alert/**init**.py:11-71](file://backend/modelscope_studio/components/antd/alert/__init__.py#L11-L71) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:10-55](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L10-L55) + +## 架构总览 + +以下序列图展示了从后端 Gradio 组件到前端 Svelte 包装层再到 Ant Design 组件的调用链路，以及错误边界包装的路径。 + +```mermaid +sequenceDiagram +participant Py as "后端组件
AntdAlert/AntdAlertErrorBoundary" +participant Svelte as "前端包装
Index.svelte" +participant ReactComp as "React 组件
alert.tsx / alert.error-boundary.tsx" +participant AntD as "Ant Design Alert" +Py->>Svelte : 渲染请求属性+插槽 +Svelte->>ReactComp : 传递属性与 slots +ReactComp->>AntD : 渲染 Alert 或 ErrorBoundary 包裹的 Alert +AntD-->>ReactComp : 视觉呈现与交互点击关闭、动作按钮等 +ReactComp-->>Svelte : 回调 afterClose 等事件 +Svelte-->>Py : 事件上报如 close +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/alert/**init**.py:11-71](file://backend/modelscope_studio/components/antd/alert/__init__.py#L11-L71) +- [frontend/antd/alert/Index.svelte:10-47](file://frontend/antd/alert/Index.svelte#L10-L47) +- [frontend/antd/alert/alert.tsx:12-42](file://frontend/antd/alert/alert.tsx#L12-L42) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:17-29](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L17-L29) + +## 详细组件分析 + +### 类型与语义 + +- 类型（type）支持：success、info、warning、error。分别对应不同的视觉强调与语义含义，便于用户快速识别状态。 +- 语义建议： + - 成功：操作完成、流程结束等正向反馈 + - 信息：一般性提示、补充说明 + - 警告：潜在问题、需注意的操作 + - 错误：失败、异常、需要立即处理的问题 + +章节来源 + +- [backend/modelscope_studio/components/antd/alert/**init**.py:37-37](file://backend/modelscope_studio/components/antd/alert/__init__.py#L37-L37) + +### 插槽与可定制点 + +- 支持插槽： + - action：自定义操作区域（如“查看详情”按钮） + - closable.closeIcon：自定义关闭图标 + - description：辅助描述文本/富内容 + - icon：自定义图标 + - message：标题/消息主体 +- 属性透传：除上述插槽外，其余属性直接透传至 Ant Design Alert，包括 closable、show_icon、banner、after_close 等。 + +章节来源 + +- [backend/modelscope_studio/components/antd/alert/**init**.py:22-23](file://backend/modelscope_studio/components/antd/alert/__init__.py#L22-L23) +- [frontend/antd/alert/alert.tsx:11-43](file://frontend/antd/alert/alert.tsx#L11-L43) + +### 事件与交互 + +- close 事件：当用户点击关闭按钮时触发，后端可通过事件监听器绑定处理逻辑。 +- after_close 回调：在动画结束后触发，可用于清理资源或切换状态。 +- 键盘操作：默认遵循 Ant Design 行为，通常通过 Tab 导航聚焦关闭按钮，Enter/Space 触发关闭。 + +章节来源 + +- [backend/modelscope_studio/components/antd/alert/**init**.py:16-20](file://backend/modelscope_studio/components/antd/alert/__init__.py#L16-L20) +- [frontend/antd/alert/alert.tsx:13-13](file://frontend/antd/alert/alert.tsx#L13-L13) + +### 错误边界（Error Boundary） + +- 作用：对 Alert 子树进行错误捕获，避免单个插槽或内容渲染异常导致整页崩溃。 +- 使用场景：当 message/description 等插槽中包含动态渲染或外部数据时，建议使用错误边界版本。 +- 事件：同样支持 close 事件，便于统一处理关闭行为。 + +```mermaid +flowchart TD +Start(["进入 Alert 错误边界"]) --> RenderMsg["渲染 message 插槽"] +RenderMsg --> MsgOK{"渲染成功？"} +MsgOK --> |是| RenderDesc["渲染 description 插槽"] +MsgOK --> |否| Fallback["显示兜底内容/空状态"] +RenderDesc --> DescOK{"渲染成功？"} +DescOK --> |是| Ready["正常显示"] +DescOK --> |否| Fallback +Fallback --> End(["结束"]) +Ready --> End +``` + +图表来源 + +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:17-29](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L17-L29) + +章节来源 + +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:6-32](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L6-L32) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:10-55](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L10-L55) + +### 样式与类名 + +- 支持通过 elem_id、elem_classes、elem_style 注入基础样式与标识。 +- 主要类名前缀： + - ms-gr-antd-alert：主 Alert 组件 + - ms-gr-antd-alert-error-boundary：错误边界版本 +- 可结合 Ant Design 自身的 type、show_icon、closable 等属性控制外观。 + +章节来源 + +- [frontend/antd/alert/Index.svelte:53-53](file://frontend/antd/alert/Index.svelte#L53-L53) +- [frontend/antd/alert/error-boundary/Index.svelte:56-56](file://frontend/antd/alert/error-boundary/Index.svelte#L56-L56) + +### 无障碍与键盘支持 + +- 无障碍：遵循 Ant Design 默认可访问性设计，确保屏幕阅读器可读取消息与描述。 +- 键盘：Tab 导航至关闭按钮，Enter/Space 关闭；建议在 action 中提供明确的可访问名称。 + +章节来源 + +- [frontend/antd/alert/alert.tsx:17-40](file://frontend/antd/alert/alert.tsx#L17-L40) + +### 典型使用场景 + +- 表单验证提示：使用 info/warning/error 类型，配合 description 提供具体错误信息，action 提供“查看详情”。 +- 操作反馈：成功后使用 success 类型，展示简短消息与 icon。 +- 系统通知：使用 banner 模式与 closable，提升可见性与可控性。 +- 动态内容：当 message/description 来自外部数据或异步渲染时，优先使用错误边界版本。 + +章节来源 + +- [docs/components/antd/alert/README-zh_CN.md:1-8](file://docs/components/antd/alert/README-zh_CN.md#L1-L8) +- [docs/components/antd/alert/README.md:1-8](file://docs/components/antd/alert/README.md#L1-L8) + +## 依赖关系分析 + +- 前端导出：通过 package.json 将 Gradio 与默认入口指向 Index.svelte，确保后端按约定加载。 +- 组件耦合：前端包装层与 Ant Design 组件强耦合，但通过 slots 与属性透传保持高扩展性。 +- 后端集成：后端组件通过 resolve_frontend_dir 解析前端目录，事件与插槽在 Python 层声明，运行时由前端执行。 + +```mermaid +graph LR +PyMain["Python 组件
AntdAlert"] --> FEIndex["Svelte 包装
Index.svelte"] +PyEB["Python 组件
AntdAlertErrorBoundary"] --> FEIndexEB["Svelte 包装
error-boundary/Index.svelte"] +FEIndex --> ReactComp["React 组件
alert.tsx"] +FEIndexEB --> ReactCompEB["React 组件
alert.error-boundary.tsx"] +ReactComp --> AntD["Ant Design Alert"] +ReactCompEB --> AntDEB["Ant Design ErrorBoundary(Alert)"] +``` + +图表来源 + +- [frontend/antd/alert/package.json:4-12](file://frontend/antd/alert/package.json#L4-L12) +- [backend/modelscope_studio/components/antd/alert/**init**.py:71-71](file://backend/modelscope_studio/components/antd/alert/__init__.py#L71-L71) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:55-55](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L55-L55) + +章节来源 + +- [frontend/antd/alert/package.json:1-15](file://frontend/antd/alert/package.json#L1-L15) +- [backend/modelscope_studio/components/antd/alert/**init**.py:71-71](file://backend/modelscope_studio/components/antd/alert/__init__.py#L71-L71) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:55-55](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L55-L55) + +## 性能考虑 + +- 避免频繁重渲染：message/description/icon 等插槽尽量使用稳定值，必要时在上层缓存计算结果。 +- 控制插槽复杂度：复杂子树建议拆分组件并在错误边界内使用，降低整体渲染压力。 +- 合理使用 banner：banner 模式会占据更多空间，仅在关键提示时启用。 +- 事件节流：after_close 与 close 事件回调中避免重型同步操作，必要时使用微任务或防抖。 + +## 故障排查指南 + +- 插槽不生效 + - 检查插槽名称是否正确（action、closable.closeIcon、description、icon、message）。 + - 确认前端包装层已透传 slots 至 React 组件。 +- 关闭事件未触发 + - 确认后端事件监听器已注册 close 事件。 + - 检查 closable 是否为对象且包含 closeIcon 插槽时，是否正确透传。 +- 错误边界未捕获异常 + - 确认使用的是错误边界版本组件。 + - 检查 message/description 插槽中的异常是否被正确包裹。 +- 样式未生效 + - 检查 elem_id、elem_classes、elem_style 是否正确传入。 + - 确认类名前缀 ms-gr-antd-alert 或 ms-gr-antd-alert-error-boundary 已应用。 + +章节来源 + +- [frontend/antd/alert/alert.tsx:11-43](file://frontend/antd/alert/alert.tsx#L11-L43) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:12-29](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L12-L29) +- [backend/modelscope_studio/components/antd/alert/**init**.py:16-23](file://backend/modelscope_studio/components/antd/alert/__init__.py#L16-L23) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:14-21](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L14-L21) + +## 结论 + +Alert 警告提示组件在本项目中提供了类型化、可插槽、可关闭与错误边界保护的完整能力。通过前后端清晰的职责划分与稳定的导出约定，既能满足常规提示需求，也能在复杂渲染场景下保持健壮性。建议在涉及动态/外部内容时优先采用错误边界版本，并结合事件与样式系统实现一致的用户体验。 + +## 附录 + +- 示例入口参考：文档中提供的 demo 名称为 basic，可在对应文档页面查看演示效果。 + +章节来源 + +- [docs/components/antd/alert/README-zh_CN.md:5-7](file://docs/components/antd/alert/README-zh_CN.md#L5-L7) +- [docs/components/antd/alert/README.md:5-7](file://docs/components/antd/alert/README.md#L5-L7) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Drawer \346\212\275\345\261\211.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Drawer \346\212\275\345\261\211.md" new file mode 100644 index 00000000..d170ef12 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Drawer \346\212\275\345\261\211.md" @@ -0,0 +1,348 @@ +# Drawer 抽屉 + + +**本文引用的文件** +- [frontend/antd/drawer/drawer.tsx](file://frontend/antd/drawer/drawer.tsx) +- [frontend/antd/drawer/Index.svelte](file://frontend/antd/drawer/Index.svelte) +- [backend/modelscope_studio/components/antd/drawer/__init__.py](file://backend/modelscope_studio/components/antd/drawer/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [docs/components/antd/drawer/README.md](file://docs/components/antd/drawer/README.md) +- [docs/components/antd/drawer/README-zh_CN.md](file://docs/components/antd/drawer/README-zh_CN.md) +- [docs/components/antd/watermark/demos/modal_or_drawer.py](file://docs/components/antd/watermark/demos/modal_or_drawer.py) +- [frontend/antd/layout/layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Drawer 抽屉是一个从屏幕边缘滑出的面板，常用于承载侧边栏导航、详情面板、设置面板等场景。本组件基于 Ant Design Drawer 实现，并通过 Gradio 生态进行桥接，支持位置配置（左、右、上、下）、尺寸控制、遮罩行为、键盘交互以及丰富的插槽扩展能力。本文将系统阐述其布局设计、交互模式、使用场景与最佳实践，并提供可直接参考的示例路径。 + +## 项目结构 + +Drawer 组件在前端与后端分别由 Svelte 前端包装器与 Python 后端组件构成，二者通过 Gradio 的桥接机制协同工作。整体结构如下： + +```mermaid +graph TB +subgraph "后端" +PyInit["AntdDrawer 初始化
参数与事件定义"] +PySlots["支持的插槽列表"] +PyEntry["注册到组件入口"] +end +subgraph "前端" +SvelteIndex["Index.svelte
条件渲染与属性透传"] +ReactWrapper["drawer.tsx
sveltify 包装与插槽处理"] +AntdDrawer["Ant Design Drawer
原生组件"] +end +PyInit --> PySlots +PyInit --> PyEntry +SvelteIndex --> ReactWrapper +ReactWrapper --> AntdDrawer +``` + +图表来源 + +- [frontend/antd/drawer/Index.svelte:10-61](file://frontend/antd/drawer/Index.svelte#L10-L61) +- [frontend/antd/drawer/drawer.tsx:14-57](file://frontend/antd/drawer/drawer.tsx#L14-L57) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:10-108](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L10-L108) +- [backend/modelscope_studio/components/antd/components.py:38](file://backend/modelscope_studio/components/antd/components.py#L38) + +章节来源 + +- [frontend/antd/drawer/Index.svelte:1-65](file://frontend/antd/drawer/Index.svelte#L1-L65) +- [frontend/antd/drawer/drawer.tsx:1-60](file://frontend/antd/drawer/drawer.tsx#L1-L60) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:1-126](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L1-L126) +- [backend/modelscope_studio/components/antd/components.py:38](file://backend/modelscope_studio/components/antd/components.py#L38) + +## 核心组件 + +- 后端组件：AntdDrawer（Python） + - 支持的参数覆盖位置、尺寸、遮罩、键盘、推挤、渲染策略等关键行为 + - 定义了 close 事件绑定机制 + - 暴露多个插槽以支持自定义标题、页脚、额外操作、关闭图标等 +- 前端包装器：Index.svelte 与 drawer.tsx + - 条件渲染：仅在 visible 为真时加载并挂载 Drawer + - 属性透传：将 Gradio 属性与额外属性合并传递给底层组件 + - 插槽处理：支持 closeIcon、closable.closeIcon、extra、footer、title、drawerRender 等插槽 +- 基础布局组件：Base（layout.base.tsx） + - 提供 Ant Design Layout 的基础封装，便于与 Drawer 协同构建页面布局 + +章节来源 + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:10-108](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L10-L108) +- [frontend/antd/drawer/Index.svelte:13-42](file://frontend/antd/drawer/Index.svelte#L13-L42) +- [frontend/antd/drawer/drawer.tsx:14-57](file://frontend/antd/drawer/drawer.tsx#L14-L57) +- [frontend/antd/layout/layout.base.tsx:6-37](file://frontend/antd/layout/layout.base.tsx#L6-L37) + +## 架构总览 + +Drawer 的调用链路从后端 AntdDrawer 开始，经由前端 Index.svelte 条件渲染，再由 drawer.tsx 使用 sveltify 将 React 组件桥接到 Svelte 环境，最终渲染为 Ant Design Drawer。该流程确保了参数与事件的双向绑定，同时保留了 Ant Design Drawer 的全部能力。 + +```mermaid +sequenceDiagram +participant User as "用户" +participant Backend as "AntdDrawer(后端)" +participant FrontIndex as "Index.svelte(前端)" +participant Wrapper as "drawer.tsx(桥接)" +participant AD as "Antd Drawer(React)" +User->>Backend : 设置 open/visible 等参数 +Backend->>FrontIndex : 渲染请求 +FrontIndex->>FrontIndex : 判断 visible +FrontIndex->>Wrapper : 传入 props 与 slots +Wrapper->>AD : sveltify 包装并渲染 +AD-->>User : 显示抽屉并触发事件回调 +``` + +图表来源 + +- [frontend/antd/drawer/Index.svelte:48-61](file://frontend/antd/drawer/Index.svelte#L48-L61) +- [frontend/antd/drawer/drawer.tsx:24-56](file://frontend/antd/drawer/drawer.tsx#L24-L56) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:14-18](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L14-L18) + +## 详细组件分析 + +### 参数与插槽总览 + +- 关键参数（节选） + - 位置与尺寸：placement（left/right/top/bottom）、width、height、size（default/large） + - 行为控制：open、keyboard、mask、maskClosable、closable、destroyOnClose、destroyOnHidden、forceRender + - 布局与渲染：getContainer、push、resizable、drawerRender、as_item、visible、elem_id/elem_classes/elem_style +- 插槽（slots） + - closeIcon、closable.closeIcon、extra、footer、title、drawerRender + +章节来源 + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:26-107](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L26-L107) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:20-24](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L20-L24) +- [frontend/antd/drawer/drawer.tsx:14-57](file://frontend/antd/drawer/drawer.tsx#L14-L57) + +### 打开/关闭机制与事件 + +- 可见性控制：Index.svelte 通过 visible 控制是否渲染 Drawer +- 事件绑定：后端定义了 close 事件监听，用于在关闭时更新状态 +- 回调函数：afterOpenChange 等回调通过 useFunction 转换为可安全传递的函数 + +```mermaid +flowchart TD +Start(["开始"]) --> CheckVisible["检查 visible"] +CheckVisible --> |false| Skip["不渲染"] +CheckVisible --> |true| Render["渲染 Drawer 组件"] +Render --> BindEvents["绑定 close 等事件"] +BindEvents --> Open["显示抽屉"] +Open --> UserAction{"用户操作？"} +UserAction --> |点击遮罩/按 ESC| Close["触发关闭"] +Close --> UpdateState["更新 open/visible 状态"] +UpdateState --> Destroy{"销毁策略？"} +Destroy --> |是| Unmount["卸载组件"] +Destroy --> |否| Hide["隐藏但保留 DOM"] +Unmount --> End(["结束"]) +Hide --> End +Skip --> End +``` + +图表来源 + +- [frontend/antd/drawer/Index.svelte:48-61](file://frontend/antd/drawer/Index.svelte#L48-L61) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:14-18](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L14-L18) +- [frontend/antd/drawer/drawer.tsx:24-26](file://frontend/antd/drawer/drawer.tsx#L24-L26) + +### 位置配置与尺寸控制 + +- 位置：placement 支持 left、right、top、bottom +- 尺寸：width/height 或 size（default/large）控制抽屉大小 +- 推挤与容器：push 可配合布局推动内容；getContainer 指定挂载容器 + +章节来源 + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:47-50](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L47-L50) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:42-56](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L42-L56) +- [frontend/antd/drawer/drawer.tsx:52-54](file://frontend/antd/drawer/drawer.tsx#L52-L54) + +### 遮罩层行为与键盘交互 + +- 遮罩：mask 控制是否显示遮罩；maskClosable 控制点击遮罩是否关闭 +- 键盘：keyboard 控制是否启用 ESC 关闭 +- 自动聚焦：autoFocus 可在打开时自动聚焦到抽屉 + +章节来源 + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:44-46](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L44-L46) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:31-32](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L31-L32) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:91](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L91) + +### 动画与渲染策略 + +- 动画：由 Ant Design Drawer 内置动画驱动，无需额外配置 +- 渲染策略：destroyOnClose、destroyOnHidden、forceRender 控制销毁时机与强制渲染 + +章节来源 + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:36-39](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L36-L39) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:87-89](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L87-L89) + +### 插槽与样式定制 + +- 插槽映射：closeIcon、closable.closeIcon、extra、footer、title、drawerRender +- 样式：elem_id、elem_classes、elem_style、styles、class_names、root_style、root_class_name +- 自定义渲染：drawerRender 可接收参数并返回自定义渲染内容 + +章节来源 + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:20-24](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L20-L24) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:33-35](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L33-L35) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:57-60](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L57-L60) +- [frontend/antd/drawer/drawer.tsx:41-51](file://frontend/antd/drawer/drawer.tsx#L41-L51) + +### 与页面布局的协调与响应式适配 + +- 布局协作：可与 Ant Design Layout（Header/Footer/Content/Sider）组合使用 +- 响应式：结合 Flex/Grid 等布局组件，根据屏幕尺寸调整抽屉宽度或切换 placement + +章节来源 + +- [frontend/antd/layout/layout.base.tsx:6-37](file://frontend/antd/layout/layout.base.tsx#L6-L37) + +### 无障碍访问与移动端优化 + +- 无障碍：keyboard 与 focus 策略需配合自动聚焦与标签语义化 +- 移动端：建议在小屏设备上优先使用 bottom 或较小的 width，避免遮挡主要内容 + +章节来源 + +- [backend/modelscope_studio/components/antd/drawer/**init**.py:91](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L91) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:31-32](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L31-L32) + +### 常见应用场景与示例路径 + +- 侧边栏导航：在左侧抽屉中放置菜单项，点击菜单项时更新路由或数据 +- 详情面板：在右侧抽屉中展示详情内容，支持滚动与底部操作区 +- 设置面板：在顶部或底部抽屉中提供设置项，支持快速开关与保存 +- 示例参考： + - Drawer 基础用法与额外操作：[docs/components/antd/drawer/README.md](file://docs/components/antd/drawer/README.md) + - Drawer 与 Modal 对比演示：[docs/components/antd/watermark/demos/modal_or_drawer.py](file://docs/components/antd/watermark/demos/modal_or_drawer.py) + +章节来源 + +- [docs/components/antd/drawer/README.md:1-9](file://docs/components/antd/drawer/README.md#L1-L9) +- [docs/components/antd/watermark/demos/modal_or_drawer.py:19-26](file://docs/components/antd/watermark/demos/modal_or_drawer.py#L19-L26) + +## 依赖关系分析 + +- 组件继承与上下文 + - AntdDrawer 继承自 ModelScopeLayoutComponent，具备布局组件的通用特性 + - 通过 AppContext 保证应用上下文可用 +- 组件注册 + - 在组件入口中导出 AntdDrawer，便于统一导入使用 + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++bool visible ++str elem_id ++any elem_classes ++dict elem_style ++bool skip_api +} +class AntdDrawer { ++dict additional_props ++str after_open_change ++bool auto_focus ++dict body_style ++str close_icon ++any class_names ++any closable ++bool destroy_on_close ++bool destroy_on_hidden ++bool draggable ++str extra ++str footer ++bool force_render ++any get_container ++num height ++bool keyboard ++bool mask ++bool mask_closable ++str placement ++any push ++bool resizable ++str size ++any styles ++str title ++bool loading ++bool open ++num width ++int z_index ++str drawer_render ++dict root_style ++str root_class_name ++str as_item ++dict _internal ++bool visible ++str elem_id ++any elem_classes ++dict elem_style ++bool render +} +ModelScopeLayoutComponent <|-- AntdDrawer +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:10-108](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L10-L108) + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-50](file://backend/modelscope_studio/utils/dev/component.py#L11-L50) +- [backend/modelscope_studio/components/antd/components.py:38](file://backend/modelscope_studio/components/antd/components.py#L38) + +## 性能考量 + +- 条件渲染：仅在 visible 为真时渲染 Drawer，减少不必要的 DOM 开销 +- 渲染策略：合理使用 destroyOnClose/destroyOnHidden 以平衡内存占用与交互流畅度 +- 插槽与自定义渲染：避免在 drawerRender 中执行重型计算，必要时进行缓存或异步处理 + +## 故障排查指南 + +- 抽屉不显示 + - 检查 visible/open 是否为真 + - 确认 Index.svelte 的条件渲染逻辑 +- 插槽未生效 + - 确认插槽名称正确（closeIcon、closable.closeIcon、extra、footer、title、drawerRender） + - 确认 drawer.tsx 中的插槽映射逻辑 +- 关闭事件未触发 + - 检查后端事件绑定与回调函数传递 +- 遮罩无效或无法点击关闭 + - 检查 mask 与 maskClosable 配置 +- 键盘关闭失效 + - 检查 keyboard 配置与自动聚焦策略 + +章节来源 + +- [frontend/antd/drawer/Index.svelte:48-61](file://frontend/antd/drawer/Index.svelte#L48-L61) +- [frontend/antd/drawer/drawer.tsx:41-51](file://frontend/antd/drawer/drawer.tsx#L41-L51) +- [backend/modelscope_studio/components/antd/drawer/**init**.py:14-18](file://backend/modelscope_studio/components/antd/drawer/__init__.py#L14-L18) + +## 结论 + +Drawer 抽屉组件通过前后端一体化的设计，在保持 Ant Design Drawer 原生能力的同时，提供了更灵活的参数与插槽扩展。借助条件渲染与事件绑定机制，它能够高效地适配多种交互场景，包括侧边导航、详情面板与设置面板等。在布局层面，可与 Ant Design Layout 协同工作；在无障碍与移动端方面，建议结合键盘与尺寸策略提升体验。 + +## 附录 + +- 示例参考 + - Drawer 基础与额外操作：[docs/components/antd/drawer/README.md](file://docs/components/antd/drawer/README.md) + - Drawer 与 Modal 对比演示：[docs/components/antd/watermark/demos/modal_or_drawer.py](file://docs/components/antd/watermark/demos/modal_or_drawer.py) +- 相关文档 + - Ant Design Drawer 官方文档：[Ant Design Drawer](https://ant.design/components/drawer/) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Watermark \346\260\264\345\215\260.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Watermark \346\260\264\345\215\260.md" new file mode 100644 index 00000000..9e8247f8 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/Watermark \346\260\264\345\215\260.md" @@ -0,0 +1,434 @@ +# Watermark 水印 + + +**本文引用的文件** +- [watermark.tsx](file://frontend/antd/watermark/watermark.tsx) +- [Index.svelte](file://frontend/antd/watermark/Index.svelte) +- [__init__.py](file://backend/modelscope_studio/components/antd/watermark/__init__.py) +- [watermark-wBOVRUhz.js](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js) +- [basic.py](file://docs/components/antd/watermark/demos/basic.py) +- [modal_or_drawer.py](file://docs/components/antd/watermark/demos/modal_or_drawer.py) +- [README.md](file://docs/components/antd/watermark/README.md) +- [README-zh_CN.md](file://docs/components/antd/watermark/README-zh_CN.md) +- [app.py](file://docs/components/antd/watermark/app.py) +- [component.py](file://backend/modelscope_studio/utils/dev/component.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Watermark 水印组件用于在页面或容器上叠加显示文本或图片水印，常用于版权保护、版本标识、客户区分等场景。本仓库中的 Watermark 组件基于 Ant Design 的 Watermark 实现，并通过 Svelte/React 桥接层在 Gradio 生态中使用。 + +- 功能特性 + - 文本水印：支持单行或多行文本水印。 + - 图片水印：支持自定义图片作为水印源。 + - 位置与布局：通过宽度、高度、间距、偏移等参数控制重复与排布。 + - 角度旋转与缩放：支持旋转角度与缩放比例配置。 + - 透明度与层级：支持透明度与 z-index 控制。 + - 嵌入式使用：可包裹任意子元素，随容器变化自动生效。 + - 事件绑定：支持移除事件绑定，便于动态控制。 + +- 应用场景 + - 版权保护：在预览图或报表上添加“受版权保护”水印。 + - 版本标识：在开发/测试环境添加“DEVELOPMENT”或“TEST”水印。 + - 客户区分：按客户或租户添加专属水印，便于识别与审计。 + - 敏感数据保护：在导出或展示界面添加水印，降低误传播风险。 + +- 实现原理 + - 前端桥接：通过 sveltify 将 Ant Design 的 Watermark 组件包装为 Svelte 可用组件。 + - 属性透传：将 Gradio 属性（如 elem_id、elem_classes、elem_style、visible）与额外属性合并后传递给底层组件。 + - 渲染控制：根据 visible 控制是否渲染；支持 slots 插槽与 children 子节点。 + - 后端封装：Python 层提供 AntdWatermark 类，承载属性并声明前端目录映射，同时声明事件监听。 + +- 使用要点 + - 文本与图片：可通过 content 或 image 参数设置；多行文本可用数组形式。 + - 重复模式：通过 width、height、gap、offset 控制重复与偏移。 + - 旋转与缩放：rotate 控制角度；z_index 控制层级。 + - 动态更新：通过 Gradio 的更新机制可动态切换水印内容与样式。 + - 样式定制：通过 elem_style、elem_classes 与额外属性进行样式扩展。 + +**章节来源** + +- [README.md:1-9](file://docs/components/antd/watermark/README.md#L1-L9) +- [README-zh_CN.md:1-9](file://docs/components/antd/watermark/README-zh_CN.md#L1-L9) + +## 项目结构 + +Watermark 组件在仓库中的组织方式如下： + +- 前端 + - Svelte 包装层：Index.svelte 负责属性处理、可见性控制与子节点渲染。 + - React 桥接层：watermark.tsx 使用 sveltify 将 Ant Design 的 Watermark 包装为 Svelte 组件。 + - 运行时模板：watermark-wBOVRUhz.js 是组件运行时模板，负责 React 组件挂载与桥接逻辑。 +- 后端 + - Python 封装：AntdWatermark 类承载属性与事件，声明前端目录映射。 +- 示例与文档 + - 基础示例：basic.py 展示文本与图片水印的基本用法。 + - 弹窗示例：modal_or_drawer.py 展示在 Modal/Drawer 中使用水印的方法。 + - 文档页：README/README-zh_CN.md 提供示例占位与链接。 + +```mermaid +graph TB +subgraph "前端" +IDX["Index.svelte
属性处理与渲染控制"] +WRAP["watermark.tsx
sveltify 包装"] +RT["watermark-wBOVRUhz.js
运行时模板与桥接"] +end +subgraph "后端" +PY["__init__.py
AntdWatermark 类与属性"] +DEV["component.py
ModelScopeLayoutComponent 基类"] +end +subgraph "示例与文档" +DEMO1["basic.py"] +DEMO2["modal_or_drawer.py"] +DOC["README.md / README-zh_CN.md"] +end +IDX --> WRAP --> RT +PY --> IDX +PY --> WRAP +PY --> RT +DEV --> PY +DEMO1 --> PY +DEMO2 --> PY +DOC --> DEMO1 +DOC --> DEMO2 +``` + +**图表来源** + +- [Index.svelte:1-64](file://frontend/antd/watermark/Index.svelte#L1-L64) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [watermark-wBOVRUhz.js:1-442](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js#L1-L442) +- [**init**.py:1-83](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L1-L83) +- [component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [basic.py:1-23](file://docs/components/antd/watermark/demos/basic.py#L1-L23) +- [modal_or_drawer.py:1-30](file://docs/components/antd/watermark/demos/modal_or_drawer.py#L1-L30) +- [README.md:1-9](file://docs/components/antd/watermark/README.md#L1-L9) +- [README-zh_CN.md:1-9](file://docs/components/antd/watermark/README-zh_CN.md#L1-L9) + +**章节来源** + +- [Index.svelte:1-64](file://frontend/antd/watermark/Index.svelte#L1-L64) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [watermark-wBOVRUhz.js:1-442](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js#L1-L442) +- [**init**.py:1-83](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L1-L83) +- [component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [README.md:1-9](file://docs/components/antd/watermark/README.md#L1-L9) +- [README-zh_CN.md:1-9](file://docs/components/antd/watermark/README-zh_CN.md#L1-L9) + +## 核心组件 + +- AntdWatermark（后端） + - 职责：承载水印组件的属性与事件，声明前端目录映射，跳过 API 调用。 + - 关键属性（来自构造函数）：content、width、height、inherit、rotate、z_index、image、font、gap、offset、root_class_name 等。 + - 事件：remove（绑定移除事件）。 + - 其他：skip_api 返回 True，表示该组件不参与标准 API 流程。 + +- Watermark（前端桥接） + - 职责：通过 sveltify 将 Ant Design 的 Watermark 组件包装为 Svelte 组件，便于在 Gradio 中使用。 + - 行为：直接导出 Watermark 并默认导出。 + +- Index.svelte（前端包装） + - 职责：处理 Gradio 属性（elem_id、elem_classes、elem_style、visible），合并额外属性，控制可见性与子节点渲染。 + - 行为：当 visible 为真时，异步加载 Watermark 并渲染；支持 slots 与 children。 + +- 运行时模板（watermark-wBOVRUhz.js） + - 职责：提供 React 组件桥接、上下文合并、Portal 渲染与效果注册等能力，确保组件在浏览器环境中正确挂载与更新。 + +**章节来源** + +- [**init**.py:8-83](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L8-L83) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [Index.svelte:1-64](file://frontend/antd/watermark/Index.svelte#L1-L64) +- [watermark-wBOVRUhz.js:330-442](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js#L330-L442) + +## 架构总览 + +下图展示了从 Python 到前端再到运行时的整体调用链路与职责分工： + +```mermaid +sequenceDiagram +participant Py as "Python 后端
AntdWatermark" +participant Wrap as "前端包装
Index.svelte" +participant Bridge as "桥接层
watermark.tsx" +participant Runtime as "运行时模板
watermark-wBOVRUhz.js" +Py->>Wrap : "声明组件与属性" +Wrap->>Bridge : "导入并包装 Watermark" +Bridge->>Runtime : "创建 React 组件实例" +Runtime-->>Wrap : "返回可渲染的 React 组件" +Wrap-->>Py : "根据 visible 渲染或隐藏" +``` + +**图表来源** + +- [**init**.py:66-66](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L66-L66) +- [Index.svelte:10-63](file://frontend/antd/watermark/Index.svelte#L10-L63) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [watermark-wBOVRUhz.js:330-442](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js#L330-L442) + +## 详细组件分析 + +### 属性与配置 + +- 文本水印 + - content：字符串或字符串数组，用于设置水印文本；支持多行文本。 + - font：字体相关配置（如颜色、字号等），由底层 Ant Design 支持。 +- 图片水印 + - image：图片地址，用于设置图片水印源。 +- 重复与布局 + - width、height：水印单元的宽高。 + - gap：水印之间的水平与垂直间距。 + - offset：水印的初始偏移量（通常用于控制起始位置）。 +- 旋转与缩放 + - rotate：水印旋转角度。 + - inherit：是否继承父级样式。 +- 层级与透明度 + - z_index：水印层级。 + - 其他样式：通过 elem_style 与 elem_classes 控制透明度、背景等。 +- 其他 + - root_class_name：根节点类名前缀。 + - additional_props：额外属性透传。 + +- 动态更新与样式定制 + - visible：控制组件是否渲染。 + - elem_id、elem_classes、elem_style：用于定位与样式定制。 + - slots 与 children：支持插槽与子节点渲染。 + +**章节来源** + +- [**init**.py:50-64](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L50-L64) +- [Index.svelte:21-44](file://frontend/antd/watermark/Index.svelte#L21-L44) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) + +### 使用流程与示例 + +- 基础文本水印 + - 在容器内嵌套 Watermark，并设置 content 为字符串或数组。 + - 可参考示例：basic.py。 +- 图片水印 + - 设置 image 为图片地址，配合 width、height 控制水印尺寸。 + - 可参考示例：basic.py。 +- 在弹窗/抽屉中使用 + - 在 Modal/Drawer 外层包裹 Watermark，实现弹窗内的水印覆盖。 + - 可参考示例：modal_or_drawer.py。 + +```mermaid +sequenceDiagram +participant Demo as "示例脚本
basic.py / modal_or_drawer.py" +participant Py as "AntdWatermark
后端" +participant Wrap as "Index.svelte" +participant Bridge as "watermark.tsx" +participant RT as "watermark-wBOVRUhz.js" +Demo->>Py : "创建 Watermark 组件并传入属性" +Py->>Wrap : "声明组件与属性" +Wrap->>Bridge : "导入并包装" +Bridge->>RT : "创建 React 实例" +RT-->>Wrap : "返回可渲染组件" +Wrap-->>Demo : "渲染结果" +``` + +**图表来源** + +- [basic.py:1-23](file://docs/components/antd/watermark/demos/basic.py#L1-L23) +- [modal_or_drawer.py:1-30](file://docs/components/antd/watermark/demos/modal_or_drawer.py#L1-L30) +- [**init**.py:8-83](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L8-L83) +- [Index.svelte:50-63](file://frontend/antd/watermark/Index.svelte#L50-L63) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [watermark-wBOVRUhz.js:330-442](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js#L330-L442) + +**章节来源** + +- [basic.py:1-23](file://docs/components/antd/watermark/demos/basic.py#L1-L23) +- [modal_or_drawer.py:1-30](file://docs/components/antd/watermark/demos/modal_or_drawer.py#L1-L30) + +### 事件与生命周期 + +- remove 事件 + - 通过事件监听绑定，可在需要时移除水印。 + - 事件回调会更新内部状态以启用移除行为。 + +**章节来源** + +- [**init**.py:12-16](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L12-L16) + +### 类关系图 + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__init__() ++__exit__() +} +class AntdWatermark { ++EVENTS ++content ++width ++height ++inherit ++rotate ++z_index ++image ++font ++gap ++offset ++root_class_name ++FRONTEND_DIR ++skip_api ++preprocess() ++postprocess() ++example_payload() ++example_value() +} +ModelScopeLayoutComponent <|-- AntdWatermark +``` + +**图表来源** + +- [component.py:11-127](file://backend/modelscope_studio/utils/dev/component.py#L11-L127) +- [**init**.py:8-83](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L8-L83) + +## 依赖关系分析 + +- 组件耦合 + - AntdWatermark 依赖于前端目录映射与运行时模板，确保在浏览器中正确渲染。 + - Index.svelte 依赖于包装层与运行时模板，负责属性处理与可见性控制。 + - watermark.tsx 仅负责桥接，耦合度低，便于维护。 +- 外部依赖 + - Ant Design Watermark：底层实现。 + - Svelte/React 桥接工具：sveltify、@svelte-preprocess-react 等。 +- 潜在问题 + - 若未正确设置 FRONTEND_DIR，可能导致前端资源无法加载。 + - visible 为假时不会渲染，需注意动态切换时的副作用。 + +```mermaid +graph LR +PY["AntdWatermark
后端"] --> IDX["Index.svelte
前端包装"] +IDX --> WRAP["watermark.tsx
桥接"] +WRAP --> RT["watermark-wBOVRUhz.js
运行时模板"] +PY --> AD["Ant Design Watermark
外部依赖"] +``` + +**图表来源** + +- [**init**.py:66-66](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L66-L66) +- [Index.svelte:10-10](file://frontend/antd/watermark/Index.svelte#L10-L10) +- [watermark.tsx:1-1](file://frontend/antd/watermark/watermark.tsx#L1-L1) +- [watermark-wBOVRUhz.js:330-330](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js#L330-L330) + +**章节来源** + +- [**init**.py:66-66](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L66-L66) +- [Index.svelte:10-10](file://frontend/antd/watermark/Index.svelte#L10-L10) +- [watermark.tsx:1-1](file://frontend/antd/watermark/watermark.tsx#L1-L1) +- [watermark-wBOVRUhz.js:330-330](file://backend/modelscope_studio/components/antd/watermark/templates/component/watermark-wBOVRUhz.js#L330-L330) + +## 性能考量 + +- 渲染开销 + - 水印本质上是叠加在容器上的背景层，对主内容渲染影响较小；但大量重复单元可能增加绘制成本。 +- 重绘与重排 + - 频繁变更 content、image、rotate、z_index 等属性可能触发重绘；建议批量更新或减少变更频率。 +- 图片水印 + - 图片加载与解码会带来额外开销；建议使用合适尺寸与格式的图片，避免超大图片导致卡顿。 +- 可见性控制 + - 通过 visible 控制渲染时机，可有效减少不必要的开销。 +- 建议 + - 合理设置 width、height、gap，避免过度密集的重复。 + - 对于频繁切换的场景，优先使用缓存与节流策略。 + - 在弹窗/抽屉中使用时，注意弹窗打开/关闭时的渲染时机。 + +[本节为通用性能建议，无需特定文件来源] + +## 故障排查指南 + +- 无法显示水印 + - 检查 visible 是否为真；确认属性是否正确透传到组件。 + - 确认 FRONTEND_DIR 是否正确指向前端目录。 +- 图片水印不显示 + - 检查 image 地址是否可访问；确认图片尺寸与格式合理。 + - 调整 width、height 使其适配容器。 +- 旋转或层级异常 + - 检查 rotate、z_index 设置是否符合预期；确认是否有其他样式覆盖。 +- 动态更新无效 + - 确认更新逻辑是否正确；必要时使用重新渲染策略。 +- 事件未生效 + - 确认已绑定 remove 事件；检查事件回调是否正确执行。 + +**章节来源** + +- [Index.svelte:50-63](file://frontend/antd/watermark/Index.svelte#L50-L63) +- [**init**.py:66-66](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L66-L66) + +## 结论 + +Watermark 组件通过简洁的属性体系与稳定的桥接机制，在 Gradio 生态中提供了灵活的水印能力。其支持文本与图片水印、重复布局、旋转缩放与层级控制，适用于版权保护、版本标识与客户区分等多种场景。结合可见性控制与事件绑定，可实现动态化与可维护的水印方案。 + +[本节为总结性内容，无需特定文件来源] + +## 附录 + +### 常见使用场景示例路径 + +- 版权保护：在预览图或报表容器上添加“受版权保护”的文本或图片水印。 +- 版本标识：在开发/测试环境添加“DEVELOPMENT”或“TEST”水印。 +- 客户区分：按客户或租户添加专属水印，便于识别与审计。 +- 导出保护：在导出界面或打印预览中添加水印，降低误传播风险。 + +**章节来源** + +- [basic.py:1-23](file://docs/components/antd/watermark/demos/basic.py#L1-L23) +- [modal_or_drawer.py:1-30](file://docs/components/antd/watermark/demos/modal_or_drawer.py#L1-L30) + +### 属性配置速查 + +- 文本水印：content（字符串或数组）、font +- 图片水印：image、width、height +- 重复与布局：gap、offset +- 旋转与层级：rotate、z_index +- 样式与可见性：elem_style、elem_classes、elem_id、visible +- 其他：root_class_name、additional_props + +**章节来源** + +- [**init**.py:50-64](file://backend/modelscope_studio/components/antd/watermark/__init__.py#L50-L64) +- [Index.svelte:21-44](file://frontend/antd/watermark/Index.svelte#L21-L44) + +### 安全与防篡改建议 + +- 内容来源可信：确保 content 与 image 来源可信，避免注入恶意内容。 +- 访问控制：限制水印组件的修改权限，防止被绕过或删除。 +- 日志审计：记录水印变更日志，便于追踪与审计。 +- 最小权限原则：仅授予必要的水印配置权限，避免过度授权。 + +[本节为通用安全建议，无需特定文件来源] + +### 无障碍访问与屏幕阅读器兼容 + +- 文本水印 + - 确保文本语义清晰，避免使用装饰性文本。 + - 为关键信息提供替代文本或标题。 +- 图片水印 + - 为图片水印提供描述性 alt 文本，便于屏幕阅读器识别。 +- 交互与焦点 + - 水印不应干扰用户操作；确保可聚焦元素不受遮挡。 +- 样式与对比度 + - 确保水印与背景有足够对比度，避免影响可读性。 +- 可访问性测试 + - 使用屏幕阅读器与键盘导航进行测试，验证无障碍体验。 + +[本节为通用无障碍建议，无需特定文件来源] diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\344\272\244\344\272\222\345\217\215\351\246\210\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\344\272\244\344\272\222\345\217\215\351\246\210\347\273\204\344\273\266.md" new file mode 100644 index 00000000..b44b23f8 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\344\272\244\344\272\222\345\217\215\351\246\210\347\273\204\344\273\266.md" @@ -0,0 +1,301 @@ +# 交互反馈组件 + + +**本文引用的文件** +- [frontend/antd/popconfirm/popconfirm.tsx](file://frontend/antd/popconfirm/popconfirm.tsx) +- [frontend/antd/popover/popover.tsx](file://frontend/antd/popover/popover.tsx) +- [frontend/antd/popconfirm/Index.svelte](file://frontend/antd/popconfirm/Index.svelte) +- [frontend/antd/popover/Index.svelte](file://frontend/antd/popover/Index.svelte) +- [backend/modelscope_studio/components/antd/popconfirm/__init__.py](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py) +- [backend/modelscope_studio/components/antd/popover/__init__.py](file://backend/modelscope_studio/components/antd/popover/__init__.py) +- [docs/components/antd/popconfirm/README-zh_CN.md](file://docs/components/antd/popconfirm/README-zh_CN.md) +- [docs/components/antd/popover/README-zh_CN.md](file://docs/components/antd/popover/README-zh_CN.md) + + +## 目录 + +1. [引言](#引言) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 引言 + +本文件聚焦于交互反馈组件群组中的两类：气泡确认框（Popconfirm）与气泡卡片（Popover）。我们将从设计理念、交互模式、确认流程、内容承载、触发与定位策略、属性与事件、样式定制以及常见使用场景等方面进行系统化说明，并给出可追溯到源码的参考路径，帮助开发者快速理解与正确使用。 + +## 项目结构 + +这两个组件在前端采用“Svelte 包装层 + React 组件库桥接”的模式，后端通过 Gradio 组件封装暴露 Python API。其组织方式如下： + +- 前端层：Svelte 组件负责属性透传、插槽渲染与事件映射；TypeScript 桥接层将 Ant Design 的 React 组件适配为 Svelte 可用形式。 +- 后端层：Python 组件类定义属性、事件、插槽与默认值，并声明前端目录映射，使运行时可加载对应前端组件。 + +```mermaid +graph TB +subgraph "前端" +IDX_PCF["Index.svelte
popconfirm"] --> BRG_PCF["popconfirm.tsx
桥接层"] +IDX_POV["Index.svelte
popover"] --> BRG_POV["popover.tsx
桥接层"] +end +subgraph "后端" +PY_PCF["AntdPopconfirm
Python 组件"] --> FE_DIR_PCF["resolve_frontend_dir('popconfirm')"] +PY_POV["AntdPopover
Python 组件"] --> FE_DIR_POV["resolve_frontend_dir('popover')"] +end +BRG_PCF --> ANT_PCF["Ant Design Popconfirm"] +BRG_POV --> ANT_POV["Ant Design Popover"] +PY_PCF --> IDX_PCF +PY_POV --> IDX_POV +``` + +图表来源 + +- [frontend/antd/popconfirm/Index.svelte:1-76](file://frontend/antd/popconfirm/Index.svelte#L1-L76) +- [frontend/antd/popover/Index.svelte:1-76](file://frontend/antd/popover/Index.svelte#L1-L76) +- [frontend/antd/popconfirm/popconfirm.tsx:1-65](file://frontend/antd/popconfirm/popconfirm.tsx#L1-L65) +- [frontend/antd/popover/popover.tsx:1-37](file://frontend/antd/popover/popover.tsx#L1-L37) +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:138-138](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L138-L138) +- [backend/modelscope_studio/components/antd/popover/**init**.py:106-106](file://backend/modelscope_studio/components/antd/popover/__init__.py#L106-L106) + +章节来源 + +- [frontend/antd/popconfirm/Index.svelte:1-76](file://frontend/antd/popconfirm/Index.svelte#L1-L76) +- [frontend/antd/popover/Index.svelte:1-76](file://frontend/antd/popover/Index.svelte#L1-L76) +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:138-138](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L138-L138) +- [backend/modelscope_studio/components/antd/popover/**init**.py:106-106](file://backend/modelscope_studio/components/antd/popover/__init__.py#L106-L106) + +## 核心组件 + +- 气泡确认框（Popconfirm） + - 设计理念：对危险或不可逆操作进行二次确认，减少误操作风险。 + - 关键交互：支持 hover/focus/click/contextMenu 触发；提供“确认/取消”双按钮与文案/图标插槽。 + - 确认流程：点击确认触发回调；取消关闭弹层；支持 open 状态受控与受控事件回调。 +- 气泡卡片（Popover） + - 设计理念：在不改变页面布局的前提下，对目标元素进行上下文信息提示或简短操作入口。 + - 关键交互：支持 hover/focus/click/contextMenu 触发；标题与内容可插槽化，支持自动避障与定位。 + +章节来源 + +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:10-27](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L10-L27) +- [backend/modelscope_studio/components/antd/popover/**init**.py:10-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L18) + +## 架构总览 + +下图展示了从前端 Svelte 到后端 Python 组件的调用链路与数据流。 + +```mermaid +sequenceDiagram +participant Py as "Python 组件
AntdPopconfirm/AntdPopover" +participant Idx as "Svelte 包装层
Index.svelte" +participant Br as "桥接层
popconfirm.tsx / popover.tsx" +participant AD as "Ant Design 组件" +Py->>Idx : "实例化并传递属性/事件/插槽" +Idx->>Br : "渲染桥接组件，透传属性与插槽" +Br->>AD : "调用 Ant Design 组件，注入事件与容器" +AD-->>Br : "状态变化(openChange)" +Br-->>Idx : "回调触发" +Idx-->>Py : "事件上报(如 open_change/popup_click)" +``` + +图表来源 + +- [frontend/antd/popconfirm/Index.svelte:24-55](file://frontend/antd/popconfirm/Index.svelte#L24-L55) +- [frontend/antd/popover/Index.svelte:24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- [frontend/antd/popconfirm/popconfirm.tsx:17-62](file://frontend/antd/popconfirm/popconfirm.tsx#L17-L62) +- [frontend/antd/popover/popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:14-27](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L14-L27) +- [backend/modelscope_studio/components/antd/popover/**init**.py:14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) + +## 详细组件分析 + +### 气泡确认框（Popconfirm） + +- 设计理念与交互模式 + - 面向“高风险操作”，通过二次确认降低误触成本。 + - 支持多种触发方式，弹层内提供确认/取消按钮与可选图标。 +- 属性与事件 + - 属性要点：标题、描述、确认文案/按钮属性、取消文案/按钮属性、触发类型、定位与避障、容器挂载点、延迟、z-index 等。 + - 事件要点：open_change、cancel、confirm、popup_click。 + - 插槽要点：title、description、okText、okButtonProps.icon、cancelText、cancelButtonProps.icon。 +- 回调与状态 + - 通过 afterOpenChange 获取打开/关闭状态变化。 + - 通过 getPopupContainer 自定义挂载容器，便于复杂布局下的定位与层级控制。 +- 使用场景 + - 删除确认、编辑确认、批量操作确认等。 + +```mermaid +flowchart TD +Start(["用户触发"]) --> Trigger{"触发类型"} +Trigger --> |click/hover/focus/contextMenu| Open["打开确认框"] +Open --> Action{"用户选择"} +Action --> |确认| Confirm["触发 confirm 回调"] +Action --> |取消| Cancel["触发 cancel 回调"] +Confirm --> Close["关闭弹层"] +Cancel --> Close +Close --> End(["结束"]) +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:14-27](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L14-L27) +- [frontend/antd/popconfirm/popconfirm.tsx:17-62](file://frontend/antd/popconfirm/popconfirm.tsx#L17-L62) + +章节来源 + +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:10-137](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L10-L137) +- [frontend/antd/popconfirm/popconfirm.tsx:7-62](file://frontend/antd/popconfirm/popconfirm.tsx#L7-L62) +- [frontend/antd/popconfirm/Index.svelte:24-75](file://frontend/antd/popconfirm/Index.svelte#L24-L75) + +### 气泡卡片（Popover） + +- 设计理念与交互模式 + - 提供非侵入式的信息展示与轻量操作入口。 + - 支持标题与内容插槽，自动避障与多方位定位。 +- 属性与事件 + - 属性要点：标题、内容、触发类型、定位、箭头、颜色、容器挂载点、延迟、z-index 等。 + - 事件要点：open_change。 + - 插槽要点：title、content。 +- 使用场景 + - 信息提示、操作菜单、辅助说明等。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant P as "Popover" +participant C as "内容插槽" +participant D as "定位与避障" +U->>P : "触发(点击/悬停/焦点/右键)" +P->>D : "计算最佳位置与避障" +P->>C : "渲染 title/content 插槽" +P-->>U : "显示浮层" +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/popover/**init**.py:14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) +- [frontend/antd/popover/popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) + +章节来源 + +- [backend/modelscope_studio/components/antd/popover/**init**.py:10-104](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L104) +- [frontend/antd/popover/popover.tsx:7-34](file://frontend/antd/popover/popover.tsx#L7-L34) +- [frontend/antd/popover/Index.svelte:24-72](file://frontend/antd/popover/Index.svelte#L24-L72) + +### 组件类与桥接层关系 + +```mermaid +classDiagram +class AntdPopconfirm { ++EVENTS ++SLOTS ++属性与方法... +} +class PopconfirmBridge { ++slots : title, description, okText, okButtonProps.icon, cancelText, cancelButtonProps.icon ++afterOpenChange() ++getPopupContainer() +} +class AntdPopover { ++EVENTS ++SLOTS ++属性与方法... +} +class PopoverBridge { ++slots : title, content ++afterOpenChange() ++getPopupContainer() +} +AntdPopconfirm --> PopconfirmBridge : "实例化并渲染" +AntdPopover --> PopoverBridge : "实例化并渲染" +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:10-37](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L10-L37) +- [frontend/antd/popconfirm/popconfirm.tsx:7-17](file://frontend/antd/popconfirm/popconfirm.tsx#L7-L17) +- [backend/modelscope_studio/components/antd/popover/**init**.py:10-21](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L21) +- [frontend/antd/popover/popover.tsx:7-12](file://frontend/antd/popover/popover.tsx#L7-L12) + +## 依赖关系分析 + +- 前端依赖 + - Svelte 包装层依赖桥接层；桥接层依赖 Ant Design React 组件库。 + - 事件与插槽通过函数包装与 ReactSlot 渲染实现跨框架传递。 +- 后端依赖 + - Python 组件类通过 resolve_frontend_dir 将组件名映射到前端目录，确保运行时可加载。 +- 耦合与内聚 + - 组件职责清晰：Python 负责属性/事件/插槽定义，Svelte 负责属性透传与事件映射，TS 桥接层负责插槽渲染与回调包装。 + +```mermaid +graph LR +PY_PCF["Python: AntdPopconfirm"] --> IDX_PCF["Svelte: popconfirm/Index.svelte"] +IDX_PCF --> BRG_PCF["TS: popconfirm.tsx"] +BRG_PCF --> AD_PCF["Ant Design Popconfirm"] +PY_POV["Python: AntdPopover"] --> IDX_POV["Svelte: popover/Index.svelte"] +IDX_POV --> BRG_POV["TS: popover.tsx"] +BRG_POV --> AD_POV["Ant Design Popover"] +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:138-138](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L138-L138) +- [frontend/antd/popconfirm/Index.svelte:10-10](file://frontend/antd/popconfirm/Index.svelte#L10-L10) +- [frontend/antd/popconfirm/popconfirm.tsx:1-5](file://frontend/antd/popconfirm/popconfirm.tsx#L1-L5) +- [backend/modelscope_studio/components/antd/popover/**init**.py:106-106](file://backend/modelscope_studio/components/antd/popover/__init__.py#L106-L106) +- [frontend/antd/popover/Index.svelte:10-10](file://frontend/antd/popover/Index.svelte#L10-L10) +- [frontend/antd/popover/popover.tsx:1-5](file://frontend/antd/popover/popover.tsx#L1-L5) + +章节来源 + +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:138-138](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L138-L138) +- [backend/modelscope_studio/components/antd/popover/**init**.py:106-106](file://backend/modelscope_studio/components/antd/popover/__init__.py#L106-L106) +- [frontend/antd/popconfirm/Index.svelte:10-10](file://frontend/antd/popconfirm/Index.svelte#L10-L10) +- [frontend/antd/popover/Index.svelte:10-10](file://frontend/antd/popover/Index.svelte#L10-L10) +- [frontend/antd/popconfirm/popconfirm.tsx:1-5](file://frontend/antd/popconfirm/popconfirm.tsx#L1-L5) +- [frontend/antd/popover/popover.tsx:1-5](file://frontend/antd/popover/popover.tsx#L1-L5) + +## 性能考量 + +- 按需加载与懒渲染 + - Svelte 包装层使用动态导入组件，避免初始包体过大。 +- 插槽渲染优化 + - 仅在需要时渲染插槽内容，减少不必要的虚拟 DOM 更新。 +- 容器挂载与层级管理 + - 通过 getPopupContainer 将弹层挂载到合适容器，避免层级冲突与重排。 +- 延迟与销毁策略 + - 合理设置鼠标进入/离开延迟，避免频繁抖动；根据场景选择隐藏即销毁策略以节省内存。 + +## 故障排查指南 + +- 无法打开/关闭 + - 检查触发类型与 open 状态是否一致；确认 open_change 事件是否正确绑定。 + - 参考路径：[frontend/antd/popconfirm/Index.svelte:24-55](file://frontend/antd/popconfirm/Index.svelte#L24-L55)、[frontend/antd/popover/Index.svelte:24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- 内容未显示或错位 + - 确认插槽名称与渲染逻辑；检查 getPopupContainer 是否返回有效容器。 + - 参考路径：[frontend/antd/popconfirm/popconfirm.tsx:17-62](file://frontend/antd/popconfirm/popconfirm.tsx#L17-L62)、[frontend/antd/popover/popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) +- 事件未触发 + - 确认后端事件监听与前端事件映射是否一致；检查回调函数包装是否生效。 + - 参考路径：[backend/modelscope_studio/components/antd/popconfirm/**init**.py:14-27](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L14-L27)、[backend/modelscope_studio/components/antd/popover/**init**.py:14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) + +章节来源 + +- [frontend/antd/popconfirm/Index.svelte:24-55](file://frontend/antd/popconfirm/Index.svelte#L24-L55) +- [frontend/antd/popover/Index.svelte:24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- [frontend/antd/popconfirm/popconfirm.tsx:17-62](file://frontend/antd/popconfirm/popconfirm.tsx#L17-L62) +- [frontend/antd/popover/popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) +- [backend/modelscope_studio/components/antd/popconfirm/**init**.py:14-27](file://backend/modelscope_studio/components/antd/popconfirm/__init__.py#L14-L27) +- [backend/modelscope_studio/components/antd/popover/**init**.py:14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) + +## 结论 + +Popconfirm 与 Popover 在本项目中通过统一的“Python 组件 + Svelte 包装 + TS 桥接 + Ant Design 组件”的架构实现，既保证了与 Ant Design 行为的一致性，又提供了灵活的插槽与事件扩展能力。合理利用触发、定位、容器挂载与事件回调，可在复杂界面中实现稳定且友好的交互体验。 + +## 附录 + +- 示例入口 + - Popconfirm 示例入口：[docs/components/antd/popconfirm/README-zh_CN.md:5-8](file://docs/components/antd/popconfirm/README-zh_CN.md#L5-L8) + - Popover 示例入口：[docs/components/antd/popover/README-zh_CN.md:5-8](file://docs/components/antd/popover/README-zh_CN.md#L5-L8) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\345\212\240\350\275\275\351\252\250\346\236\266\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\345\212\240\350\275\275\351\252\250\346\236\266\347\273\204\344\273\266.md" new file mode 100644 index 00000000..258e7582 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\345\212\240\350\275\275\351\252\250\346\236\266\347\273\204\344\273\266.md" @@ -0,0 +1,327 @@ +# 加载骨架组件 + + +**本文引用的文件** +- [frontend/antd/skeleton/skeleton.tsx](file://frontend/antd/skeleton/skeleton.tsx) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx) +- [frontend/antd/skeleton/button/skeleton.button.tsx](file://frontend/antd/skeleton/button/skeleton.button.tsx) +- [frontend/antd/skeleton/image/skeleton.image.tsx](file://frontend/antd/skeleton/image/skeleton.image.tsx) +- [frontend/antd/skeleton/input/skeleton.input.tsx](file://frontend/antd/skeleton/input/skeleton.input.tsx) +- [frontend/antd/skeleton/node/skeleton.node.tsx](file://frontend/antd/skeleton/node/skeleton.node.tsx) +- [frontend/antd/spin/spin.tsx](file://frontend/antd/spin/spin.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：常见使用场景与最佳实践](#附录常见使用场景与最佳实践) + +## 简介 + +本文件聚焦于加载骨架组件群组，系统性阐述骨架屏（Skeleton）与加载中（Spin）两类组件在本仓库中的实现方式、使用策略与用户体验设计要点。内容涵盖： + +- 骨架屏占位符类型、动画效果与内容布局模拟思路 +- 加载中旋转指示器的尺寸变化与状态管理 +- 组件属性配置、自定义动画与样式定制方法 +- 列表加载、图片占位、表单加载、页面切换等常见场景的实践建议 +- 骨架屏与真实内容的切换时机与过渡效果 +- 性能优化建议与网络状态适配方案 + +## 项目结构 + +加载骨架组件群组位于前端 Ant Design 组件层，采用统一的“适配器”封装模式，将 Ant Design 的 React 组件通过预处理工具桥接到 Svelte 生态中，确保在本项目的组件体系中保持一致的调用体验。 + +```mermaid +graph TB +subgraph "Antd 骨架屏子组件" +SA["Skeleton.Avatar
avatar/skeleton.avatar.tsx"] +SB["Skeleton.Button
button/skeleton.button.tsx"] +SI["Skeleton.Image
image/skeleton.image.tsx"] +SIN["Skeleton.Input
input/skeleton.input.tsx"] +SN["Skeleton.Node
node/skeleton.node.tsx"] +end +SMain["Skeleton
skeleton.tsx"] +subgraph "Antd 加载中" +SP["Spin
spin.tsx"] +end +SMain --> SA +SMain --> SB +SMain --> SI +SMain --> SIN +SMain --> SN +``` + +图表来源 + +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) +- [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) +- [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) +- [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) +- [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) + +章节来源 + +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) +- [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) +- [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) +- [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) +- [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) + +## 核心组件 + +- Skeleton（骨架屏） + - 主入口：将 Ant Design 的 Skeleton 组件以统一方式桥接至 Svelte 环境 + - 子组件：Avatar、Button、Image、Input、Node，分别对应不同元素类型的占位骨架 +- Spin（加载中） + - 主入口：将 Ant Design 的 Spin 组件以统一方式桥接至 Svelte 环境，并支持插槽化 tip 与 indicator 自定义 + +章节来源 + +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) +- [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) +- [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) +- [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) +- [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) + +## 架构总览 + +整体架构采用“适配器 + 插槽”的组合模式： + +- 适配器：通过统一的 sveltify 工具将 Ant Design 的 React 组件桥接为 Svelte 可用组件 +- 插槽化：Spin 支持 tip 与 indicator 两个插槽，便于自定义提示文案与指示器样式 +- 目标选择：Spin 内部通过目标选择钩子将 children 转换为可定位的目标集合，保证包裹逻辑正确 + +```mermaid +sequenceDiagram +participant U as "用户代码" +participant S as "Spin 组件" +participant Hook as "useTargets 钩子" +participant AD as "Antd Spin" +U->>S : 传入 children 与 props +S->>Hook : useTargets(children) +Hook-->>S : 返回目标集合 targets +S->>AD : 渲染 Antd Spin(props, slots) +AD-->>U : 显示加载中可带自定义 tip/indicator +``` + +图表来源 + +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) + +章节来源 + +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) + +## 详细组件分析 + +### 骨架屏（Skeleton）组件族 + +- 设计目标 + - 在数据未就绪时提供稳定的内容布局占位，避免页面跳动与布局抖动 + - 通过合理的动画与形状模拟真实内容，提升感知速度与可用性 +- 占位符类型 + - Avatar：头像占位 + - Button：按钮占位 + - Image：图片占位 + - Input：输入框占位 + - Node：通用节点占位 +- 动画与布局 + - 基于 Ant Design 的 Skeleton 动画机制，通常表现为渐变闪烁（shimmer）效果 + - 通过设置不同的形状（圆形/方形/矩形）与行数，模拟文本、卡片、列表等复杂布局 +- 使用建议 + - 列表加载：优先使用 Node 或多行 Input 模拟行项 + - 图片占位：使用 Image 占位，尺寸与真实图片一致 + - 表单加载：使用 Input/Button 模拟字段与操作区域 + - 页面切换：在路由切换期间使用 Skeleton 包裹容器，减少白屏感知 + +```mermaid +classDiagram +class Skeleton { ++主入口 +} +class SkeletonAvatar { ++头像占位 +} +class SkeletonButton { ++按钮占位 +} +class SkeletonImage { ++图片占位 +} +class SkeletonInput { ++输入占位 +} +class SkeletonNode { ++通用节点占位 +} +Skeleton --> SkeletonAvatar : "包含" +Skeleton --> SkeletonButton : "包含" +Skeleton --> SkeletonImage : "包含" +Skeleton --> SkeletonInput : "包含" +Skeleton --> SkeletonNode : "包含" +``` + +图表来源 + +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) +- [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) +- [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) +- [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) +- [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) + +章节来源 + +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) +- [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) +- [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) +- [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) +- [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) + +### 加载中（Spin）组件 + +- 设计目标 + - 在异步操作期间提供明确的反馈，避免用户误以为页面无响应 + - 支持自定义提示文案与指示器，满足不同场景的视觉需求 +- 关键特性 + - 插槽化：支持 tip 与 indicator 插槽，便于注入自定义文案与图标 + - 目标选择：内部通过目标选择钩子将 children 转为目标集合，保证包裹逻辑正确 + - 属性透传：除额外扩展外，其余属性直接透传至 Ant Design 的 Spin +- 使用建议 + - 列表加载：将 Spin 作为列表容器，children 为列表项，tip 提示“加载中” + - 图片占位：在图片未加载完成时包裹图片，indicator 使用简洁的旋转图标 + - 表单提交：在提交过程中禁用交互并显示 Spin，tip 提示“提交中” + - 页面切换：在路由切换期间包裹整个页面，提供全局加载反馈 + +```mermaid +flowchart TD +Start(["进入 Spin 渲染"]) --> Targets["useTargets(children)
解析目标集合"] +Targets --> HasTargets{"是否存在目标？"} +HasTargets --> |否| HideChildren["隐藏 children仅渲染占位"] +HasTargets --> |是| ShowChildren["显示 children"] +HideChildren --> RenderAD["渲染 Antd Spin(props, slots)"] +ShowChildren --> RenderAD +RenderAD --> End(["结束"]) +``` + +图表来源 + +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) + +章节来源 + +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) + +## 依赖关系分析 + +- 组件耦合 + - Skeleton 家族均依赖 Ant Design 的 Skeleton 实现，通过 sveltify 进行桥接 + - Spin 依赖 Ant Design 的 Spin 实现，并引入目标选择钩子与 ReactSlot 插槽机制 +- 外部依赖 + - @svelte-preprocess-react：提供 sveltify 与 ReactSlot 能力 + - Ant Design：提供 Skeleton 与 Spin 的具体实现 +- 潜在问题 + - 插槽名称与属性命名需与 Ant Design 保持一致，避免运行时错误 + - 目标选择逻辑需确保 children 结构合理，避免包裹异常 + +```mermaid +graph LR +Spin["Spin 组件"] --> AD_Spin["Antd Spin"] +Spin --> RS["ReactSlot 插槽"] +Spin --> UT["useTargets 钩子"] +Skeleton["Skeleton 组件"] --> AD_Skeleton["Antd Skeleton"] +Skeleton --> SA["Skeleton.Avatar"] +Skeleton --> SB["Skeleton.Button"] +Skeleton --> SI["Skeleton.Image"] +Skeleton --> SIN["Skeleton.Input"] +Skeleton --> SN["Skeleton.Node"] +``` + +图表来源 + +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) +- [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) +- [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) +- [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) +- [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) + +章节来源 + +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) + +## 性能考量 + +- 骨架屏渲染成本 + - Skeleton 的占位元素数量与层级应与真实内容尽量接近，避免过度渲染导致卡顿 + - 对长列表使用 Skeleton.Node 或少量行输入进行占位，减少 DOM 数量 +- 加载中反馈 + - Spin 的 tip 与 indicator 应尽量轻量，避免额外的重绘与回流 + - 在高频刷新场景下，建议使用节流或防抖控制加载状态的切换频率 +- 网络状态适配 + - 对弱网环境，建议延长 Skeleton 显示时间阈值，避免频繁闪烁 + - 对高延迟场景，Spin 的 tip 文案应明确告知用户等待原因（如“正在连接服务器”） + +## 故障排查指南 + +- 问题：Spin 无法正确包裹 children + - 排查：确认 children 是否为可识别的目标结构；检查 useTargets 的返回结果 + - 参考实现位置：[frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- 问题：插槽 tip/indicator 不生效 + - 排查：确认插槽名称是否为 tip 与 indicator；确保 slots 对象存在对应键 + - 参考实现位置：[frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- 问题：Skeleton 子组件样式异常 + - 排查：确认子组件是否正确导入 Ant Design 的对应模块；检查主题与样式覆盖 + - 参考实现位置： + - [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) + - [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) + - [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) + - [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) + - [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) + - [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) + +章节来源 + +- [frontend/antd/spin/spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- [frontend/antd/skeleton/skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [frontend/antd/skeleton/avatar/skeleton.avatar.tsx:1-9](file://frontend/antd/skeleton/avatar/skeleton.avatar.tsx#L1-L9) +- [frontend/antd/skeleton/button/skeleton.button.tsx:1-9](file://frontend/antd/skeleton/button/skeleton.button.tsx#L1-L9) +- [frontend/antd/skeleton/image/skeleton.image.tsx:1-9](file://frontend/antd/skeleton/image/skeleton.image.tsx#L1-L9) +- [frontend/antd/skeleton/input/skeleton.input.tsx:1-9](file://frontend/antd/skeleton/input/skeleton.input.tsx#L1-L9) +- [frontend/antd/skeleton/node/skeleton.node.tsx:1-9](file://frontend/antd/skeleton/node/skeleton.node.tsx#L1-L9) + +## 结论 + +本仓库的加载骨架组件群组通过统一的适配器与插槽化设计，实现了对 Ant Design Skeleton 与 Spin 的无缝集成。在实际应用中，应结合业务场景合理选择骨架屏类型与加载中反馈形式，并通过属性与插槽定制满足品牌与交互需求。同时，关注渲染性能与网络状态适配，确保在不同设备与环境下提供一致、流畅的用户体验。 + +## 附录：常见使用场景与最佳实践 + +- 列表加载 + - 使用 Skeleton.Node 或多行 Input 模拟列表项占位 + - 在 Spin 中包裹列表容器，tip 提示“加载中”，indicator 使用默认旋转图标 +- 图片占位 + - 使用 Skeleton.Image 模拟图片尺寸与占位 + - 在图片加载失败时，可切换为占位骨架或错误提示 +- 表单加载 + - 使用 Skeleton.Input 与 Skeleton.Button 模拟输入与提交区域 + - 在提交过程中禁用交互并显示 Spin，tip 提示“提交中” +- 页面切换 + - 在路由切换期间使用 Skeleton 包裹页面主体，减少白屏感知 + - 对高延迟场景，Spin 的 tip 文案应明确告知用户等待原因 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\345\217\215\351\246\210\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\345\217\215\351\246\210\347\273\204\344\273\266.md" new file mode 100644 index 00000000..192eaad4 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\345\217\215\351\246\210\347\273\204\344\273\266.md" @@ -0,0 +1,437 @@ +# 反馈组件 + + +**本文引用的文件** +- [alert.tsx](file://frontend/antd/alert/alert.tsx) +- [drawer.tsx](file://frontend/antd/drawer/drawer.tsx) +- [message.tsx](file://frontend/antd/message/message.tsx) +- [modal.tsx](file://frontend/antd/modal/modal.tsx) +- [notification.tsx](file://frontend/antd/notification/notification.tsx) +- [popconfirm.tsx](file://frontend/antd/popconfirm/popconfirm.tsx) +- [progress.tsx](file://frontend/antd/progress/progress.tsx) +- [result.tsx](file://frontend/antd/result/result.tsx) +- [skeleton.tsx](file://frontend/antd/skeleton/skeleton.tsx) +- [spin.tsx](file://frontend/antd/spin/spin.tsx) +- [watermark.tsx](file://frontend/antd/watermark/watermark.tsx) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [useTargets.ts](file://frontend/utils/hooks/useTargets.ts) +- [renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件系统性梳理 Ant Design 反馈类组件在前端侧的封装与使用，覆盖以下组件：警告提示（Alert）、抽屉（Drawer）、全局提示（Message）、对话框（Modal）、通知提醒框（Notification）、气泡确认框（Popconfirm）、进度条（Progress）、结果（Result）、骨架屏（Skeleton）、加载中（Spin）、水印（Watermark）。文档重点阐述各组件的触发机制、显示时机、交互逻辑、动画与过渡状态管理、错误与异常处理策略、无障碍与键盘操作支持，以及复杂交互场景下的反馈设计模式。 + +## 项目结构 + +反馈组件均位于前端目录下，采用统一的封装模式：通过 sveltify 将 Ant Design 原生组件桥接为 Svelte 风格组件；利用 ReactSlot 与 renderParamsSlot 实现插槽化渲染；通过 useFunction/useTargets 等工具钩子确保回调与插槽目标的正确传递与排序。 + +```mermaid +graph TB +subgraph "Ant Design 反馈组件" +A1["Alert
frontend/antd/alert/alert.tsx"] +A2["Drawer
frontend/antd/drawer/drawer.tsx"] +A3["Message
frontend/antd/message/message.tsx"] +A4["Modal
frontend/antd/modal/modal.tsx"] +A5["Notification
frontend/antd/notification/notification.tsx"] +A6["Popconfirm
frontend/antd/popconfirm/popconfirm.tsx"] +A7["Progress
frontend/antd/progress/progress.tsx"] +A8["Result
frontend/antd/result/result.tsx"] +A9["Skeleton
frontend/antd/skeleton/skeleton.tsx"] +A10["Spin
frontend/antd/spin/spin.tsx"] +A11["Watermark
frontend/antd/watermark/watermark.tsx"] +end +subgraph "工具与钩子" +U1["useFunction
frontend/utils/hooks/useFunction.ts"] +U2["useTargets
frontend/utils/hooks/useTargets.ts"] +U3["renderParamsSlot
frontend/utils/renderParamsSlot.tsx"] +end +A1 --> U1 +A2 --> U1 +A3 --> U1 +A4 --> U1 +A5 --> U1 +A6 --> U1 +A7 --> U1 +A8 --> U2 +A9 --> U1 +A10 --> U2 +A11 --> U1 +A2 --> U3 +A4 --> U3 +``` + +图表来源 + +- [alert.tsx:1-46](file://frontend/antd/alert/alert.tsx#L1-L46) +- [drawer.tsx:1-60](file://frontend/antd/drawer/drawer.tsx#L1-L60) +- [message.tsx:1-79](file://frontend/antd/message/message.tsx#L1-L79) +- [modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) +- [notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [popconfirm.tsx:1-65](file://frontend/antd/popconfirm/popconfirm.tsx#L1-L65) +- [progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) +- [skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +章节来源 + +- [alert.tsx:1-46](file://frontend/antd/alert/alert.tsx#L1-L46) +- [drawer.tsx:1-60](file://frontend/antd/drawer/drawer.tsx#L1-L60) +- [message.tsx:1-79](file://frontend/antd/message/message.tsx#L1-L79) +- [modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) +- [notification.tsx:1-106](file://frontend/antd/notification/notification.tsx#L1-L106) +- [popconfirm.tsx:1-65](file://frontend/antd/popconfirm/popconfirm.tsx#L1-L65) +- [progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) +- [skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [spin.tsx:1-38](file://frontend/antd/spin/spin.tsx#L1-L38) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +## 核心组件 + +- 统一封装：所有反馈组件均通过 sveltify 包裹原生 Ant Design 组件，保留其 API 并扩展插槽能力。 +- 插槽系统：使用 ReactSlot 渲染具名插槽（如 title、description、icon、footer 等），部分组件支持带参数的插槽渲染（renderParamsSlot）。 +- 回调适配：useFunction 将传入的函数包装为稳定引用，避免因每次渲染导致的副作用或重复订阅。 +- 目标选择：useTargets 用于从 children 中提取可投递的目标节点，支撑复杂布局与条件渲染。 +- 上下文持有：Message/Notification 通过 useMessage/useNotification 获取上下文持有器，实现全局消息与通知的挂载与销毁。 + +章节来源 + +- [alert.tsx:7-43](file://frontend/antd/alert/alert.tsx#L7-L43) +- [drawer.tsx:14-57](file://frontend/antd/drawer/drawer.tsx#L14-L57) +- [message.tsx:9-76](file://frontend/antd/message/message.tsx#L9-L76) +- [modal.tsx:8-104](file://frontend/antd/modal/modal.tsx#L8-L104) +- [notification.tsx:8-103](file://frontend/antd/notification/notification.tsx#L8-L103) +- [popconfirm.tsx:7-62](file://frontend/antd/popconfirm/popconfirm.tsx#L7-L62) +- [progress.tsx:5-21](file://frontend/antd/progress/progress.tsx#L5-L21) +- [result.tsx:7-30](file://frontend/antd/result/result.tsx#L7-L30) +- [skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) +- [spin.tsx:7-35](file://frontend/antd/spin/spin.tsx#L7-L35) +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [renderParamsSlot.tsx:5-50](file://frontend/utils/renderParamsSlot.tsx#L5-L50) + +## 架构总览 + +反馈组件的运行时架构围绕“属性透传 + 插槽渲染 + 回调适配”展开。对于需要全局挂载的组件（Message/Notification），通过 useMessage/useNotification 获取上下文持有器并在组件挂载时注入到 DOM；对于容器型组件（Drawer/Modal），通过 getContainer 或字符串选择器决定挂载目标；对于内容型组件（Alert/Result/Spin），通过插槽控制标题、描述、图标、额外内容等。 + +```mermaid +graph TB +C["应用层组件"] --> F1["useFunction
稳定函数引用"] +C --> F2["useTargets
解析插槽目标"] +C --> F3["renderParamsSlot
参数化插槽渲染"] +subgraph "全局反馈" +M["Message
useMessage"] --> D1["DOM 挂载点"] +N["Notification
useNotification"] --> D2["DOM 挂载点"] +end +subgraph "容器反馈" +DR["Drawer"] --> G1["getContainer / 字符串"] +MD["Modal"] --> G2["getContainer / 字符串"] +end +subgraph "内容反馈" +AL["Alert"] +RS["Result"] +SP["Spin"] +end +``` + +图表来源 + +- [message.tsx:30-33](file://frontend/antd/message/message.tsx#L30-L33) +- [notification.tsx:31-36](file://frontend/antd/notification/notification.tsx#L31-L36) +- [drawer.tsx:52-54](file://frontend/antd/drawer/drawer.tsx#L52-L54) +- [modal.tsx:96-98](file://frontend/antd/modal/modal.tsx#L96-L98) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [renderParamsSlot.tsx:5-50](file://frontend/utils/renderParamsSlot.tsx#L5-L50) + +## 组件详解 + +### 警告提示（Alert） + +- 触发机制：由业务状态变化或用户操作触发显示；可通过 closable 关闭并触发 afterClose 回调。 +- 显示时机：页面初始化后根据数据源决定是否展示；支持动态切换 message/description/icon/action 插槽。 +- 交互逻辑：点击关闭按钮触发动画收起，afterClose 回调可用于清理资源或跳转。 +- 动画与过渡：基于 Ant Design 内置动画；插槽内容可自定义图标与操作按钮。 +- 错误处理：当插槽内容为空时回退到 props 提供的内容；关闭后释放资源。 +- 无障碍与键盘：遵循 Ant Design 的默认可访问性；建议为关闭按钮提供明确的 ARIA 标签。 + +章节来源 + +- [alert.tsx:7-43](file://frontend/antd/alert/alert.tsx#L7-L43) + +### 抽屉（Drawer） + +- 触发机制：按钮点击或路由变化触发 visible；支持 afterOpenChange 控制打开/关闭后的状态。 +- 显示时机：首次打开时执行动画入场；关闭时执行动画离场。 +- 交互逻辑：支持自定义 closeIcon、extra、footer、title；closable.closeIcon 可替换默认关闭图标。 +- 动画与过渡：由 Ant Design 控制抽屉滑入/滑出动画；drawerRender 支持自定义渲染逻辑。 +- 错误处理：getContainer 为字符串时通过 useFunction 包装；异常时回退到默认容器。 +- 无障碍与键盘：保持原生焦点顺序；建议在 footer 中提供明确的操作按钮。 + +章节来源 + +- [drawer.tsx:8-57](file://frontend/antd/drawer/drawer.tsx#L8-L57) + +### 全局提示（Message） + +- 触发机制：通过 visible 属性控制显示/隐藏；内部使用 messageApi.open 打开消息。 +- 显示时机：effect 监听 visible=true 时打开消息；duration 到期或手动关闭后触发 onClose。 +- 交互逻辑：onVisible(false) 与 onClose 同步回调；支持 key 去重与 destroy。 +- 动画与过渡：由 Ant Design 内置动画；content/icon 插槽可自定义内容与图标。 +- 错误处理：effect 清理阶段调用 destroy；异常时保证只打开一次。 +- 无障碍与键盘：自动挂载到上下文持有器；建议提供可读性强的文本与简短描述。 + +章节来源 + +- [message.tsx:19-76](file://frontend/antd/message/message.tsx#L19-L76) + +### 对话框（Modal） + +- 触发机制：visible 控制显示；afterOpenChange/afterClose 管理打开/关闭后的生命周期。 +- 显示时机：首次打开时动画入场；关闭时动画离场。 +- 交互逻辑：ok/cancel 文案与图标均可通过插槽定制；footer 支持函数或默认值。 +- 动画与过渡：Ant Design 内置动画；modalRender 支持自定义渲染。 +- 错误处理：getContainer 为字符串时包装为函数；footer 为 DEFAULT_FOOTER 时回退为 undefined。 +- 无障碍与键盘：保持默认焦点与 ESC 关闭；建议提供明确的确认/取消语义。 + +章节来源 + +- [modal.tsx:22-104](file://frontend/antd/modal/modal.tsx#L22-L104) + +### 通知提醒框（Notification） + +- 触发机制：visible 控制显示；useNotification 返回的 open/destroy 控制消息生命周期。 +- 显示时机：effect 监听 visible=true 时打开；duration 到期或手动关闭后触发 onClose。 +- 交互逻辑：onVisible(false)/onClose 同步回调；支持 placement、stack、top/bottom 定位。 +- 动画与过渡：由 Ant Design 内置动画；支持 description/icon/actions/btn 插槽。 +- 错误处理：effect 清理阶段调用 destroy；异常时保证只打开一次。 +- 无障碍与键盘：建议提供可读性强的标题与描述；支持 hover 暂停与进度条。 + +章节来源 + +- [notification.tsx:18-103](file://frontend/antd/notification/notification.tsx#L18-L103) + +### 气泡确认框（Popconfirm） + +- 触发机制：用户点击触发气泡弹窗；afterOpenChange 管理弹窗打开状态。 +- 显示时机：点击目标元素后立即弹出；确认/取消后关闭。 +- 交互逻辑：ok/cancel 文案与图标均可通过插槽定制；title/description 支持 clone 渲染。 +- 动画与过渡：由 Ant Design 控制气泡动画；getPopupContainer 支持指定挂载容器。 +- 错误处理：插槽内容为空时回退到 props；异常时保持交互可用。 +- 无障碍与键盘：保持默认焦点与 ESC 关闭；建议提供明确的确认/取消语义。 + +章节来源 + +- [popconfirm.tsx:7-62](file://frontend/antd/popconfirm/popconfirm.tsx#L7-L62) + +### 进度条（Progress） + +- 触发机制：数值变化驱动进度更新；format 与 rounding 支持自定义格式化。 +- 显示时机：数值变化即刻反映；支持静态与动态两种模式。 +- 交互逻辑：format 与 rounding 通过 useFunction 包装为稳定引用。 +- 动画与过渡：由 Ant Design 内置动画；支持百分比、状态与自定义文案。 +- 错误处理：数值越界时由 Ant Design 处理；异常时保持组件稳定。 +- 无障碍与键盘：无交互输入；建议提供可读性强的文案。 + +章节来源 + +- [progress.tsx:5-21](file://frontend/antd/progress/progress.tsx#L5-L21) + +### 结果（Result） + +- 触发机制：业务结果完成后展示；支持 title/subTitle/icon/extra 插槽。 +- 显示时机：数据就绪后立即渲染；children 作为附加内容。 +- 交互逻辑：useTargets 解析插槽目标；无插槽时回退到 children。 +- 动画与过渡：由 Ant Design 内置动画；支持多种状态图标与文案。 +- 错误处理：插槽内容为空时回退到 props；异常时保持内容可见。 +- 无障碍与键盘：建议提供可读性强的标题与描述。 + +章节来源 + +- [result.tsx:7-30](file://frontend/antd/result/result.tsx#L7-L30) + +### 骨架屏（Skeleton） + +- 触发机制：数据加载前展示骨架；加载完成后切换真实内容。 +- 显示时机：组件挂载即刻显示；真实内容就绪后自动切换。 +- 交互逻辑：无交互；支持动画与形状配置。 +- 动画与过渡：由 Ant Design 内置骨架动画。 +- 错误处理：异常时保持骨架稳定；建议提供超时降级。 +- 无障碍与键盘：无交互；建议提供加载状态的 ARIA 提示。 + +章节来源 + +- [skeleton.tsx:1-7](file://frontend/antd/skeleton/skeleton.tsx#L1-L7) + +### 加载中（Spin） + +- 触发机制：异步任务开始时显示；任务结束时隐藏。 +- 显示时机：组件挂载即刻显示；children 为空时包裹真实内容。 +- 交互逻辑：useTargets 解析插槽目标；tip/indicator 支持插槽。 +- 动画与过渡：由 Ant Design 内置旋转动画；支持自定义指示器与提示文案。 +- 错误处理：插槽内容为空时回退到 props；异常时保持加载态。 +- 无障碍与键盘：建议提供 ARIA label 与 loading 状态提示。 + +章节来源 + +- [spin.tsx:7-35](file://frontend/antd/spin/spin.tsx#L7-L35) + +### 水印（Watermark） + +- 触发机制：页面加载后生成水印；支持动态更新文本与尺寸。 +- 显示时机：组件挂载即刻生效；适合全屏或局部水印。 +- 交互逻辑：无交互；支持多行文本与透明度配置。 +- 动画与过渡：无动画；适合背景装饰。 +- 错误处理：异常时保持水印稳定；建议提供降级方案。 +- 无障碍与键盘：无交互；不影响可访问性。 + +章节来源 + +- [watermark.tsx:1-6](file://frontend/antd/watermark/watermark.tsx#L1-L6) + +## 依赖关系分析 + +- 组件间耦合：反馈组件彼此独立，仅共享工具钩子；容器型组件共享 getContainer 与 renderParamsSlot；全局型组件共享上下文持有器。 +- 外部依赖：Ant Design 原生组件与样式；React Slot 渲染；Svelte Preprocess React 桥接。 +- 循环依赖：未发现循环依赖；工具钩子为纯函数式封装。 +- 接口契约：所有组件均通过 sveltify 保持与 Ant Design API 的兼容性；插槽键名与渲染策略一致。 + +```mermaid +graph LR +subgraph "工具层" +UF["useFunction"] +UT["useTargets"] +RPS["renderParamsSlot"] +end +subgraph "反馈组件" +MSG["Message"] +NOTI["Notification"] +MOD["Modal"] +DRW["Drawer"] +ALERT["Alert"] +POP["Popconfirm"] +PROG["Progress"] +RES["Result"] +SKEL["Skeleton"] +SPIN["Spin"] +WM["Watermark"] +end +UF --> MSG +UF --> NOTI +UF --> MOD +UF --> DRW +UF --> ALERT +UF --> POP +UF --> PROG +UT --> RES +UT --> SPIN +RPS --> MOD +RPS --> DRW +``` + +图表来源 + +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [renderParamsSlot.tsx:5-50](file://frontend/utils/renderParamsSlot.tsx#L5-L50) +- [message.tsx:29-33](file://frontend/antd/message/message.tsx#L29-L33) +- [notification.tsx:31-36](file://frontend/antd/notification/notification.tsx#L31-L36) +- [modal.tsx:34-35](file://frontend/antd/modal/modal.tsx#L34-L35) +- [drawer.tsx:27-28](file://frontend/antd/drawer/drawer.tsx#L27-L28) +- [alert.tsx:13-20](file://frontend/antd/alert/alert.tsx#L13-L20) +- [popconfirm.tsx:18-20](file://frontend/antd/popconfirm/popconfirm.tsx#L18-L20) +- [progress.tsx:10-12](file://frontend/antd/progress/progress.tsx#L10-L12) +- [result.tsx:11-12](file://frontend/antd/result/result.tsx#L11-L12) +- [spin.tsx:13-14](file://frontend/antd/spin/spin.tsx#L13-L14) + +章节来源 + +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [renderParamsSlot.tsx:5-50](file://frontend/utils/renderParamsSlot.tsx#L5-L50) +- [message.tsx:29-33](file://frontend/antd/message/message.tsx#L29-L33) +- [notification.tsx:31-36](file://frontend/antd/notification/notification.tsx#L31-L36) +- [modal.tsx:34-35](file://frontend/antd/modal/modal.tsx#L34-L35) +- [drawer.tsx:27-28](file://frontend/antd/drawer/drawer.tsx#L27-L28) +- [alert.tsx:13-20](file://frontend/antd/alert/alert.tsx#L13-L20) +- [popconfirm.tsx:18-20](file://frontend/antd/popconfirm/popconfirm.tsx#L18-L20) +- [progress.tsx:10-12](file://frontend/antd/progress/progress.tsx#L10-L12) +- [result.tsx:11-12](file://frontend/antd/result/result.tsx#L11-L12) +- [spin.tsx:13-14](file://frontend/antd/spin/spin.tsx#L13-L14) + +## 性能考量 + +- 函数引用稳定化：useFunction 将回调包装为 useMemo 引用，减少不必要的重渲染与副作用。 +- 插槽渲染优化：ReactSlot 与 renderParamsSlot 仅在必要时克隆与渲染，避免全量重排。 +- 生命周期管理：Message/Notification 在 effect 清理阶段主动 destroy，防止内存泄漏。 +- 容器挂载：Drawer/Modal 的 getContainer 为字符串时通过包装函数避免重复绑定。 +- 条件渲染：Spin/Result 使用 useTargets 与条件分支，仅在有插槽时渲染真实内容，降低 DOM 开销。 + +## 故障排查指南 + +- 插槽不生效 + - 检查插槽键名是否与组件声明一致；确认 ReactSlot 是否正确包裹。 + - 参考路径：[alert.tsx:17-40](file://frontend/antd/alert/alert.tsx#L17-L40)、[result.tsx:17-27](file://frontend/antd/result/result.tsx#L17-L27)、[spin.tsx:20-32](file://frontend/antd/spin/spin.tsx#L20-L32) +- 回调未触发或重复触发 + - 使用 useFunction 包装回调，确保引用稳定；检查 effect 依赖数组。 + - 参考路径：[message.tsx:35-68](file://frontend/antd/message/message.tsx#L35-L68)、[notification.tsx:38-95](file://frontend/antd/notification/notification.tsx#L38-L95) +- 全局消息未显示 + - 确认上下文持有器已渲染；visible 与 key 配置正确；duration 设置合理。 + - 参考路径：[message.tsx:30-33](file://frontend/antd/message/message.tsx#L30-L33)、[notification.tsx:31-36](file://frontend/antd/notification/notification.tsx#L31-L36) +- 容器挂载异常 + - getContainer 为字符串时需确保包装为函数；检查选择器有效性。 + - 参考路径：[drawer.tsx:52-54](file://frontend/antd/drawer/drawer.tsx#L52-L54)、[modal.tsx:96-98](file://frontend/antd/modal/modal.tsx#L96-L98) +- 动画卡顿或闪烁 + - 检查插槽内容是否频繁变更；避免在动画期间进行大量 DOM 操作。 + - 参考路径：[progress.tsx:10-12](file://frontend/antd/progress/progress.tsx#L10-L12)、[spin.tsx:13-14](file://frontend/antd/spin/spin.tsx#L13-L14) + +章节来源 + +- [alert.tsx:17-40](file://frontend/antd/alert/alert.tsx#L17-L40) +- [result.tsx:17-27](file://frontend/antd/result/result.tsx#L17-L27) +- [spin.tsx:20-32](file://frontend/antd/spin/spin.tsx#L20-L32) +- [message.tsx:30-33](file://frontend/antd/message/message.tsx#L30-L33) +- [notification.tsx:31-36](file://frontend/antd/notification/notification.tsx#L31-L36) +- [drawer.tsx:52-54](file://frontend/antd/drawer/drawer.tsx#L52-L54) +- [modal.tsx:96-98](file://frontend/antd/modal/modal.tsx#L96-L98) +- [progress.tsx:10-12](file://frontend/antd/progress/progress.tsx#L10-L12) + +## 结论 + +本仓库对 Ant Design 反馈组件进行了系统化的封装，统一了插槽渲染、回调适配与生命周期管理。通过稳定的函数引用、条件渲染与上下文持有器，实现了高可用、可维护的反馈体系。建议在实际项目中结合业务场景选择合适的组件与触发策略，并关注无障碍与性能细节。 + +## 附录 + +- 最佳实践 + - 使用 visible 与 key 管理全局消息的唯一性与生命周期。 + - 为重要操作提供明确的确认/取消语义与键盘支持。 + - 在复杂布局中优先使用 renderParamsSlot 与 useTargets 管理插槽目标。 + - 为加载态与错误态提供清晰的文案与视觉提示。 +- 复杂交互场景 + - 多步骤流程：使用 Result 展示最终状态；Progress 展示进度；Spin 包裹关键区域。 + - 全局通知：Notification 放置在右上角或右下角，支持堆叠与暂停。 + - 模态确认：Modal/Popconfirm 用于关键删除与危险操作，提供二次确认。 + - 抽屉导航：Drawer 作为二级面板承载长列表或设置页，注意 getContainer 与层级管理。 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\346\250\241\346\200\201\345\257\271\350\257\235\346\241\206\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\346\250\241\346\200\201\345\257\271\350\257\235\346\241\206\347\273\204\344\273\266.md" new file mode 100644 index 00000000..9c9b5c99 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\346\250\241\346\200\201\345\257\271\350\257\235\346\241\206\347\273\204\344\273\266.md" @@ -0,0 +1,322 @@ +# 模态对话框组件 + + +**本文引用的文件** +- [frontend/antd/modal/modal.tsx](file://frontend/antd/modal/modal.tsx) +- [frontend/antd/modal/static/modal.static.tsx](file://frontend/antd/modal/static/modal.static.tsx) +- [backend/modelscope_studio/components/antd/modal/__init__.py](file://backend/modelscope_studio/components/antd/modal/__init__.py) +- [backend/modelscope_studio/components/antd/modal/static/__init__.py](file://backend/modelscope_studio/components/antd/modal/static/__init__.py) +- [frontend/antd/modal/static/Index.svelte](file://frontend/antd/modal/static/Index.svelte) +- [docs/components/antd/modal/README.md](file://docs/components/antd/modal/README.md) +- [docs/components/antd/modal/demos/basic.py](file://docs/components/antd/modal/demos/basic.py) +- [docs/components/antd/modal/demos/custom_footer.py](file://docs/components/antd/modal/demos/custom_footer.py) +- [docs/components/antd/modal/demos/static.py](file://docs/components/antd/modal/demos/static.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能与动画](#性能与动画) +8. [无障碍与键盘交互](#无障碍与键盘交互) +9. [故障排查](#故障排查) +10. [结论](#结论) +11. [附录：常用场景示例](#附录常用场景示例) + +## 简介 + +本文件系统性梳理“模态对话框”组件群组，覆盖普通模态对话框（Modal）与静态模态对话框（Static Modal）的设计原理、使用场景、层级管理、焦点控制、键盘交互、事件与样式定制、动画与过渡、性能优化以及无障碍支持。文档同时提供基于仓库示例的实践指引，帮助开发者在 Gradio/ModelScope 生态中高效集成与扩展。 + +## 项目结构 + +该组件位于前端 Ant Design 包装层与后端 Python 组件桥接层之间，采用“前端 Svelte + React Slot + 后端 LayoutComponent”的分层设计： + +- 前端层：通过 sveltify 将 Ant Design 的 Modal 包装为可插槽组件；静态模态通过 useModal API 动态渲染。 +- 后端层：Python 组件封装 AntdModal/AntdModalStatic，暴露统一的属性与事件接口，并声明支持的插槽。 +- 文档与示例：提供基础、自定义页脚、静态调用三类示例，便于快速上手。 + +```mermaid +graph TB +subgraph "后端" +PY_API["AntdModal
AntdModalStatic"] +end +subgraph "前端" +F_Svelte["Index.svelte
静态包装器"] +F_Modal["Modal.tsx
普通对话框"] +F_Static["ModalStatic.tsx
静态对话框"] +end +subgraph "第三方" +AntD["Ant Design Modal"] +end +PY_API --> F_Svelte +F_Svelte --> F_Modal +F_Svelte --> F_Static +F_Modal --> AntD +F_Static --> AntD +``` + +图表来源 + +- [frontend/antd/modal/modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) +- [frontend/antd/modal/static/modal.static.tsx:1-132](file://frontend/antd/modal/static/modal.static.tsx#L1-L132) +- [frontend/antd/modal/static/Index.svelte:1-69](file://frontend/antd/modal/static/Index.svelte#L1-L69) +- [backend/modelscope_studio/components/antd/modal/**init**.py:1-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L1-L136) +- [backend/modelscope_studio/components/antd/modal/static/**init**.py:1-133](file://backend/modelscope_studio/components/antd/modal/static/__init__.py#L1-L133) + +章节来源 + +- [docs/components/antd/modal/README.md:1-13](file://docs/components/antd/modal/README.md#L1-L13) + +## 核心组件 + +- 普通模态对话框（AntdModal） + - 设计定位：以组件形式直接渲染，适合需要在布局树中显式管理生命周期与层级的场景。 + - 关键能力：支持插槽化标题、页脚、按钮图标与文本、关闭图标、自定义渲染器、容器挂载点、键盘与遮罩行为等。 +- 静态模态对话框（AntdModalStatic） + - 设计定位：通过 useModal 动态触发，无需在布局树中声明，适合消息提示、确认流程等一次性弹窗。 + - 关键能力：支持 info/success/error/warning/confirm 类型，自动聚焦按钮、可见性受控、onOk/onCancel 回调联动。 + +章节来源 + +- [backend/modelscope_studio/components/antd/modal/**init**.py:11-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L11-L136) +- [backend/modelscope_studio/components/antd/modal/static/**init**.py:10-133](file://backend/modelscope_studio/components/antd/modal/static/__init__.py#L10-L133) + +## 架构总览 + +下图展示从用户触发到对话框呈现的关键调用链路，包括普通与静态两种模式： + +```mermaid +sequenceDiagram +participant U as "用户" +participant PY as "后端组件(AntdModal/Static)" +participant FE as "前端包装(Index.svelte)" +participant MOD as "Modal/ModalStatic" +participant ANT as "Ant Design Modal" +U->>PY : 触发显示(如点击按钮) +PY->>FE : 传递属性与可见性 +alt 普通模式 +FE->>MOD : 渲染 Modal 组件 +MOD->>ANT : 渲染普通对话框 +else 静态模式 +FE->>MOD : 传入 visible/type 等 +MOD->>ANT : 调用 useModal(type) 创建实例 +end +ANT-->>U : 展示对话框并响应交互 +``` + +图表来源 + +- [frontend/antd/modal/static/Index.svelte:54-68](file://frontend/antd/modal/static/Index.svelte#L54-L68) +- [frontend/antd/modal/modal.tsx:36-102](file://frontend/antd/modal/modal.tsx#L36-L102) +- [frontend/antd/modal/static/modal.static.tsx:46-128](file://frontend/antd/modal/static/modal.static.tsx#L46-L128) + +## 组件详解 + +### 普通模态对话框（Modal） + +- 插槽与属性映射 + - 支持插槽：okText、okButtonProps.icon、cancelText、cancelButtonProps.icon、closable.closeIcon、closeIcon、footer、title、modalRender。 + - 属性透传：afterOpenChange、afterClose、getContainer、keyboard、mask、maskClosable、width、zIndex、wrapClassName 等。 +- 事件绑定 + - 通过事件监听器绑定 ok/cancel 事件，用于触发回调或更新可见性。 +- 容器挂载与层级 + - 可通过 getContainer 指定挂载节点，避免层级被局部容器遮挡；默认挂载至 body。 +- 焦点与键盘 + - keyboard 控制是否允许 Esc 关闭；可通过 autoFocusButton 等属性影响初始焦点。 +- 自定义渲染 + - modalRender 可替换整块渲染逻辑；footer 支持函数式插槽，实现复杂页脚布局。 + +```mermaid +flowchart TD +Start(["进入渲染"]) --> CheckSlots["检查插槽是否存在"] +CheckSlots --> |存在| RenderSlot["渲染插槽内容"] +CheckSlots --> |不存在| UseProp["使用属性值"] +RenderSlot --> Combine["合并到最终 props"] +UseProp --> Combine +Combine --> Mount["挂载到目标容器"] +Mount --> Focus["根据配置设置焦点/键盘行为"] +Focus --> End(["完成"]) +``` + +图表来源 + +- [frontend/antd/modal/modal.tsx:36-99](file://frontend/antd/modal/modal.tsx#L36-L99) + +章节来源 + +- [frontend/antd/modal/modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) +- [backend/modelscope_studio/components/antd/modal/**init**.py:18-32](file://backend/modelscope_studio/components/antd/modal/__init__.py#L18-L32) + +### 静态模态对话框（ModalStatic） + +- 动态创建与销毁 + - 通过 useModal 获取 API；当 visible 为真时创建对应类型实例，否则销毁当前实例。 + - 默认禁用自动聚焦按钮，除非显式传入。 +- 事件与可见性联动 + - onOk/onCancel 内部会同步触发 onVisible(false)，实现“确认/取消即关闭”的一致行为。 +- 插槽与属性 + - 支持 title、content、footer、okText、okButtonProps.icon、cancelText、cancelButtonProps.icon、closable.closeIcon、closeIcon、modalRender 等。 +- 使用限制 + - 不在布局树中声明，仅通过 visible/type 等属性驱动；适合一次性提示与确认流程。 + +```mermaid +sequenceDiagram +participant C as "调用方" +participant MS as "ModalStatic" +participant API as "useModal" +participant D as "对话框实例" +C->>MS : visible=true, type=info/success/... +MS->>API : 调用对应类型方法(type) +API-->>MS : 返回实例引用 +MS->>D : 渲染并应用插槽/属性 +D-->>MS : 用户操作(确认/取消) +MS->>C : 触发 onVisible(false) +MS->>API : 销毁实例 +``` + +图表来源 + +- [frontend/antd/modal/static/modal.static.tsx:46-128](file://frontend/antd/modal/static/modal.static.tsx#L46-L128) + +章节来源 + +- [frontend/antd/modal/static/modal.static.tsx:1-132](file://frontend/antd/modal/static/modal.static.tsx#L1-L132) +- [backend/modelscope_studio/components/antd/modal/static/**init**.py:14-28](file://backend/modelscope_studio/components/antd/modal/static/__init__.py#L14-L28) + +### 组件关系与继承 + +- 后端组件类 AntdModal 与 AntdModalStatic 均继承自 ModelScopeLayoutComponent，统一了事件、插槽、属性与生命周期处理。 +- 前端 Index.svelte 作为动态加载入口，负责将 props 与 slots 传递给 Modal 或 ModalStatic。 + +```mermaid +classDiagram +class ModelScopeLayoutComponent +class AntdModal { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class AntdModalStatic { ++EVENTS ++SLOTS ++FRONTEND_DIR +} +class Modal_tsx +class ModalStatic_tsx +class Index_svelte +ModelScopeLayoutComponent <|-- AntdModal +ModelScopeLayoutComponent <|-- AntdModalStatic +Index_svelte --> Modal_tsx : "渲染普通" +Index_svelte --> ModalStatic_tsx : "渲染静态" +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/modal/**init**.py:11-16](file://backend/modelscope_studio/components/antd/modal/__init__.py#L11-L16) +- [backend/modelscope_studio/components/antd/modal/static/**init**.py:10-13](file://backend/modelscope_studio/components/antd/modal/static/__init__.py#L10-L13) +- [frontend/antd/modal/static/Index.svelte:10-68](file://frontend/antd/modal/static/Index.svelte#L10-L68) + +## 依赖关系分析 + +- 前端依赖 + - sveltify：将 React 组件桥接到 Svelte。 + - useFunction：将回调函数稳定化，避免重复渲染导致的副作用。 + - renderParamsSlot：支持带参数的插槽渲染。 + - Ant Design Modal：核心 UI 行为与样式。 +- 后端依赖 + - Gradio 事件系统：通过事件监听器绑定 ok/cancel。 + - 组件基类 ModelScopeLayoutComponent：统一生命周期与属性处理。 + +```mermaid +graph LR +A["Modal.tsx"] --> B["Ant Design Modal"] +C["ModalStatic.tsx"] --> B +D["Index.svelte"] --> A +D --> C +E["AntdModal"] --> D +F["AntdModalStatic"] --> D +``` + +图表来源 + +- [frontend/antd/modal/modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) +- [frontend/antd/modal/static/modal.static.tsx:1-132](file://frontend/antd/modal/static/modal.static.tsx#L1-L132) +- [frontend/antd/modal/static/Index.svelte:1-69](file://frontend/antd/modal/static/Index.svelte#L1-L69) +- [backend/modelscope_studio/components/antd/modal/**init**.py:1-136](file://backend/modelscope_studio/components/antd/modal/__init__.py#L1-L136) +- [backend/modelscope_studio/components/antd/modal/static/**init**.py:1-133](file://backend/modelscope_studio/components/antd/modal/static/__init__.py#L1-L133) + +## 性能与动画 + +- 渲染策略 + - 普通模式：按需渲染，open=false 时可配合 destroyOnClose/destroyOnHidden 减少内存占用。 + - 静态模式：visible 切换时动态创建/销毁实例，避免常驻 DOM。 +- 动画与过渡 + - 由 Ant Design Modal 提供开合动画与遮罩过渡；可通过 width、zIndex、wrapClassName 等调整视觉层级与尺寸。 +- 性能建议 + - 大量弹窗场景优先使用静态模式，减少布局树节点数量。 + - 对频繁切换的弹窗，合理设置 getContainer，避免不必要的重排。 + - 使用 modalRender 自定义渲染时，尽量减少深层嵌套与昂贵计算。 + +[本节为通用指导，不直接分析具体文件] + +## 无障碍与键盘交互 + +- 键盘交互 + - keyboard 控制是否允许 Esc 关闭；maskClosable 控制点击遮罩是否关闭。 + - 静态模式默认禁用自动聚焦按钮，避免打断用户操作；可通过 autoFocusButton 显式指定。 +- 焦点管理 + - 打开后应将焦点移至首个交互元素（如确认按钮），关闭后返回触发源（focusTriggerAfterClose）。 +- 屏幕阅读器 + - 提供清晰的标题与内容；必要时通过 aria-\* 属性补充语义。 + - 避免在 modalRender 中使用仅有颜色区分的提示，确保文本可读。 + +[本节为通用指导，不直接分析具体文件] + +## 故障排查 + +- 问题：弹窗未显示 + - 检查 visible/open 是否正确传入；静态模式需确保 visible 从 false 切换为 true。 + - 确认 getContainer 指向有效节点，避免被父级裁剪。 +- 问题：点击遮罩无法关闭 + - 检查 maskClosable 与 keyboard 设置；确认未被外部事件拦截。 +- 问题：静态弹窗不消失 + - 确保 onOk/onCancel 回调中调用了 onVisible(false)；或直接将 visible 更新为 false。 +- 问题：插槽不生效 + - 确认插槽名称与组件支持列表一致；普通模式使用 slots，静态模式使用 visible/type 驱动。 + +章节来源 + +- [frontend/antd/modal/static/modal.static.tsx:107-114](file://frontend/antd/modal/static/modal.static.tsx#L107-L114) +- [backend/modelscope_studio/components/antd/modal/**init**.py:18-32](file://backend/modelscope_studio/components/antd/modal/__init__.py#L18-L32) + +## 结论 + +- 普通模态对话框适合需要在布局树中精细控制生命周期与层级的场景；静态模态对话框适合一次性提示与确认流程。 +- 通过插槽与属性的灵活组合，可实现丰富的交互与样式定制；结合 useModal 与事件系统，可构建一致的用户体验。 +- 在性能与无障碍方面，建议优先选择静态模式处理高频弹窗，合理设置焦点与键盘行为，并确保内容对屏幕阅读器友好。 + +[本节为总结性内容，不直接分析具体文件] + +## 附录：常用场景示例 + +以下示例来自仓库文档与演示，展示不同使用方式与典型场景。 + +- 基础弹窗 + - 场景：打开/关闭、确认/取消。 + - 示例路径：[docs/components/antd/modal/demos/basic.py:1-19](file://docs/components/antd/modal/demos/basic.py#L1-L19) +- 自定义页脚 + - 场景：自定义底部按钮、链接跳转、组合交互。 + - 示例路径：[docs/components/antd/modal/demos/custom_footer.py:1-31](file://docs/components/antd/modal/demos/custom_footer.py#L1-L31) +- 静态弹窗（信息/成功/错误/警告/确认） + - 场景：消息提示、确认对话框。 + - 示例路径：[docs/components/antd/modal/demos/static.py:1-74](file://docs/components/antd/modal/demos/static.py#L1-L74) + +章节来源 + +- [docs/components/antd/modal/demos/basic.py:1-19](file://docs/components/antd/modal/demos/basic.py#L1-L19) +- [docs/components/antd/modal/demos/custom_footer.py:1-31](file://docs/components/antd/modal/demos/custom_footer.py#L1-L31) +- [docs/components/antd/modal/demos/static.py:1-74](file://docs/components/antd/modal/demos/static.py#L1-L74) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\346\266\210\346\201\257\351\200\232\347\237\245\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\346\266\210\346\201\257\351\200\232\347\237\245\347\273\204\344\273\266.md" new file mode 100644 index 00000000..319d837d --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\346\266\210\346\201\257\351\200\232\347\237\245\347\273\204\344\273\266.md" @@ -0,0 +1,332 @@ +# 消息通知组件 + + +**本文引用的文件** +- [frontend/antd/message/message.tsx](file://frontend/antd/message/message.tsx) +- [frontend/antd/notification/notification.tsx](file://frontend/antd/notification/notification.tsx) +- [frontend/antd/message/Index.svelte](file://frontend/antd/message/Index.svelte) +- [frontend/antd/notification/Index.svelte](file://frontend/antd/notification/Index.svelte) +- [backend/modelscope_studio/components/antd/message/__init__.py](file://backend/modelscope_studio/components/antd/message/__init__.py) +- [backend/modelscope_studio/components/antd/notification/__init__.py](file://backend/modelscope_studio/components/antd/notification/__init__.py) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/antd/message/package.json](file://frontend/antd/message/package.json) +- [frontend/antd/notification/package.json](file://frontend/antd/notification/package.json) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能与内存管理](#性能与内存管理) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：使用示例与最佳实践](#附录使用示例与最佳实践) + +## 简介 + +本文件系统性梳理消息通知组件群组，聚焦两类全局反馈组件：全局提示（Message）与通知提醒框（Notification）。文档从设计理念、使用场景、差异对比、配置项与动态行为、生命周期与内存清理、到无障碍与体验优化进行完整说明，并提供可直接定位到源码的路径指引，帮助开发者快速上手并正确使用。 + +## 项目结构 + +消息通知组件由“后端 Python 组件 + 前端 Svelte 包装 + React/antd 实现”三层构成： + +- 后端组件负责参数校验、事件绑定、渲染控制与前端包导出声明； +- 前端 Svelte 层负责属性透传、插槽（slots）映射与可见性状态同步； +- React 层基于 antd 的 message/notification API 实现具体的消息弹出、堆叠与销毁逻辑。 + +```mermaid +graph TB +subgraph "后端" +PY_MSG["AntdMessage
Python 组件"] +PY_NOTI["AntdNotification
Python 组件"] +end +subgraph "前端 Svelte" +SV_MSG["message/Index.svelte"] +SV_NOTI["notification/Index.svelte"] +end +subgraph "React/antd" +TSX_MSG["message.tsx
useMessage 驱动"] +TSX_NOTI["notification.tsx
useNotification 驱动"] +end +PY_MSG --> SV_MSG --> TSX_MSG +PY_NOTI --> SV_NOTI --> TSX_NOTI +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/message/**init**.py:10-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L10-L91) +- [backend/modelscope_studio/components/antd/notification/**init**.py:10-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L10-L109) +- [frontend/antd/message/Index.svelte:10-78](file://frontend/antd/message/Index.svelte#L10-L78) +- [frontend/antd/notification/Index.svelte:10-80](file://frontend/antd/notification/Index.svelte#L10-L80) +- [frontend/antd/message/message.tsx:9-79](file://frontend/antd/message/message.tsx#L9-L79) +- [frontend/antd/notification/notification.tsx:8-106](file://frontend/antd/notification/notification.tsx#L8-L106) + +章节来源 + +- [frontend/antd/message/package.json:1-15](file://frontend/antd/message/package.json#L1-L15) +- [frontend/antd/notification/package.json:1-15](file://frontend/antd/notification/package.json#L1-L15) + +## 核心组件 + +- 全局提示（Message） + - 设计目标：对用户操作给出即时、简洁的反馈，常用于提交成功、失败、警告或加载提示。 + - 关键特性：轻量、无遮罩、自动消失、可配置时长、可按 key 控制唯一性与覆盖。 +- 通知提醒框（Notification） + - 设计目标：在页面角落区域弹出较丰富的内容，适合需要携带标题、描述、按钮、动作等的提醒。 + - 关键特性：支持多位置放置（top/bottom/left/right）、堆叠管理、进度条、悬停暂停、可自定义按钮与动作。 + +章节来源 + +- [backend/modelscope_studio/components/antd/message/**init**.py:10-91](file://backend/modelscope_studio/components/antd/message/__init__.py#L10-L91) +- [backend/modelscope_studio/components/antd/notification/**init**.py:10-109](file://backend/modelscope_studio/components/antd/notification/__init__.py#L10-L109) + +## 架构总览 + +消息组件的调用链路如下：后端组件实例化 → 前端 Svelte 渲染 → React/antd 执行 open/destroy → 生命周期回调触发状态回传。 + +```mermaid +sequenceDiagram +participant Py as "后端组件" +participant S as "Svelte 包装" +participant R as "React/antd" +participant UI as "浏览器界面" +Py->>S : 传递属性与插槽 +S->>R : 透传 props 与 slots +R->>R : useMessage/useNotification 初始化 +alt 可见且打开 +R->>UI : open({key, content, duration, ...}) +else 关闭或销毁 +R->>UI : destroy(key) +end +UI-->>R : 用户交互点击/关闭 +R-->>S : 触发 onVisible(false) 回调 +S-->>Py : 更新 visible 状态 +``` + +图表来源 + +- [frontend/antd/message/message.tsx:30-68](file://frontend/antd/message/message.tsx#L30-L68) +- [frontend/antd/notification/notification.tsx:31-95](file://frontend/antd/notification/notification.tsx#L31-L95) +- [frontend/antd/message/Index.svelte:58-77](file://frontend/antd/message/Index.svelte#L58-L77) +- [frontend/antd/notification/Index.svelte:59-79](file://frontend/antd/notification/Index.svelte#L59-L79) + +## 详细组件分析 + +### 全局提示（Message）组件 + +- 职责与行为 + - 基于 antd 的 message.useMessage 提供全局提示能力； + - 支持通过 visible 控制是否打开，messageKey 控制唯一性； + - 支持 slots.content 与 slots.icon 自定义内容与图标； + - 关闭时触发 onVisible(false)，并在组件卸载时销毁对应 key。 +- 关键配置项（节选） + - 内容与类型：content、type（success/info/warning/error/loading） + - 显示时长：duration（秒） + - 容器挂载点：getContainer（函数） + - 文案与样式：className、style、rootClassName + - 键值与可见性：messageKey、visible +- 动态更新与批量 + - 通过 messageKey 实现同一位置的覆盖与更新； + - 多个消息可同时存在，互不干扰； + - 使用 destroy(key) 或 destroyAll() 进行批量清理。 +- 生命周期与内存 + - 打开时注册；关闭/卸载时销毁；避免残留 DOM 与事件监听。 + +```mermaid +flowchart TD +Start(["进入 Effect"]) --> CheckVisible{"visible 为真？"} +CheckVisible -- 否 --> Destroy["destroy(key) 并返回"] +CheckVisible -- 是 --> Open["messageApi.open({...})"] +Open --> OnClose["onClose 回调中触发 onVisible(false)"] +OnClose --> End(["结束"]) +Destroy --> End +``` + +图表来源 + +- [frontend/antd/message/message.tsx:35-68](file://frontend/antd/message/message.tsx#L35-L68) + +章节来源 + +- [frontend/antd/message/message.tsx:9-79](file://frontend/antd/message/message.tsx#L9-L79) +- [frontend/antd/message/Index.svelte:19-77](file://frontend/antd/message/Index.svelte#L19-L77) +- [backend/modelscope_studio/components/antd/message/**init**.py:26-72](file://backend/modelscope_studio/components/antd/message/__init__.py#L26-L72) + +### 通知提醒框（Notification）组件 + +- 职责与行为 + - 基于 antd 的 notification.useNotification 提供全局通知能力； + - 支持多位置（top/bottom/left/right 及其组合）与堆叠管理； + - 支持 slots.message/description/icon/actions/btn/closeIcon 等丰富插槽； + - 关闭时触发 onVisible(false)，并在卸载时销毁对应 key。 +- 关键配置项（节选） + - 位置与堆叠：placement、stack、top、bottom、rtl + - 内容与交互：message、description、btn、actions、closeIcon、icon + - 行为与体验：duration、showProgress、pauseOnHover、role（alert/status） + - 键值与可见性：notificationKey、visible +- 动态更新与批量 + - 通过 notificationKey 实现同一通知的覆盖； + - 支持 destroyAll() 进行批量清理； + - 堆叠模式下可控制新旧通知的排列与覆盖策略。 +- 生命周期与内存 + - 打开时注册；关闭/卸载时销毁；避免内存泄漏。 + +```mermaid +sequenceDiagram +participant S as "Svelte 包装" +participant R as "React/antd" +participant N as "notificationApi" +participant U as "用户" +S->>R : visible=true 且传入 props +R->>N : open({key, message, description, actions, ...}) +U-->>N : 点击/关闭 +N-->>R : onClose 回调 +R-->>S : onVisible(false) +S-->>S : updateProps({visible : false}) +R->>N : destroy(key) 或 destroyAll() +``` + +图表来源 + +- [frontend/antd/notification/notification.tsx:38-95](file://frontend/antd/notification/notification.tsx#L38-L95) +- [frontend/antd/notification/Index.svelte:59-79](file://frontend/antd/notification/Index.svelte#L59-L79) + +章节来源 + +- [frontend/antd/notification/notification.tsx:8-106](file://frontend/antd/notification/notification.tsx#L8-L106) +- [frontend/antd/notification/Index.svelte:19-79](file://frontend/antd/notification/Index.svelte#L19-L79) +- [backend/modelscope_studio/components/antd/notification/**init**.py:26-90](file://backend/modelscope_studio/components/antd/notification/__init__.py#L26-L90) + +### 两者的区别与适用场景 + +- 适用场景 + - Message：轻量反馈、短文本提示、无需复杂交互； + - Notification：需要标题/描述/按钮/动作、多位置展示、强调重要信息。 +- 显示位置与堆叠 + - Message：默认在容器内顶部或指定容器出现，不支持多位置； + - Notification：支持 top/bottom/left/right 及组合，具备堆叠管理与进度条。 +- 交互与可访问性 + - Notification：支持 role（alert/status），便于屏幕阅读器识别； + - Message：更偏向一次性提示，交互较少。 +- 动态与批量 + - 两者均支持 key 唯一性与覆盖；Notification 更易实现批量清理与堆叠策略。 + +章节来源 + +- [backend/modelscope_studio/components/antd/message/**init**.py:26-72](file://backend/modelscope_studio/components/antd/message/__init__.py#L26-L72) +- [backend/modelscope_studio/components/antd/notification/**init**.py:26-90](file://backend/modelscope_studio/components/antd/notification/__init__.py#L26-L90) + +## 依赖关系分析 + +- 组件导出与入口 + - message/notification 均通过 package.json 暴露 Gradio 兼容入口； +- 前端桥接 + - Svelte 包装负责属性与插槽透传、visible 状态回写； + - React 层通过 useFunction 将 getContainer 等函数安全注入 antd API； +- 事件与插槽 + - 后端声明事件 click/close，Svelte 侧通过 \_internal 标志绑定； + - 插槽映射：Message(content/icon)、Notification(actions/btn/closeIcon/description/icon/message/title)。 + +```mermaid +graph LR +PkgMsg["message/package.json"] --> SMsg["message/Index.svelte"] +PkgNoti["notification/package.json"] --> SNoti["notification/Index.svelte"] +SMsg --> TMsg["message.tsx"] +SNoti --> TNoti["notification.tsx"] +TMsg --> Hook["useFunction.ts"] +TNoti --> Hook +``` + +图表来源 + +- [frontend/antd/message/package.json:1-15](file://frontend/antd/message/package.json#L1-L15) +- [frontend/antd/notification/package.json:1-15](file://frontend/antd/notification/package.json#L1-L15) +- [frontend/antd/message/Index.svelte:10](file://frontend/antd/message/Index.svelte#L10) +- [frontend/antd/notification/Index.svelte:10](file://frontend/antd/notification/Index.svelte#L10) +- [frontend/antd/message/message.tsx:29](file://frontend/antd/message/message.tsx#L29) +- [frontend/antd/notification/notification.tsx:31](file://frontend/antd/notification/notification.tsx#L31) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) + +章节来源 + +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) + +## 性能与内存管理 + +- 性能特征 + - Message：轻量、无遮罩、DOM 数量少，适合高频提示； + - Notification：支持堆叠与进度条，视觉反馈更强但 DOM 数量可能增加。 +- 内存清理策略 + - 关闭与卸载时统一调用 destroy(key)/destroyAll()； + - 通过 key 精准控制资源回收，避免重复渲染与事件累积； + - 使用 getContainer 将消息挂载到最小必要容器，减少重排与重绘。 +- 最佳实践 + - 为每个独立消息设置唯一 key； + - 合理设置 duration，避免过多消息长期驻留； + - 在批量操作中使用 destroyAll() 清理过期消息； + - 对于频繁触发的操作，优先使用 Message，必要时再引入 Notification。 + +章节来源 + +- [frontend/antd/message/message.tsx:51-58](file://frontend/antd/message/message.tsx#L51-L58) +- [frontend/antd/notification/notification.tsx:74-77](file://frontend/antd/notification/notification.tsx#L74-L77) + +## 故障排查指南 + +- 常见问题 + - 消息未显示：检查 visible 是否为 true，以及 messageKey 是否正确传入； + - 无法关闭：确认 onClose 回调是否被覆盖，确保 onVisible 回调链路正常； + - 重复消息：为每个消息设置唯一 key，避免被后续 open 覆盖； + - 位置异常：确认 getContainer 返回的挂载节点存在且可见。 +- 排查步骤 + - 在 Svelte 层打印 props 与 visible 状态； + - 在 React 层确认 messageApi/notificationApi 已初始化； + - 使用 destroyAll() 快速清场，验证是否仍残留 DOM； + - 检查 getContainer 函数是否稳定返回同一节点。 + +章节来源 + +- [frontend/antd/message/message.tsx:35-68](file://frontend/antd/message/message.tsx#L35-L68) +- [frontend/antd/notification/notification.tsx:38-95](file://frontend/antd/notification/notification.tsx#L38-L95) + +## 结论 + +消息通知组件群组以“后端参数 + 前端桥接 + React/antd 驱动”的分层设计实现了高可用、可扩展的全局反馈能力。Message 适合轻量提示，Notification 适合丰富通知。通过合理的 key 策略、时长配置与销毁机制，可在保证体验的同时维持良好的性能与内存健康。 + +## 附录：使用示例与最佳实践 + +- 成功提示（Message） + - 设置 type 为 success，duration 为合适时长，messageKey 唯一化； + - 通过 visible 切换显示，onClose 同步 visible 状态。 + - 示例路径参考：[frontend/antd/message/message.tsx:35-50](file://frontend/antd/message/message.tsx#L35-L50) +- 错误警告（Notification） + - 设置 type 为 error，message/description 丰富内容，actions 提供操作； + - 使用 destroyAll() 清理历史错误消息，避免堆积。 + - 示例路径参考：[frontend/antd/notification/notification.tsx:38-69](file://frontend/antd/notification/notification.tsx#L38-L69) +- 信息通知（Notification） + - 使用 placement 指定位置（如 topRight），role 设为 status； + - 通过 stack 控制堆叠，pauseOnHover 提升可读性。 + - 示例路径参考：[frontend/antd/notification/notification.tsx:31-36](file://frontend/antd/notification/notification.tsx#L31-L36) +- 手动关闭 + - 通过 onVisible(false) 主动关闭，或在外部调用 destroy(key)； + - 示例路径参考：[frontend/antd/message/message.tsx:46-50](file://frontend/antd/message/message.tsx#L46-L50)、[frontend/antd/notification/notification.tsx:65-69](file://frontend/antd/notification/notification.tsx#L65-L69) +- 动态更新与批量操作 + - 使用 messageKey 覆盖已有消息； + - 使用 destroyAll() 批量清理，避免内存泄漏。 + - 示例路径参考：[frontend/antd/message/message.tsx:51-58](file://frontend/antd/message/message.tsx#L51-L58)、[frontend/antd/notification/notification.tsx:74-77](file://frontend/antd/notification/notification.tsx#L74-L77) + +无障碍与体验优化建议 + +- 为 Notification 设置 role（alert/status），提升可访问性； +- 合理设置 duration，避免打断用户任务； +- 对关键操作提供明确的反馈文案与操作按钮； +- 在暗色主题或高对比度场景下，确保消息颜色与图标清晰可辨。 + +章节来源 + +- [backend/modelscope_studio/components/antd/notification/**init**.py:40-44](file://backend/modelscope_studio/components/antd/notification/__init__.py#L40-L44) +- [frontend/antd/notification/notification.tsx:65-69](file://frontend/antd/notification/notification.tsx#L65-L69) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\350\277\233\345\272\246\347\273\223\346\236\234\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\350\277\233\345\272\246\347\273\223\346\236\234\347\273\204\344\273\266.md" new file mode 100644 index 00000000..675d3a0d --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\217\215\351\246\210\347\273\204\344\273\266/\350\277\233\345\272\246\347\273\223\346\236\234\347\273\204\344\273\266.md" @@ -0,0 +1,289 @@ +# 进度结果组件 + + +**本文引用的文件** +- [frontend/antd/progress/progress.tsx](file://frontend/antd/progress/progress.tsx) +- [frontend/antd/progress/Index.svelte](file://frontend/antd/progress/Index.svelte) +- [docs/components/antd/progress/README.md](file://docs/components/antd/progress/README.md) +- [docs/components/antd/progress/demos/basic.py](file://docs/components/antd/progress/demos/basic.py) +- [frontend/antd/result/result.tsx](file://frontend/antd/result/result.tsx) +- [frontend/antd/result/Index.svelte](file://frontend/antd/result/Index.svelte) +- [docs/components/antd/result/README.md](file://docs/components/antd/result/README.md) +- [docs/components/antd/result/demos/basic.py](file://docs/components/antd/result/demos/basic.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件聚焦于进度结果组件群组，系统性梳理进度条（Progress）与结果（Result）两大组件的功能特性、形态差异、状态语义、属性配置、动画与样式定制方法，并结合仓库内的演示示例，给出文件上传进度、任务执行状态、操作结果反馈等典型应用场景的实践建议。同时，提供用户体验优化与无障碍访问支持要点，帮助开发者在 Gradio 生态中高效、一致地使用进度与结果组件。 + +## 项目结构 + +- 组件实现位于前端层：每个组件由 Svelte 入口文件负责属性处理与插槽渲染，TypeScript 包装器对接 Ant Design 原生组件。 +- 文档与演示位于 docs/components/antd 下，提供组件说明与可运行示例。 +- 组件入口与包装器的关系如下图所示： + +```mermaid +graph TB +subgraph "前端实现" +PIndex["progress/Index.svelte"] +PWrap["progress/progress.tsx"] +RIndex["result/Index.svelte"] +RWrap["result/result.tsx"] +end +subgraph "第三方库" +AntD["Ant Design Progress/Result"] +end +PIndex --> PWrap +RIndex --> RWrap +PWrap --> AntD +RWrap --> AntD +``` + +图表来源 + +- [frontend/antd/progress/Index.svelte:1-64](file://frontend/antd/progress/Index.svelte#L1-L64) +- [frontend/antd/progress/progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [frontend/antd/result/Index.svelte:1-64](file://frontend/antd/result/Index.svelte#L1-L64) +- [frontend/antd/result/result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) + +章节来源 + +- [frontend/antd/progress/Index.svelte:1-64](file://frontend/antd/progress/Index.svelte#L1-L64) +- [frontend/antd/progress/progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [frontend/antd/result/Index.svelte:1-64](file://frontend/antd/result/Index.svelte#L1-L64) +- [frontend/antd/result/result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) + +## 核心组件 + +- 进度条（Progress） + - 支持线形、环形、仪表盘三种形态（通过 type 控制），并可叠加步骤分段（steps）、数值显示开关（show_info）、状态色（stroke_color）等。 + - 提供百分比（percent）与格式化回调（format）以灵活控制文本显示；支持自定义取整函数（rounding）。 + - 常见状态：默认、进行中（status='active'）、异常（status='exception'）、完成（status='success'）。 +- 结果（Result） + - 用于反馈一系列操作的最终结果，支持成功、信息、警告、错误四种状态（status）。 + - 支持标题（title）、副标题（sub_title）、图标（icon）与额外操作区（extra）插槽，便于扩展按钮、链接或复杂内容。 + +章节来源 + +- [docs/components/antd/progress/README.md:1-8](file://docs/components/antd/progress/README.md#L1-L8) +- [docs/components/antd/result/README.md:1-8](file://docs/components/antd/result/README.md#L1-L8) +- [docs/components/antd/progress/demos/basic.py:1-39](file://docs/components/antd/progress/demos/basic.py#L1-L39) +- [docs/components/antd/result/demos/basic.py:1-57](file://docs/components/antd/result/demos/basic.py#L1-L57) + +## 架构总览 + +下图展示了从 Svelte 入口到 Ant Design 原生组件的调用链路与插槽传递机制： + +```mermaid +sequenceDiagram +participant UI as "页面/布局" +participant PIdx as "progress/Index.svelte" +participant PWrap as "progress/progress.tsx" +participant RIdx as "result/Index.svelte" +participant RWrap as "result/result.tsx" +participant Ant as "Ant Design 组件" +UI->>PIdx : 传入属性与插槽 +PIdx->>PIdx : 处理可见性/样式/附加属性 +PIdx->>PWrap : 渲染包装器并透传属性 +PWrap->>Ant : 调用 Ant Design Progress +Ant-->>UI : 渲染进度条 +UI->>RIdx : 传入属性与插槽 +RIdx->>RIdx : 处理可见性/样式/附加属性 +RIdx->>RWrap : 渲染包装器并透传插槽 +RWrap->>Ant : 调用 Ant Design Result +Ant-->>UI : 渲染结果面板 +``` + +图表来源 + +- [frontend/antd/progress/Index.svelte:10-61](file://frontend/antd/progress/Index.svelte#L10-L61) +- [frontend/antd/progress/progress.tsx:5-21](file://frontend/antd/progress/progress.tsx#L5-L21) +- [frontend/antd/result/Index.svelte:10-59](file://frontend/antd/result/Index.svelte#L10-L59) +- [frontend/antd/result/result.tsx:7-30](file://frontend/antd/result/result.tsx#L7-L30) + +## 详细组件分析 + +### 进度条（Progress）组件 + +- 形态与行为 + - 线形进度条：默认类型，适合长流程、持续时间较长的任务。 + - 环形进度条：type="circle"，适合强调完成度或作为卡片内指标。 + - 仪表盘进度条：type="dashboard"，适合阈值判断与区间可视化。 + - 步骤分段：steps 参数将进度拆分为若干阶段，常用于多阶段任务。 +- 数值显示与格式化 + - percent 百分比输入，show_info 控制是否显示数字或状态图标。 + - format 回调可自定义文本内容，如完成时显示“完成”文案。 + - rounding 可对百分比进行取整策略定制。 +- 颜色与状态 + - stroke_color 支持单色或渐变数组，按步骤或整体着色。 + - status 控制状态色与动画：默认、进行中（active）、异常（exception）、成功（success）。 +- 属性与插槽 + - 属性：percent、type、steps、stroke_color、status、show_info、format、rounding 等。 + - 插槽：无内置插槽，主要通过 format 自定义文本。 +- 使用场景 + - 文件上传进度：线形进度条展示实时百分比，完成时切换为成功状态。 + - 任务执行状态：环形进度条作为卡片内指标，仪表盘用于阈值提醒。 + - 分步流程：steps 将复杂流程拆解为多个阶段，提升可感知性。 + +```mermaid +flowchart TD +Start(["开始"]) --> SetType["设置类型
type=linear/circle/dashboard"] +SetType --> SetPercent["设置百分比
percent"] +SetPercent --> ShowInfo{"是否显示信息？"} +ShowInfo --> |是| FormatText["格式化文本
format 回调"] +ShowInfo --> |否| SkipFormat["跳过文本显示"] +FormatText --> Color["设置颜色
stroke_color/status"] +SkipFormat --> Color +Color --> Steps{"是否分步？"} +Steps --> |是| StepSeg["按步骤绘制
steps"] +Steps --> |否| SingleSeg["整体绘制"] +StepSeg --> Render["渲染进度条"] +SingleSeg --> Render +Render --> End(["结束"]) +``` + +图表来源 + +- [frontend/antd/progress/progress.tsx:5-21](file://frontend/antd/progress/progress.tsx#L5-L21) +- [docs/components/antd/progress/demos/basic.py:9-35](file://docs/components/antd/progress/demos/basic.py#L9-L35) + +章节来源 + +- [frontend/antd/progress/progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [frontend/antd/progress/Index.svelte:10-61](file://frontend/antd/progress/Index.svelte#L10-L61) +- [docs/components/antd/progress/README.md:1-8](file://docs/components/antd/progress/README.md#L1-L8) +- [docs/components/antd/progress/demos/basic.py:1-39](file://docs/components/antd/progress/demos/basic.py#L1-L39) + +### 结果（Result）组件 + +- 状态与语义 + - 成功（success）：操作已成功完成，鼓励继续下一步。 + - 信息（info）：提供中性提示，引导用户查看详情。 + - 警告（warning）：存在风险或需注意的问题，建议用户确认。 + - 错误（error）：操作失败，需要修正后重试。 +- 视觉与内容 + - 标题（title）与副标题（sub_title）清晰传达结果与上下文。 + - 图标（icon）可自定义，配合状态色增强识别。 + - 额外区域（extra）插槽放置操作按钮、链接或补充说明。 +- 属性与插槽 + - 属性：status、title、sub_title、icon、extra 等。 + - 插槽：extra、icon、subTitle、title。 +- 使用场景 + - 操作结果反馈：提交表单、购买服务后的统一反馈界面。 + - 错误诊断：在错误状态下展示具体问题与修复指引。 + - 引导转化：在成功后提供“前往控制台”“再次购买”等操作。 + +```mermaid +sequenceDiagram +participant App as "应用" +participant R as "Result 组件" +participant Slot as "插槽内容" +participant Ant as "Ant Design Result" +App->>R : 传入 status/title/subTitle/icon +App->>Slot : 提供 extra/icon/subTitle/title 插槽 +R->>R : 解析 slots 并透传给包装器 +R->>Ant : 渲染 Result +Ant-->>App : 展示结果面板与操作区 +``` + +图表来源 + +- [frontend/antd/result/result.tsx:7-30](file://frontend/antd/result/result.tsx#L7-L30) +- [frontend/antd/result/Index.svelte:10-59](file://frontend/antd/result/Index.svelte#L10-L59) + +章节来源 + +- [frontend/antd/result/result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) +- [frontend/antd/result/Index.svelte:1-64](file://frontend/antd/result/Index.svelte#L1-L64) +- [docs/components/antd/result/README.md:1-8](file://docs/components/antd/result/README.md#L1-L8) +- [docs/components/antd/result/demos/basic.py:1-57](file://docs/components/antd/result/demos/basic.py#L1-L57) + +## 依赖关系分析 + +- 组件耦合与职责 + - Svelte 入口负责属性收集、可见性控制、样式拼接与插槽解析。 + - TypeScript 包装器负责对接 Ant Design 组件，透传属性与回调（format、rounding）。 + - 插槽系统通过 ReactSlot 与 useTargets 实现，确保 slots 的动态渲染与回退。 +- 外部依赖 + - Ant Design Progress/Result：提供核心 UI 与交互行为。 + - @svelte-preprocess-react：桥接 React 组件与 Svelte 上下文。 + - @utils/hooks：提供 useFunction、useTargets 等工具函数。 + +```mermaid +graph LR +PIdx["progress/Index.svelte"] --> PWrap["progress/progress.tsx"] +RIdx["result/Index.svelte"] --> RWrap["result/result.tsx"] +PWrap --> AntD["Ant Design Progress"] +RWrap --> AntD2["Ant Design Result"] +PWrap --> Hooks["@utils/hooks"] +RWrap --> Hooks +``` + +图表来源 + +- [frontend/antd/progress/Index.svelte:1-64](file://frontend/antd/progress/Index.svelte#L1-L64) +- [frontend/antd/progress/progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [frontend/antd/result/Index.svelte:1-64](file://frontend/antd/result/Index.svelte#L1-L64) +- [frontend/antd/result/result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) + +章节来源 + +- [frontend/antd/progress/progress.tsx:1-24](file://frontend/antd/progress/progress.tsx#L1-L24) +- [frontend/antd/result/result.tsx:1-33](file://frontend/antd/result/result.tsx#L1-L33) + +## 性能考量 + +- 渲染开销 + - 进度条：线形与环形渲染成本相近，分步（steps）会增加路径绘制次数；建议在高频更新场景下减少不必要的重渲染。 + - 结果：内容相对静态，插槽渲染仅在内容变化时触发。 +- 动画与流畅度 + - 使用 format 回调时避免复杂计算，尽量返回轻量字符串。 + - 圆形/仪表盘进度条在高刷新率下可能带来 GPU 压力，建议在移动端谨慎使用大尺寸环形进度。 +- 样式与主题 + - 通过 elem_style/elem_classes 注入样式时，优先使用原子类或主题变量，减少内联样式的抖动。 + +## 故障排查指南 + +- 插槽未生效 + - 确认插槽名称正确（extra、icon、subTitle、title），并在包装器中显式透传 slots。 + - 若未提供插槽内容，包装器会回退到 props 对应字段。 +- 百分比不更新 + - 确保 percent 属性随数据变化而更新；避免在 format 中进行昂贵计算导致卡顿。 + - 如需自定义取整，检查 rounding 函数的输入输出类型与边界值。 +- 状态色异常 + - status 与 stroke_color 同时使用时，注意状态优先级与颜色覆盖顺序。 + - steps 为数组时，确保长度与阶段数一致，避免越界。 +- 可访问性 + - 为关键状态（成功/错误）提供语义化标签与屏幕阅读器友好的文本。 + - 在环形进度条中为不可见文本提供替代描述，确保辅助技术可理解进度含义。 + +章节来源 + +- [frontend/antd/result/result.tsx:10-30](file://frontend/antd/result/result.tsx#L10-L30) +- [frontend/antd/progress/progress.tsx:9-21](file://frontend/antd/progress/progress.tsx#L9-L21) + +## 结论 + +进度条与结果组件在 Gradio 生态中承担了“过程可见性”与“结果反馈”的双重职责。通过 Ant Design 的成熟能力与本项目的 Svelte 包装器，开发者可以以最小成本获得一致、可扩展且可定制的进度与结果体验。建议在实际项目中结合业务场景选择合适的形态与状态，并遵循可访问性与性能最佳实践，以提升用户满意度与可维护性。 + +## 附录 + +- 示例参考 + - 进度条基础演示：[docs/components/antd/progress/demos/basic.py:1-39](file://docs/components/antd/progress/demos/basic.py#L1-L39) + - 结果组件基础演示：[docs/components/antd/result/demos/basic.py:1-57](file://docs/components/antd/result/demos/basic.py#L1-L57) +- 组件文档 + - 进度条文档：[docs/components/antd/progress/README.md:1-8](file://docs/components/antd/progress/README.md#L1-L8) + - 结果文档：[docs/components/antd/result/README.md:1-8](file://docs/components/antd/result/README.md#L1-L8) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\344\270\213\346\213\211\350\217\234\345\215\225\347\273\204\344\273\266 (Dropdown).md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\344\270\213\346\213\211\350\217\234\345\215\225\347\273\204\344\273\266 (Dropdown).md" new file mode 100644 index 00000000..06e80ff9 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\344\270\213\346\213\211\350\217\234\345\215\225\347\273\204\344\273\266 (Dropdown).md" @@ -0,0 +1,325 @@ +# 下拉菜单组件（Dropdown） + + +**本文引用的文件** +- [frontend/antd/dropdown/dropdown.tsx](file://frontend/antd/dropdown/dropdown.tsx) +- [frontend/antd/dropdown/button/Index.svelte](file://frontend/antd/dropdown/button/Index.svelte) +- [backend/modelscope_studio/components/antd/dropdown/__init__.py](file://backend/modelscope_studio/components/antd/dropdown/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [docs/components/antd/dropdown/README.md](file://docs/components/antd/dropdown/README.md) +- [docs/components/antd/dropdown/demos/basic.py](file://docs/components/antd/dropdown/demos/basic.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件系统性地介绍下拉菜单组件（Dropdown）在模型空间前端中的实现与使用方式，覆盖以下主题： + +- 触发机制与弹出容器 +- 菜单项配置与渲染 +- 弹出位置与定位策略 +- 交互行为与事件处理 +- 键盘导航与无障碍支持 +- 与表单、图标按钮、文本链接的集成 +- 高级用法：多级菜单、动态菜单、远程加载 +- 性能优化建议与常见问题 + +## 项目结构 + +下拉菜单组件由后端 Python 组件与前端 Svelte/React 包装层共同构成，并通过 Gradio 生态进行桥接。 + +```mermaid +graph TB +subgraph "后端" +PY_API["AntdDropdown
Python 组件"] +BTN_PY["AntdDropdown.Button
Python 组件"] +end +subgraph "前端" +WRAP["Dropdown 包装器
dropdown.tsx"] +BTN_SVLT["Dropdown.Button 前端包装
button/Index.svelte"] +ANTD["Antd Dropdown 组件"] +MENU_CTX["菜单上下文 Provider"] +end +PY_API --> WRAP +BTN_PY --> BTN_SVLT +WRAP --> ANTD +WRAP --> MENU_CTX +BTN_SVLT --> ANTD +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:11-38](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L11-L38) +- [frontend/antd/dropdown/dropdown.tsx:15-108](file://frontend/antd/dropdown/dropdown.tsx#L15-L108) +- [frontend/antd/dropdown/button/Index.svelte:10-70](file://frontend/antd/dropdown/button/Index.svelte#L10-L70) + +章节来源 + +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:11-38](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L11-L38) +- [frontend/antd/dropdown/dropdown.tsx:15-108](file://frontend/antd/dropdown/dropdown.tsx#L15-L108) +- [frontend/antd/dropdown/button/Index.svelte:10-70](file://frontend/antd/dropdown/button/Index.svelte#L10-L70) + +## 核心组件 + +- 后端 Python 组件：AntdDropdown 与 AntdDropdown.Button +- 前端包装层：Dropdown（React 包装 + Antd Dropdown）、Dropdown.Button（Svelte 包装） +- 菜单上下文：通过菜单上下文 Provider 将“菜单项”注入到下拉菜单中 + +关键特性 + +- 支持通过 slots 注入菜单项、展开图标、溢出指示器、自定义弹出渲染 +- 支持 getPopupContainer 自定义弹出容器 +- 支持 open*change、menu*\* 系列事件绑定 +- 提供内联样式透传（innerStyle）与容器样式（overlayStyle） + +章节来源 + +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:34-38](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L34-L38) +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:40-100](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L40-L100) +- [frontend/antd/dropdown/dropdown.tsx:15-25](file://frontend/antd/dropdown/dropdown.tsx#L15-L25) +- [frontend/antd/dropdown/dropdown.tsx:44-92](file://frontend/antd/dropdown/dropdown.tsx#L44-L92) + +## 架构总览 + +下拉菜单的调用链路如下： + +```mermaid +sequenceDiagram +participant User as "用户" +participant Py as "AntdDropdown(Python)" +participant Wrap as "Dropdown 包装器(React)" +participant MenuCtx as "菜单上下文 Provider" +participant Antd as "Antd Dropdown" +participant Popup as "弹出层" +User->>Py : 渲染下拉菜单 +Py->>Wrap : 传递属性与 slots +Wrap->>MenuCtx : 读取菜单项 +Wrap->>Antd : 渲染 Antd Dropdown +Antd->>Popup : 按触发条件显示 +User->>Popup : 点击/悬停/键盘操作 +Popup-->>Antd : 触发回调 +Antd-->>Wrap : 回传事件 +Wrap-->>Py : 触发 open_change / menu_* 事件 +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:16-32](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L16-L32) +- [frontend/antd/dropdown/dropdown.tsx:26-107](file://frontend/antd/dropdown/dropdown.tsx#L26-L107) + +## 详细组件分析 + +### 组件一：下拉菜单（Dropdown） + +- 角色：将 Ant Design 的 Dropdown 与内部菜单上下文结合，支持 slots 注入菜单项与自定义渲染 +- 关键点 + - 菜单项来源：优先使用 props.menu.items；否则从菜单上下文中渲染“menu.items” + - 扩展图标与溢出指示器：可通过 slots 注入 ReactSlot 或回退到原生属性 + - 弹出容器：支持 getPopupContainer 自定义容器 + - 自定义渲染：dropdownRender、popupRender 可通过 slots 注入或函数形式传入 + - 内联样式：innerStyle 透传到内容容器 + +```mermaid +flowchart TD +Start(["进入 Dropdown 包装器"]) --> ReadCtx["读取菜单上下文中的 items"] +ReadCtx --> MergeItems{"是否提供 props.menu.items?"} +MergeItems --> |是| UseProps["使用 props.menu.items"] +MergeItems --> |否| RenderItems["渲染菜单上下文 items"] +UseProps --> Slots["处理 slots: expandIcon / overflowedIndicator / dropdownRender / popupRender"] +RenderItems --> Slots +Slots --> Container["getPopupContainer 定位"] +Container --> Mount["挂载到 Antd Dropdown 并渲染"] +Mount --> End(["完成"]) +``` + +图表来源 + +- [frontend/antd/dropdown/dropdown.tsx:26-107](file://frontend/antd/dropdown/dropdown.tsx#L26-L107) + +章节来源 + +- [frontend/antd/dropdown/dropdown.tsx:15-108](file://frontend/antd/dropdown/dropdown.tsx#L15-L108) + +### 组件二：下拉按钮（Dropdown.Button） + +- 角色：将 Antd Dropdown.Button 以 Svelte 方式包装，支持 slots 与事件映射 +- 关键点 + - 通过 importComponent 动态导入 React 版本的 Dropdown.Button + - 属性映射：open_change → openChange，menu_open_change → menu_OpenChange + - 可见性控制：通过 visible 控制是否渲染 + - 样式与 ID：支持 elem_style、elem_id、elem_classes 透传 + +```mermaid +sequenceDiagram +participant User as "用户" +participant BtnPy as "AntdDropdown.Button(Python)" +participant BtnSvlt as "Dropdown.Button(Svelte)" +participant BtnReact as "Dropdown.Button(React)" +participant Antd as "Antd Dropdown.Button" +User->>BtnPy : 渲染 Dropdown.Button +BtnPy->>BtnSvlt : 传递属性与 slots +BtnSvlt->>BtnReact : 动态导入并渲染 +BtnReact->>Antd : 渲染 Antd Dropdown.Button +User->>Antd : 点击/交互 +Antd-->>BtnReact : 回调事件 +BtnReact-->>BtnSvlt : 事件透传 +BtnSvlt-->>BtnPy : 事件透传 +``` + +图表来源 + +- [frontend/antd/dropdown/button/Index.svelte:10-70](file://frontend/antd/dropdown/button/Index.svelte#L10-L70) +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:8-8](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L8-L8) + +章节来源 + +- [frontend/antd/dropdown/button/Index.svelte:10-70](file://frontend/antd/dropdown/button/Index.svelte#L10-L70) +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:15-15](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L15-L15) + +### 事件处理与键盘导航 + +- 事件绑定 + - open_change：下拉面板显隐状态变化 + - menu_click / menu_select / menu_deselect / menu_open_change：菜单项点击、选择、取消选择、菜单面板显隐 +- 键盘导航 + - 使用 Antd Dropdown 的默认键盘行为（上下移动、Enter/空格选择、Esc 关闭） +- 无障碍支持 + - 保持原生语义标签与可访问性属性（由 Antd Dropdown 提供） + - 建议：为触发元素设置 aria-controls、aria-expanded 等属性以增强可访问性 + +章节来源 + +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:16-32](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L16-L32) + +### 弹出位置与容器 + +- 定位策略 + - placement：支持 topLeft/top/topRight/bottomLeft/bottom/bottomRight + - auto_adjust_overflow：自动调整溢出 +- 容器选择 + - get_popup_container：自定义弹出容器，常用于固定在特定区域或滚动容器内 + +章节来源 + +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:56-59](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L56-L59) +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:52-52](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L52-L52) + +### 与表单、图标按钮、文本链接的集成 + +- 表单组件 + - 在菜单项中嵌入输入类组件时，注意表单联动与校验时机 +- 图标按钮 + - 使用 antd.Icon 与 antd.Button（type="text" 或 "primary"/"default"）组合 +- 文本链接 + - 使用 antd.Button（type="link"）作为菜单项标签，支持 href 与新窗口打开 + +章节来源 + +- [docs/components/antd/dropdown/demos/basic.py:6-31](file://docs/components/antd/dropdown/demos/basic.py#L6-L31) +- [docs/components/antd/dropdown/demos/basic.py:37-47](file://docs/components/antd/dropdown/demos/basic.py#L37-L47) + +### 高级用法 + +- 多级菜单 + - 在菜单项中嵌套子菜单项，实现二级或多级下拉 +- 动态菜单 + - 通过 slots 注入“menu.items”，运行时根据状态更新 +- 远程加载 + - 在 dropdownRender/popupRender 中加入加载态与错误态，异步请求后更新菜单项 + +章节来源 + +- [frontend/antd/dropdown/dropdown.tsx:20-24](file://frontend/antd/dropdown/dropdown.tsx#L20-L24) +- [frontend/antd/dropdown/dropdown.tsx:71-92](file://frontend/antd/dropdown/dropdown.tsx#L71-L92) + +## 依赖关系分析 + +- Python 层 + - AntdDropdown 导出 Button 子组件，并声明支持的 slots 与事件 + - 组件注册于 components.py，统一导出 +- 前端层 + - Dropdown 包装器依赖 Antd Dropdown、菜单上下文 Provider、slots 渲染工具 + - Dropdown.Button 通过 Svelte 包装 React 组件 + +```mermaid +graph LR +PY["AntdDropdown(Python)"] --> WRAP["Dropdown(React)"] +WRAP --> ANTD["Antd Dropdown"] +WRAP --> CTX["菜单上下文 Provider"] +BTN_PY["AntdDropdown.Button(Python)"] --> BTN_SVLT["Dropdown.Button(Svelte)"] +BTN_SVLT --> BTN_REACT["Dropdown.Button(React)"] +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:39-40](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L39-L40) +- [backend/modelscope_studio/components/antd/components.py:39-40](file://backend/modelscope_studio/components/antd/components.py#L39-L40) +- [frontend/antd/dropdown/dropdown.tsx:10-13](file://frontend/antd/dropdown/dropdown.tsx#L10-L13) +- [frontend/antd/dropdown/button/Index.svelte:10-12](file://frontend/antd/dropdown/button/Index.svelte#L10-L12) + +章节来源 + +- [backend/modelscope_studio/components/antd/components.py:39-40](file://backend/modelscope_studio/components/antd/components.py#L39-L40) +- [frontend/antd/dropdown/dropdown.tsx:10-13](file://frontend/antd/dropdown/dropdown.tsx#L10-L13) + +## 性能考虑 + +- 菜单项渲染 + - 使用 useMemo 缓存菜单项列表，避免不必要的重渲染 +- slots 渲染 + - 仅在需要时渲染 slots，减少无用节点 +- 弹出容器 + - 合理设置 getPopupContainer，避免弹出层频繁重排 +- 事件绑定 + - 仅在必要时绑定 open*change 与 menu*\* 事件，避免过度监听 + +章节来源 + +- [frontend/antd/dropdown/dropdown.tsx:49-57](file://frontend/antd/dropdown/dropdown.tsx#L49-L57) +- [frontend/antd/dropdown/dropdown.tsx:37-39](file://frontend/antd/dropdown/dropdown.tsx#L37-L39) + +## 故障排查指南 + +- 无法显示菜单项 + - 检查是否通过 slots 注入“menu.items”，或是否正确传入 props.menu.items +- 弹出层位置异常 + - 检查 getPopupContainer 是否返回正确的容器元素 + - 调整 placement 与 auto_adjust_overflow +- 事件未触发 + - 确认已启用对应事件（open*change、menu*\*），并在 Python 层正确绑定 +- 样式不生效 + - innerStyle 仅作用于内容容器；overlayStyle 应通过后端属性传入 + +章节来源 + +- [frontend/antd/dropdown/dropdown.tsx:44-92](file://frontend/antd/dropdown/dropdown.tsx#L44-L92) +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:52-59](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L52-L59) +- [backend/modelscope_studio/components/antd/dropdown/**init**.py:16-32](file://backend/modelscope_studio/components/antd/dropdown/__init__.py#L16-L32) + +## 结论 + +下拉菜单组件通过“Python 组件 + 前端包装 + 菜单上下文”的设计，实现了灵活的菜单项注入、弹出层自定义与事件绑定。配合 Antd Dropdown 的成熟能力，能够满足从基础下拉到复杂多级菜单、动态与远程加载等场景。建议在实际项目中关注性能与可访问性，合理使用 slots 与事件，确保良好的用户体验。 + +## 附录 + +- 示例参考 + - 基础示例：包含普通下拉与下拉按钮，以及菜单项中嵌入按钮与链接 +- 文档入口 + - 组件文档首页与示例入口 + +章节来源 + +- [docs/components/antd/dropdown/README.md:1-8](file://docs/components/antd/dropdown/README.md#L1-L8) +- [docs/components/antd/dropdown/demos/basic.py:33-47](file://docs/components/antd/dropdown/demos/basic.py#L33-L47) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\345\210\206\351\241\265\347\273\204\344\273\266 (Pagination).md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\345\210\206\351\241\265\347\273\204\344\273\266 (Pagination).md" new file mode 100644 index 00000000..6f9152d2 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\345\210\206\351\241\265\347\273\204\344\273\266 (Pagination).md" @@ -0,0 +1,340 @@ +# 分页组件（Pagination） + + +**本文引用的文件** +- [pagination.tsx](file://frontend/antd/pagination/pagination.tsx) +- [Index.svelte](file://frontend/antd/pagination/Index.svelte) +- [__init__.py](file://backend/modelscope_studio/components/antd/pagination/__init__.py) +- [basic.py](file://docs/components/antd/pagination/demos/basic.py) +- [data_changes.py](file://docs/components/antd/pagination/demos/data_changes.py) +- [README.md](file://docs/components/antd/pagination/README.md) +- [app.py](file://docs/components/antd/pagination/app.py) +- [table/__init__.py](file://backend/modelscope_studio/components/antd/table/__init__.py) +- [list/__init__.py](file://backend/modelscope_studio/components/antd/list/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件系统性地介绍分页组件（Pagination）在模型空间前端与后端的实现与使用方式，覆盖以下主题： + +- 数据分页机制：如何基于总条目数与每页条数计算页码范围与边界 +- 页面跳转逻辑：点击页码、快速跳转、上一页/下一页、首页/末页 +- 数据量统计：通过“显示总数”回调或属性展示当前范围与总量 +- 配置项详解：每页数量设置、默认页码、页面大小选择器、跳转器、简单模式、尺寸、禁用、隐藏单页等 +- 与数据表格、列表视图的集成：如何将分页与表格/列表联动，实现数据加载、状态同步与错误处理 +- 国际化支持、样式定制、响应式适配 +- 高级用法：大数据量分页、虚拟滚动、服务端分页 +- 完整示例与性能优化建议 + +## 项目结构 + +分页组件由三部分组成： + +- 前端 Svelte 包装层：负责属性透传、插槽渲染与可见性控制 +- 前端 React 封装层：对接 Ant Design 的 Pagination，并支持插槽与函数型渲染 +- 后端 Gradio 组件：定义事件、插槽、属性映射与渲染入口 + +```mermaid +graph TB +subgraph "后端" +PY_INIT["Python 初始化
__init__.py"] +end +subgraph "前端" +IDX["Svelte 包装层
Index.svelte"] +REACT["React 封装层
pagination.tsx"] +ANTDP["Ant Design Pagination"] +end +PY_INIT --> IDX --> REACT --> ANTDP +``` + +图表来源 + +- [Index.svelte:1-68](file://frontend/antd/pagination/Index.svelte#L1-L68) +- [pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [**init**.py:1-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L1-L107) + +章节来源 + +- [Index.svelte:1-68](file://frontend/antd/pagination/Index.svelte#L1-L68) +- [pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [**init**.py:1-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L1-L107) + +## 核心组件 + +- 后端组件类：定义事件、插槽、属性映射与渲染目录 +- 前端包装层：统一处理属性、类名、样式、可见性与插槽 +- React 封装层：对接 Ant Design 的 Pagination，支持自定义渲染与插槽注入 + +关键点 + +- 事件：change、showSizeChange +- 插槽：showQuickJumper.goButton、itemRender +- 属性映射：如 show_size_change → showSizeChange + +章节来源 + +- [**init**.py:14-25](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L14-L25) +- [Index.svelte:22-48](file://frontend/antd/pagination/Index.svelte#L22-L48) +- [pagination.tsx:8-52](file://frontend/antd/pagination/pagination.tsx#L8-L52) + +## 架构总览 + +分页组件的调用链路如下： + +```mermaid +sequenceDiagram +participant User as "用户" +participant Backend as "后端组件类
AntdPagination" +participant FrontIndex as "前端包装层
Index.svelte" +participant ReactLayer as "React 封装层
pagination.tsx" +participant Antd as "Ant Design Pagination" +User->>Backend : 渲染请求 +Backend->>FrontIndex : 传递属性与插槽 +FrontIndex->>ReactLayer : 透传属性与插槽 +ReactLayer->>Antd : 渲染组件并绑定事件 +User->>Antd : 触发分页/切换页大小 +Antd-->>ReactLayer : onChange(page, pageSize) +ReactLayer-->>FrontIndex : 回调触发 +FrontIndex-->>Backend : 事件回调如 change +``` + +图表来源 + +- [**init**.py:14-21](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L14-L21) +- [Index.svelte:54-66](file://frontend/antd/pagination/Index.svelte#L54-L66) +- [pagination.tsx:36-38](file://frontend/antd/pagination/pagination.tsx#L36-L38) + +## 详细组件分析 + +### 配置选项与行为 + +- 基础参数 + - 总条目数：total + - 默认页码：default_current + - 当前页：current + - 每页条数：default_page_size / page_size + - 页码选项：page_size_options + - 禁用：disabled + - 单页隐藏：hide_on_single_page + - 尺寸：size（small/default） + - 对齐：align（start/center/end） + - 简单模式：simple + - 显示标题：show_title + - 显示较少项：show_less_items + - 响应式：responsive + - 自定义渲染：item_render + - 显示总数：show_total + - 快速跳转：show_quick_jumper（可带 goButton 插槽） + - 显示页大小选择器：show_size_changer +- 插槽 + - showQuickJumper.goButton：快速跳转按钮 + - itemRender：自定义页码项渲染 + +章节来源 + +- [**init**.py:26-88](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L26-L88) +- [Index.svelte:46-47](file://frontend/antd/pagination/Index.svelte#L46-L47) +- [pagination.tsx:12-47](file://frontend/antd/pagination/pagination.tsx#L12-L47) + +### 事件与状态同步 + +- change：页码或页大小变化时触发，返回(page, pageSize) +- showSizeChange：页大小变更时触发 +- 与 Gradio 状态联动：通过事件回调将页码与页大小写入 gr.State，再驱动数据加载 + +章节来源 + +- [**init**.py:14-21](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L14-L21) +- [data_changes.py:6-11](file://docs/components/antd/pagination/demos/data_changes.py#L6-L11) + +### 数据分页机制与页面跳转逻辑 + +- 计算规则 + - 总页数：Math.ceil(total / pageSize) + - 当前页范围：1 到总页数 + - 边界处理：current 超出范围时回退到合法值 +- 跳转流程 + - 点击页码：触发 change + - 上一页/下一页/首页/末页：由 Ant Design 内部处理并触发 change + - 快速跳转：启用 show_quick_jumper 并提供 goButton 插槽时，使用插槽按钮执行跳转 +- 自定义渲染 + - 使用 itemRender 自定义页码按钮内容 + - 使用 show_total 在分页左侧显示范围/总数 + +```mermaid +flowchart TD +Start(["开始"]) --> Init["接收 total 与 pageSize"] +Init --> CalcPages["计算总页数"] +CalcPages --> ValidateCurrent["校验 current 是否在有效范围"] +ValidateCurrent --> Render["渲染页码按钮"] +Render --> Jump["用户点击页码/跳转按钮"] +Jump --> ChangeEvent["触发 change(page, pageSize)"] +ChangeEvent --> UpdateState["更新状态如 gr.State"] +UpdateState --> LoadData["根据新页码加载数据"] +LoadData --> End(["结束"]) +``` + +图表来源 + +- [pagination.tsx:36-38](file://frontend/antd/pagination/pagination.tsx#L36-L38) +- [data_changes.py:6-11](file://docs/components/antd/pagination/demos/data_changes.py#L6-L11) + +### 与数据表格、列表视图的集成 + +- 表格集成 + - 在表格组件中开启 pagination，并将分页的 change 事件与表格数据加载逻辑绑定 + - 可通过 show_size_changer 动态切换每页条数，联动表格列宽与行高 +- 列表集成 + - 列表组件支持 pagination 参数，可直接传入分页实例 + - 列表的加载更多（load_more）与分页可二选一或组合使用 +- 状态同步 + - 将分页状态写入 gr.State，作为后续数据请求的输入 + - 表格/列表的 loading 与分页的禁用状态可联动，避免并发请求 + +章节来源 + +- [table/**init**.py:114-133](file://backend/modelscope_studio/components/antd/table/__init__.py#L114-L133) +- [list/**init**.py:59-82](file://backend/modelscope_studio/components/antd/list/__init__.py#L59-L82) +- [data_changes.py:24-28](file://docs/components/antd/pagination/demos/data_changes.py#L24-L28) + +### 国际化支持、样式定制与响应式适配 + +- 国际化 + - 通过 ConfigProvider 提供语言环境，分页文案随全局配置生效 +- 样式定制 + - 支持 elem_id、elem_classes、elem_style 以及额外属性 additional_props + - 可通过 root_class_name 与 class_names/styles 进行主题级定制 +- 响应式 + - responsive 开启时，组件在小屏设备上自动调整布局与字号 + +章节来源 + +- [README.md:1-14](file://docs/components/antd/pagination/README.md#L1-L14) +- [Index.svelte:56-58](file://frontend/antd/pagination/Index.svelte#L56-L58) +- [**init**.py:49-50](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L49-L50) + +### 高级用法：大数据量分页、虚拟滚动、服务端分页 + +- 大数据量分页 + - 使用较大的 total，结合较小的 page_size 与合理的 page_size_options + - 通过 change 事件按需加载数据，避免一次性渲染全部数据 +- 虚拟滚动 + - 表格组件支持 virtual 参数，可在大数据量场景下显著提升渲染性能 +- 服务端分页 + - 分页仅负责 UI 交互；实际数据由后端接口提供，前端在 change 中发起请求并更新表格/列表 + - 可结合 loading 与禁用状态，防止重复请求 + +章节来源 + +- [table/**init**.py:129-130](file://backend/modelscope_studio/components/antd/table/__init__.py#L129-L130) +- [data_changes.py:6-11](file://docs/components/antd/pagination/demos/data_changes.py#L6-L11) + +### 示例与最佳实践 + +- 基础示例 + - 展示 total、快速跳转、页大小选择器与总数显示 +- 数据变更示例 + - 通过 change 事件将页码与页大小写入 gr.State，并在按钮点击时弹出提示 +- 最佳实践 + - 将分页状态与数据请求解耦，使用事件驱动 + - 在数据加载期间禁用分页，避免并发 + - 合理设置 page_size_options，兼顾加载速度与用户体验 + +章节来源 + +- [basic.py:7-11](file://docs/components/antd/pagination/demos/basic.py#L7-L11) +- [data_changes.py:6-11](file://docs/components/antd/pagination/demos/data_changes.py#L6-L11) + +## 依赖分析 + +- 组件耦合 + - 后端组件类与前端包装层松耦合，通过属性与插槽进行契约式通信 + - React 封装层对 Ant Design 的依赖明确，便于升级与替换 +- 事件与插槽 + - 事件：change、showSizeChange + - 插槽：showQuickJumper.goButton、itemRender +- 外部依赖 + - Ant Design Pagination + - Gradio 事件系统与状态管理 + +```mermaid +graph LR +PY["后端组件类
__init__.py"] --> IDX["前端包装层
Index.svelte"] +IDX --> REACT["React 封装层
pagination.tsx"] +REACT --> ANTDP["Ant Design Pagination"] +PY --> |"事件/插槽"| PY +``` + +图表来源 + +- [**init**.py:14-25](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L14-L25) +- [Index.svelte:54-66](file://frontend/antd/pagination/Index.svelte#L54-L66) +- [pagination.tsx:28-48](file://frontend/antd/pagination/pagination.tsx#L28-L48) + +章节来源 + +- [**init**.py:14-25](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L14-L25) +- [Index.svelte:54-66](file://frontend/antd/pagination/Index.svelte#L54-L66) +- [pagination.tsx:28-48](file://frontend/antd/pagination/pagination.tsx#L28-L48) + +## 性能考虑 + +- 渲染优化 + - 使用虚拟滚动（表格）减少 DOM 数量 + - 控制 page_size，避免过大的单页渲染压力 +- 请求优化 + - 仅在 change 时发起数据请求，避免频繁刷新 + - 在请求期间禁用分页，防止重复请求 +- 样式与资源 + - 合理使用 elem_classes 与样式缓存，减少重绘 + - 避免在 itemRender 中进行重型计算 + +## 故障排查指南 + +- 问题：分页不触发 change + - 检查是否正确绑定 change 事件 + - 确认 total 与 page_size 设置合理 +- 问题：页大小切换无效 + - 检查 show_size_changer 是否启用 + - 确认 show_size_change 属性映射是否正确 +- 问题：快速跳转按钮不显示 + - 检查是否提供了 showQuickJumper.goButton 插槽 +- 问题：样式未生效 + - 检查 elem_id、elem_classes、elem_style 与 root_class_name 的使用 +- 问题：国际化文案异常 + - 确认 ConfigProvider 已正确配置语言 + +章节来源 + +- [Index.svelte:46-47](file://frontend/antd/pagination/Index.svelte#L46-L47) +- [pagination.tsx:39-47](file://frontend/antd/pagination/pagination.tsx#L39-L47) +- [README.md:1-14](file://docs/components/antd/pagination/README.md#L1-L14) + +## 结论 + +分页组件通过清晰的前后端分工与事件/插槽契约，实现了灵活的分页体验。配合表格与列表组件，可轻松构建高性能、可扩展的数据浏览界面。在大数据量场景下，建议结合虚拟滚动与服务端分页策略，确保交互流畅与资源高效。 + +## 附录 + +- 示例入口 + - 文档应用入口：[app.py:1-7](file://docs/components/antd/pagination/app.py#L1-L7) +- 示例脚本 + - 基础示例：[basic.py:1-15](file://docs/components/antd/pagination/demos/basic.py#L1-L15) + - 数据变更示例：[data_changes.py:1-36](file://docs/components/antd/pagination/demos/data_changes.py#L1-L36) +- 组件源码 + - 后端组件类：[**init**.py:1-107](file://backend/modelscope_studio/components/antd/pagination/__init__.py#L1-L107) + - 前端包装层：[Index.svelte:1-68](file://frontend/antd/pagination/Index.svelte#L1-L68) + - React 封装层：[pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\345\257\274\350\210\252\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\345\257\274\350\210\252\347\273\204\344\273\266.md" new file mode 100644 index 00000000..86f4ba37 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\345\257\274\350\210\252\347\273\204\344\273\266.md" @@ -0,0 +1,542 @@ +# 导航组件 + + +**本文引用的文件** +- [frontend/antd/anchor/anchor.tsx](file://frontend/antd/anchor/anchor.tsx) +- [frontend/antd/anchor/context.ts](file://frontend/antd/anchor/context.ts) +- [frontend/antd/breadcrumb/breadcrumb.tsx](file://frontend/antd/breadcrumb/breadcrumb.tsx) +- [frontend/antd/breadcrumb/context.ts](file://frontend/antd/breadcrumb/context.ts) +- [frontend/antd/dropdown/dropdown.tsx](file://frontend/antd/dropdown/dropdown.tsx) +- [frontend/antd/menu/menu.tsx](file://frontend/antd/menu/menu.tsx) +- [frontend/antd/menu/context.ts](file://frontend/antd/menu/context.ts) +- [frontend/antd/pagination/pagination.tsx](file://frontend/antd/pagination/pagination.tsx) +- [frontend/antd/steps/steps.tsx](file://frontend/antd/steps/steps.tsx) +- [frontend/antd/steps/context.ts](file://frontend/antd/steps/context.ts) +- [frontend/antd/layout/layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) +- [frontend/antd/layout/Index.svelte](file://frontend/antd/layout/Index.svelte) +- [frontend/antd/layout/package.json](file://frontend/antd/layout/package.json) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/utils/omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件系统性梳理并讲解 Ant Design 导航相关组件在本仓库中的实现与使用方式，覆盖以下组件：锚点（Anchor）、面包屑（Breadcrumb）、下拉菜单（Dropdown）、导航菜单（Menu）、分页（Pagination）、步骤条（Steps）。文档重点阐述： + +- 组件的状态管理与事件处理机制 +- 与路由系统的集成思路与最佳实践 +- 权限控制在导航中的落地方式 +- 导航模式设计指南：顶部导航、侧边导航、混合导航 +- 多层级导航的实现方法与性能优化建议 +- 交互设计与用户体验优化要点 + +## 项目结构 + +导航相关组件主要位于前端目录下的 antd 子模块中，采用“按需渲染 + 上下文注入”的通用模式组织，配合工具函数完成插槽渲染与属性适配。 + +```mermaid +graph TB +subgraph "导航组件" +A["Anchor
锚点"] +B["Breadcrumb
面包屑"] +C["Dropdown
下拉菜单"] +D["Menu
导航菜单"] +E["Pagination
分页"] +F["Steps
步骤条"] +end +subgraph "通用工具" +U1["createItemsContext.tsx
上下文工厂"] +U2["renderItems.tsx
插槽项渲染"] +U3["renderParamsSlot.tsx
参数化插槽"] +U4["useFunction.ts
函数包装"] +U5["omitUndefinedProps.ts
属性过滤"] +end +subgraph "布局" +L1["layout.base.tsx
基础布局容器"] +L2["layout/Index.svelte
布局入口"] +L3["layout/package.json
导出配置"] +end +A --> U1 +B --> U1 +D --> U1 +F --> U1 +C --> D +A --> U2 +B --> U2 +D --> U2 +F --> U2 +A --> U3 +B --> U3 +D --> U3 +F --> U3 +C --> U4 +D --> U5 +L1 --> L2 +L3 --> L2 +``` + +图表来源 + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/package.json:1-15](file://frontend/antd/layout/package.json#L1-L15) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/utils/omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +章节来源 + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/package.json:1-15](file://frontend/antd/layout/package.json#L1-L15) + +## 核心组件 + +本节对各导航组件进行总体能力与行为说明，便于快速建立认知框架。 + +- 锚点（Anchor） + - 负责页面内定位与高亮，支持容器选择器与当前锚点回调 + - 通过上下文注入 items，支持插槽化子项渲染 +- 面包屑（Breadcrumb） + - 展示当前页面路径，支持自定义分隔符、项渲染器与下拉图标 + - 支持通过插槽替换默认渲染逻辑 +- 下拉菜单（Dropdown） + - 基于 Ant Design Dropdown，内部可嵌套菜单项，支持弹层渲染与溢出指示器 + - 与菜单上下文共享 items 渲染策略 +- 导航菜单（Menu） + - 支持展开图标、溢出指示器与弹出渲染 + - 提供 open/select/deselect 事件透传 +- 分页（Pagination） + - 支持总数渲染、跳转按钮与自定义页码渲染 + - 事件回调统一由函数包装器处理 +- 步骤条（Steps） + - 支持进度点自定义渲染 + - 通过上下文注入 items，支持插槽化子项 + +章节来源 + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) + +## 架构总览 + +导航组件普遍采用“Svelte 包装 + React 组件 + 插槽渲染 + 上下文注入”的统一架构。其关键特征如下： + +- 使用 sveltify 将 React 组件桥接为 Svelte 组件 +- 通过 withItemsContextProvider 注入 items 上下文，统一处理 children 与 slots 的组合 +- 使用 renderItems 与 renderParamsSlot 实现插槽项与参数化插槽的渲染 +- 使用 useFunction 对回调进行包装，确保在 Svelte 环境中稳定执行 +- 使用 omitUndefinedProps 过滤未定义属性，避免向底层组件传递无效值 + +```mermaid +sequenceDiagram +participant S as "Svelte 组件" +participant P as "withItemsContextProvider" +participant R as "renderItems/renderParamsSlot" +participant A as "Antd 组件" +participant U as "useFunction/omitUndefinedProps" +S->>P : 传入 props 与 slots +P->>R : 解析 items 与插槽 +R-->>P : 返回标准化的 items/渲染节点 +P->>U : 包装回调/过滤属性 +U-->>P : 返回安全的 props +P->>A : 渲染 Antd 组件 +A-->>S : 触发事件回调 +``` + +图表来源 + +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/utils/omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +## 详细组件分析 + +### 锚点（Anchor）分析 + +- 数据流与状态 + - 通过上下文注入 items，支持 children 与 slots 的组合 + - 使用 useMemo 缓存 items 计算结果，避免重复渲染 +- 事件与回调 + - getContainer 与 getCurrentAnchor 通过 useFunction 包装，保证在 Svelte 中稳定调用 +- 插槽与渲染 + - 优先使用显式 items；否则从上下文解析 default 或 items 插槽 +- 性能与可用性 + - 仅在必要时重新计算 items，减少渲染开销 + - 通过隐藏 children 容器避免重复渲染 + +```mermaid +flowchart TD +Start(["进入 Anchor 渲染"]) --> Resolve["解析上下文 items"] +Resolve --> HasExplicit{"是否提供显式 items?"} +HasExplicit --> |是| UseExplicit["使用显式 items"] +HasExplicit --> |否| UseSlot["使用插槽 items/default"] +UseSlot --> Memo["useMemo 缓存 items"] +UseExplicit --> Memo +Memo --> Render["渲染 Antd Anchor"] +Render --> End(["完成"]) +``` + +图表来源 + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) + +章节来源 + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) + +### 面包屑（Breadcrumb）分析 + +- 数据流与状态 + - 合并 items 与插槽，支持自定义分隔符与项渲染器 + - dropdownIcon 与 separator 可通过插槽替换 +- 插槽与渲染 + - itemRender 与 dropdown_icon、separator 通过 renderParamsSlot 与 ReactSlot 渲染 +- 回调与事件 + - 保持与 Antd Breadcrumb 的接口一致，无额外封装 + +```mermaid +sequenceDiagram +participant S as "Svelte Breadcrumb" +participant Ctx as "上下文解析" +participant Slot as "插槽渲染" +participant A as "Antd Breadcrumb" +S->>Ctx : 获取 items/default +Ctx-->>S : 返回 items +S->>Slot : 渲染 separator/itemRender/dropdownIcon +Slot-->>S : 返回节点 +S->>A : 传入 items 与渲染后的插槽 +A-->>S : 触发点击/跳转 +``` + +图表来源 + +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) + +章节来源 + +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) + +### 下拉菜单（Dropdown）分析 + +- 数据流与状态 + - 内部菜单项通过菜单上下文注入，支持 expandIcon 与溢出指示器插槽 + - dropdownRender 与 popupRender 支持参数化插槽 +- 事件与回调 + - getPopupContainer 通过 useFunction 包装 +- 与菜单的关系 + - 共享菜单上下文，复用 items 渲染策略 + +```mermaid +classDiagram +class Dropdown { ++props ++slots ++menu.items ++dropdownRender() ++popupRender() ++getPopupContainer() +} +class MenuContext { ++items ++expandIcon ++overflowedIndicator +} +Dropdown --> MenuContext : "共享上下文" +``` + +图表来源 + +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) + +章节来源 + +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) + +### 导航菜单（Menu）分析 + +- 数据流与状态 + - 通过上下文注入 items，支持 expandIcon、溢出指示器与弹出渲染插槽 + - open/select/deselect 事件透传 +- 属性处理 + - 使用 omitUndefinedProps 过滤未定义属性，避免向底层组件传递无效值 +- 插槽与渲染 + - expandIcon、overflowedIndicator、popup_render 通过 renderParamsSlot 与 ReactSlot 渲染 + +```mermaid +flowchart TD +Enter(["进入 Menu 渲染"]) --> Ctx["解析上下文 items/default"] +Ctx --> Items["renderItems 标准化"] +Items --> Props["omitUndefinedProps 过滤属性"] +Props --> Slots["插槽 expandIcon/overflowedIndicator/popup_render"] +Slots --> Antd["渲染 Antd Menu"] +Antd --> Events["透传 open/select/deselect"] +Events --> Exit(["完成"]) +``` + +图表来源 + +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [frontend/utils/omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +章节来源 + +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/menu/context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) + +### 分页（Pagination）分析 + +- 数据流与状态 + - 支持 showTotal、itemRender、showQuickJumper.goButton 等插槽化配置 + - onChange 回调通过 useFunction 包装 +- 插槽与渲染 + - itemRender 与 goButton 通过 renderParamsSlot 与 ReactSlot 渲染 + +```mermaid +sequenceDiagram +participant S as "Svelte Pagination" +participant Slot as "插槽渲染" +participant A as "Antd Pagination" +S->>Slot : 渲染 itemRender/goButton +Slot-->>S : 返回节点 +S->>A : 传入配置与回调包装 +A-->>S : onChange(page, pageSize) +``` + +图表来源 + +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) + +章节来源 + +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) + +### 步骤条（Steps）分析 + +- 数据流与状态 + - 通过上下文注入 items，支持 progressDot 插槽化 + - 通过 useFunction 包装 progressDot 回调 +- 插槽与渲染 + - progressDot 通过 renderParamsSlot 渲染 + +```mermaid +flowchart TD +Start(["进入 Steps 渲染"]) --> Ctx["解析 items/default"] +Ctx --> Normalize["renderItems 标准化"] +Normalize --> Slot["渲染 progressDot"] +Slot --> Antd["渲染 Antd Steps"] +Antd --> End(["完成"]) +``` + +图表来源 + +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/steps/context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) + +章节来源 + +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/steps/context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) + +### 布局（Layout）与导航模式 + +- 基础布局容器 + - Base 组件根据 component 参数动态选择 Layout、Header、Footer、Content + - 通过类名区分样式作用域 +- 布局入口与导出 + - Index.svelte 作为入口，layout/package.json 提供 Gradio 导出配置 + +```mermaid +graph LR +Base["layout.base.tsx
Base 组件"] --> |component| L["Layout"] +Base --> H["Header"] +Base --> F["Footer"] +Base --> C["Content"] +Index["layout/Index.svelte"] --> Base +Package["layout/package.json"] --> Index +``` + +图表来源 + +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/package.json:1-15](file://frontend/antd/layout/package.json#L1-L15) + +章节来源 + +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/package.json:1-15](file://frontend/antd/layout/package.json#L1-L15) + +## 依赖关系分析 + +- 组件间耦合 + - Dropdown 与 Menu 共享菜单上下文，形成弱耦合的复用关系 + - Anchor、Breadcrumb、Steps、Menu 均依赖 createItemsContext 工厂与 renderItems +- 外部依赖 + - Ant Design React 组件库 + - Svelte Preprocess React（sveltify、ReactSlot） + - 工具函数（useFunction、renderItems、renderParamsSlot、omitUndefinedProps） + +```mermaid +graph TB +subgraph "组件" +M["Menu"] +D["Dropdown"] +A["Anchor"] +B["Breadcrumb"] +S["Steps"] +P["Pagination"] +end +subgraph "工具" +Ctx["createItemsContext"] +RI["renderItems"] +RS["renderParamsSlot"] +UF["useFunction"] +OU["omitUndefinedProps"] +end +M --> Ctx +D --> Ctx +A --> Ctx +B --> Ctx +S --> Ctx +M --> RI +D --> RI +A --> RI +B --> RI +S --> RI +M --> RS +D --> RS +A --> RS +B --> RS +S --> RS +M --> OU +D --> UF +A --> UF +B --> UF +S --> UF +P --> UF +``` + +图表来源 + +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/utils/omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +章节来源 + +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) + +## 性能考量 + +- 渲染优化 + - 大量组件使用 useMemo 缓存 items 计算结果，避免不必要的重渲染 + - 通过 renderItems 与 renderParamsSlot 统一插槽渲染，减少分支判断 +- 回调与属性 + - 使用 useFunction 包装回调，确保在 Svelte 生命周期内稳定执行 + - 使用 omitUndefinedProps 过滤未定义属性，降低底层组件处理负担 +- 复杂度与扩展性 + - 上下文工厂 createItemsContext 为多个组件提供一致的 items 注入策略，提升扩展性 + - 插槽化设计使组件具备更强的可定制性，同时保持默认行为稳定 + +## 故障排查指南 + +- 插槽未生效 + - 检查插槽键名是否与组件约定一致（如 menu.items、itemRender、progressDot 等） + - 确认插槽节点已正确传递给组件（ReactSlot 与 renderParamsSlot） +- items 不显示 + - 确认上下文是否正确注入（withItemsContextProvider） + - 检查 children 与 slots 的组合是否被正确解析 +- 回调不触发 + - 确认回调是否通过 useFunction 包装 + - 检查事件透传链路（onOpenChange/onSelect/onDeselect 等） +- 布局异常 + - 检查 layout.base 的 component 参数与类名映射 + - 确认样式作用域未被外部覆盖 + +章节来源 + +- [frontend/antd/menu/menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [frontend/antd/dropdown/dropdown.tsx:1-111](file://frontend/antd/dropdown/dropdown.tsx#L1-L111) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/steps/steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [frontend/antd/pagination/pagination.tsx:1-55](file://frontend/antd/pagination/pagination.tsx#L1-L55) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +## 结论 + +本仓库的导航组件以统一的上下文与插槽渲染策略为核心，实现了高内聚、低耦合的组件体系。通过 useMemo、useFunction、renderItems 等工具的协同，既保证了性能，又提供了强大的可定制性。结合布局组件，可灵活构建顶部导航、侧边导航、混合导航等多种导航模式，并在路由集成与权限控制方面具备良好的扩展空间。 + +## 附录 + +- 导航模式设计指南（概念性建议） + - 顶部导航：适合入口清晰、层级较浅的场景；搭配 Breadcrumb 提升路径感知 + - 侧边导航：适合内容丰富、需要快速切换的后台系统；搭配 Anchor 快速定位 + - 混合导航：顶部主导航 + 侧边二级导航，兼顾全局与局部操作 +- 路由集成与权限控制（概念性建议） + - 路由集成：将路由元信息注入到菜单/面包屑/步骤条的 items 中，实现导航与路由联动 + - 权限控制：在渲染前对 items 进行过滤，仅展示用户有权限的节点 +- 多层级导航实现与性能考虑（概念性建议） + - 使用虚拟滚动与懒加载减少大列表渲染压力 + - 对深层级菜单启用折叠与缓存，避免频繁重渲染 + - 在路由切换时保留必要的导航状态，提升用户体验 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\345\257\274\350\210\252\350\217\234\345\215\225\347\273\204\344\273\266 (Menu).md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\345\257\274\350\210\252\350\217\234\345\215\225\347\273\204\344\273\266 (Menu).md" new file mode 100644 index 00000000..dfb9bb71 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\345\257\274\350\210\252\350\217\234\345\215\225\347\273\204\344\273\266 (Menu).md" @@ -0,0 +1,344 @@ +# 导航菜单组件（Menu） + + +**本文档引用的文件** +- [menu.tsx](file://frontend/antd/menu/menu.tsx) +- [menu.item.tsx](file://frontend/antd/menu/item/menu.item.tsx) +- [Index.svelte](file://frontend/antd/menu/item/Index.svelte) +- [context.ts](file://frontend/antd/menu/context.ts) +- [menu.less](file://frontend/antd/menu/menu.less) +- [createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [README.md](file://docs/components/antd/menu/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件系统性地介绍导航菜单组件（Menu）的设计与实现，覆盖布局模式、菜单项配置、状态管理、交互行为、图标与禁用、子菜单嵌套、水平/垂直布局切换、折叠展开机制、响应式适配、与路由系统的集成（动态菜单、权限控制、面包屑联动）、手风琴与多选模式、可搜索菜单等高级能力，并提供使用示例、样式定制与性能优化建议。 + +## 项目结构 + +菜单组件由“容器组件 + 菜单项组件 + 上下文与渲染工具”三部分组成，采用 Ant Design 的 Menu 组件作为底层实现，通过 Svelte 预处理桥接为 React 组件，结合自研的“项目上下文”系统实现灵活的菜单项收集与渲染。 + +```mermaid +graph TB +subgraph "前端/antd/menu" +M["menu.tsx
菜单容器"] +MI["menu.item.tsx
菜单项包装"] +IDX["Index.svelte
菜单项入口"] +CTX["context.ts
项目上下文导出"] +LESS["menu.less
样式与过渡"] +end +subgraph "工具层" +CIC["createItemsContext.tsx
项目上下文工厂"] +RIT["renderItems.tsx
项目渲染器"] +end +subgraph "外部依赖" +AD["Ant Design Menu
底层UI"] +end +IDX --> MI +MI --> CTX +CTX --> CIC +M --> RIT +M --> AD +M --> LESS +``` + +图表来源 + +- [menu.tsx:14-93](file://frontend/antd/menu/menu.tsx#L14-L93) +- [menu.item.tsx:9-33](file://frontend/antd/menu/item/menu.item.tsx#L9-L33) +- [Index.svelte:13-83](file://frontend/antd/menu/item/Index.svelte#L13-L83) +- [context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [createItemsContext.tsx:97-273](file://frontend/utils/createItemsContext.tsx#L97-L273) +- [renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +章节来源 + +- [menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [menu.item.tsx:1-36](file://frontend/antd/menu/item/menu.item.tsx#L1-L36) +- [Index.svelte:1-84](file://frontend/antd/menu/item/Index.svelte#L1-L84) +- [context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [menu.less:1-45](file://frontend/antd/menu/menu.less#L1-L45) +- [createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + +## 核心组件 + +- 菜单容器（Menu） + - 作用：封装 Ant Design Menu，统一事件透传、插槽渲染、图标与溢出指示器的自定义渲染、以及项目上下文注入。 + - 关键点：支持 slots 扩展（如 expandIcon、overflowedIndicator、popupRender），支持 items 或插槽两种数据源；内部通过 renderItems 将“项目上下文”转换为 Antd 所需的 ItemType 数组。 +- 菜单项（MenuItem） + - 作用：将“项目上下文”中的菜单项包装为 Antd MenuItem/SubMenu，自动识别类型（普通项/子菜单），并注入样式类名。 +- 项目上下文（createItemsContext） + - 作用：提供“项目收集 + 子项目收集”的上下文，支持多插槽、索引定位、属性与子项变换、变更回调等。 +- 渲染器（renderItems） + - 作用：将“项目上下文”树形结构渲染为 Antd 所需的 props 结构，支持插槽注入、克隆、参数化插槽等。 + +章节来源 + +- [menu.tsx:14-93](file://frontend/antd/menu/menu.tsx#L14-L93) +- [menu.item.tsx:9-33](file://frontend/antd/menu/item/menu.item.tsx#L9-L33) +- [createItemsContext.tsx:97-273](file://frontend/utils/createItemsContext.tsx#L97-L273) +- [renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +## 架构总览 + +菜单组件采用“容器 + 项包装 + 上下文”的分层设计，通过 Svelte 预处理桥接到 React，再由 React 调用 Antd Menu。项目上下文负责在运行时收集菜单项及其插槽，最终由渲染器输出为 Antd 可识别的数据结构。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Menu as "Menu 容器" +participant Ctx as "项目上下文" +participant Render as "renderItems" +participant Antd as "Antd Menu" +Dev->>Menu : 传入 items 或插槽 +Menu->>Ctx : withItemsContextProvider 注入 +Ctx-->>Menu : useItems 提供 items +Menu->>Render : renderItems(resolvedSlotItems, { clone }) +Render-->>Menu : 返回 Antd Item 列表 +Menu->>Antd : 渲染并绑定事件 +Antd-->>Dev : 触发 openChange/onSelect/onDeselect +``` + +图表来源 + +- [menu.tsx:18-54](file://frontend/antd/menu/menu.tsx#L18-L54) +- [createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) +- [renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +## 详细组件分析 + +### 菜单容器（Menu） + +- 数据源选择 + - 支持直接传入 items（Antd Item 类型数组）或通过插槽收集（default/items 插槽）。 + - 若插槽存在，则优先使用插槽中的 items；否则回退到 default 插槽。 +- 插槽扩展 + - expandIcon：自定义展开图标，支持带参数渲染。 + - overflowedIndicator：溢出指示器（如“更多”按钮）。 + - popupRender：下拉弹层自定义渲染。 +- 事件透传 + - onOpenChange、onSelect、onDeselect 原样透传至 Antd Menu。 +- 性能优化 + - 使用 useMemo 缓存 items 计算结果，避免重复渲染。 + - 仅在 items 或 resolvedSlotItems 变更时重新计算。 + +章节来源 + +- [menu.tsx:14-93](file://frontend/antd/menu/menu.tsx#L14-L93) + +### 菜单项（MenuItem） + +- 类型识别 + - 当存在默认插槽子项时，自动识别为子菜单（SubMenu）；否则为普通菜单项（MenuItem）。 +- 样式类名 + - 自动注入 ms-gr-antd-menu-item 或 ms-gr-antd-menu-item-{type}，便于主题与样式定制。 +- 插槽处理 + - 将 icon 插槽以克隆方式注入到 Antd 的 icon 字段，确保图标与文本间距一致。 + +章节来源 + +- [menu.item.tsx:9-33](file://frontend/antd/menu/item/menu.item.tsx#L9-L33) + +### 项目上下文（createItemsContext） + +- 多插槽支持 + - 允许定义多个插槽（如 default、items），并通过 setItem 按索引写入。 +- 子项目收集 + - ItemHandler 内部再次包裹 ItemsContextProvider，形成“父级收集 + 子级收集”的树形结构。 +- 属性与子项变换 + - itemProps 与 itemChildren 支持对当前项的 props 与 children 进行变换，便于动态生成。 +- 变更通知 + - onChange 回调返回当前插槽下的完整 items，便于上层监听变化。 + +章节来源 + +- [createItemsContext.tsx:97-273](file://frontend/utils/createItemsContext.tsx#L97-L273) + +### 渲染器（renderItems） + +- 插槽注入 + - 将项目上下文中记录的插槽元素注入到对应字段（支持嵌套路径），并支持 withParams 的参数化插槽。 +- 克隆与强制克隆 + - clone 控制是否克隆节点；forceClone 在 withParams 时默认启用，保证参数传递正确。 +- 子项递归 + - 对 children 字段进行递归渲染，形成完整的菜单树。 +- 键值生成 + - 为每个项生成稳定 key，避免 React diff 异常。 + +章节来源 + +- [renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +### 样式与响应式（menu.less） + +- 图标与文本间距 + - 当存在图标时，自动为相邻文本设置 margin-inline-start，并添加过渡动画。 +- 折叠模式 + - 在内联折叠（inline-collapsed）状态下，隐藏文本，仅显示图标，提升空间利用率。 +- 动画与过渡 + - 通过 CSS 变量控制过渡时长与缓动，保证视觉一致性。 + +章节来源 + +- [menu.less:1-45](file://frontend/antd/menu/menu.less#L1-L45) + +### Svelte 入口（Index.svelte） + +- 属性与插槽处理 + - 通过 getProps/processProps 获取组件属性与附加属性，支持 visible 控制可见性。 + - 将 icon 插槽以克隆方式注入到 Antd 的 icon 字段。 +- 主题与样式 + - 支持 elem_id、elem_classes、elem_style 注入，便于主题与样式定制。 +- 条件渲染 + - 仅在 visible 为真时渲染 children。 + +章节来源 + +- [Index.svelte:1-84](file://frontend/antd/menu/item/Index.svelte#L1-L84) + +## 依赖关系分析 + +- 组件耦合 + - Menu 依赖 createItemsContext 与 renderItems；MenuItem 依赖 ItemHandler 与 context；Svelte 入口负责属性与插槽预处理。 +- 外部依赖 + - Ant Design Menu 作为底层 UI；ReactSlot 用于插槽渲染；classnames 用于类名拼接。 +- 循环依赖 + - 通过“导出工厂 + 上下文注入”的方式避免循环依赖；Menu 与 MenuItem 通过上下文解耦。 + +```mermaid +graph LR +Menu["menu.tsx"] --> Ctx["context.ts"] +Ctx --> CIC["createItemsContext.tsx"] +Menu --> RIT["renderItems.tsx"] +Menu --> AD["Antd Menu"] +MenuItem["menu.item.tsx"] --> Ctx +IDX["Index.svelte"] --> MenuItem +Menu --> LESS["menu.less"] +``` + +图表来源 + +- [menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [menu.item.tsx:1-36](file://frontend/antd/menu/item/menu.item.tsx#L1-L36) +- [Index.svelte:1-84](file://frontend/antd/menu/item/Index.svelte#L1-L84) +- [menu.less:1-45](file://frontend/antd/menu/menu.less#L1-L45) + +章节来源 + +- [menu.tsx:1-96](file://frontend/antd/menu/menu.tsx#L1-L96) +- [menu.item.tsx:1-36](file://frontend/antd/menu/item/menu.item.tsx#L1-L36) +- [Index.svelte:1-84](file://frontend/antd/menu/item/Index.svelte#L1-L84) +- [context.ts:1-7](file://frontend/antd/menu/context.ts#L1-L7) +- [createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [menu.less:1-45](file://frontend/antd/menu/menu.less#L1-L45) + +## 性能考虑 + +- 渲染缓存 + - Menu 中对 items 计算使用 useMemo，避免不必要的重渲染。 +- 事件函数记忆化 + - createItemsContext 内部使用 useMemoizedFn，减少回调函数重建带来的副作用。 +- 插槽克隆策略 + - 默认克隆插槽元素，避免 DOM 复用导致的状态错乱；在 withParams 场景下强制克隆。 +- 递归渲染优化 + - renderItems 仅对有效项进行过滤与映射，避免空项参与渲染。 + +章节来源 + +- [menu.tsx:46-54](file://frontend/antd/menu/menu.tsx#L46-L54) +- [createItemsContext.tsx:203-254](file://frontend/utils/createItemsContext.tsx#L203-L254) +- [renderItems.tsx:19-22](file://frontend/utils/renderItems.tsx#L19-L22) + +## 故障排查指南 + +- 插槽未生效 + - 检查插槽名称是否在 allowedSlots 中声明；确认插槽元素已正确注入到 ItemHandler 的 slots。 +- 图标不显示或文本不出现 + - 确认图标插槽已通过 Svelte 入口注入到 icon 字段；检查菜单处于折叠模式时的行为。 +- 事件未触发 + - 确认 Menu 是否正确透传 onOpenChange/onSelect/onDeselect；检查 Antd 版本兼容性。 +- 子菜单不展开 + - 检查子项 children 是否通过 renderItems 正确递归；确认 itemChildren 回调返回了正确的子项列表。 +- 样式异常 + - 检查是否引入了 menu.less；确认主题变量（如 --ms-gr-ant-menu-icon-margin-inline-end）是否正确设置。 + +章节来源 + +- [menu.tsx:35-88](file://frontend/antd/menu/menu.tsx#L35-L88) +- [menu.item.tsx:16-30](file://frontend/antd/menu/item/menu.item.tsx#L16-L30) +- [Index.svelte:69-78](file://frontend/antd/menu/item/Index.svelte#L69-L78) +- [menu.less:1-45](file://frontend/antd/menu/menu.less#L1-L45) + +## 结论 + +该菜单组件通过“容器 + 项包装 + 上下文”的架构，实现了对 Ant Design Menu 的增强与扩展，具备灵活的插槽系统、强大的子菜单与图标支持、良好的性能与可维护性。配合路由系统与权限控制，可快速构建复杂导航场景。 + +## 附录 + +### 使用示例（路径指引） + +- 基础示例 + - 参考文档示例标签：
主组件"] +F_item_index["Index.svelte
步骤项入口"] +F_item_impl["steps.item.tsx
步骤项实现"] +F_context["context.ts
步骤项上下文"] +F_pkg["package.json
导出配置"] +F_cfg["gradio.config.js
构建配置"] +end +subgraph "后端" +B_init["__init__.py
Python 封装"] +end +subgraph "文档" +D_readme["README.md
组件说明"] +end +F_steps_tsx --> F_context +F_steps_tsx --> F_item_impl +F_item_index --> F_item_impl +F_steps_tsx --> B_init +F_pkg --> F_steps_tsx +F_cfg --> F_steps_tsx +D_readme --> B_init +``` + +**图表来源** + +- [steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [steps.item.tsx:1-14](file://frontend/antd/steps/item/steps.item.tsx#L1-L14) +- [Index.svelte:1-65](file://frontend/antd/steps/item/Index.svelte#L1-L65) +- [context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) +- [package.json:1-15](file://frontend/antd/steps/package.json#L1-L15) +- [gradio.config.js:1-4](file://frontend/antd/steps/gradio.config.js#L1-L4) +- [**init**.py:1-95](file://backend/modelscope_studio/components/antd/steps/__init__.py#L1-L95) +- [README.md:1-8](file://docs/components/antd/steps/README.md#L1-L8) + +**章节来源** + +- [steps.tsx:1-52](file://frontend/antd/steps/steps.tsx#L1-L52) +- [steps.item.tsx:1-14](file://frontend/antd/steps/item/steps.item.tsx#L1-L14) +- [Index.svelte:1-65](file://frontend/antd/steps/item/Index.svelte#L1-L65) +- [context.ts:1-7](file://frontend/antd/steps/context.ts#L1-L7) +- [package.json:1-15](file://frontend/antd/steps/package.json#L1-L15) +- [gradio.config.js:1-4](file://frontend/antd/steps/gradio.config.js#L1-L4) +- [**init**.py:1-95](file://backend/modelscope_studio/components/antd/steps/__init__.py#L1-L95) +- [README.md:1-8](file://docs/components/antd/steps/README.md#L1-L8) + +## 核心组件 + +- 主组件 Steps（前端）：负责接收 props、解析 slots（如 progressDot）、合并 items 数据源（显式 items 或插槽 items/default），并将最终数据传递给 Ant Design 的 Steps。 +- 步骤项 StepsItem（前端）：作为步骤项的 React 包装器，通过 ItemHandler 上下文将步骤项注入到 Steps 容器中。 +- 步骤项入口 Index.svelte：在 Svelte 中渲染 StepsItem，并处理可见性、类名、ID、内联样式、插槽等属性。 +- 上下文 context：提供 createItemsContext 能力，使 Steps 与 StepsItem 之间建立稳定的父子关系与数据通道。 +- 后端封装 AntdSteps：提供丰富的属性（current、direction、size、status、type、responsive 等），并声明支持的 slots（progressDot、items）。 + +**章节来源** + +- [steps.tsx:10-49](file://frontend/antd/steps/steps.tsx#L10-L49) +- [steps.item.tsx:7-11](file://frontend/antd/steps/item/steps.item.tsx#L7-L11) +- [Index.svelte:16-64](file://frontend/antd/steps/item/Index.svelte#L16-L64) +- [context.ts:3-4](file://frontend/antd/steps/context.ts#L3-L4) +- [**init**.py:11-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L11-L77) + +## 架构总览 + +步骤条的运行时控制流如下：前端 Steps 组件从上下文读取步骤项集合，解析 items 或默认插槽；若存在 progressDot 插槽，则以参数化插槽方式渲染；否则回退到函数或布尔值形式。Ant Design 的 Steps 接收最终的 items 与进度点配置，渲染 UI 并触发 change 事件（由后端监听）。 + +```mermaid +sequenceDiagram +participant Py as "后端组件
AntdSteps" +participant FE as "前端组件
Steps" +participant Ctx as "上下文
withItemsContextProvider" +participant AD as "Ant Design Steps" +Py->>FE : 渲染组件并传入 props +FE->>Ctx : 请求当前步骤项集合 +Ctx-->>FE : 返回 items/default +FE->>FE : 解析 items 或默认插槽 +FE->>FE : 处理 progressDot 插槽/函数 +FE->>AD : 传入 items 与进度点配置 +AD-->>FE : 渲染 UI +FE-->>Py : 触发 change 事件由后端监听 +``` + +**图表来源** + +- [steps.tsx:16-44](file://frontend/antd/steps/steps.tsx#L16-L44) +- [context.ts:3-4](file://frontend/antd/steps/context.ts#L3-L4) +- [**init**.py:16-20](file://backend/modelscope_studio/components/antd/steps/__init__.py#L16-L20) + +**章节来源** + +- [steps.tsx:16-44](file://frontend/antd/steps/steps.tsx#L16-L44) +- [context.ts:3-4](file://frontend/antd/steps/context.ts#L3-L4) +- [**init**.py:16-20](file://backend/modelscope_studio/components/antd/steps/__init__.py#L16-L20) + +## 详细组件分析 + +### 步骤条主组件（Steps） + +- 功能职责 + - 接收 Ant Design Steps 的所有可用 props，并扩展 children 支持。 + - 通过上下文读取步骤项集合，优先使用显式 items，其次使用默认插槽 items/default。 + - 进度点配置支持两种形式：插槽 progressDot（参数化渲染）或函数/布尔值。 + - 使用 useMemo 对 items 进行稳定化处理，避免不必要的重渲染。 +- 关键行为 + - 隐藏 children（display: none）以避免重复渲染，实际内容通过插槽注入。 + - progressDot 的优先级：存在插槽则使用插槽渲染，否则使用函数或原生布尔/字符串配置。 +- 典型用法 + - 在 items 中直接传入步骤数组，或通过插槽注入步骤项。 + - 使用 progressDot 插槽来自定义每个步骤点的渲染逻辑。 + +```mermaid +flowchart TD +Start(["进入 Steps 渲染"]) --> ReadCtx["读取上下文中的 items/default"] +ReadCtx --> HasExplicit{"是否提供显式 items?"} +HasExplicit --> |是| UseExplicit["使用显式 items"] +HasExplicit --> |否| UseDefault["使用默认插槽 items/default"] +UseExplicit --> ResolveItems["解析步骤项列表"] +UseDefault --> ResolveItems +ResolveItems --> HasProgressDotSlot{"是否存在 progressDot 插槽?"} +HasProgressDotSlot --> |是| RenderSlot["参数化插槽渲染"] +HasProgressDotSlot --> |否| UseFuncOrProp["使用函数/布尔/字符串配置"] +RenderSlot --> RenderAD["渲染 Ant Design Steps"] +UseFuncOrProp --> RenderAD +RenderAD --> End(["完成"]) +``` + +**图表来源** + +- [steps.tsx:18-44](file://frontend/antd/steps/steps.tsx#L18-L44) + +**章节来源** + +- [steps.tsx:10-49](file://frontend/antd/steps/steps.tsx#L10-L49) + +### 步骤项（StepsItem） + +- 功能职责 + - 作为步骤项的 React 包装器，将步骤项属性与上下文结合，交由 ItemHandler 处理。 + - 通过 sveltify 将 TypeScript/React 组件桥接到 Svelte 生态。 +- 集成要点 + - 与 Steps 的上下文配合，确保步骤项被正确注入到容器中。 + - 支持额外属性透传与内部索引（itemIndex）传递。 + +```mermaid +classDiagram +class StepsItem { ++props : 步骤项属性 ++渲染到 ItemHandler +} +class ItemHandler { ++注入步骤项 ++维护上下文 +} +StepsItem --> ItemHandler : "包装并注入" +``` + +**图表来源** + +- [steps.item.tsx:7-11](file://frontend/antd/steps/item/steps.item.tsx#L7-L11) +- [context.ts:3-4](file://frontend/antd/steps/context.ts#L3-L4) + +**章节来源** + +- [steps.item.tsx:7-11](file://frontend/antd/steps/item/steps.item.tsx#L7-L11) +- [context.ts:3-4](file://frontend/antd/steps/context.ts#L3-L4) + +### 步骤项入口（Index.svelte） + +- 功能职责 + - 在 Svelte 中动态导入 StepsItem 并渲染。 + - 处理可见性、类名、ID、内联样式、插槽等属性。 + - 将子节点通过 {@render children()} 注入到 StepsItem。 +- 设计要点 + - 使用 getProps/processProps 获取并过滤不需要透传的内部属性。 + - 通过 getSlotKey 获取插槽键，传递给 StepsItem 以便插槽识别。 + +```mermaid +flowchart TD +SStart(["Index.svelte 渲染开始"]) --> ImportItem["动态导入 StepsItem"] +ImportItem --> GetProps["提取组件与附加属性"] +GetProps --> CheckVisible{"可见性检查"} +CheckVisible --> |隐藏| Skip["跳过渲染"] +CheckVisible --> |显示| RenderItem["渲染 StepsItem 并传入属性/插槽"] +RenderItem --> SEnd(["结束"]) +Skip --> SEnd +``` + +**图表来源** + +- [Index.svelte:16-64](file://frontend/antd/steps/item/Index.svelte#L16-L64) + +**章节来源** + +- [Index.svelte:1-65](file://frontend/antd/steps/item/Index.svelte#L1-L65) + +### 后端封装（AntdSteps） + +- 属性概览（节选） + - 当前步骤 current、方向 direction（horizontal/vertical）、初始值 initial、标签位置 label_placement、标题位置 title_placement、百分比 percent、进度点 progress_dot、响应式 responsive、尺寸 size（small/default）、状态 status（wait/process/finish/error）、类型 type（default/navigation/inline）、根类名 root_class_name、类名 class_names、样式 styles、插槽 items/progressDot 等。 +- 事件 + - change：监听步骤变更事件（由后端绑定）。 +- 其他 + - FRONTEND_DIR 指向前端 steps 组件目录。 + - skip_api 为 True，表示该组件不参与标准 API 流程。 + +```mermaid +classDiagram +class AntdSteps { ++current : number ++direction : "horizontal|vertical" ++initial : number ++label_placement : "horizontal|vertical" ++title_placement : "horizontal|vertical"|None ++percent : number|None ++progress_dot : bool|string ++responsive : bool ++size : "small|default"|None ++status : "wait|process|finish|error" ++type : "default|navigation|inline" ++items : list|None ++root_class_name : str|None ++class_names : dict|str|None ++styles : dict|str|None ++EVENTS : ["change"] ++SLOTS : ["progressDot","items"] +} +``` + +**图表来源** + +- [**init**.py:25-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L25-L77) + +**章节来源** + +- [**init**.py:11-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L11-L77) + +## 依赖关系分析 + +- 前端依赖 + - 使用 Ant Design 的 Steps 作为底层 UI 组件。 + - 通过 sveltify 将 React 组件桥接到 Svelte。 + - 通过 createItemsContext 提供步骤项上下文。 + - 使用 renderItems/renderParamsSlot 渲染步骤项与插槽。 +- 后端依赖 + - 通过 ModelScopeLayoutComponent 与 Gradio 交互。 + - 通过 resolve_frontend_dir 指定前端组件目录。 +- 导出与构建 + - package.json 指定 Gradio 与默认导出路径。 + - gradio.config.js 基于全局 defineConfig 进行构建配置。 + +```mermaid +graph LR +Pkg["package.json"] --> StepsTSX["steps.tsx"] +Cfg["gradio.config.js"] --> StepsTSX +StepsTSX --> AD["Ant Design Steps"] +StepsTSX --> Ctx["createItemsContext"] +StepsTSX --> Utils["renderItems / renderParamsSlot"] +StepsTSX --> Py["AntdSteps(__init__.py)"] +``` + +**图表来源** + +- [package.json:4-12](file://frontend/antd/steps/package.json#L4-L12) +- [gradio.config.js:1-4](file://frontend/antd/steps/gradio.config.js#L1-L4) +- [steps.tsx:1-8](file://frontend/antd/steps/steps.tsx#L1-L8) +- [**init**.py:77-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L77-L77) + +**章节来源** + +- [package.json:1-15](file://frontend/antd/steps/package.json#L1-L15) +- [gradio.config.js:1-4](file://frontend/antd/steps/gradio.config.js#L1-L4) +- [steps.tsx:1-8](file://frontend/antd/steps/steps.tsx#L1-L8) +- [**init**.py:77-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L77-L77) + +## 性能考量 + +- 数据稳定化：通过 useMemo 对 items 进行稳定化处理，减少不必要的重渲染。 +- 插槽渲染：progressDot 插槽采用参数化渲染，避免在每次渲染中重复创建复杂结构。 +- 可见性控制：步骤项入口对 visible 进行判断，隐藏不可见项，降低 DOM 开销。 +- 事件绑定：仅在需要时绑定 change 事件，避免无谓的回调触发。 + +[本节为通用性能建议，无需特定文件引用] + +## 故障排查指南 + +- 问题：步骤项未显示 + - 检查 Steps 是否正确注入了 items 或插槽 items/default。 + - 确认步骤项的 visible 属性是否为真。 +- 问题：进度点未按预期渲染 + - 若使用 progressDot 插槽，请确认插槽键与组件约定一致。 + - 若使用函数/布尔值，请确认传入的配置与 Ant Design 的期望一致。 +- 问题：样式或类名未生效 + - 检查 root_class_name、class_names、styles 的传入是否正确。 + - 确认 CSS 作用域与覆盖规则。 +- 问题：响应式布局异常 + - 检查 responsive 与 direction 的组合使用是否符合预期。 + - 确认父容器的宽度与断点设置。 + +**章节来源** + +- [steps.tsx:20-44](file://frontend/antd/steps/steps.tsx#L20-L44) +- [Index.svelte:49-64](file://frontend/antd/steps/item/Index.svelte#L49-L64) +- [**init**.py:25-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L25-L77) + +## 结论 + +步骤条组件通过清晰的前后端分层设计，实现了对 Ant Design Steps 的完整封装与扩展。其支持多布局、多状态、可定制进度点与响应式适配，适用于表单向导、业务流程与用户注册等多种场景。通过上下文与插槽机制，组件具备良好的可组合性与可维护性。 + +[本节为总结性内容，无需特定文件引用] + +## 附录 + +### 步骤项（Item）配置选项 + +- 基础属性 + - 标题：用于步骤项的标题文本。 + - 描述：用于步骤项的描述文本。 + - 图标：用于步骤项的图标元素。 +- 状态与行为 + - 状态：wait、process、finish、error，用于指示步骤当前状态。 + - 可见性：visible 控制步骤项是否渲染。 + - 内部索引：itemIndex 用于标识步骤项在列表中的位置。 +- 插槽与样式 + - 插槽：支持通过插槽注入自定义内容。 + - 类名与 ID：elem_classes、elem_id 用于样式与定位。 + - 内联样式：elem_style 用于局部样式覆盖。 + +**章节来源** + +- [Index.svelte:16-64](file://frontend/antd/steps/item/Index.svelte#L16-L64) +- [steps.item.tsx:7-11](file://frontend/antd/steps/item/steps.item.tsx#L7-L11) + +### 布局模式与应用场景 + +- 水平步骤条（horizontal） + - 适合线性流程，如表单向导、支付流程。 +- 垂直步骤条（vertical） + - 适合长流程或需要强调时间顺序的场景。 +- 小型步骤条（small） + - 适合空间受限或需要简洁呈现的界面。 + +**章节来源** + +- [**init**.py:30-39](file://backend/modelscope_studio/components/antd/steps/__init__.py#L30-L39) + +### 与表单向导、业务流程、用户注册的集成 + +- 表单向导 + - 使用 current 与 status 控制当前步骤与状态；通过 change 事件同步后端状态。 +- 业务流程 + - 使用 direction 与 responsive 实现流程可视化；使用 progress_dot 自定义流程节点。 +- 用户注册 + - 使用 size 与 type 切换不同风格；使用 items 与插槽组织注册步骤。 + +**章节来源** + +- [**init**.py:25-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L25-L77) +- [steps.tsx:16-44](file://frontend/antd/steps/steps.tsx#L16-L44) + +### 样式定制与响应式适配 + +- 样式定制 + - 使用 root_class_name、class_names、styles 进行整体与局部样式控制。 + - 通过 elem_classes、elem_id、elem_style 精细化控制步骤项外观。 +- 响应式适配 + - 使用 responsive 与 direction 组合，适配移动端与桌面端布局。 + +**章节来源** + +- [**init**.py:40-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L40-L77) +- [Index.svelte:52-58](file://frontend/antd/steps/item/Index.svelte#L52-L58) + +### 使用示例与最佳实践 + +- 示例参考 + - 文档中提供基础示例占位，可结合后端 AntdSteps 的属性与插槽进行演示。 +- 最佳实践 + - 明确步骤状态与导航逻辑，避免状态错乱。 + - 合理使用 progress_dot 插槽，保持视觉一致性。 + - 在复杂流程中拆分步骤，提升用户体验。 + +**章节来源** + +- [README.md:1-8](file://docs/components/antd/steps/README.md#L1-L8) +- [**init**.py:25-77](file://backend/modelscope_studio/components/antd/steps/__init__.py#L25-L77) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\351\224\232\347\202\271\347\273\204\344\273\266 (Anchor).md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\351\224\232\347\202\271\347\273\204\344\273\266 (Anchor).md" new file mode 100644 index 00000000..c681a2ec --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\351\224\232\347\202\271\347\273\204\344\273\266 (Anchor).md" @@ -0,0 +1,302 @@ +# 锚点组件（Anchor） + + +**本文引用的文件** +- [frontend/antd/anchor/Index.svelte](file://frontend/antd/anchor/Index.svelte) +- [frontend/antd/anchor/anchor.tsx](file://frontend/antd/anchor/anchor.tsx) +- [frontend/antd/anchor/context.ts](file://frontend/antd/anchor/context.ts) +- [frontend/antd/anchor/item/Index.svelte](file://frontend/antd/anchor/item/Index.svelte) +- [frontend/antd/anchor/item/anchor.item.tsx](file://frontend/antd/anchor/item/anchor.item.tsx) +- [backend/modelscope_studio/components/antd/anchor/__init__.py](file://backend/modelscope_studio/components/antd/anchor/__init__.py) +- [backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js](file://backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js) +- [docs/components/antd/anchor/README.md](file://docs/components/antd/anchor/README.md) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +锚点组件用于在单页内提供可点击的导航链接，支持滚动定位到对应标题或区域，并可结合固定模式（Affix）在页面滚动时保持可见。本组件基于 Ant Design 的 Anchor 组件进行封装，提供以下能力： + +- 滚动定位：根据锚点项的目标位置进行平滑或直接跳转 +- 链接生成：支持通过 items 列表或插槽动态生成锚点项 +- 激活状态管理：自动高亮当前处于可视区域内的锚点项 +- 嵌套结构：锚点项支持嵌套，形成层级化导航 +- 事件与扩展：支持 change、click、affix_change 等事件绑定，以及 affix 固定模式 + +## 项目结构 + +锚点组件由前端 Svelte 包装层与后端 Gradio 组件层共同构成，同时提供锚点项子组件以支持嵌套与插槽渲染。 + +```mermaid +graph TB +subgraph "前端" +A_Index["frontend/antd/anchor/Index.svelte"] +A_Component["frontend/antd/anchor/anchor.tsx"] +A_Context["frontend/antd/anchor/context.ts"] +A_Item_Index["frontend/antd/anchor/item/Index.svelte"] +A_Item_Component["frontend/antd/anchor/item/anchor.item.tsx"] +end +subgraph "后端" +B_Anchor["backend/modelscope_studio/components/antd/anchor/__init__.py"] +B_Item_Template["backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js"] +end +subgraph "文档" +D_Readme["docs/components/antd/anchor/README.md"] +end +A_Index --> A_Component +A_Component --> A_Context +A_Item_Index --> A_Item_Component +A_Component --> B_Anchor +A_Item_Component --> B_Item_Template +D_Readme --> B_Anchor +``` + +图表来源 + +- [frontend/antd/anchor/Index.svelte:1-66](file://frontend/antd/anchor/Index.svelte#L1-L66) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [frontend/antd/anchor/item/Index.svelte:1-75](file://frontend/antd/anchor/item/Index.svelte#L1-L75) +- [frontend/antd/anchor/item/anchor.item.tsx:1-22](file://frontend/antd/anchor/item/anchor.item.tsx#L1-L22) +- [backend/modelscope_studio/components/antd/anchor/**init**.py:1-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L1-L117) +- [backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js:1-450](file://backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js#L1-L450) +- [docs/components/antd/anchor/README.md:1-8](file://docs/components/antd/anchor/README.md#L1-L8) + +章节来源 + +- [frontend/antd/anchor/Index.svelte:1-66](file://frontend/antd/anchor/Index.svelte#L1-L66) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [frontend/antd/anchor/item/Index.svelte:1-75](file://frontend/antd/anchor/item/Index.svelte#L1-L75) +- [frontend/antd/anchor/item/anchor.item.tsx:1-22](file://frontend/antd/anchor/item/anchor.item.tsx#L1-L22) +- [backend/modelscope_studio/components/antd/anchor/**init**.py:1-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L1-L117) +- [backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js:1-450](file://backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js#L1-L450) +- [docs/components/antd/anchor/README.md:1-8](file://docs/components/antd/anchor/README.md#L1-L8) + +## 核心组件 + +- 顶层锚点组件（AntdAnchor） + - 负责接收 items 列表或插槽 children，将其转换为 Ant Design Anchor 所需的 items 结构 + - 支持 affix、bounds、offsetTop、direction、replace、rootClassName 等属性 + - 提供 change、click、affix_change 事件绑定入口 +- 锚点项组件（AntdAnchorItem） + - 作为锚点项的容器，支持默认插槽内容渲染 + - 通过上下文系统与父级锚点组件协作，实现嵌套与层级展示 + +章节来源 + +- [backend/modelscope_studio/components/antd/anchor/**init**.py:11-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L11-L117) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [frontend/antd/anchor/item/Index.svelte:1-75](file://frontend/antd/anchor/item/Index.svelte#L1-L75) +- [frontend/antd/anchor/item/anchor.item.tsx:1-22](file://frontend/antd/anchor/item/anchor.item.tsx#L1-L22) + +## 架构总览 + +下图展示了从后端 Gradio 组件到前端 Svelte/React 包装层，再到 Ant Design Anchor 的调用链路，以及事件与插槽的传递过程。 + +```mermaid +sequenceDiagram +participant Backend as "后端组件
AntdAnchor" +participant FrontIndex as "前端包装
Index.svelte" +participant AnchorTSX as "前端实现
anchor.tsx" +participant Context as "上下文
context.ts" +participant Antd as "Ant Design Anchor" +Backend->>FrontIndex : 渲染包装组件并传入 props +FrontIndex->>AnchorTSX : 传递 restProps、additionalProps、slots +AnchorTSX->>Context : 使用 Items 上下文解析插槽 items/default +AnchorTSX->>Antd : 渲染 Anchor 并注入 items、getContainer、getCurrentAnchor +Antd-->>AnchorTSX : 触发 change/click/affix_change 等事件回调 +AnchorTSX-->>FrontIndex : 事件透传至后端 +``` + +图表来源 + +- [frontend/antd/anchor/Index.svelte:1-66](file://frontend/antd/anchor/Index.svelte#L1-L66) +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [backend/modelscope_studio/components/antd/anchor/**init**.py:11-33](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L11-L33) + +## 详细组件分析 + +### 顶层锚点组件（AntdAnchor） + +- 功能特性 + - 接收 items 列表或插槽 children，内部通过工具函数将插槽转换为 items + - 支持 getContainer、getCurrentAnchor 自定义容器与当前锚点判定逻辑 + - 提供 affix 固定模式、bounds 边界距离、offsetTop 顶部偏移、direction 方向、replace 替换历史等配置 + - 事件：change（锚点变化）、click（点击）、affix_change（固定状态变化） +- 数据流 + - 插槽 items/default → 上下文解析 → Ant Design Anchor items + - getContainer/getCurrentAnchor 通过 useFunction 包装后传入 Ant Design Anchor +- 适用场景 + - 文档目录、长列表导航、帮助中心、产品介绍页等需要快速跳转的场景 + +```mermaid +flowchart TD +Start(["开始"]) --> Resolve["解析插槽 items/default"] +Resolve --> HasItems{"是否有 items 参数?"} +HasItems --> |是| UseParam["使用传入 items"] +HasItems --> |否| RenderItems["通过工具函数渲染 items"] +UseParam --> BuildProps["构建 Anchor 属性"] +RenderItems --> BuildProps +BuildProps --> Inject["注入 getContainer / getCurrentAnchor"] +Inject --> Render["渲染 Ant Design Anchor"] +Render --> End(["结束"]) +``` + +图表来源 + +- [frontend/antd/anchor/anchor.tsx:13-42](file://frontend/antd/anchor/anchor.tsx#L13-L42) + +章节来源 + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [backend/modelscope_studio/components/antd/anchor/**init**.py:38-98](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L38-L98) + +### 锚点项组件（AntdAnchorItem） + +- 功能特性 + - 作为锚点项的容器，支持默认插槽内容渲染 + - 通过 ItemHandler 将插槽内容映射为 AntdAnchor 的 item 子项 + - 支持 href_target 属性映射为 target 属性，便于控制链接打开方式 +- 嵌套结构 + - 通过 createItemsContext 与父级协作，支持多层嵌套的锚点项 +- 适用场景 + - 在复杂文档中对章节进行分组与层级化展示 + +```mermaid +classDiagram +class AnchorItem { ++允许插槽 : "default" ++属性 : "href_target" -> "target" ++功能 : "将插槽内容映射为 item 子项" +} +class Context { ++useItems() ++withItemsContextProvider() ++ItemHandler +} +AnchorItem --> Context : "使用上下文" +``` + +图表来源 + +- [frontend/antd/anchor/item/anchor.item.tsx:1-22](file://frontend/antd/anchor/item/anchor.item.tsx#L1-L22) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) + +章节来源 + +- [frontend/antd/anchor/item/Index.svelte:1-75](file://frontend/antd/anchor/item/Index.svelte#L1-L75) +- [frontend/antd/anchor/item/anchor.item.tsx:1-22](file://frontend/antd/anchor/item/anchor.item.tsx#L1-L22) +- [backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js:437-449](file://backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js#L437-L449) + +### 事件与生命周期 + +- change：当当前激活的锚点发生变化时触发 +- click：点击锚点链接时触发 +- affix_change：当固定模式（Affix）状态改变时触发 +- 生命周期：组件在退出作用域时会更新布局标记，确保渲染顺序正确 + +章节来源 + +- [backend/modelscope_studio/components/antd/anchor/**init**.py:20-33](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L20-L33) +- [backend/modelscope_studio/utils/dev/component.py:24-26](file://backend/modelscope_studio/utils/dev/component.py#L24-L26) + +## 依赖关系分析 + +- 前端包装层依赖 Ant Design Anchor 组件，通过 sveltify 与 withItemsContextProvider 进行桥接 +- 插槽系统通过 createItemsContext 实现父子组件通信，支持 items/default 两种插槽 +- 后端组件继承自 ModelScopeLayoutComponent，提供统一的布局与事件绑定能力 + +```mermaid +graph LR +AnchorTSX["anchor.tsx"] --> Antd["Ant Design Anchor"] +AnchorTSX --> Context["context.ts"] +AnchorItemTSX["anchor.item.tsx"] --> Context +AnchorTSX --> Backend["AntdAnchor(__init__.py)"] +AnchorItemTSX --> BackendItem["anchor.item 模板"] +``` + +图表来源 + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [frontend/antd/anchor/item/anchor.item.tsx:1-22](file://frontend/antd/anchor/item/anchor.item.tsx#L1-L22) +- [backend/modelscope_studio/components/antd/anchor/**init**.py:1-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L1-L117) +- [backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js:1-450](file://backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js#L1-L450) + +章节来源 + +- [frontend/antd/anchor/anchor.tsx:1-46](file://frontend/antd/anchor/anchor.tsx#L1-L46) +- [frontend/antd/anchor/context.ts:1-7](file://frontend/antd/anchor/context.ts#L1-L7) +- [frontend/antd/anchor/item/anchor.item.tsx:1-22](file://frontend/antd/anchor/item/anchor.item.tsx#L1-L22) +- [backend/modelscope_studio/components/antd/anchor/**init**.py:1-117](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L1-L117) +- [backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js:1-450](file://backend/modelscope_studio/components/antd/anchor/item/templates/component/anchor.item-DRmYMecq.js#L1-L450) + +## 性能考量 + +- items 渲染优化 + - 使用 useMemo 缓存 items 计算结果，避免不必要的重渲染 + - 优先传入 items 参数而非依赖插槽，减少插槽解析成本 +- 函数包装 + - 通过 useFunction 包装 getContainer/getCurrentAnchor，确保回调稳定且可复用 +- 滚动监听 + - 合理设置 bounds 与 offsetTop，避免频繁触发 change 事件 + - 在大文档中建议使用 replace 替换历史记录，减少内存占用 +- 固定模式（Affix） + - affix 模式会在滚动时保持可见，注意容器选择与层级关系，避免遮挡 + +## 故障排查指南 + +- 锚点不生效 + - 检查 getContainer 是否指向正确的滚动容器；若未设置，可能无法正确计算可视区域 + - 确认目标元素存在且具有对应的锚点标识 +- 激活状态不更新 + - 检查 bounds 与 offsetTop 设置是否合理；过小的边界可能导致切换不及时 + - 确认 getCurrentAnchor 返回值与 items 中的 key 或 href 匹配 +- 链接打开行为异常 + - href_target 映射为 target，确认是否需要在新窗口或当前窗口打开 +- 事件未触发 + - 确认事件绑定是否启用（bind_change_event、bind_click_event、bind_affix_change_event） + - 检查 affix 模式下的状态变化是否符合预期 + +章节来源 + +- [frontend/antd/anchor/anchor.tsx:13-42](file://frontend/antd/anchor/anchor.tsx#L13-L42) +- [backend/modelscope_studio/components/antd/anchor/**init**.py:20-33](file://backend/modelscope_studio/components/antd/anchor/__init__.py#L20-L33) + +## 结论 + +锚点组件通过前后端协同的方式，提供了灵活的锚点导航能力。其核心优势在于： + +- 通过 items 与插槽双通道生成锚点项，满足不同场景需求 +- 与 Ant Design Anchor 深度集成，具备完善的滚动定位与激活状态管理 +- 事件体系完善，便于扩展交互与埋点统计 +- 支持嵌套结构与固定模式，适合复杂文档与长页面导航 + +## 附录 + +- 使用示例与文档 + - 参考文档中的基础示例，了解基本用法与参数说明 +- 常见问题 + - 若页面存在多个滚动容器，请明确指定 getContainer + - 大文档建议开启 replace 以优化历史记录管理 + - 如需自定义高亮策略，可通过 getCurrentAnchor 定制 + +章节来源 + +- [docs/components/antd/anchor/README.md:1-8](file://docs/components/antd/anchor/README.md#L1-L8) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\351\235\242\345\214\205\345\261\221\347\273\204\344\273\266 (Breadcrumb).md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\351\235\242\345\214\205\345\261\221\347\273\204\344\273\266 (Breadcrumb).md" new file mode 100644 index 00000000..d1b33565 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\257\274\350\210\252\347\273\204\344\273\266/\351\235\242\345\214\205\345\261\221\347\273\204\344\273\266 (Breadcrumb).md" @@ -0,0 +1,393 @@ +# 面包屑组件（Breadcrumb） + + +**本文引用的文件** +- [frontend/antd/breadcrumb/breadcrumb.tsx](file://frontend/antd/breadcrumb/breadcrumb.tsx) +- [frontend/antd/breadcrumb/context.ts](file://frontend/antd/breadcrumb/context.ts) +- [frontend/antd/breadcrumb/Index.svelte](file://frontend/antd/breadcrumb/Index.svelte) +- [backend/modelscope_studio/components/antd/breadcrumb/__init__.py](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py) +- [backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) +- [docs/components/antd/breadcrumb/README.md](file://docs/components/antd/breadcrumb/README.md) +- [docs/components/antd/breadcrumb/README-zh_CN.md](file://docs/components/antd/breadcrumb/README-zh_CN.md) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：使用示例与最佳实践](#附录使用示例与最佳实践) + +## 简介 + +面包屑组件用于在层级结构中显示当前位置，并允许用户返回上层状态。本仓库中的面包屑组件基于 Ant Design 的 Breadcrumb 实现，通过 React 包装与 Svelte 前端桥接，同时提供 Python 后端组件以支持 Gradio 生态下的布局与事件绑定。组件支持： + +- 导航路径展示与点击跳转 +- 自定义分隔符与每个面包屑项的渲染 +- 下拉菜单与溢出指示器等高级交互 +- 与路由系统集成时的动态路径生成与权限控制 +- 多语言与主题样式定制 + +## 项目结构 + +面包屑组件由前端 React 包装层、Svelte 桥接层、后端 Gradio 组件层以及运行时模板组成，整体结构如下： + +```mermaid +graph TB +subgraph "前端" +SvelteIndex["frontend/antd/breadcrumb/Index.svelte"] +ReactWrapper["frontend/antd/breadcrumb/breadcrumb.tsx"] +ItemsCtx["frontend/antd/breadcrumb/context.ts"] +end +subgraph "后端" +PyComp["backend/modelscope_studio/components/antd/breadcrumb/__init__.py"] +PyItem["backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py"] +DevBase["backend/modelscope_studio/utils/dev/component.py"] +ResolveDir["backend/modelscope_studio/utils/dev/resolve_frontend_dir.py"] +end +subgraph "运行时模板" +RuntimeJS["backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js"] +end +SvelteIndex --> ReactWrapper +ReactWrapper --> ItemsCtx +PyComp --> ResolveDir +PyComp --> RuntimeJS +PyItem --> ResolveDir +PyItem --> RuntimeJS +DevBase --> PyComp +DevBase --> PyItem +``` + +图示来源 + +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:1-114](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L1-L114) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:1-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L1-L17) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:1-766](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L1-L766) + +章节来源 + +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:1-114](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L1-L114) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:1-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L1-L17) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:1-766](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L1-L766) + +## 核心组件 + +- 前端 React 包装：负责将 Ant Design 的 Breadcrumb 与 Slots 渲染系统对接，支持自定义分隔符、项渲染函数与下拉图标。 +- Svelte 桥接：将后端传入的属性与插槽转换为前端可消费的 props，并按需引入 React 组件。 +- 后端组件：提供 AntdBreadcrumb 与 AntdBreadcrumbItem，支持事件绑定、插槽与前端目录解析。 +- 运行时模板：包含实际的 React 组件实现与插槽处理逻辑。 + +章节来源 + +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:1-114](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L1-L114) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:1-766](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L1-L766) + +## 架构总览 + +面包屑组件的调用链从后端到前端如下： + +```mermaid +sequenceDiagram +participant Py as "Python 后端组件
AntdBreadcrumb/AntdBreadcrumbItem" +participant Svelte as "Svelte 桥接
Index.svelte" +participant React as "React 包装
breadcrumb.tsx" +participant AD as "Ant Design Breadcrumb" +Py->>Svelte : 解析前端目录并传递属性/插槽 +Svelte->>React : 转换 props 并注入 slots +React->>AD : 渲染 Breadcrumb，应用自定义分隔符/项渲染/下拉图标 +AD-->>React : 渲染结果 +React-->>Svelte : 返回 DOM +Svelte-->>Py : 完成渲染 +``` + +图示来源 + +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:1-114](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L1-L114) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:1-766](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L1-L766) + +## 详细组件分析 + +### 前端 React 包装（breadcrumb.tsx） + +- 功能要点 + - 使用 sveltify 将 Svelte 组件桥接到 React。 + - 通过 withItemsContextProvider 提供面包屑项上下文。 + - 支持 slots：separator、itemRender、dropdownIcon；优先使用插槽，否则回退到 props。 + - 使用 renderItems 将插槽项转换为 Ant Design 所需的 ItemType 列表。 + - 使用 renderParamsSlot 渲染带参数的 itemRender 插槽。 +- 关键流程 + - 读取上下文中的 items/default。 + - 计算最终 items 列表（items 优先于插槽）。 + - 渲染 Ant Design Breadcrumb，并注入自定义分隔符与项渲染。 + +```mermaid +flowchart TD +Start(["进入 React 包装"]) --> ReadCtx["读取上下文 items/default"] +ReadCtx --> DecideItems{"是否提供 items 参数？"} +DecideItems --> |是| UseParam["使用传入 items"] +DecideItems --> |否| UseSlot["使用插槽 items/default"] +UseParam --> RenderItems["renderItems 转换为 AntD Item 类型"] +UseSlot --> RenderItems +RenderItems --> ApplySlots{"插槽是否存在？"} +ApplySlots --> |分隔符| SepSlot["使用 separator 插槽"] +ApplySlots --> |项渲染| ItemRenderSlot["使用 itemRender 插槽"] +ApplySlots --> |下拉图标| DropSlot["使用 dropdownIcon 插槽"] +ApplySlots --> |无| UseProps["使用 props 原值"] +SepSlot --> RenderAD["渲染 AntD Breadcrumb"] +ItemRenderSlot --> RenderAD +DropSlot --> RenderAD +UseProps --> RenderAD +RenderAD --> End(["完成"]) +``` + +图示来源 + +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:727-761](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L727-L761) + +章节来源 + +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [frontend/antd/breadcrumb/context.ts:1-7](file://frontend/antd/breadcrumb/context.ts#L1-L7) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:727-761](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L727-L761) + +### Svelte 桥接（Index.svelte） + +- 功能要点 + - 获取后端传入的 props 与附加属性。 + - 将事件名映射为 Ant Design 所需的驼峰命名。 + - 将 children 渲染为 React 组件的子节点。 + - 通过 importComponent 异步加载 React 包装的 Breadcrumb。 +- 关键流程 + - processProps 将属性标准化并处理事件别名。 + - getSlots 获取插槽集合。 + - 渲染 Breadcrumb 并传入 slots 与 children。 + +```mermaid +sequenceDiagram +participant Svelte as "Index.svelte" +participant Loader as "importComponent" +participant Wrapper as "breadcrumb.tsx" +Svelte->>Loader : 加载 React 包装组件 +Loader-->>Svelte : 返回组件引用 +Svelte->>Wrapper : 传入 props/slots/children +Wrapper-->>Svelte : 返回渲染结果 +``` + +图示来源 + +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) + +章节来源 + +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) + +### 后端组件（AntdBreadcrumb / AntdBreadcrumbItem） + +- AntdBreadcrumb + - 支持插槽：separator、itemRender、items、dropdownIcon。 + - 通过 resolve_frontend_dir 指向前端 breadcrumb 目录。 + - 继承 ModelScopeLayoutComponent，具备布局组件通用能力。 +- AntdBreadcrumbItem + - 支持插槽：title、menu._、dropdownProps._、dropdownProps.menu.\*。 + - 支持事件：click、menu*\*、dropdownProps*\* 等，用于与路由或菜单交互。 + - 通过 resolve_frontend_dir 指向前端 breadcrumb/item 子组件目录。 + +```mermaid +classDiagram +class ModelScopeLayoutComponent { ++skip_api : bool ++SLOTS : list ++__init__(...) +} +class AntdBreadcrumb { ++SLOTS : list ++FRONTEND_DIR : str ++__init__(...) +} +class AntdBreadcrumbItem { ++SLOTS : list ++EVENTS : list ++FRONTEND_DIR : str ++__init__(...) +} +ModelScopeLayoutComponent <|-- AntdBreadcrumb +ModelScopeLayoutComponent <|-- AntdBreadcrumbItem +``` + +图示来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:1-114](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L1-L114) + +章节来源 + +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:1-114](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L1-L114) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:1-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L1-L17) + +### 运行时模板（breadcrumb-C7MaDQtV.js） + +- 功能要点 + - 提供 createItemsContext 上下文，用于在 React 层共享面包屑项。 + - 提供 renderItems 与 renderParamsSlot 的运行时实现，支持插槽克隆与参数化渲染。 + - 将 Svelte 插槽转换为 React 可消费的结构，支持嵌套插槽与菜单项。 +- 关键流程 + - 从上下文读取 items/default。 + - 使用 ve/oe/Mt 等工具函数将插槽转换为 AntD 所需的 props。 + - 渲染 AntD Breadcrumb，并应用自定义分隔符与项渲染。 + +```mermaid +flowchart TD +LoadCtx["读取上下文 items/default"] --> MergeItems["合并 items/default"] +MergeItems --> Convert["ve/oe/Mt 转换插槽为 React 结构"] +Convert --> RenderAD["渲染 AntD Breadcrumb"] +RenderAD --> Done(["完成"]) +``` + +图示来源 + +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:727-761](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L727-L761) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:649-726](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L649-L726) + +章节来源 + +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:1-766](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L1-L766) + +## 依赖关系分析 + +- 前端依赖 + - React 包装依赖 Ant Design Breadcrumb 类型与渲染工具。 + - Svelte 桥接依赖 @svelte-preprocess-react 的组件导入与插槽系统。 +- 后端依赖 + - AntdBreadcrumb/AntdBreadcrumbItem 依赖 resolve_frontend_dir 解析前端目录。 + - 继承 ModelScopeLayoutComponent，复用布局组件通用能力。 +- 运行时依赖 + - 模板文件提供插槽与上下文处理逻辑，确保前后端一致的渲染行为。 + +```mermaid +graph LR +PyComp["AntdBreadcrumb"] --> Resolve["resolve_frontend_dir"] +PyItem["AntdBreadcrumbItem"] --> Resolve +PyComp --> Runtime["运行时模板 breadcrumb-C7MaDQtV.js"] +PyItem --> Runtime +Svelte["Index.svelte"] --> ReactWrap["breadcrumb.tsx"] +ReactWrap --> AD["Ant Design Breadcrumb"] +``` + +图示来源 + +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:56-56](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L56-L56) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:97-97](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L97-L97) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:4-16](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L4-L16) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:1-766](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L1-L766) +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) + +章节来源 + +- [backend/modelscope_studio/components/antd/breadcrumb/**init**.py:1-73](file://backend/modelscope_studio/components/antd/breadcrumb/__init__.py#L1-L73) +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:1-114](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L1-L114) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py:1-17](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py#L1-L17) +- [frontend/antd/breadcrumb/Index.svelte:1-78](file://frontend/antd/breadcrumb/Index.svelte#L1-L78) +- [frontend/antd/breadcrumb/breadcrumb.tsx:1-67](file://frontend/antd/breadcrumb/breadcrumb.tsx#L1-L67) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:1-766](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L1-L766) + +## 性能考量 + +- 插槽克隆策略 + - 插槽渲染默认采用克隆策略，避免重复渲染开销，但可通过 forceClone 控制。 +- 计算缓存 + - 使用 useMemo 缓存最终 items 列表，减少不必要的重渲染。 +- 事件映射 + - 在 Svelte 层统一进行事件名驼峰化映射，降低运行时转换成本。 +- 模板优化 + - 运行时模板提供稳定的插槽转换与上下文合并逻辑，减少分支判断与对象拷贝。 + +章节来源 + +- [frontend/antd/breadcrumb/breadcrumb.tsx:44-51](file://frontend/antd/breadcrumb/breadcrumb.tsx#L44-L51) +- [frontend/antd/breadcrumb/Index.svelte:27-58](file://frontend/antd/breadcrumb/Index.svelte#L27-L58) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:190-206](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L190-L206) + +## 故障排查指南 + +- 插槽未生效 + - 确认插槽名称正确（如 separator、itemRender），并在 React 包装层已声明支持。 + - 检查插槽元素是否存在于 children 中，且未被隐藏或移除。 +- 事件未触发 + - 确认事件名称已在后端组件中注册（如 click、menu*\*、dropdownProps*\*）。 + - 检查 Svelte 层是否正确映射为 AntD 所需的驼峰命名。 +- 路由集成问题 + - 若使用下拉菜单或溢出指示器，请确认菜单项的 href/path 与路由匹配。 + - 对于权限控制，建议在 itemRender 中根据用户权限动态决定渲染内容。 +- 样式异常 + - 使用 elem_classes/elem_style 或 classNames/styles 传入样式，确保与 AntD 主题兼容。 + - 如需覆盖默认样式，建议通过 CSS Modules 或主题变量进行定制。 + +章节来源 + +- [backend/modelscope_studio/components/antd/breadcrumb/item/**init**.py:15-46](file://backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py#L15-L46) +- [frontend/antd/breadcrumb/Index.svelte:51-57](file://frontend/antd/breadcrumb/Index.svelte#L51-L57) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:370-391](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L370-L391) + +## 结论 + +面包屑组件通过前后端协同设计，实现了灵活的路径展示与用户引导。其核心优势在于： + +- 插槽化扩展：支持自定义分隔符、项渲染与下拉图标。 +- 事件驱动：内置丰富的事件监听，便于与路由系统集成。 +- 主题适配：通过样式属性与运行时上下文，轻松适配不同主题。 +- 性能友好：利用缓存与克隆策略，降低渲染成本。 + +## 附录：使用示例与最佳实践 + +- 基础用法 + - 参考文档示例，快速搭建面包屑路径。 +- 动态路径生成 + - 使用 items 参数或插槽 items 动态构建路径数组，结合路由参数生成标题与链接。 +- 权限控制 + - 在 itemRender 中根据用户角色决定是否渲染某一项或禁用点击。 +- 多语言支持 + - 将标题与分隔符文案通过插槽传入，或在 itemRender 中根据语言环境切换。 +- 样式定制 + - 使用 elem_classes/ elem_style 或 classNames/styles 传入自定义样式；必要时通过主题变量覆盖默认样式。 +- 性能优化 + - 合理使用 forceClone 与 useMemo，避免不必要的克隆与重渲染。 + - 对长列表启用下拉菜单与溢出指示器，减少渲染节点数量。 + +章节来源 + +- [docs/components/antd/breadcrumb/README.md:1-8](file://docs/components/antd/breadcrumb/README.md#L1-L8) +- [docs/components/antd/breadcrumb/README-zh_CN.md:1-8](file://docs/components/antd/breadcrumb/README-zh_CN.md#L1-L8) +- [frontend/antd/breadcrumb/breadcrumb.tsx:44-51](file://frontend/antd/breadcrumb/breadcrumb.tsx#L44-L51) +- [backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js:727-761](file://backend/modelscope_studio/components/antd/breadcrumb/templates/component/breadcrumb-C7MaDQtV.js#L727-L761) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Divider \345\210\206\345\211\262\347\272\277.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Divider \345\210\206\345\211\262\347\272\277.md" new file mode 100644 index 00000000..a250678b --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Divider \345\210\206\345\211\262\347\272\277.md" @@ -0,0 +1,291 @@ +# Divider 分割线 + + +**本文引用的文件** +- [divider.tsx](file://frontend/antd/divider/divider.tsx) +- [Index.svelte](file://frontend/antd/divider/Index.svelte) +- [__init__.py](file://backend/modelscope_studio/components/antd/divider/__init__.py) +- [components.py](file://backend/modelscope_studio/components/antd/components.py) +- [README.md](file://docs/components/antd/divider/README.md) +- [README-zh_CN.md](file://docs/components/antd/divider/README-zh_CN.md) +- [basic.py](file://docs/components/antd/divider/demos/basic.py) +- [basic.py（表单）](file://docs/components/antd/form/demos/basic.py) +- [basic.py（布局）](file://docs/components/antd/layout/demos/basic.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能与可访问性](#性能与可访问性) +8. [使用场景与示例](#使用场景与示例) +9. [故障排查](#故障排查) +10. [结论](#结论) + +## 简介 + +Divider 分割线用于在内容之间建立视觉分隔，帮助用户快速识别信息区块。该组件基于 Ant Design Divider 实现，支持水平与垂直两种方向、多种线条样式（实线、虚线、点线）、标题文本居中与左右对齐、纯文本风格等能力，并提供灵活的样式覆盖接口，便于在不同布局与主题下统一风格。 + +## 项目结构 + +Divider 组件由后端 Python 组件类与前端 Svelte 包装层组成，通过 Gradio 风格的属性传递到 Ant Design React 组件，最终渲染为浏览器可见的分割线。 + +```mermaid +graph TB +subgraph "后端" +PY_INIT["AntdDivider.__init__()
Python 组件类"] +PY_EXPORT["components.py 导出"] +end +subgraph "前端" +SVELTE_INDEX["Index.svelte
属性处理与渲染"] +TS_WRAPPER["divider.tsx
sveltify 包装"] +ANTD_REACT["antd.Divider
Ant Design React 组件"] +end +PY_INIT --> PY_EXPORT +PY_EXPORT --> SVELTE_INDEX +SVELTE_INDEX --> TS_WRAPPER +TS_WRAPPER --> ANTD_REACT +``` + +图表来源 + +- [**init**.py:1-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L1-L95) +- [components.py:37-37](file://backend/modelscope_studio/components/antd/components.py#L37-L37) +- [Index.svelte:1-75](file://frontend/antd/divider/Index.svelte#L1-L75) +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) + +章节来源 + +- [**init**.py:1-95](file://backend/modelscope_studio/components/antd/divider/__init__.py#L1-L95) +- [components.py:37-37](file://backend/modelscope_studio/components/antd/components.py#L37-L37) +- [Index.svelte:1-75](file://frontend/antd/divider/Index.svelte#L1-L75) +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) + +## 核心组件 + +- 后端组件类：AntdDivider，负责定义属性、默认值、样式与渲染策略，并声明前端资源路径。 +- 前端包装层：Index.svelte 负责属性合并、样式注入与条件渲染；divider.tsx 使用 sveltify 将 Ant Design React Divider 桥接为 Svelte 可用组件。 + +关键职责 + +- 属性映射：将 Python 层的 dashed、variant、orientation、orientation_margin、plain、type、size、value、elem_style、elem_classes 等映射到 React Divider。 +- 渲染分支：根据是否传入 children 或 value 决定渲染带文本或纯线段的分割线。 +- 样式注入：通过 elem_style 与 elem_classes 注入自定义样式与类名。 + +章节来源 + +- [**init**.py:21-76](file://backend/modelscope_studio/components/antd/divider/__init__.py#L21-L76) +- [Index.svelte:23-57](file://frontend/antd/divider/Index.svelte#L23-L57) +- [divider.tsx:5-12](file://frontend/antd/divider/divider.tsx#L5-L12) + +## 架构总览 + +下图展示了从 Python 组件到浏览器渲染的调用链路与数据流。 + +```mermaid +sequenceDiagram +participant Py as "Python 后端
AntdDivider" +participant Svelte as "前端
Index.svelte" +participant Wrapper as "包装层
divider.tsx" +participant AD as "Ant Design React
Divider" +Py->>Svelte : 传递属性与值 +Svelte->>Svelte : 处理 visible、样式、附加属性 +Svelte->>Wrapper : 渲染 React Divider +Wrapper->>AD : 传入 props含 children/value +AD-->>Wrapper : 渲染 DOM +Wrapper-->>Svelte : 返回节点 +Svelte-->>Py : 完成一次渲染 +``` + +图表来源 + +- [**init**.py:77-77](file://backend/modelscope_studio/components/antd/divider/__init__.py#L77-L77) +- [Index.svelte:60-74](file://frontend/antd/divider/Index.svelte#L60-L74) +- [divider.tsx:5-12](file://frontend/antd/divider/divider.tsx#L5-L12) + +## 详细组件分析 + +### 属性与配置项 + +- 类型与方向 + - type: horizontal | vertical，控制水平或垂直分割线。 + - size: small | middle | large（仅水平有效），影响分割线整体尺寸。 +- 线条样式 + - variant: dashed | dotted | solid，控制线型。 + - dashed: 布尔开关（兼容旧版），与 variant=dashed 等价。 +- 文本与对齐 + - value 或插槽内容：作为分割线上的文本。 + - orientation: left | right | center | start | end，控制文本位置。 + - orientation_margin: 数字或字符串（带单位时按指定单位解析，无单位时按 px 解析），设置文本与边界的间距。 + - plain: 是否以“纯文本”风格显示文本。 +- 样式与外观 + - elem_style: 注入内联样式（如 borderColor）。 + - elem_classes: 注入额外 CSS 类。 + - root_class_name: 根元素类名（由上层容器传入）。 + - additional_props: 其他透传属性。 +- 布局与可见性 + - visible: 控制组件是否渲染。 + - as_item、\_internal、render 等：框架内部属性，影响渲染上下文。 + +章节来源 + +- [**init**.py:21-76](file://backend/modelscope_studio/components/antd/divider/__init__.py#L21-L76) +- [Index.svelte:13-57](file://frontend/antd/divider/Index.svelte#L13-L57) + +### 渲染逻辑与分支 + +- 当存在子内容（children）或 value 时，渲染带文本的分割线。 +- 否则渲染纯线段分割线。 +- 支持在布局内部模式下直接渲染子节点。 + +```mermaid +flowchart TD +Start(["进入渲染"]) --> CheckVisible{"visible 为真？"} +CheckVisible --> |否| EndHidden["不渲染"] +CheckVisible --> |是| CheckInternal{"内部布局模式？"} +CheckInternal --> |是| RenderWithChildren["渲染带 children 的 Divider"] +CheckInternal --> |否| CheckValue{"有 value？"} +CheckValue --> |是| RenderWithValue["渲染带 value 的 Divider"] +CheckValue --> |否| RenderPlain["渲染纯线段 Divider"] +RenderWithChildren --> End(["完成"]) +RenderWithValue --> End +RenderPlain --> End +EndHidden --> End +``` + +图表来源 + +- [Index.svelte:60-74](file://frontend/antd/divider/Index.svelte#L60-L74) + +### 文本居中与对齐 + +- 通过 orientation=center（或等价的 start/end）实现文本居中。 +- 通过 orientation=left/right 或 orientation=start/end 并配合 orientation_margin 控制文本与边界的间距。 +- plain=True 时，文本以更轻量的样式呈现，适合小字号或弱提示场景。 + +章节来源 + +- [**init**.py:27-32](file://backend/modelscope_studio/components/antd/divider/__init__.py#L27-L32) +- [basic.py:11-26](file://docs/components/antd/divider/demos/basic.py#L11-L26) + +### 样式定制与颜色配置 + +- 通过 elem_style 注入 borderColor、borderWidth 等样式，实现颜色与粗细定制。 +- 通过 elem_classes 注入自定义 CSS 类，满足复杂主题需求。 +- variant 与 dashed 提供线型切换（实线/虚线/点线）。 + +章节来源 + +- [basic.py:11-26](file://docs/components/antd/divider/demos/basic.py#L11-L26) +- [**init**.py:26-32](file://backend/modelscope_studio/components/antd/divider/__init__.py#L26-L32) + +### 响应式行为与屏幕适配 + +- 组件本身不内置媒体查询逻辑，但可通过 elem_style 与布局容器（如 Flex、Layout）实现响应式表现。 +- 在水平布局中，size 可微调分割线的整体视觉尺寸；在垂直布局中，size 不生效。 +- 在窄屏设备上，建议结合容器宽度与文本长度调整 orientation 与 margin，避免文本截断。 + +章节来源 + +- [**init**.py:32-34](file://backend/modelscope_studio/components/antd/divider/__init__.py#L32-L34) +- [basic.py（布局）:42-88](file://docs/components/antd/layout/demos/basic.py#L42-L88) + +## 依赖关系分析 + +- 后端导出：AntdDivider 在 antd 组件集中被统一导出，便于按模块化方式使用。 +- 前端桥接：Index.svelte 通过 importComponent 动态加载 divider.tsx，后者使用 sveltify 将 Ant Design React Divider 包装为 Svelte 组件。 +- 属性透传：除框架保留字段外，其余属性均透传至 React Divider，确保与 Ant Design API 保持一致。 + +```mermaid +graph LR +A["components.py"] --> B["AntdDivider.__init__"] +B --> C["FRONTEND_DIR=resolve_frontend_dir('divider')"] +C --> D["Index.svelte"] +D --> E["divider.tsx"] +E --> F["antd.Divider"] +``` + +图表来源 + +- [components.py:37-37](file://backend/modelscope_studio/components/antd/components.py#L37-L37) +- [**init**.py:77-77](file://backend/modelscope_studio/components/antd/divider/__init__.py#L77-L77) +- [Index.svelte:10-10](file://frontend/antd/divider/Index.svelte#L10-L10) +- [divider.tsx:3-3](file://frontend/antd/divider/divider.tsx#L3-L3) + +章节来源 + +- [components.py:37-37](file://backend/modelscope_studio/components/antd/components.py#L37-L37) +- [**init**.py:77-77](file://backend/modelscope_studio/components/antd/divider/__init__.py#L77-L77) +- [Index.svelte:10-10](file://frontend/antd/divider/Index.svelte#L10-L10) +- [divider.tsx:3-3](file://frontend/antd/divider/divider.tsx#L3-L3) + +## 性能与可访问性 + +- 渲染开销：组件为轻量级纯展示，动态导入与条件渲染避免不必要的重绘。 +- 可访问性：文本内容通过语义化标签渲染，建议为重要分割线提供简短描述（如 aria-label），提升屏幕阅读器体验。 +- 主题一致性：通过 elem_style 与 elem_classes 统一样式，减少重复计算与样式冲突。 + +[本节为通用建议，无需特定文件引用] + +## 使用场景与示例 + +### 表单分组 + +- 在表单中使用分割线对不同业务域进行分组，提升可读性。 +- 示例参考：表单演示中展示了分割线在表单控件之间的分隔用法。 + +章节来源 + +- [basic.py（表单）:16-90](file://docs/components/antd/form/demos/basic.py#L16-L90) + +### 内容区域划分 + +- 在文章或页面中使用水平分割线划分段落，配合 orientation=center 实现标题式分隔。 +- 示例参考：基础演示中展示了不同 variant 与带文本的分割线用法。 + +章节来源 + +- [basic.py:5-29](file://docs/components/antd/divider/demos/basic.py#L5-L29) + +### 导航菜单分隔 + +- 在导航列表中使用垂直分割线或水平分割线分隔菜单项，注意在窄屏下调整 orientation 与 margin，避免文本溢出。 +- 建议：垂直分割线优先用于侧边导航，水平分割线用于顶部或底部导航。 + +[本小节为概念性说明，无需特定文件引用] + +### 响应式布局中的表现 + +- 结合 Flex、Layout 等布局组件，在不同屏幕尺寸下调整分割线方向与文本长度。 +- 建议：在移动端优先使用水平分割线与较短文本，必要时隐藏文本仅保留线段。 + +章节来源 + +- [basic.py（布局）:42-88](file://docs/components/antd/layout/demos/basic.py#L42-L88) + +## 故障排查 + +- 文本未显示 + - 检查是否传入了 value 或子内容；若未传入，组件将渲染纯线段。 + - 确认 visible 为 True。 +- 文本位置异常 + - orientation 设置为 left/right/start/end 时，需配合 orientation_margin 调整间距。 + - plain 会影响文本视觉权重，必要时移除以获得更强的分隔感。 +- 线条样式无效 + - dashed 与 variant=dashed 等价；确保未同时设置冲突属性。 + - elem_style 中的 borderColor、borderWidth 等需与目标平台兼容。 +- 垂直分割线尺寸无效 + - size 仅对 horizontal 生效；vertical 下请通过容器宽度与边框控制视觉尺寸。 + +章节来源 + +- [Index.svelte:60-74](file://frontend/antd/divider/Index.svelte#L60-L74) +- [**init**.py:26-34](file://backend/modelscope_studio/components/antd/divider/__init__.py#L26-L34) + +## 结论 + +Divider 分割线组件以简洁的 API 提供了丰富的视觉表达能力，既能满足基础的线段分隔，也能胜任带文本的标题式分隔。通过类型、线型、对齐与样式等多维配置，可在不同布局与主题中稳定地实现信息层级与空间分隔。建议在实际项目中结合布局容器与响应式策略，合理选择 orientation 与 size，并通过 elem_style/elem_classes 实现品牌化与主题化定制。 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Flex \345\274\271\346\200\247\345\270\203\345\261\200.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Flex \345\274\271\346\200\247\345\270\203\345\261\200.md" new file mode 100644 index 00000000..e3ac45aa --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Flex \345\274\271\346\200\247\345\270\203\345\261\200.md" @@ -0,0 +1,291 @@ +# Flex 弹性布局 + + +**本文引用的文件** +- [frontend/antd/flex/flex.tsx](file://frontend/antd/flex/flex.tsx) +- [frontend/antd/flex/Index.svelte](file://frontend/antd/flex/Index.svelte) +- [backend/modelscope_studio/components/antd/flex/__init__.py](file://backend/modelscope_studio/components/antd/flex/__init__.py) +- [docs/components/antd/flex/README.md](file://docs/components/antd/flex/README.md) +- [docs/components/antd/flex/demos/basic.py](file://docs/components/antd/flex/demos/basic.py) +- [docs/components/antd/flex/demos/align.py](file://docs/components/antd/flex/demos/align.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本篇文档围绕 Flex 弹性布局组件展开，系统阐述其在模型空间（ModelScope Studio）中的实现与使用方式。Flex 组件基于 Ant Design 的 Flex 容器能力，提供主轴与交叉轴对齐、排列方向、换行控制、间距设置等能力，并通过 Gradio 生态进行前后端桥接。文档将从概念到实践，覆盖以下主题： + +- 核心概念：主轴/交叉轴、justify-content、align-items、align-content 对应关系 +- 关键属性：orientation/vertical、wrap、justify、align、flex、gap +- 实战场景：按钮组对齐、内容区域分布、响应式卡片布局 +- 复杂嵌套布局与最佳实践 +- 兼容性与跨浏览器注意事项 + +## 项目结构 + +Flex 组件在仓库中采用“后端 Python 组件 + 前端 Svelte 包装 + Ant Design Flex 容器”的分层设计： + +- 后端：Python 类负责参数校验、渲染策略与前端资源定位 +- 前端：Svelte 组件负责动态导入、属性透传与样式拼接 +- 依赖：通过 svelte-preprocess-react 将 React/Ant Design 组件桥接到 Svelte + +```mermaid +graph TB +subgraph "后端" +PY["AntdFlex
Python 组件"] +DEV["ModelScopeLayoutComponent
基础布局组件"] +end +subgraph "前端" +IDX["Index.svelte
动态导入包装"] +FLEX_TS["flex.tsx
sveltify 包装"] +ANTDFLEX["Ant Design Flex
容器"] +end +subgraph "文档与示例" +DOC["README.md"] +DEMO1["basic.py 示例"] +DEMO2["align.py 示例"] +end +PY --> IDX +DEV --> PY +IDX --> FLEX_TS +FLEX_TS --> ANTDFLEX +DOC --> DEMO1 +DOC --> DEMO2 +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/flex/**init**.py:8-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L8-L98) +- [frontend/antd/flex/Index.svelte:10-61](file://frontend/antd/flex/Index.svelte#L10-L61) +- [frontend/antd/flex/flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [docs/components/antd/flex/README.md:1-9](file://docs/components/antd/flex/README.md#L1-L9) + +章节来源 + +- [backend/modelscope_studio/components/antd/flex/**init**.py:8-98](file://backend/modelscope_studio/components/antd/flex/__init__.py#L8-L98) +- [frontend/antd/flex/Index.svelte:1-62](file://frontend/antd/flex/Index.svelte#L1-L62) +- [frontend/antd/flex/flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [docs/components/antd/flex/README.md:1-9](file://docs/components/antd/flex/README.md#L1-L9) + +## 核心组件 + +- AntdFlex（后端） + - 负责接收并校验所有 Flex 相关参数（方向、换行、主轴/交叉轴对齐、flex 缩写、间距等），并将这些参数映射为前端可消费的 props。 + - 提供 FRONTEND_DIR 指向前端 flex 目录，确保运行时正确加载前端组件。 + - 遵循 ModelScopeLayoutComponent 的布局语义，参与应用级布局上下文。 + +- Index.svelte（前端包装） + - 使用 importComponent 动态导入前端 flex 组件，避免首屏阻塞。 + - 通过 getProps/processProps 获取并处理组件属性，支持额外属性透传与可见性控制。 + - 将 elem_id、elem_classes、elem_style 等通用属性注入到最终渲染节点。 + +- flex.tsx（Svelte 包装） + - 使用 sveltify 将 Ant Design 的 Flex 容器转换为 Svelte 可用的组件，直接透传 props 与 children。 + +- 文档与示例 + - README.md 提供基本说明与示例占位 + - basic.py 与 align.py 展示了垂直/水平方向切换、主轴/交叉轴对齐的交互式示例 + +章节来源 + +- [backend/modelscope_studio/components/antd/flex/**init**.py:21-79](file://backend/modelscope_studio/components/antd/flex/__init__.py#L21-L79) +- [frontend/antd/flex/Index.svelte:13-42](file://frontend/antd/flex/Index.svelte#L13-L42) +- [frontend/antd/flex/flex.tsx:4-8](file://frontend/antd/flex/flex.tsx#L4-L8) +- [docs/components/antd/flex/README.md:1-9](file://docs/components/antd/flex/README.md#L1-L9) +- [docs/components/antd/flex/demos/basic.py:8-23](file://docs/components/antd/flex/demos/basic.py#L8-L23) +- [docs/components/antd/flex/demos/align.py:8-41](file://docs/components/antd/flex/demos/align.py#L8-L41) + +## 架构总览 + +下图展示了从用户代码到最终渲染的调用链路，体现 Flex 组件在前后端之间的协作关系： + +```mermaid +sequenceDiagram +participant U as "用户代码" +participant PY as "AntdFlex(后端)" +participant IDX as "Index.svelte(前端包装)" +participant F as "flex.tsx(Svelte 包装)" +participant AD as "Ant Design Flex" +U->>PY : 创建 AntdFlex 并传入参数 +PY->>IDX : 解析 FRONTEND_DIR 并渲染 +IDX->>F : 动态导入 Antd Flex 组件 +F->>AD : 透传 props 与 children +AD-->>U : 渲染完成的弹性布局容器 +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/flex/**init**.py:81-81](file://backend/modelscope_studio/components/antd/flex/__init__.py#L81-L81) +- [frontend/antd/flex/Index.svelte:10-10](file://frontend/antd/flex/Index.svelte#L10-L10) +- [frontend/antd/flex/flex.tsx:4-8](file://frontend/antd/flex/flex.tsx#L4-L8) + +## 详细组件分析 + +### 后端类：AntdFlex 参数与行为 + +- 关键参数 + - orientation/vertical：控制排列方向（水平/垂直） + - wrap：控制单行或多行显示 + - justify：主轴对齐（start/end/center/flex-start/flex-end/space-\* 等） + - align：交叉轴对齐（start/end/center/flex-start/flex-end/baseline/stretch 等） + - flex：flex 缩写属性 + - gap：元素间距（small/middle/large 或数值） + - component/root_class_name/class_names/styles/as_item/\_internal：通用属性与样式注入 + - 可见性与 DOM 注入：elem_id/elem_classes/elem_style/visible/render + +- 行为特征 + - skip_api=True：不暴露为标准 API 组件，适合内部布局使用 + - FRONTEND_DIR 指向前端 flex 目录，保证运行时组件可用 + - 继承自 ModelScopeLayoutComponent，具备布局上下文能力 + +章节来源 + +- [backend/modelscope_studio/components/antd/flex/**init**.py:21-79](file://backend/modelscope_studio/components/antd/flex/__init__.py#L21-L79) +- [backend/modelscope_studio/utils/dev/component.py:11-52](file://backend/modelscope_studio/utils/dev/component.py#L11-L52) + +### 前端包装：Index.svelte + +- 动态导入：通过 importComponent 延迟加载 flex.tsx，减少首屏开销 +- 属性处理：getProps/processProps 提取并合并组件属性、附加属性、可见性与 DOM 注入 +- 样式拼接：elem_classes 与固定类名组合，elem_id/elem_style 注入到根节点 +- 条件渲染：根据 visible 控制是否渲染 + +章节来源 + +- [frontend/antd/flex/Index.svelte:13-42](file://frontend/antd/flex/Index.svelte#L13-L42) +- [frontend/antd/flex/Index.svelte:48-61](file://frontend/antd/flex/Index.svelte#L48-L61) + +### Svelte 包装：flex.tsx + +- 使用 sveltify 将 Ant Design Flex 容器桥接为 Svelte 组件 +- 直接透传 props 与 children，保持与 Antd Flex 的一致语义 + +章节来源 + +- [frontend/antd/flex/flex.tsx:4-8](file://frontend/antd/flex/flex.tsx#L4-L8) + +### 示例：基础与对齐 + +- basic.py：展示垂直/水平方向切换与间距设置 +- align.py：展示主轴/交叉轴对齐选项与交互更新 + +章节来源 + +- [docs/components/antd/flex/demos/basic.py:8-23](file://docs/components/antd/flex/demos/basic.py#L8-L23) +- [docs/components/antd/flex/demos/align.py:8-41](file://docs/components/antd/flex/demos/align.py#L8-L41) + +### 关键属性与 CSS Flex 对应关系 + +- 主轴与交叉轴 + - 主轴：由排列方向决定（horizontal/vertical 对应 row/column） + - 交叉轴：垂直于主轴的方向 +- 对齐关系 + - justify-content ↔ justify（主轴对齐） + - align-items ↔ align（交叉轴对齐） + - align-content ↔ 多行时的交叉轴分布（wrap 为 wrap/ wrap-reverse 时生效） + +章节来源 + +- [backend/modelscope_studio/components/antd/flex/**init**.py:52-58](file://backend/modelscope_studio/components/antd/flex/__init__.py#L52-L58) + +### 实际应用场景 + +- 按钮组对齐：使用 justify/align 快速实现水平或垂直居中、两端对齐等 +- 内容区域分布：利用 gap 与 wrap 实现响应式网格与换行 +- 响应式卡片布局：结合 orientation/vertical 与 justify/align 实现卡片流式排列与对齐 + +章节来源 + +- [docs/components/antd/flex/demos/basic.py:8-23](file://docs/components/antd/flex/demos/basic.py#L8-L23) +- [docs/components/antd/flex/demos/align.py:8-41](file://docs/components/antd/flex/demos/align.py#L8-L41) + +### 复杂嵌套布局与最佳实践 + +- 嵌套策略 + - 外层容器设置主轴对齐与换行，内层容器聚焦交叉轴对齐 + - 使用 gap 控制层级间间距，避免硬编码 margin/padding +- 最佳实践 + - 优先使用 vertical/orientation 控制方向，再用 justify/align 微调 + - 在多行场景下，合理选择 wrap 与 align-content 的组合 + - 结合交互组件（如 Segmented）动态切换对齐方式，提升可探索性 + +章节来源 + +- [docs/components/antd/flex/demos/align.py:8-41](file://docs/components/antd/flex/demos/align.py#L8-L41) + +## 依赖分析 + +- 组件耦合 + - AntdFlex 仅依赖前端 flex 目录，通过 FRONTEND_DIR 解析路径，降低耦合度 + - Index.svelte 与 flex.tsx 之间为松散耦合，前者负责运行时加载，后者负责桥接 +- 外部依赖 + - Ant Design Flex：提供核心布局能力 + - svelte-preprocess-react：提供 sveltify 与动态导入工具 +- 可能的循环依赖 + - 当前结构无明显循环依赖；若后续扩展，需避免后端组件相互引用 + +```mermaid +graph LR +PY["AntdFlex(后端)"] --> |FRONTEND_DIR| FE["flex 前端目录"] +IDX["Index.svelte"] --> |动态导入| FLEX_TS["flex.tsx"] +FLEX_TS --> |sveltify| AD["Ant Design Flex"] +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/flex/**init**.py:81-81](file://backend/modelscope_studio/components/antd/flex/__init__.py#L81-L81) +- [frontend/antd/flex/Index.svelte:10-10](file://frontend/antd/flex/Index.svelte#L10-L10) +- [frontend/antd/flex/flex.tsx:4-8](file://frontend/antd/flex/flex.tsx#L4-L8) + +章节来源 + +- [backend/modelscope_studio/components/antd/flex/**init**.py:81-81](file://backend/modelscope_studio/components/antd/flex/__init__.py#L81-L81) +- [frontend/antd/flex/Index.svelte:10-10](file://frontend/antd/flex/Index.svelte#L10-L10) +- [frontend/antd/flex/flex.tsx:4-8](file://frontend/antd/flex/flex.tsx#L4-L8) + +## 性能考虑 + +- 动态导入优化：Index.svelte 使用 importComponent 延迟加载，减少首屏体积与渲染时间 +- 属性透传最小化：仅传递必要属性，避免冗余计算与重排 +- 间距与换行：合理使用 gap 与 wrap，避免过度嵌套导致的复杂布局回流 + +## 故障排查指南 + +- 组件不可见 + - 检查 visible 是否为 true + - 确认 elem_style/ elem_classes 是否导致溢出或隐藏 +- 方向与对齐异常 + - 确认 orientation/vertical 与 justify/align 的组合是否符合预期 + - 在多行场景下检查 wrap 与 align-content 的影响 +- 运行时加载失败 + - 确认 FRONTEND_DIR 指向正确且前端包已构建 + - 查看动态导入是否抛错（Index.svelte 中的 {#await} 分支） + +章节来源 + +- [frontend/antd/flex/Index.svelte:48-61](file://frontend/antd/flex/Index.svelte#L48-L61) +- [backend/modelscope_studio/components/antd/flex/**init**.py:81-81](file://backend/modelscope_studio/components/antd/flex/__init__.py#L81-L81) + +## 结论 + +Flex 弹性布局组件在模型空间中以“后端参数 + 前端包装 + Antd Flex 容器”的方式实现，既保持了与 CSS Flex 的语义一致性，又提供了良好的可配置性与可维护性。通过 orientation/vertical、wrap、justify、align、flex、gap 等关键属性，能够高效覆盖按钮组对齐、内容区域分布、响应式卡片布局等常见场景；配合动态导入与属性透传机制，兼顾性能与灵活性。 + +## 附录 + +- 示例入口 + - 基础示例：[basic.py:1-26](file://docs/components/antd/flex/demos/basic.py#L1-L26) + - 对齐示例：[align.py:1-45](file://docs/components/antd/flex/demos/align.py#L1-L45) +- 文档说明：[README.md:1-9](file://docs/components/antd/flex/README.md#L1-L9) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Grid \346\240\205\346\240\274.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Grid \346\240\205\346\240\274.md" new file mode 100644 index 00000000..bbc2929e --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Grid \346\240\205\346\240\274.md" @@ -0,0 +1,348 @@ +# Grid 栅格 + + +**本文引用的文件** +- [frontend/antd/grid/row/Index.svelte](file://frontend/antd/grid/row/Index.svelte) +- [frontend/antd/grid/row/row.tsx](file://frontend/antd/grid/row/row.tsx) +- [frontend/antd/grid/col/Index.svelte](file://frontend/antd/grid/col/Index.svelte) +- [frontend/antd/grid/col/col.tsx](file://frontend/antd/grid/col/col.tsx) +- [frontend/antd/grid/context.ts](file://frontend/antd/grid/context.ts) +- [backend/modelscope_studio/components/antd/grid/row/__init__.py](file://backend/modelscope_studio/components/antd/grid/row/__init__.py) +- [backend/modelscope_studio/components/antd/grid/col/__init__.py](file://backend/modelscope_studio/components/antd/grid/col/__init__.py) +- [docs/components/antd/grid/README.md](file://docs/components/antd/grid/README.md) +- [docs/components/antd/grid/demos/basic.py](file://docs/components/antd/grid/demos/basic.py) +- [docs/components/antd/grid/demos/playground.py](file://docs/components/antd/grid/demos/playground.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本篇文档围绕 Grid 栅格组件展开，系统性阐述其设计原理、24 栅格体系与响应式断点配置，并深入讲解 Row 与 Col 的使用方法（含栅格偏移、排序、嵌套规则、对齐方式等），提供仪表板布局、产品展示页面、表单布局等常见场景的应用思路，同时给出响应式行为说明与性能优化建议。 + +## 项目结构 + +Grid 组件由前端 Svelte 包装层与后端 Python 组件层协同构成：前端负责渲染与上下文传递，后端负责参数透传与生命周期控制；文档侧提供示例与说明。 + +```mermaid +graph TB +subgraph "后端组件" +PY_ROW["Python 行组件
backend/modelscope_studio/components/antd/grid/row/__init__.py"] +PY_COL["Python 列组件
backend/modelscope_studio/components/antd/grid/col/__init__.py"] +end +subgraph "前端包装" +IDX_ROW["行包装入口
frontend/antd/grid/row/Index.svelte"] +ROW_IMPL["行实现
frontend/antd/grid/row/row.tsx"] +IDX_COL["列包装入口
frontend/antd/grid/col/Index.svelte"] +COL_IMPL["列实现
frontend/antd/grid/col/col.tsx"] +CTX["栅格上下文
frontend/antd/grid/context.ts"] +end +PY_ROW --> IDX_ROW --> ROW_IMPL +PY_COL --> IDX_COL --> COL_IMPL +ROW_IMPL --> CTX +COL_IMPL --> CTX +``` + +**图表来源** + +- [frontend/antd/grid/row/Index.svelte:1-61](file://frontend/antd/grid/row/Index.svelte#L1-L61) +- [frontend/antd/grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [frontend/antd/grid/col/Index.svelte:1-77](file://frontend/antd/grid/col/Index.svelte#L1-L77) +- [frontend/antd/grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:1-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L1-L94) +- [backend/modelscope_studio/components/antd/grid/col/**init**.py:1-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L1-L114) + +**章节来源** + +- [frontend/antd/grid/row/Index.svelte:1-61](file://frontend/antd/grid/row/Index.svelte#L1-L61) +- [frontend/antd/grid/col/Index.svelte:1-77](file://frontend/antd/grid/col/Index.svelte#L1-L77) +- [frontend/antd/grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [frontend/antd/grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:1-94](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L1-L94) +- [backend/modelscope_studio/components/antd/grid/col/**init**.py:1-114](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L1-L114) + +## 核心组件 + +- 行组件（Row） + - 支持对齐方式、间距、换行等属性，用于承载多个列并管理布局方向与分布。 + - 关键参数：align、justify、gutter、wrap 等。 +- 列组件（Col） + - 支持跨度、偏移、排序、左右推动、响应式断点等，用于具体的内容区块。 + - 关键参数：span、offset、order、pull、push、xs/sm/md/lg/xl/xxl 等。 + +上述参数在后端组件中均有明确声明与默认值，便于在 Python 层直接使用。 + +**章节来源** + +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:30-76](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L30-L76) +- [backend/modelscope_studio/components/antd/grid/col/**init**.py:30-95](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L30-L95) + +## 架构总览 + +Grid 的运行时流程如下：后端 Python 组件接收参数并渲染前端包装组件；前端包装组件再调用 Ant Design 的 Row/Col 实现，并通过上下文机制收集 Col 子项，最终组合为标准栅格布局。 + +```mermaid +sequenceDiagram +participant PyRow as "后端行组件" +participant IdxRow as "行包装入口" +participant RowImpl as "行实现" +participant Ctx as "栅格上下文" +participant PyCol as "后端列组件" +participant IdxCol as "列包装入口" +participant ColImpl as "列实现" +PyRow->>IdxRow : 渲染行包装 +IdxRow->>RowImpl : 传递行参数 +PyCol->>IdxCol : 渲染列包装 +IdxCol->>ColImpl : 传递列参数 +ColImpl->>Ctx : 注册列项 +RowImpl->>Ctx : 消费列项并渲染 +RowImpl-->>IdxRow : 输出 Row 容器 +IdxRow-->>PyRow : 返回渲染结果 +``` + +**图表来源** + +- [frontend/antd/grid/row/Index.svelte:10-44](file://frontend/antd/grid/row/Index.svelte#L10-L44) +- [frontend/antd/grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [frontend/antd/grid/col/Index.svelte:10-47](file://frontend/antd/grid/col/Index.svelte#L10-L47) +- [frontend/antd/grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) +- [frontend/antd/grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) + +## 详细组件分析 + +### 行组件（Row）分析 + +- 设计要点 + - 基于 Ant Design Row，支持水平排列（justify）、垂直对齐（align）、间距（gutter）、自动换行（wrap）等。 + - 通过上下文收集子 Col 并统一渲染，避免直接在 Row 中写死子元素。 +- 使用建议 + - 在复杂布局中优先设置 gutter，以保证跨断点的一致性。 + - 合理使用 wrap，避免长列表导致的横向滚动问题。 +- 参数要点 + - align：top/middle/bottom/stretch + - justify：start/end/center/space-between/space-around/space-evenly + - gutter：数字或对象（含断点）或数组 [水平, 垂直] + - wrap：布尔值 + +```mermaid +classDiagram +class Row { ++align ++justify ++gutter ++wrap ++render() +} +class Context { ++register(item) ++collect() +} +Row --> Context : "消费列项" +``` + +**图表来源** + +- [frontend/antd/grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [frontend/antd/grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) + +**章节来源** + +- [frontend/antd/grid/row/Index.svelte:12-42](file://frontend/antd/grid/row/Index.svelte#L12-L42) +- [frontend/antd/grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:30-76](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L30-L76) + +### 列组件（Col）分析 + +- 设计要点 + - 基于 Ant Design Col，支持 span、offset、order、pull、push 等基础能力。 + - 支持响应式断点 xs/sm/md/lg/xl/xxl，可分别指定 span 或完整属性对象。 + - 通过上下文注册自身，供 Row 统一调度。 +- 使用建议 + - 合理规划每行总 span 不超过 24，超出则自动换行。 + - 使用 offset/push/pull 实现视觉偏移与重排，但需注意可访问性与语义化。 + - 在移动端优先使用 xs，桌面端使用更大断点，确保不同设备体验一致。 +- 参数要点 + - span：占位栅格数（0 对应不显示） + - offset/push/pull：偏移/左移/右移 + - order：排序 + - xs/sm/md/lg/xl/xxl：断点级配置 + +```mermaid +classDiagram +class Col { ++span ++offset ++order ++pull ++push ++xs/sm/md/lg/xl/xxl ++render() +} +class Context { ++register(item) ++collect() +} +Col --> Context : "注册到上下文" +``` + +**图表来源** + +- [frontend/antd/grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) +- [frontend/antd/grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) +- [backend/modelscope_studio/components/antd/grid/col/**init**.py:30-95](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L30-L95) + +**章节来源** + +- [frontend/antd/grid/col/Index.svelte:23-47](file://frontend/antd/grid/col/Index.svelte#L23-L47) +- [frontend/antd/grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) +- [backend/modelscope_studio/components/antd/grid/col/**init**.py:30-95](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L30-L95) + +### 响应式断点与行为 + +- 断点定义 + - xs：屏幕宽度小于 576px，且为默认断点 + - sm：≥ 576px + - md：≥ 768px + - lg：≥ 992px + - xl：≥ 1200px + - xxl：≥ 1600px +- 配置方式 + - 可直接传入整数 span，也可传入对象，按断点分别配置 span 与其他属性（如 offset、order 等）。 +- 行为说明 + - 当一行内所有列的 span 总和超过 24 时，溢出列会整体换行。 + - gutter 支持断点级配置，可实现不同屏幕下的差异化间距。 + +**章节来源** + +- [backend/modelscope_studio/components/antd/grid/col/**init**.py:58-72](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L58-L72) +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:54-60](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L54-L60) + +### 嵌套规则与对齐方式 + +- 嵌套规则 + - Row 内仅放置 Col；Col 内可继续放置 Row，形成嵌套栅格。 + - 注意嵌套层级不要过深，避免样式与可维护性问题。 +- 对齐方式 + - Row 提供水平（justify）与垂直（align）对齐，结合 gutter 实现稳定布局。 + - 垂直对齐支持 stretch，使列高度自适应容器高度。 + +**章节来源** + +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:34-40](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L34-L40) +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:56-59](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L56-L59) + +### 实际应用案例 + +- 仪表板布局 + - 使用 Row 的 gutter 与 wrap 控制卡片间距与换行；Col 的 span 与响应式断点适配多屏。 + - 在窄屏下减少列数，宽屏下增加列数，保持信息密度与可读性。 +- 产品展示页面 + - 头图区域使用单列铺满；商品列表使用等分列；侧栏使用固定 span，主内容区自适应。 + - 通过 xs/sm/md/lg/xl/xxl 分别配置不同断点下的列数与间距。 +- 表单布局 + - 小型表单项使用较小 span，复合字段使用较大 span；在 xs 下合并为单列，提升移动端可用性。 + - 使用 offset 进行微调，但避免过度偏移影响阅读顺序。 + +（以上为通用布局策略说明，具体实现请参考示例） + +**章节来源** + +- [docs/components/antd/grid/README.md:1-9](file://docs/components/antd/grid/README.md#L1-L9) +- [docs/components/antd/grid/demos/basic.py:7-24](file://docs/components/antd/grid/demos/basic.py#L7-L24) +- [docs/components/antd/grid/demos/playground.py:17-90](file://docs/components/antd/grid/demos/playground.py#L17-L90) + +## 依赖关系分析 + +- 组件耦合 + - Col 通过上下文注册自身，Row 从上下文中收集并渲染，降低直接耦合度。 + - 前端包装组件仅负责参数透传与渲染，逻辑集中在 Row/Col 实现与上下文中。 +- 外部依赖 + - 依赖 Ant Design 的 Row/Col 组件，复用成熟的栅格系统。 + - 使用 Svelte Preprocess React 工具链进行桥接与插槽处理。 + +```mermaid +graph LR +PY_ROW["后端行组件"] --> IDX_ROW["行包装入口"] +IDX_ROW --> ROW_IMPL["行实现"] +PY_COL["后端列组件"] --> IDX_COL["列包装入口"] +IDX_COL --> COL_IMPL["列实现"] +ROW_IMPL --> CTX["栅格上下文"] +COL_IMPL --> CTX +ROW_IMPL --> ANTDESIGN["Ant Design Row/Col"] +COL_IMPL --> ANTDESIGN +``` + +**图表来源** + +- [frontend/antd/grid/row/Index.svelte:10-18](file://frontend/antd/grid/row/Index.svelte#L10-L18) +- [frontend/antd/grid/col/Index.svelte:10-21](file://frontend/antd/grid/col/Index.svelte#L10-L21) +- [frontend/antd/grid/row/row.tsx:3-5](file://frontend/antd/grid/row/row.tsx#L3-L5) +- [frontend/antd/grid/col/col.tsx:3-5](file://frontend/antd/grid/col/col.tsx#L3-L5) +- [frontend/antd/grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) + +**章节来源** + +- [frontend/antd/grid/row/Index.svelte:10-44](file://frontend/antd/grid/row/Index.svelte#L10-L44) +- [frontend/antd/grid/col/Index.svelte:10-47](file://frontend/antd/grid/col/Index.svelte#L10-L47) +- [frontend/antd/grid/row/row.tsx:3-5](file://frontend/antd/grid/row/row.tsx#L3-L5) +- [frontend/antd/grid/col/col.tsx:3-5](file://frontend/antd/grid/col/col.tsx#L3-L5) +- [frontend/antd/grid/context.ts:3-4](file://frontend/antd/grid/context.ts#L3-L4) + +## 性能考虑 + +- 减少不必要的重渲染 + - 合理拆分子组件，避免整行频繁更新；对 Col 的响应式断点配置尽量静态化，减少动态计算。 +- 控制嵌套层级 + - 嵌套越深，样式计算与布局成本越高；建议不超过三层嵌套。 +- 合理使用 gutter + - 大量小间距可能引发频繁回流；可统一在 Row 上设置 gutter，避免在每个 Col 单独设置。 +- 选择合适的断点 + - 仅在必要断点启用响应式配置，避免过多条件分支导致的渲染开销。 +- 使用 span 与 wrap + - 通过合理的 span 分配与 wrap，减少复杂计算与额外的 DOM 结构。 + +（本节为通用优化建议，不涉及特定文件分析） + +## 故障排查指南 + +- 列未显示或错位 + - 检查每行总 span 是否超过 24；若超过，溢出列会整体换行。 + - 检查 xs/sm/md/lg/xl/xxl 断点配置是否冲突。 +- 偏移/排序无效 + - 确认 Col 的 offset/push/pull/order 是否在正确断点下生效。 + - 确保 Row 的 justify/align 未覆盖预期的视觉效果。 +- 响应式不生效 + - 确认断点参数类型为对象时，包含正确的属性（如 span、offset 等）。 + - 确认父级 Row 的 gutter/justify/align 未与断点配置产生冲突。 +- 性能问题 + - 检查是否存在深层嵌套与大量动态计算；适当简化布局结构。 + - 避免在 Col 上重复设置相同的间距与样式，统一在 Row 上配置。 + +**章节来源** + +- [backend/modelscope_studio/components/antd/grid/col/**init**.py:58-72](file://backend/modelscope_studio/components/antd/grid/col/__init__.py#L58-L72) +- [backend/modelscope_studio/components/antd/grid/row/**init**.py:54-60](file://backend/modelscope_studio/components/antd/grid/row/__init__.py#L54-L60) + +## 结论 + +Grid 栅格组件通过后端参数与前端包装的协作，提供了与 Ant Design 一致的栅格能力，并在此基础上增强了响应式断点与上下文收集机制。合理使用 Row/Col 的对齐、间距、嵌套与断点配置，可在多场景下快速构建稳定、可维护的布局方案。 + +## 附录 + +- 示例入口 + - 基础示例：[docs/components/antd/grid/demos/basic.py:7-24](file://docs/components/antd/grid/demos/basic.py#L7-L24) + - 演练场示例：[docs/components/antd/grid/demos/playground.py:17-90](file://docs/components/antd/grid/demos/playground.py#L17-L90) +- 文档说明：[docs/components/antd/grid/README.md:1-9](file://docs/components/antd/grid/README.md#L1-L9) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Layout \345\270\203\345\261\200.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Layout \345\270\203\345\261\200.md" new file mode 100644 index 00000000..b609a098 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Layout \345\270\203\345\261\200.md" @@ -0,0 +1,295 @@ +# Layout 布局 + + +**本文引用的文件** +- [frontend/antd/layout/Index.svelte](file://frontend/antd/layout/Index.svelte) +- [frontend/antd/layout/Base.svelte](file://frontend/antd/layout/Base.svelte) +- [frontend/antd/layout/layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) +- [frontend/antd/layout/content/Index.svelte](file://frontend/antd/layout/content/Index.svelte) +- [frontend/antd/layout/footer/Index.svelte](file://frontend/antd/layout/footer/Index.svelte) +- [frontend/antd/layout/header/Index.svelte](file://frontend/antd/layout/header/Index.svelte) +- [frontend/antd/layout/sider/Index.svelte](file://frontend/antd/layout/sider/Index.svelte) +- [frontend/antd/layout/sider/layout.sider.tsx](file://frontend/antd/layout/sider/layout.sider.tsx) +- [docs/components/antd/layout/README.md](file://docs/components/antd/layout/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本篇文档系统性介绍 Layout 布局组件的整体架构与使用方法，覆盖 Header、Sider、Content、Footer 等布局区域的组合与嵌套规则；解释响应式行为与固定定位策略；提供侧边栏布局、顶部导航布局、混合布局等经典页面模板思路；并说明与栅格系统的结合使用及在不同屏幕尺寸下的自适应表现。同时给出样式定制、主题切换与动画效果等高级能力的实践建议。 + +## 项目结构 + +Layout 组件采用“统一基座 + 区域子组件”的分层设计： + +- 基础层：Index.svelte 作为入口，Base.svelte 负责属性处理与渲染，layout.base.tsx 将 Svelte 包装为 Ant Design 的具体组件（Header/Footer/Content/Layout）。 +- 区域层：header、footer、content、sider 各自通过 Index.svelte 指定 component 类型，复用 Base.svelte 渲染逻辑。 +- 特殊区域：sider 提供独立的 layout.sider.tsx，支持 trigger 插槽以实现折叠触发器。 + +```mermaid +graph TB +subgraph "布局组件层" +L["Index.svelte
统一入口"] +HB["Base.svelte
通用基座"] +C["content/Index.svelte"] +F["footer/Index.svelte"] +H["header/Index.svelte"] +S["sider/Index.svelte"] +end +subgraph "底层实现层" +LB["layout.base.tsx
Ant Design 组件包装"] +LS["layout.sider.tsx
Sider 实现与 trigger 插槽"] +end +L --> HB +C --> HB +F --> HB +H --> HB +S --> HB +HB --> LB +S --> LS +``` + +图表来源 + +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +章节来源 + +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/content/Index.svelte:1-15](file://frontend/antd/layout/content/Index.svelte#L1-L15) +- [frontend/antd/layout/footer/Index.svelte:1-15](file://frontend/antd/layout/footer/Index.svelte#L1-L15) +- [frontend/antd/layout/header/Index.svelte:1-15](file://frontend/antd/layout/header/Index.svelte#L1-L15) +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +## 核心组件 + +- Layout（整体容器） + - 入口：Index.svelte 将 props 透传给 Base.svelte，并指定 component 为 layout。 + - 基座：Base.svelte 复用通用属性处理逻辑，最终由 layout.base.tsx 决定渲染 Ant Design 的 Layout 容器。 +- Header（顶部区域） + - 入口：header/Index.svelte 指定 component 为 header，复用 Base.svelte 渲染 Ant Design 的 Header。 +- Footer（底部区域） + - 入口：footer/Index.svelte 指定 component 为 footer，复用 Base.svelte 渲染 Ant Design 的 Footer。 +- Content（内容区域） + - 入口：content/Index.svelte 指定 component 为 content，复用 Base.svelte 渲染 Ant Design 的 Content。 +- Sider（侧边栏） + - 入口：sider/Index.svelte 通过异步加载 layout.sider.tsx，实现 Ant Design 的 Sider，并支持 trigger 插槽。 + +章节来源 + +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/header/Index.svelte:1-15](file://frontend/antd/layout/header/Index.svelte#L1-L15) +- [frontend/antd/layout/footer/Index.svelte:1-15](file://frontend/antd/layout/footer/Index.svelte#L1-L15) +- [frontend/antd/layout/content/Index.svelte:1-15](file://frontend/antd/layout/content/Index.svelte#L1-L15) +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +## 架构总览 + +下图展示从 Svelte 到 Ant Design 的渲染链路，以及 Sider 的 trigger 插槽机制： + +```mermaid +sequenceDiagram +participant U as "用户代码" +participant L as "Layout/Index.svelte" +participant B as "Base.svelte" +participant LB as "layout.base.tsx" +participant AD as "Ant Design Layout" +U->>L : 传入 props如 children +L->>B : 透传 props 并设置 component="layout" +B->>LB : 计算并选择组件类型 +LB->>AD : 渲染 Ant Design Layout +AD-->>U : 布局容器渲染完成 +``` + +图表来源 + +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +章节来源 + +- [frontend/antd/layout/Index.svelte:1-18](file://frontend/antd/layout/Index.svelte#L1-L18) +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +## 详细组件分析 + +### 布局嵌套与区域组合 + +- 嵌套规则 + - Layout 作为根容器，可直接包含 Header、Sider、Content、Footer。 + - Sider 通常置于 Layout 左侧，Content 置于右侧，Header/ Footer 分别位于顶部与底部。 + - 可在 Content 中继续嵌套更细粒度的布局或栅格系统。 +- 响应式与固定定位 + - 通过 Sider 的折叠属性与断点配置，实现移动端自适应。 + - Header/ Footer 固定高度时，需确保 Content 的高度计算不受干扰，避免滚动冲突。 +- 触发器与交互 + - Sider 支持自定义 trigger 插槽，用于实现折叠按钮与图标切换。 + +```mermaid +flowchart TD +Start(["开始"]) --> Root["Layout 根容器"] +Root --> Hdr["Header 顶部区域"] +Root --> Sider["Sider 侧边栏"] +Root --> Cnt["Content 主内容区"] +Root --> Ftr["Footer 底部区域"] +Sider --> Trigger["trigger 插槽可选"] +Cnt --> Inner["内部嵌套栅格/卡片/列表等"] +Hdr --> End(["结束"]) +Ftr --> End +``` + +图表来源 + +- [frontend/antd/layout/header/Index.svelte:1-15](file://frontend/antd/layout/header/Index.svelte#L1-L15) +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/content/Index.svelte:1-15](file://frontend/antd/layout/content/Index.svelte#L1-L15) +- [frontend/antd/layout/footer/Index.svelte:1-15](file://frontend/antd/layout/footer/Index.svelte#L1-L15) + +章节来源 + +- [frontend/antd/layout/header/Index.svelte:1-15](file://frontend/antd/layout/header/Index.svelte#L1-L15) +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/content/Index.svelte:1-15](file://frontend/antd/layout/content/Index.svelte#L1-L15) +- [frontend/antd/layout/footer/Index.svelte:1-15](file://frontend/antd/layout/footer/Index.svelte#L1-L15) + +### Sider 组件与触发器插槽 + +- 触发器机制 + - 若提供 trigger 插槽，则优先使用插槽内容；若未提供且 trigger 为默认值，则渲染默认触发器；否则按传入的 trigger 值决定是否显示。 +- 折叠状态管理 + - 结合 Sider 的 collapsed 状态与 trigger 行为，实现点击切换展开/收起。 + +```mermaid +flowchart TD +A["进入 Sider 渲染"] --> B{"是否存在 trigger 插槽？"} +B -- 是 --> C["渲染插槽内容作为触发器"] +B -- 否 --> D{"trigger 是否为默认值？"} +D -- 是 --> E["渲染默认触发器"] +D -- 否 --> F{"trigger 是否为 null/undefined？"} +F -- 是 --> G["不渲染触发器"] +F -- 否 --> H["渲染传入的 trigger 内容"] +C --> I["完成"] +E --> I +G --> I +H --> I +``` + +图表来源 + +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +章节来源 + +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +### 经典页面布局模板 + +- 侧边栏布局 + - 使用 Layout + Header + Sider + Content + Footer 的组合，Sider 固定宽度并在移动端可折叠。 +- 顶部导航布局 + - 使用 Layout + Header（仅顶部导航）+ Content，Sider 可省略或隐藏。 +- 混合布局 + - 在 Content 内部嵌套栅格系统，实现多列内容与侧边信息面板的组合。 + +章节来源 + +- [docs/components/antd/layout/README.md:1-8](file://docs/components/antd/layout/README.md#L1-L8) + +### 与栅格系统的结合 + +- 在 Content 中使用栅格 Row/Col 进行列划分，配合响应式断点实现自适应。 +- 注意：当 Header/ Footer 高度固定时，Content 的高度计算需考虑可视区域剩余空间，避免溢出或滚动异常。 + +## 依赖关系分析 + +- 组件耦合 + - 所有区域组件均依赖 Base.svelte 的属性处理与渲染流程，降低重复代码，提升一致性。 + - Sider 独立实现 layout.sider.tsx，避免与通用 Base 流程耦合，增强扩展性。 +- 外部依赖 + - Ant Design 的 Layout、Header、Footer、Content、Sider 组件作为渲染目标。 + - Svelte Slot 与 React Slot 的桥接用于插槽传递与克隆。 + +```mermaid +graph LR +Base["Base.svelte"] --> Wrap["layout.base.tsx"] +Wrap --> ADL["Ant Design Layout"] +Wrap --> ADH["Ant Design Header"] +Wrap --> ADF["Ant Design Footer"] +Wrap --> ADC["Ant Design Content"] +SBase["sider/Index.svelte"] --> SWrap["layout.sider.tsx"] +SWrap --> ADS["Ant Design Sider"] +``` + +图表来源 + +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +章节来源 + +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +## 性能考量 + +- 异步加载 + - Sider 通过 importComponent 异步加载实现，减少初始包体与首屏阻塞。 +- 属性透传与派生 + - Base.svelte 对属性进行统一处理与派生，避免不必要的重渲染。 +- 样式类名 + - 通过条件拼接类名，避免运行时大量字符串拼接开销。 + +章节来源 + +- [frontend/antd/layout/sider/Index.svelte:1-62](file://frontend/antd/layout/sider/Index.svelte#L1-L62) +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) + +## 故障排查指南 + +- 无内容渲染 + - 检查 visible 属性是否被置为 false；确认 Base.svelte 的可见性判断逻辑。 +- Sider 触发器不显示 + - 确认是否提供了 trigger 插槽；检查 trigger 值是否为 null/undefined 或默认值。 +- 样式异常 + - 确认是否正确拼接了类名；检查是否有外部样式覆盖导致布局错位。 + +章节来源 + +- [frontend/antd/layout/Base.svelte:1-71](file://frontend/antd/layout/Base.svelte#L1-L71) +- [frontend/antd/layout/sider/layout.sider.tsx:1-26](file://frontend/antd/layout/sider/layout.sider.tsx#L1-L26) + +## 结论 + +Layout 布局组件通过统一的基座与区域化拆分，实现了对 Ant Design 布局体系的完整封装。借助 Sider 的触发器插槽与异步加载机制，既保证了灵活性，也兼顾了性能。结合栅格系统与响应式断点，可快速搭建多种经典页面布局模板，并通过样式与主题定制满足复杂业务场景。 + +## 附录 + +- 示例入口参考：[docs/components/antd/layout/README.md:1-8](file://docs/components/antd/layout/README.md#L1-L8) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Masonry \347\200\221\345\270\203\346\265\201\345\270\203\345\261\200.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Masonry \347\200\221\345\270\203\346\265\201\345\270\203\345\261\200.md" new file mode 100644 index 00000000..c497a9f4 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Masonry \347\200\221\345\270\203\346\265\201\345\270\203\345\261\200.md" @@ -0,0 +1,464 @@ +# Masonry 瀑布流布局 + + +**本文档引用的文件** +- [frontend/antd/masonry/masonry.tsx](file://frontend/antd/masonry/masonry.tsx) +- [frontend/antd/masonry/context.ts](file://frontend/antd/masonry/context.ts) +- [frontend/antd/masonry/Index.svelte](file://frontend/antd/masonry/Index.svelte) +- [frontend/antd/masonry/package.json](file://frontend/antd/masonry/package.json) +- [backend/modelscope_studio/components/antd/masonry/__init__.py](file://backend/modelscope_studio/components/antd/masonry/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [docs/components/antd/masonry/README.md](file://docs/components/antd/masonry/README.md) +- [docs/components/antd/masonry/README-zh_CN.md](file://docs/components/antd/masonry/README-zh_CN.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构概览](#架构概览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) + +## 简介 + +Masonry 瀑布流布局是 ModelScope Studio 中的一个重要布局组件，基于 Ant Design 的 Masonry 组件实现。该组件专门用于显示具有不同高度的内容，如图片、卡片等，能够自动创建瀑布流效果，使内容在多列布局中均匀分布。 + +瀑布流布局特别适用于以下场景： + +- 展示具有不规则高度的图片或卡片 +- 需要在列之间均匀分布内容 +- 需要响应式列数调整的布局需求 + +## 项目结构 + +ModelScope Studio 采用前后端分离的架构设计，Masonry 组件在项目中的组织结构如下： + +```mermaid +graph TB +subgraph "前端层" +A[frontend/antd/masonry/] --> A1[masonry.tsx] +A --> A2[Index.svelte] +A --> A3[context.ts] +A --> A4[package.json] +subgraph "utils/" +B[frontend/utils/] --> B1[createItemsContext.tsx] +B --> B2[renderItems.tsx] +B --> B3[renderParamsSlot.tsx] +end +end +subgraph "后端层" +C[backend/modelscope_studio/] --> C1[components/antd/masonry/] +C --> C2[components/antd/components.py] +C1 --> C3[__init__.py] +end +subgraph "文档层" +D[docs/components/antd/masonry/] --> D1[README.md] +D --> D2[README-zh_CN.md] +end +A1 --> B1 +A1 --> B2 +A1 --> B3 +C3 --> A2 +``` + +**图表来源** + +- [frontend/antd/masonry/masonry.tsx:1-52](file://frontend/antd/masonry/masonry.tsx#L1-L52) +- [frontend/antd/masonry/Index.svelte:1-64](file://frontend/antd/masonry/Index.svelte#L1-L64) +- [backend/modelscope_studio/components/antd/masonry/**init**.py:1-83](file://backend/modelscope_studio/components/antd/masonry/__init__.py#L1-L83) + +**章节来源** + +- [frontend/antd/masonry/masonry.tsx:1-52](file://frontend/antd/masonry/masonry.tsx#L1-L52) +- [frontend/antd/masonry/Index.svelte:1-64](file://frontend/antd/masonry/Index.svelte#L1-L64) +- [backend/modelscope_studio/components/antd/masonry/**init**.py:1-83](file://backend/modelscope_studio/components/antd/masonry/__init__.py#L1-L83) + +## 核心组件 + +### 前端核心组件 + +Masonry 组件的核心实现位于 `frontend/antd/masonry/masonry.tsx` 文件中，该组件使用了 React 和 Ant Design 的 Masonry 组件，并集成了 ModelScope Studio 的组件系统。 + +主要特性包括： + +- **React 包装器**: 使用 `sveltify` 将 Svelte 组件包装为 React 组件 +- **上下文管理**: 集成 `createItemsContext` 实现组件间的数据共享 +- **插槽渲染**: 支持自定义插槽渲染功能 +- **动态内容**: 支持动态内容更新和重新渲染 + +### 后端集成组件 + +后端组件位于 `backend/modelscope_studio/components/antd/masonry/__init__.py`，提供了 Python 接口与前端组件的桥接。 + +关键属性和方法： + +- **EVENTS**: 定义了 `layout_change` 事件监听 +- **SLOTS**: 支持 `items` 和 `itemRender` 插槽 +- **PROPS**: 提供 `columns`、`gutter`、`fresh` 等配置选项 + +**章节来源** + +- [frontend/antd/masonry/masonry.tsx:10-49](file://frontend/antd/masonry/masonry.tsx#L10-L49) +- [backend/modelscope_studio/components/antd/masonry/**init**.py:10-65](file://backend/modelscope_studio/components/antd/masonry/__init__.py#L10-L65) + +## 架构概览 + +Masonry 组件的整体架构采用了分层设计，确保了良好的可维护性和扩展性： + +```mermaid +graph TD +subgraph "用户界面层" +UI[Masonry 组件] +end +subgraph "前端逻辑层" +FC[函数组件] +CTX[上下文提供者] +SL[插槽处理] +end +subgraph "工具层" +CIC[createItemsContext] +RI[renderItems] +RPS[renderParamsSlot] +end +subgraph "Ant Design 层" +AD[Antd Masonry] +end +subgraph "后端集成层" +BC[后端组件] +PC[Python 接口] +end +UI --> FC +FC --> CTX +FC --> SL +FC --> AD +CTX --> CIC +SL --> RI +SL --> RPS +BC --> PC +BC --> UI +``` + +**图表来源** + +- [frontend/antd/masonry/masonry.tsx:1-52](file://frontend/antd/masonry/masonry.tsx#L1-L52) +- [frontend/utils/createItemsContext.tsx:97-184](file://frontend/utils/createItemsContext.tsx#L97-L184) +- [frontend/utils/renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +## 详细组件分析 + +### Masonry 组件实现 + +Masonry 组件的核心实现包含以下关键部分： + +#### 组件包装和属性处理 + +组件使用 `sveltify` 函数将 Svelte 组件包装为 React 组件，支持属性传递和事件处理： + +```mermaid +sequenceDiagram +participant User as 用户 +participant Masonry as Masonry 组件 +participant Context as 上下文提供者 +participant Utils as 工具函数 +User->>Masonry : 传入 props 和 children +Masonry->>Context : withItemsContextProvider 包装 +Context->>Utils : useItems 获取数据 +Utils->>Utils : renderItems 处理插槽 +Utils->>Masonry : 返回处理后的数据 +Masonry->>Masonry : useMemo 优化渲染 +Masonry->>User : 渲染最终结果 +``` + +**图表来源** + +- [frontend/antd/masonry/masonry.tsx:16-48](file://frontend/antd/masonry/masonry.tsx#L16-L48) +- [frontend/antd/masonry/context.ts:3-4](file://frontend/antd/masonry/context.ts#L3-L4) + +#### 数据流处理机制 + +组件通过 `createItemsContext` 实现数据流管理： + +```mermaid +flowchart TD +Start([组件初始化]) --> GetItems[获取 useItems 上下文] +GetItems --> CheckSlots{检查插槽类型} +CheckSlots --> |有 items| UseItems[使用 items 属性] +CheckSlots --> |无 items| UseSlots[使用插槽数据] +UseSlots --> ResolveSlot[解析插槽数据] +ResolveSlot --> RenderItems[调用 renderItems] +UseItems --> RenderItems +RenderItems --> MemoOptimize[useMemo 优化] +MemoOptimize --> FinalRender[最终渲染] +FinalRender --> End([完成]) +``` + +**图表来源** + +- [frontend/antd/masonry/masonry.tsx:18-43](file://frontend/antd/masonry/masonry.tsx#L18-L43) +- [frontend/utils/renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) + +**章节来源** + +- [frontend/antd/masonry/masonry.tsx:1-52](file://frontend/antd/masonry/masonry.tsx#L1-L52) +- [frontend/antd/masonry/context.ts:1-7](file://frontend/antd/masonry/context.ts#L1-L7) + +### 上下文管理系统 + +`createItemsContext` 提供了完整的上下文管理功能： + +#### 上下文提供者模式 + +```mermaid +classDiagram +class ItemsContextProvider { ++allowedSlots : string[] ++items : ItemsContextValue ++setItem(slotKey, index, value) ++onChange(items) +} +class ItemsContextValue { ++items : Record~string, Item[]~ ++setItem : Function ++initial : boolean +} +class ItemHandler { ++itemIndex : number ++itemSlotKey : string ++itemElement : HTMLElement ++itemProps(props, items) ++itemChildren(items) ++slots : Record~string, Slot~ +} +ItemsContextProvider --> ItemsContextValue : "提供" +ItemHandler --> ItemsContextProvider : "使用" +``` + +**图表来源** + +- [frontend/utils/createItemsContext.tsx:108-170](file://frontend/utils/createItemsContext.tsx#L108-L170) +- [frontend/utils/createItemsContext.tsx:190-261](file://frontend/utils/createItemsContext.tsx#L190-L261) + +#### 数据处理流程 + +组件的数据处理遵循以下流程： + +1. **数据收集**: 从插槽中收集所有子元素 +2. **数据转换**: 将 HTML 元素转换为内部数据结构 +3. **上下文传递**: 通过 React Context 在组件树中传递数据 +4. **状态管理**: 使用 useState 和 useEffect 管理组件状态 + +**章节来源** + +- [frontend/utils/createItemsContext.tsx:97-274](file://frontend/utils/createItemsContext.tsx#L97-L274) + +### 插槽渲染系统 + +Masonry 组件支持灵活的插槽渲染机制： + +#### 插槽处理函数 + +```mermaid +flowchart LR +Slots[插槽对象] --> CheckSlot{检查插槽存在} +CheckSlot --> |存在| RenderSlot[renderSlot 渲染] +CheckSlot --> |不存在| Fallback[回退处理] +RenderSlot --> ParamsSlot{参数化插槽} +ParamsSlot --> |有参数| RenderParams[renderParamsSlot] +ParamsSlot --> |无参数| DirectRender[直接渲染] +RenderParams --> Clone[克隆元素] +DirectRender --> Clone +Clone --> Result[返回 React 节点] +Fallback --> Result +``` + +**图表来源** + +- [frontend/utils/renderParamsSlot.tsx:5-49](file://frontend/utils/renderParamsSlot.tsx#L5-L49) +- [frontend/utils/renderItems.tsx:72-94](file://frontend/utils/renderItems.tsx#L72-L94) + +**章节来源** + +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) + +## 依赖关系分析 + +### 组件依赖图 + +```mermaid +graph TB +subgraph "Masonry 组件依赖" +A[masonry.tsx] --> B[createItemsContext.tsx] +A --> C[renderItems.tsx] +A --> D[renderParamsSlot.tsx] +A --> E[context.ts] +end +subgraph "上下文依赖" +B --> F[React Hooks] +B --> G[useMemoizedEqualValue] +B --> H[useMemoizedFn] +end +subgraph "工具函数依赖" +C --> I[ReactSlot] +C --> J[ContextPropsProvider] +D --> K[renderSlot] +end +subgraph "后端集成" +L[__init__.py] --> M[AntdMasonry] +L --> N[AntdMasonryItem] +end +A -.-> O[Antd Masonry] +L -.-> P[Gradio 事件] +``` + +**图表来源** + +- [frontend/antd/masonry/masonry.tsx:1-6](file://frontend/antd/masonry/masonry.tsx#L1-L6) +- [frontend/utils/createItemsContext.tsx:1-18](file://frontend/utils/createItemsContext.tsx#L1-L18) +- [backend/modelscope_studio/components/antd/masonry/**init**.py:1-8](file://backend/modelscope_studio/components/antd/masonry/__init__.py#L1-L8) + +### 关键依赖说明 + +1. **Ant Design Masonry**: 核心布局组件，提供瀑布流布局功能 +2. **React Hooks**: 用于状态管理和性能优化 +3. **Gradio 集成**: 支持 Python 后端的事件处理 +4. **Svelte Preprocess**: 实现 Svelte 到 React 的转换 + +**章节来源** + +- [frontend/antd/masonry/masonry.tsx:1-6](file://frontend/antd/masonry/masonry.tsx#L1-L6) +- [backend/modelscope_studio/components/antd/masonry/**init**.py:23-27](file://backend/modelscope_studio/components/antd/masonry/__init__.py#L23-L27) + +## 性能考虑 + +### 渲染优化策略 + +Masonry 组件采用了多种性能优化技术： + +#### useMemo 优化 + +组件使用 `useMemo` 缓存计算结果，避免不必要的重新渲染： + +```typescript +const memoizedItems = useMemo(() => { + return items || renderItems(resolvedSlotItems); +}, [items, resolvedSlotItems]); +``` + +#### 事件处理优化 + +使用 `useFunction` 和 `useMemoizedFn` 优化事件处理器的性能： + +```typescript +const itemRenderFunction = useFunction(props.itemRender); +``` + +#### 条件渲染 + +通过条件渲染减少 DOM 操作： + +```html +
{children}
+```
+
+### 内存管理
+
+组件实现了智能的内存管理机制：
+
+1. **引用缓存**: 使用 `useRef` 缓存昂贵的计算结果
+2. **状态同步**: 通过 `useEffect` 同步状态变化
+3. **清理机制**: 在组件卸载时清理事件监听器
+
+## 故障排除指南
+
+### 常见问题及解决方案
+
+#### 1. 组件不显示内容
+
+**症状**: Masonry 组件渲染为空白
+
+**可能原因**:
+
+- 插槽数据未正确设置
+- items 属性未提供
+- React 组件未正确包装
+
+**解决方法**:
+
+1. 检查插槽是否正确传递
+2. 确认 items 属性是否包含有效数据
+3. 验证组件包装是否正确
+
+#### 2. 布局错乱
+
+**症状**: 瀑布流布局显示异常
+
+**可能原因**:
+
+- 列数配置不正确
+- 边距设置不当
+- 内容高度计算错误
+
+**解决方法**:
+
+1. 检查 columns 配置
+2. 调整 gutter 设置
+3. 确保内容具有正确的高度信息
+
+#### 3. 性能问题
+
+**症状**: 组件渲染缓慢或卡顿
+
+**可能原因**:
+
+- 大量数据导致的渲染压力
+- 不必要的重新渲染
+- 事件处理器性能问题
+
+**解决方法**:
+
+1. 使用虚拟滚动处理大量数据
+2. 优化 useMemo 的依赖项
+3. 减少事件处理器的复杂度
+
+**章节来源**
+
+- [frontend/antd/masonry/masonry.tsx:36-43](file://frontend/antd/masonry/masonry.tsx#L36-L43)
+- [frontend/utils/createItemsContext.tsx:124-153](file://frontend/utils/createItemsContext.tsx#L124-L153)
+
+## 结论
+
+Masonry 瀑布流布局组件是 ModelScope Studio 中一个功能强大且设计精良的布局解决方案。该组件通过以下特点展现了优秀的架构设计：
+
+### 主要优势
+
+1. **模块化设计**: 采用清晰的模块划分，便于维护和扩展
+2. **性能优化**: 实现了多种性能优化技术，确保流畅的用户体验
+3. **灵活性**: 支持多种配置选项和自定义渲染功能
+4. **类型安全**: 完整的 TypeScript 类型定义，提供良好的开发体验
+
+### 技术亮点
+
+- **上下文管理模式**: 通过 `createItemsContext` 实现了强大的数据流管理
+- **插槽渲染系统**: 支持复杂的插槽渲染和参数化渲染
+- **React 集成**: 无缝集成到 React 生态系统中
+- **后端兼容**: 提供 Python 后端接口，支持 Gradio 事件处理
+
+### 应用场景
+
+Masonry 组件特别适用于以下场景：
+
+- 图片画廊展示
+- 卡片内容布局
+- 动态内容容器
+- 响应式网格布局
+
+该组件为 ModelScope Studio 提供了强大的布局能力，是构建现代化 Web 应用的重要基础设施之一。
diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Space \351\227\264\350\267\235.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Space \351\227\264\350\267\235.md"
new file mode 100644
index 00000000..96d5bfc1
--- /dev/null
+++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Space \351\227\264\350\267\235.md"
@@ -0,0 +1,268 @@
+# Space 间距
+
+
+**本文引用的文件**
+- [frontend/antd/space/space.tsx](file://frontend/antd/space/space.tsx)
+- [frontend/antd/space/Index.svelte](file://frontend/antd/space/Index.svelte)
+- [frontend/antd/space/compact/space.compact.tsx](file://frontend/antd/space/compact/space.compact.tsx)
+- [frontend/antd/space/compact/Index.svelte](file://frontend/antd/space/compact/Index.svelte)
+- [backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js](file://backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js)
+- [backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js](file://backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js)
+- [docs/components/antd/space/README.md](file://docs/components/antd/space/README.md)
+- [docs/components/antd/space/README-zh_CN.md](file://docs/components/antd/space/README-zh_CN.md)
+
+
+## 目录
+
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+
+Space 间距组件用于在多个子元素之间自动插入统一的间距，支持方向控制、间距大小配置，并可与分隔符插槽协作。该仓库提供了两种形态：
+
+- 标准 Space：基于 Ant Design 的 Space 组件封装，负责自动分配间距与方向控制。
+- 紧凑模式 Space Compact：基于 Ant Design 的 Space.Compact 封装，强调更紧密的布局与紧凑的间距策略。
+
+此外，组件通过 Svelte 与 React 的桥接机制，将 Svelte 子节点映射到 React Space/Space.Compact 的子节点，确保在 Gradio 生态中稳定渲染。
+
+## 项目结构
+
+Space 组件由前端 Svelte 层与后端模板层共同构成：
+
+- 前端 Svelte 层：负责属性透传、样式拼接、可见性控制与子节点渲染。
+- 后端模板层：生成最终的 React 包装器，处理 slot 排序、ReactSlot 渲染与 Portal 桥接。
+
+```mermaid
+graph TB
+subgraph "前端 Svelte 层"
+IDX["Index.svelte标准 Space 入口"] +COMPACT_IDX["compact/Index.svelte
紧凑 Space 入口"] +SPACE_TSX["space.tsx
标准 Space React 包装"] +COMPACT_TSX["compact/space.compact.tsx
紧凑 Space React 包装"] +end +subgraph "后端模板层" +RT_SPACE["space-BWI0-XH7.js
标准 Space 模板"] +RT_COMPACT["space.compact-C2LVtCsM.js
紧凑 Space 模板"] +end +IDX --> SPACE_TSX --> RT_SPACE +COMPACT_IDX --> COMPACT_TSX --> RT_COMPACT +``` + +**图表来源** + +- [frontend/antd/space/Index.svelte:1-61](file://frontend/antd/space/Index.svelte#L1-L61) +- [frontend/antd/space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js:651-679](file://backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L651-L679) +- [frontend/antd/space/compact/Index.svelte:1-60](file://frontend/antd/space/compact/Index.svelte#L1-L60) +- [frontend/antd/space/compact/space.compact.tsx:1-24](file://frontend/antd/space/compact/space.compact.tsx#L1-L24) +- [backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:651-674](file://backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L651-L674) + +**章节来源** + +- [frontend/antd/space/Index.svelte:1-61](file://frontend/antd/space/Index.svelte#L1-L61) +- [frontend/antd/space/compact/Index.svelte:1-60](file://frontend/antd/space/compact/Index.svelte#L1-L60) +- [docs/components/antd/space/README.md:1-8](file://docs/components/antd/space/README.md#L1-L8) +- [docs/components/antd/space/README-zh_CN.md:1-8](file://docs/components/antd/space/README-zh_CN.md#L1-L8) + +## 核心组件 + +- 标准 Space（Space）：负责自动收集子节点、注入分隔符插槽、按顺序渲染子项，支持方向、大小、对齐等配置。 +- 紧凑 Space（Space.Compact）：在紧凑模式下，减少默认间距，强调相邻元素的紧密排列，适合工具栏、按钮组等密集布局。 + +两者均通过 Svelte 的 importComponent 动态加载对应的 React 包装器，并将 slots 与额外属性透传给底层 React 组件。 + +**章节来源** + +- [frontend/antd/space/space.tsx:7-26](file://frontend/antd/space/space.tsx#L7-L26) +- [frontend/antd/space/compact/space.compact.tsx:7-21](file://frontend/antd/space/compact/space.compact.tsx#L7-L21) +- [frontend/antd/space/Index.svelte:10-60](file://frontend/antd/space/Index.svelte#L10-L60) +- [frontend/antd/space/compact/Index.svelte:10-60](file://frontend/antd/space/compact/Index.svelte#L10-L60) + +## 架构总览 + +Space 的调用链路从 Svelte 到 React，再回到 DOM，涉及 slot 解析、子节点排序与 Portal 桥接。 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 组件(Index.svelte)" +participant Loader as "importComponent" +participant ReactWrap as "React 包装(space.tsx 或 space.compact.tsx)" +participant BackendRT as "后端模板(space-BWI0-XH7.js / space.compact-C2LVtCsM.js)" +participant Antd as "Ant Design Space/Space.Compact" +Svelte->>Loader : 加载对应 React 包装器 +Loader-->>Svelte : 返回 React 组件 +Svelte->>ReactWrap : 传递 props 与 slots +ReactWrap->>BackendRT : 转换 children 为 ReactSlot +BackendRT->>Antd : 渲染 Space/Space.Compact 并注入子节点 +Antd-->>Svelte : 输出最终 DOM 结构 +``` + +**图表来源** + +- [frontend/antd/space/Index.svelte:10-60](file://frontend/antd/space/Index.svelte#L10-L60) +- [frontend/antd/space/space.tsx:7-26](file://frontend/antd/space/space.tsx#L7-L26) +- [backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js:651-679](file://backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L651-L679) +- [frontend/antd/space/compact/Index.svelte:10-60](file://frontend/antd/space/compact/Index.svelte#L10-L60) +- [frontend/antd/space/compact/space.compact.tsx:7-21](file://frontend/antd/space/compact/space.compact.tsx#L7-L21) +- [backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:651-674](file://backend/modelscope_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L651-L674) + +## 详细组件分析 + +### 标准 Space 组件 + +- 自动子节点收集：通过工具函数解析 children，将其转换为 ReactSlot，保证顺序与克隆策略可控。 +- 分隔符插槽：支持通过 slots.split 注入分隔符，若未提供则回退到 props.split。 +- 属性透传：除内部属性外，其余 props 透传至 Ant Design Space，保持与原生一致的 API。 + +```mermaid +flowchart TD +Start(["进入 Space 渲染"]) --> Collect["收集 children 并解析为 targets"] +Collect --> SplitCheck{"是否提供 split 插槽?"} +SplitCheck --> |是| UseSlot["使用 slots.split 对应的 ReactSlot"] +SplitCheck --> |否| UseProp["使用 props.split"] +UseSlot --> Render["遍历 targets 并逐个渲染 ReactSlot"] +UseProp --> Render +Render --> End(["完成渲染"]) +``` + +**图表来源** + +- [frontend/antd/space/space.tsx:8-25](file://frontend/antd/space/space.tsx#L8-L25) +- [backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js:656-673](file://backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L656-L673) + +**章节来源** + +- [frontend/antd/space/space.tsx:7-26](file://frontend/antd/space/space.tsx#L7-L26) +- [backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js:651-679](file://backend/modelscope_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L651-L679) + +### 紧凑 Space 组件 + +- 紧凑模式：使用 Ant Design 的 Space.Compact，减少默认间距，适合按钮组、工具条等需要紧密排列的场景。 +- 子节点处理：与标准 Space 类似，先隐藏原始 children，再以 ReactSlot 方式逐一渲染，确保 slot 排序与克隆策略一致。 + +```mermaid +flowchart TD +StartC(["进入 Space.Compact 渲染"]) --> Targets["解析 children 为目标节点数组"] +Targets --> RenderC["逐个渲染 ReactSlot 并注入 Compact 容器"] +RenderC --> EndC(["完成渲染"]) +``` + +**图表来源** + +- [frontend/antd/space/compact/space.compact.tsx:8-20](file://frontend/antd/space/compact/space.compact.tsx#L8-L20) +- [backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:651-669](file://backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L651-L669) + +**章节来源** + +- [frontend/antd/space/compact/space.compact.tsx:7-21](file://frontend/antd/space/compact/space.compact.tsx#L7-L21) +- [backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:651-674](file://backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L651-L674) + +### Svelte 到 React 的桥接机制 + +- Slot 排序：根据 slotIndex 与 subSlotIndex 对子节点进行稳定排序，保证渲染顺序一致。 +- Portal 桥接：将 Svelte 的 slot 内容克隆并挂载到 React 环境，同时保留事件监听与样式。 +- 可见性与样式：通过 Svelte 层拼接 className 与内联样式，最终注入到 React 组件上。 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte(Index.svelte)" +participant SlotSort as "slot 排序" +participant Bridge as "Portal 桥接" +participant React as "React 包装器" +participant DOM as "Antd Space/Space.Compact" +Svelte->>SlotSort : 获取并排序 slot +SlotSort-->>Bridge : 返回有序的 portalTarget +Bridge->>React : 生成 ReactSlot 并克隆节点 +React->>DOM : 渲染最终 DOM +``` + +**图表来源** + +- [frontend/antd/space/Index.svelte:44-60](file://frontend/antd/space/Index.svelte#L44-L60) +- [backend/modelspace_studio/components/antd/space/templates/component/space-BWI0-XH7.js:642-650](file://backend/modelspace_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L642-L650) +- [frontend/antd/space/compact/Index.svelte:43-60](file://frontend/antd/space/compact/Index.svelte#L43-L60) +- [backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:642-650](file://backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L642-L650) + +**章节来源** + +- [frontend/antd/space/Index.svelte:10-60](file://frontend/antd/space/Index.svelte#L10-L60) +- [frontend/antd/space/compact/Index.svelte:10-60](file://frontend/antd/space/compact/Index.svelte#L10-L60) +- [backend/modelspace_studio/components/antd/space/templates/component/space-BWI0-XH7.js:642-650](file://backend/modelspace_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L642-L650) +- [backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:642-650](file://backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L642-L650) + +## 依赖关系分析 + +- 组件耦合：Space 与 Space.Compact 在前端层共享相同的桥接逻辑，仅在底层使用的 Ant Design 组件不同。 +- 外部依赖：依赖 Ant Design 的 Space/Space.Compact；通过 @svelte-preprocess-react 提供 slot 与 ReactSlot 支持。 +- 后端模板：模板层负责将 Svelte 的 slot 排序与 Portal 桥接逻辑转化为可执行的 React 代码。 + +```mermaid +graph LR +Svelte_Index["Index.svelte"] --> React_Space["space.tsx"] +Svelte_Compact["compact/Index.svelte"] --> React_Compact["compact/space.compact.tsx"] +React_Space --> RT_Space["space-BWI0-XH7.js"] +React_Compact --> RT_Compact["space.compact-C2LVtCsM.js"] +RT_Space --> Antd["Ant Design Space"] +RT_Compact --> AntdCompact["Ant Design Space.Compact"] +``` + +**图表来源** + +- [frontend/antd/space/Index.svelte:10-60](file://frontend/antd/space/Index.svelte#L10-L60) +- [frontend/antd/space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [backend/modelspace_studio/components/antd/space/templates/component/space-BWI0-XH7.js:651-679](file://backend/modelspace_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L651-L679) +- [frontend/antd/space/compact/Index.svelte:10-60](file://frontend/antd/space/compact/Index.svelte#L10-L60) +- [frontend/antd/space/compact/space.compact.tsx:1-24](file://frontend/antd/space/compact/space.compact.tsx#L1-L24) +- [backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:651-674](file://backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L651-L674) + +**章节来源** + +- [frontend/antd/space/space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [frontend/antd/space/compact/space.compact.tsx:1-24](file://frontend/antd/space/compact/space.compact.tsx#L1-L24) +- [backend/modelspace_studio/components/antd/space/templates/component/space-BWI0-XH7.js:651-679](file://backend/modelspace_studio/components/antd/space/templates/component/space-BWI0-XH7.js#L651-L679) +- [backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js:651-674](file://backend/modelspace_studio/components/antd/space/compact/templates/component/space.compact-C2LVtCsM.js#L651-L674) + +## 性能考量 + +- 子节点克隆与 Portal：通过克隆与 Portal 挂载，避免直接操作真实 DOM，但需注意大量子节点时的渲染成本。 +- slot 排序稳定性：基于索引的排序在数据量较大时仍保持稳定，但建议尽量减少不必要的 slot 变化以降低重排开销。 +- SSR 与 Hugging Face Space：在某些部署环境下需禁用 SSR 以避免自定义组件兼容问题，这会影响首屏渲染时间，建议在构建阶段优化资源加载。 + +[本节为通用性能建议，不直接分析具体文件] + +## 故障排查指南 + +- 子节点未正确渲染：检查 Svelte 层是否正确传递 slots 与 children，确认 slotIndex 与 subSlotIndex 是否设置正确。 +- 分隔符未生效：确认 split 插槽是否正确传入，或 props.split 是否按预期提供。 +- SSR 兼容问题：在 Hugging Face Space 中遇到界面异常时，尝试在 demo.launch 中添加 ssr_mode=False 参数。 + +**章节来源** + +- [frontend/antd/space/space.tsx:15-17](file://frontend/antd/space/space.tsx#L15-L17) +- [docs/components/antd/space/README.md:1-8](file://docs/components/antd/space/README.md#L1-L8) +- [docs/components/antd/space/README-zh_CN.md:1-8](file://docs/components/antd/space/README-zh_CN.md#L1-L8) + +## 结论 + +Space 间距组件通过 Svelte 与 React 的桥接，实现了在 Gradio 生态中对 Ant Design Space/Space.Compact 的无缝集成。标准 Space 适用于常规布局，Space.Compact 则更适合需要紧凑排列的场景。借助 slot 排序与 Portal 桥接，组件在复杂布局中也能保持良好的可维护性与一致性。 + +[本节为总结性内容，不直接分析具体文件] + +## 附录 + +- 使用示例：参见文档目录下的示例标签，可在相应页面查看基础用法演示。 +- 文档入口：标准 Space 与紧凑 Space 的文档说明位于 docs/components/antd/space 下。 + +**章节来源** + +- [docs/components/antd/space/README.md:5-8](file://docs/components/antd/space/README.md#L5-L8) +- [docs/components/antd/space/README-zh_CN.md:5-8](file://docs/components/antd/space/README-zh_CN.md#L5-L8) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Splitter \345\210\206\345\211\262\351\235\242\346\235\277.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Splitter \345\210\206\345\211\262\351\235\242\346\235\277.md" new file mode 100644 index 00000000..b86e4fc5 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/Splitter \345\210\206\345\211\262\351\235\242\346\235\277.md" @@ -0,0 +1,387 @@ +# Splitter 分割面板 + + +**本文引用的文件** +- [frontend/antd/splitter/Index.svelte](file://frontend/antd/splitter/Index.svelte) +- [frontend/antd/splitter/splitter.tsx](file://frontend/antd/splitter/splitter.tsx) +- [frontend/antd/splitter/panel/Index.svelte](file://frontend/antd/splitter/panel/Index.svelte) +- [frontend/antd/splitter/panel/splitter.panel.tsx](file://frontend/antd/splitter/panel/splitter.panel.tsx) +- [frontend/antd/splitter/context.ts](file://frontend/antd/splitter/context.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [backend/modelscope_studio/components/antd/splitter/panel/__init__.py](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py) +- [docs/components/antd/splitter/README.md](file://docs/components/antd/splitter/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Splitter 是一个基于 Ant Design 的分割面板组件，用于将界面划分为多个可拖拽调整大小的区域。它支持水平与垂直两种方向，并通过子组件 Panel 实现面板的声明式组织。该组件广泛适用于代码编辑器（左右布局）、图片对比（左右或上下）、多视图并排展示等场景。 + +本组件文档将从架构设计、数据流、拖拽与尺寸控制、响应式与交互体验、样式与无障碍等方面进行系统化说明，并提供典型应用示例与最佳实践建议。 + +## 项目结构 + +Splitter 在前端采用 Svelte + React Slot 的桥接方式，后端通过 Python 组件封装属性与渲染逻辑。核心文件分布如下： + +- 前端入口与桥接：frontend/antd/splitter/Index.svelte +- 分割容器实现：frontend/antd/splitter/splitter.tsx +- 面板子组件桥接：frontend/antd/splitter/panel/Index.svelte +- 面板子组件实现：frontend/antd/splitter/panel/splitter.panel.tsx +- 上下文与项管理：frontend/antd/splitter/context.ts、frontend/utils/createItemsContext.tsx +- 后端 Panel 组件封装：backend/modelscope_studio/components/antd/splitter/panel/**init**.py +- 文档与示例入口：docs/components/antd/splitter/README.md + +```mermaid +graph TB +subgraph "前端(Svelte)" +A["Index.svelte
入口桥接"] +B["splitter.tsx
Splitter 容器"] +C["panel/Index.svelte
Panel 桥接"] +D["panel/splitter.panel.tsx
Panel 实现"] +E["context.ts
Items 上下文"] +F["createItemsContext.tsx
通用项上下文工具"] +end +subgraph "后端(Python)" +G["panel/__init__.py
AntdSplitterPanel 封装"] +end +A --> B +A --> C +C --> D +B --> E +D --> E +E --> F +G --> C +``` + +图表来源 + +- [frontend/antd/splitter/Index.svelte:1-71](file://frontend/antd/splitter/Index.svelte#L1-L71) +- [frontend/antd/splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [frontend/antd/splitter/panel/Index.svelte:1-77](file://frontend/antd/splitter/panel/Index.svelte#L1-L77) +- [frontend/antd/splitter/panel/splitter.panel.tsx:1-14](file://frontend/antd/splitter/panel/splitter.panel.tsx#L1-L14) +- [frontend/antd/splitter/context.ts:1-7](file://frontend/antd/splitter/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [backend/modelscope_studio/components/antd/splitter/panel/**init**.py:1-85](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L1-L85) + +章节来源 + +- [frontend/antd/splitter/Index.svelte:1-71](file://frontend/antd/splitter/Index.svelte#L1-L71) +- [frontend/antd/splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [frontend/antd/splitter/panel/Index.svelte:1-77](file://frontend/antd/splitter/panel/Index.svelte#L1-L77) +- [frontend/antd/splitter/panel/splitter.panel.tsx:1-14](file://frontend/antd/splitter/panel/splitter.panel.tsx#L1-L14) +- [frontend/antd/splitter/context.ts:1-7](file://frontend/antd/splitter/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [backend/modelscope_studio/components/antd/splitter/panel/**init**.py:1-85](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L1-L85) +- [docs/components/antd/splitter/README.md:1-8](file://docs/components/antd/splitter/README.md#L1-L8) + +## 核心组件 + +- Splitter 容器：负责接收子面板集合，渲染 Ant Design 的分割容器，并将每个 Panel 渲染为 Antd 的 Panel 子项。 +- Panel 子组件：作为面板的占位与渲染单元，通过 Items 上下文收集面板属性与插槽内容，最终注入到 Splitter 中。 +- Items 上下文：提供“项收集”能力，允许 Panel 在渲染时向 Splitter 注入自身属性与 DOM 内容。 +- 后端封装：Python 层的 AntdSplitterPanel 提供默认尺寸、最小/最大尺寸、可折叠、可调整等属性的声明与传递。 + +章节来源 + +- [frontend/antd/splitter/splitter.tsx:7-35](file://frontend/antd/splitter/splitter.tsx#L7-L35) +- [frontend/antd/splitter/panel/splitter.panel.tsx:7-11](file://frontend/antd/splitter/panel/splitter.panel.tsx#L7-L11) +- [frontend/antd/splitter/context.ts:3-4](file://frontend/antd/splitter/context.ts#L3-L4) +- [frontend/utils/createItemsContext.tsx:97-184](file://frontend/utils/createItemsContext.tsx#L97-L184) +- [backend/modelscope_studio/components/antd/splitter/panel/**init**.py:8-68](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L8-L68) + +## 架构总览 + +Splitter 的运行时流程如下： + +- Svelte 入口桥接组件加载 Splitter 与 Panel 组件； +- Panel 通过 ItemHandler 将自身属性与插槽内容写入 Items 上下文； +- Splitter 使用 withItemsContextProvider 包裹，读取上下文中收集的面板列表； +- 最终渲染 Ant Design 的 Splitter 与 Panel。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant S as "Splitter.Index.svelte" +participant P as "Panel.Index.svelte" +participant IH as "ItemHandler(splt.panel.tsx)" +participant CTX as "ItemsContext(context.ts)" +participant RCTX as "createItemsContext.tsx" +participant C as "Antd Splitter" +U->>S : 渲染 Splitter +S->>RCTX : 初始化 Items 上下文 +U->>P : 渲染 Panel +P->>IH : 创建 ItemHandler +IH->>CTX : setItem(..., index, item) +CTX-->>S : 上下文变更回调 +S->>C : 渲染 Antd Splitter +C-->>U : 可拖拽分割的面板 +``` + +图表来源 + +- [frontend/antd/splitter/Index.svelte:10-52](file://frontend/antd/splitter/Index.svelte#L10-L52) +- [frontend/antd/splitter/panel/Index.svelte:10-69](file://frontend/antd/splitter/panel/Index.svelte#L10-L69) +- [frontend/antd/splitter/panel/splitter.panel.tsx:7-11](file://frontend/antd/splitter/panel/splitter.panel.tsx#L7-L11) +- [frontend/antd/splitter/context.ts:3-4](file://frontend/antd/splitter/context.ts#L3-L4) +- [frontend/utils/createItemsContext.tsx:108-170](file://frontend/utils/createItemsContext.tsx#L108-L170) +- [frontend/antd/splitter/splitter.tsx:7-35](file://frontend/antd/splitter/splitter.tsx#L7-L35) + +## 详细组件分析 + +### Splitter 容器组件 + +- 责任边界：将收集到的面板项映射为 Ant Design 的 Panel，并渲染分割容器。 +- 关键点： + - 使用 withItemsContextProvider 包裹，确保能读取到由 Panel 注入的 items。 + - 通过 ReactSlot 将插槽内容渲染到对应 Panel。 + - 当没有面板时，不渲染任何内容，避免空容器造成的布局问题。 + +```mermaid +flowchart TD +Start(["进入 Splitter"]) --> Read["读取上下文 items"] +Read --> HasPanels{"是否有面板?"} +HasPanels -- 否 --> Exit["返回空"] +HasPanels -- 是 --> Render["遍历面板并渲染 Antd Panel"] +Render --> Done(["完成"]) +``` + +图表来源 + +- [frontend/antd/splitter/splitter.tsx:8-35](file://frontend/antd/splitter/splitter.tsx#L8-L35) + +章节来源 + +- [frontend/antd/splitter/splitter.tsx:7-35](file://frontend/antd/splitter/splitter.tsx#L7-L35) + +### Panel 子组件 + +- 责任边界：作为单个面板的占位与渲染单元，负责将自身属性与插槽内容注入到 Items 上下文。 +- 关键点： + - 通过 ItemHandler 将 itemIndex、itemSlotKey、itemElement 等信息写入上下文。 + - 支持 visible 控制显示；支持额外属性透传与样式类名绑定。 + - 插槽内容通过 Svelte slot 机制收集，并在 Splitter 中以 ReactSlot 渲染。 + +```mermaid +classDiagram +class PanelBridge { ++props : 所有透传属性 ++visible : 是否可见 ++_internal.index : 面板索引 ++elem_id/ elem_classes/ elem_style : 样式与标识 ++slots : 插槽内容 +} +class ItemHandler { ++itemIndex : number ++itemSlotKey : string ++itemElement : HTMLElement ++setItem(...) +} +PanelBridge --> ItemHandler : "注入项" +``` + +图表来源 + +- [frontend/antd/splitter/panel/Index.svelte:25-69](file://frontend/antd/splitter/panel/Index.svelte#L25-L69) +- [frontend/antd/splitter/panel/splitter.panel.tsx:7-11](file://frontend/antd/splitter/panel/splitter.panel.tsx#L7-L11) +- [frontend/antd/splitter/context.ts:3-4](file://frontend/antd/splitter/context.ts#L3-L4) + +章节来源 + +- [frontend/antd/splitter/panel/Index.svelte:14-69](file://frontend/antd/splitter/panel/Index.svelte#L14-L69) +- [frontend/antd/splitter/panel/splitter.panel.tsx:7-11](file://frontend/antd/splitter/panel/splitter.panel.tsx#L7-L11) +- [frontend/antd/splitter/context.ts:3-4](file://frontend/antd/splitter/context.ts#L3-L4) + +### Items 上下文与项收集机制 + +- 作用：在组件树中建立“项收集”通道，使 Panel 能够将自身属性与 DOM 内容写入 Splitter。 +- 关键点： + - withItemsContextProvider：为组件树提供 ItemsContextProvider，维护 items 映射与 setItem 方法。 + - useItems：在 Splitter 中读取 items 列表。 + - ItemHandler：在 Panel 渲染时写入项，支持 itemProps、itemChildren 等扩展能力。 + +```mermaid +sequenceDiagram +participant P as "Panel" +participant IH as "ItemHandler" +participant CTX as "ItemsContext" +participant SP as "Splitter" +P->>IH : 调用 ItemHandler +IH->>CTX : setItem(slotKey, index, item) +CTX-->>SP : 触发 onChange 回调 +SP->>SP : 更新内部 items 并重新渲染 +``` + +图表来源 + +- [frontend/utils/createItemsContext.tsx:108-170](file://frontend/utils/createItemsContext.tsx#L108-L170) +- [frontend/utils/createItemsContext.tsx:186-261](file://frontend/utils/createItemsContext.tsx#L186-L261) +- [frontend/antd/splitter/splitter.tsx:8-11](file://frontend/antd/splitter/splitter.tsx#L8-L11) + +章节来源 + +- [frontend/utils/createItemsContext.tsx:97-184](file://frontend/utils/createItemsContext.tsx#L97-L184) +- [frontend/utils/createItemsContext.tsx:186-261](file://frontend/utils/createItemsContext.tsx#L186-L261) +- [frontend/antd/splitter/context.ts:3-4](file://frontend/antd/splitter/context.ts#L3-L4) + +### 后端封装与属性传递 + +- AntdSplitterPanel 提供以下关键属性（来自 Python 封装）： + - default_size：默认尺寸 + - min / max：最小/最大尺寸 + - size：当前尺寸 + - collapsible：是否可折叠 + - resizable：是否可调整 + - elem_id / elem_classes / elem_style：样式与标识 +- 这些属性会通过 Svelte 桥接层透传至前端组件，最终影响 Ant Design Splitter 的行为与外观。 + +章节来源 + +- [backend/modelscope_studio/components/antd/splitter/panel/**init**.py:8-68](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L8-L68) + +## 依赖关系分析 + +- 组件耦合： + - Splitter 依赖 Items 上下文来获取面板集合。 + - Panel 通过 ItemHandler 依赖 Items 上下文写入自身项。 + - 前端桥接层（Index.svelte）负责将属性与插槽透传给 React 组件。 +- 外部依赖： + - Ant Design 的 Splitter/Panel 接口。 + - Svelte Preprocess React 工具链（sveltify、ReactSlot、processProps 等）。 +- 潜在循环依赖： + - 通过上下文与回调解耦，避免直接互相引用导致的循环。 + +```mermaid +graph LR +IDX["Index.svelte"] --> SPLIT["splitter.tsx"] +IDX --> PANEL_IDX["panel/Index.svelte"] +PANEL_IDX --> PANEL_IMPL["panel/splitter.panel.tsx"] +SPLIT --> CTX["context.ts"] +PANEL_IMPL --> CTX +CTX --> UTILS["createItemsContext.tsx"] +``` + +图表来源 + +- [frontend/antd/splitter/Index.svelte:10-52](file://frontend/antd/splitter/Index.svelte#L10-L52) +- [frontend/antd/splitter/splitter.tsx:5-6](file://frontend/antd/splitter/splitter.tsx#L5-L6) +- [frontend/antd/splitter/panel/Index.svelte:10-11](file://frontend/antd/splitter/panel/Index.svelte#L10-L11) +- [frontend/antd/splitter/panel/splitter.panel.tsx:5-5](file://frontend/antd/splitter/panel/splitter.panel.tsx#L5-L5) +- [frontend/antd/splitter/context.ts:3-4](file://frontend/antd/splitter/context.ts#L3-L4) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +章节来源 + +- [frontend/antd/splitter/Index.svelte:1-71](file://frontend/antd/splitter/Index.svelte#L1-L71) +- [frontend/antd/splitter/splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [frontend/antd/splitter/panel/Index.svelte:1-77](file://frontend/antd/splitter/panel/Index.svelte#L1-L77) +- [frontend/antd/splitter/panel/splitter.panel.tsx:1-14](file://frontend/antd/splitter/panel/splitter.panel.tsx#L1-L14) +- [frontend/antd/splitter/context.ts:1-7](file://frontend/antd/splitter/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +## 性能考量 + +- 渲染策略 + - Splitter 仅在存在面板时渲染容器，避免空渲染带来的开销。 + - 通过 useMemoizedEqualValue 与 useMemoizedFn 降低上下文更新频率与重复渲染。 +- 事件与状态 + - setItem 与 onChange 仅在值变化时触发，减少不必要的重渲染。 +- 建议 + - 对于大量面板或频繁调整尺寸的场景，建议限制面板数量与更新频率。 + - 合理设置最小/最大尺寸，避免极端尺寸导致的重排抖动。 + +章节来源 + +- [frontend/antd/splitter/splitter.tsx:15-31](file://frontend/antd/splitter/splitter.tsx#L15-L31) +- [frontend/utils/createItemsContext.tsx:113-153](file://frontend/utils/createItemsContext.tsx#L113-L153) +- [frontend/utils/createItemsContext.tsx:234-254](file://frontend/utils/createItemsContext.tsx#L234-L254) + +## 故障排查指南 + +- 面板未显示 + - 检查 Panel 的 visible 是否为真；确认桥接层已正确透传 visible。 + - 确认 Panel 是否成功写入 Items 上下文（检查 setItem 调用与索引）。 +- 拖拽无效 + - 确认 resizable 与可调整方向设置正确；检查 Ant Design 版本与样式是否完整。 +- 尺寸异常 + - 检查 min/max 与 default_size 的设置是否合理；避免设置为 0 或负数。 +- 插槽内容不渲染 + - 确认 Panel 的插槽绑定与 ReactSlot 的使用一致；避免插槽被提前销毁。 + +章节来源 + +- [frontend/antd/splitter/panel/Index.svelte:52-69](file://frontend/antd/splitter/panel/Index.svelte#L52-L69) +- [frontend/antd/splitter/splitter.tsx:14-31](file://frontend/antd/splitter/splitter.tsx#L14-L31) +- [backend/modelscope_studio/components/antd/splitter/panel/**init**.py:62-66](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L62-L66) + +## 结论 + +Splitter 通过 Items 上下文与 Svelte/React 桥接，实现了灵活的面板组织与渲染。其核心优势在于： + +- 面向用户的声明式 API（Panel 子组件） +- 与 Ant Design 的深度集成（拖拽、方向、尺寸控制） +- 可扩展的项收集机制（支持动态增删改） + +在实际应用中，建议结合业务场景合理设置尺寸约束与交互行为，并关注性能与可维护性。 + +## 附录 + +### 配置与属性参考 + +- Splitter 容器 + - 方向：由 Ant Design 的方向属性控制（水平/垂直） + - 拖拽：由 Ant Design 的拖拽能力提供 + - 事件：resizeStart/resizEnd（通过桥接层映射） +- Panel 子组件 + - default_size / size：默认/当前尺寸 + - min / max：最小/最大尺寸 + - collapsible / resizable：可折叠/可调整 + - elem_id / elem_classes / elem_style：样式与标识 + - visible：是否可见 + +章节来源 + +- [frontend/antd/splitter/Index.svelte:25-52](file://frontend/antd/splitter/Index.svelte#L25-L52) +- [frontend/antd/splitter/splitter.tsx:16-30](file://frontend/antd/splitter/splitter.tsx#L16-L30) +- [backend/modelscope_studio/components/antd/splitter/panel/**init**.py:61-66](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L61-L66) + +### 应用场景示例 + +- 代码编辑器：左侧文件树/大纲，右侧代码编辑区，支持左右拖拽调整宽度。 +- 图片对比：左右或上下排列两张图片，支持拖拽调整比例。 +- 多视图展示：三栏布局（左/中/右），中间为主视图，两侧为工具/预览。 + +章节来源 + +- [docs/components/antd/splitter/README.md:1-8](file://docs/components/antd/splitter/README.md#L1-L8) + +### 响应式与交互体验 + +- 响应式行为：根据容器宽度/高度自适应面板比例；建议在小屏设备上启用可折叠能力。 +- 交互体验：拖拽过程提供视觉反馈；建议设置合理的最小尺寸，避免误触过小。 + +章节来源 + +- [backend/modelscope_studio/components/antd/splitter/panel/**init**.py:14-16](file://backend/modelscope_studio/components/antd/splitter/panel/__init__.py#L14-L16) + +### 样式定制与无障碍 + +- 样式定制：通过 elem_classes 与 elem_style 注入自定义样式；注意与 Ant Design 默认样式的兼容性。 +- 动画效果：可结合 CSS 过渡或第三方动画库实现平滑尺寸切换。 +- 无障碍：为拖拽手柄提供可访问标签与键盘操作提示；确保可折叠状态具备明确的 ARIA 属性。 + +章节来源 + +- [frontend/antd/splitter/panel/Index.svelte:54-55](file://frontend/antd/splitter/panel/Index.svelte#L54-L55) +- [frontend/antd/splitter/splitter.tsx:16-30](file://frontend/antd/splitter/splitter.tsx#L16-L30) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/\345\270\203\345\261\200\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/\345\270\203\345\261\200\347\273\204\344\273\266.md" new file mode 100644 index 00000000..e04d6678 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\345\270\203\345\261\200\347\273\204\344\273\266/\345\270\203\345\261\200\347\273\204\344\273\266.md" @@ -0,0 +1,385 @@ +# 布局组件 + + +**本文引用的文件** +- [divider.tsx](file://frontend/antd/divider/divider.tsx) +- [flex.tsx](file://frontend/antd/flex/flex.tsx) +- [layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) +- [space.tsx](file://frontend/antd/space/space.tsx) +- [splitter.tsx](file://frontend/antd/splitter/splitter.tsx) +- [context.ts](file://frontend/antd/grid/context.ts) +- [col.tsx](file://frontend/antd/grid/col/col.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能与响应式特性](#性能与响应式特性) +8. [移动端与屏幕适配](#移动端与屏幕适配) +9. [故障排查](#故障排查) +10. [结论](#结论) +11. [附录：复杂页面布局示例与最佳实践](#附录复杂页面布局示例与最佳实践) + +## 简介 + +本章节面向使用 Ant Design 布局组件的开发者，系统梳理分割线、弹性布局、栅格、布局容器、间距、分割面板、瀑布流布局等组件在本仓库中的实现方式与使用要点。文档重点说明各组件的布局算法思想、响应式行为、嵌套规则与组合模式，并给出移动端适配与屏幕尺寸兼容性建议。 + +## 项目结构 + +这些布局组件位于前端目录下的 antd 子模块中，采用“Svelte 包裹 React 组件”的统一封装策略（通过 sveltify 将 Ant Design 的 React 组件桥接为 Svelte 可用的组件），并在部分场景下引入上下文与工具函数以支持更复杂的布局能力（如栅格列收集、分割面板子项渲染）。 + +```mermaid +graph TB +subgraph "Antd 布局组件" +D["Divider
分割线"] +F["Flex
弹性布局"] +L["Layout.Base
布局容器基类"] +S["Space
间距"] +SP["Splitter
分割面板"] +G["Grid.Context
栅格上下文"] +GC["Grid.Col
栅格列"] +end +D --> |"使用 Ant Design"| D +F --> |"使用 Ant Design"| F +L --> |"使用 Ant Design"| L +S --> |"使用 Ant Design"| S +SP --> |"使用 Ant Design"| SP +GC --> |"消费上下文"| G +``` + +图示来源 + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +章节来源 + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +## 核心组件 + +- 分割线 Divider：对 Ant Design 的 Divider 进行轻量封装，支持无子节点时的空标签渲染与有子节点时的透传渲染。 +- 弹性布局 Flex：对 Ant Design 的 Flex 进行简单封装，直接透传属性与子节点。 +- 布局容器 Layout.Base：根据传入的 component 类型动态选择 Header、Footer、Content 或 Layout，并注入样式类名以便区分。 +- 间距 Space：基于 Ant Design 的 Space，扩展了插槽渲染与 split 插槽支持，内部使用 useTargets 将子节点映射到目标集合。 +- 分割面板 Splitter：基于 Ant Design 的 Splitter，结合上下文收集默认面板列表，将每个面板的元素与属性透传给 Panel。 +- 栅格 Grid：通过上下文收集列（Col）并将其注入 Row/Col 渲染逻辑；Col 组件通过 ItemHandler 将自身注册到上下文中。 +- 瀑布流布局 Masonry：基于 Ant Design 的 Masonry 组件，支持响应式列数配置与项目高度自动调整，适合图片墙、卡片流等不等高布局场景。可参考 [Masonry 瀑布流布局](file://.qoder/repowiki/zh/content/Ant%20Design%20%E7%BB%84%E4%BB%B6%E5%BA%93/%E5%B8%83%E5%B1%80%E7%BB%84%E4%BB%B6/Masonry%20%E7%80%91%E5%B8%83%E6%B5%81%E5%B8%83%E5%B1%80.md) 详细了解。 + +章节来源 + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +## 架构总览 + +下图展示了布局组件之间的依赖与协作关系：Space 与 Splitter 在渲染前会先解析子节点并建立目标映射；Layout.Base 动态选择具体布局子组件；Grid 通过上下文机制收集 Col 并参与栅格布局。 + +```mermaid +graph LR +A["Space"] --> B["ReactSlot 渲染"] +C["Splitter"] --> D["Panel 列表渲染"] +E["Layout.Base"] --> F["Header/Footer/Content/Layout"] +G["Grid.Col"] --> H["Grid.Context 收集"] +H --> I["Row/Col 渲染"] +``` + +图示来源 + +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +## 组件详解 + +### 分割线 Divider + +- 实现要点 + - 使用 sveltify 包装 Ant Design 的 Divider。 + - 当存在子节点时，渲染带子节点的分割线；否则渲染空分割线。 +- 嵌套规则 + - 作为分隔符使用，可放置于任意容器内；不改变父容器的布局模式。 +- 响应式行为 + - 由 Ant Design 决定，默认不涉及断点控制。 +- 典型用法 + - 在列表、表单或卡片之间插入分割线，提升视觉层次。 + +章节来源 + +- [divider.tsx:1-15](file://frontend/antd/divider/divider.tsx#L1-L15) + +### 弹性布局 Flex + +- 实现要点 + - 使用 sveltify 包装 Ant Design 的 Flex，直接透传属性与子节点。 +- 布局算法 + - 遵循 Flexbox 规范，支持主轴、交叉轴、换行、对齐等常见属性。 +- 嵌套规则 + - Flex 内部可继续嵌套 Flex、Grid、Space 等布局组件，形成复合布局。 +- 响应式行为 + - Flex 属性可随断点变化，配合 Ant Design 的断点配置实现自适应。 +- 典型用法 + - 头部导航、卡片组、按钮组等需要灵活对齐与分布的场景。 + +章节来源 + +- [flex.tsx:1-11](file://frontend/antd/flex/flex.tsx#L1-L11) + +### 布局容器 Layout.Base + +- 实现要点 + - 根据 component 参数动态选择渲染 Header、Footer、Content 或 Layout。 + - 为非 layout 的子组件注入样式类名，便于样式区分与调试。 +- 布局算法 + - 通过 Ant Design 的 Layout 家族组件实现页面框架布局。 +- 嵌套规则 + - Header/Footer/Content 必须作为 Layout 的直接子节点；可嵌套侧边栏（Sider）等子组件。 +- 响应式行为 + - 结合 Sider 的折叠/展开与断点策略，实现响应式侧边栏。 +- 典型用法 + - 页面整体框架：顶部导航 + 侧边菜单 + 主体内容 + 底部信息。 + +```mermaid +flowchart TD +Start(["进入 Layout.Base"]) --> CheckComp{"component 类型"} +CheckComp --> |header| RenderHeader["渲染 Header"] +CheckComp --> |footer| RenderFooter["渲染 Footer"] +CheckComp --> |content| RenderContent["渲染 Content"] +CheckComp --> |layout| RenderLayout["渲染 Layout"] +RenderHeader --> End(["完成"]) +RenderFooter --> End +RenderContent --> End +RenderLayout --> End +``` + +图示来源 + +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +章节来源 + +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +### 间距 Space + +- 实现要点 + - 使用 Ant Design 的 Space，并扩展了插槽渲染与 split 插槽支持。 + - 内部通过 useTargets 将子节点映射为目标集合，再通过 ReactSlot 渲染。 +- 布局算法 + - 按方向与大小计算元素间的间距，支持包裹、压缩等组合模式。 +- 嵌套规则 + - 可嵌套任意组件；split 插槽用于渲染分隔符。 +- 响应式行为 + - 间距值可随断点变化，实现不同屏幕下的间距优化。 +- 典型用法 + - 导航按钮组、操作按钮组、表单项之间的紧凑排列。 + +```mermaid +sequenceDiagram +participant U as "调用者" +participant S as "Space" +participant T as "useTargets" +participant R as "ReactSlot" +U->>S : 传入 children 与 slots +S->>T : 解析子节点为 targets +S->>R : 渲染 targets +S->>R : 渲染 split 插槽如有 +R-->>U : 输出带间距的布局 +``` + +图示来源 + +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) + +章节来源 + +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) + +### 分割面板 Splitter + +- 实现要点 + - 使用 Ant Design 的 Splitter，并通过上下文收集默认面板列表。 + - 将每个面板的元素与属性透传给 Panel，实现灵活的多面板布局。 +- 布局算法 + - 基于拖拽或固定比例的分割布局，支持水平与垂直方向。 +- 嵌套规则 + - 子面板通过上下文注册，每个面板独立渲染其内容。 +- 响应式行为 + - 可结合断点调整初始比例与最小尺寸，保证移动端可用性。 +- 典型用法 + - 代码编辑器 + 预览区、左右内容对比、多视图并排展示。 + +```mermaid +sequenceDiagram +participant U as "调用者" +participant P as "Splitter" +participant Ctx as "Items 上下文" +participant Panel as "Panel" +U->>P : 提供面板插槽 +P->>Ctx : 获取默认面板列表 +loop 遍历面板 +P->>Panel : 透传属性并渲染 +Panel-->>P : 返回面板内容 +end +P-->>U : 输出分割面板布局 +``` + +图示来源 + +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) + +章节来源 + +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) + +### 栅格 Grid（Col 与上下文） + +- 实现要点 + - Col 通过 ItemHandler 将自身注册到名为 antd-grid-cols 的上下文中。 + - 上下文提供 withItemsContextProvider 与 useItems，用于收集与消费列定义。 +- 布局算法 + - 基于 24 栅格系统，Col 的 span/offset/order/gutter 等属性决定列宽与顺序。 +- 嵌套规则 + - Col 必须置于 Row/Col 的上下文中；可通过断点配置实现响应式。 +- 响应式行为 + - 支持 xs/sm/md/lg/xl 等断点，按断点设置不同的 span/offset。 +- 典型用法 + - 表单网格、卡片网格、图片墙等。 + +```mermaid +flowchart TD +A["Col 组件"] --> B["注册到上下文
key: antd-grid-cols"] +B --> C["Row/Col 渲染时读取上下文"] +C --> D["根据 span/offset/order 计算布局"] +D --> E["输出栅格列"] +``` + +图示来源 + +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +章节来源 + +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +## 依赖关系分析 + +- 组件间耦合 + - Space 与 Splitter 对 ReactSlot 与上下文有直接依赖，用于插槽与子项渲染。 + - Layout.Base 依赖 Ant Design 的 Layout 家族组件，动态选择子组件类型。 + - Grid 通过上下文实现 Col 的收集与消费，降低 Row/Col 的耦合度。 +- 外部依赖 + - 所有组件均依赖 Ant Design 的对应组件，布局算法与样式由 Ant Design 统一提供。 +- 潜在循环依赖 + - 未发现直接循环依赖；上下文仅用于数据传递，不反向依赖组件。 + +```mermaid +graph TB +Space["Space"] --> ReactSlot["ReactSlot"] +Splitter["Splitter"] --> ItemsCtx["Items 上下文"] +LayoutBase["Layout.Base"] --> ADLayout["Ant Design Layout"] +GridCol["Grid.Col"] --> GridCtx["Grid 上下文"] +``` + +图示来源 + +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +章节来源 + +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +## 性能与响应式特性 + +- 性能特性 + - 组件均采用轻量封装，避免额外状态管理开销；Space 的 useTargets 仅在初始化阶段进行一次映射。 + - Layout.Base 使用 useMemo 缓存组件类型，减少不必要的重渲染。 +- 响应式行为 + - Flex、Space、Grid、Splitter 的响应式主要由 Ant Design 的断点与属性驱动；可在断点配置中分别设置不同尺寸下的布局参数。 + - 建议在设计阶段明确断点阈值与列数，避免频繁重排。 + +## 移动端与屏幕适配 + +- 通用策略 + - 使用断点配置（如 xs/sm/md/lg/xl）针对小屏设备调整列宽、间距与布局方向。 + - 在 Space 中使用紧凑模式与合适的间距，避免移动端横向滚动。 + - 在 Splitter 中设置最小面板尺寸与初始比例，确保触控可用性。 +- 布局容器 + - 在小屏设备上优先使用纵向布局（Flex 方向列），必要时隐藏次要区域或使用抽屉式侧边栏。 +- 栅格系统 + - 合理设置 offset 与 order，使内容在小屏上保持可读性与可点击性。 + +## 故障排查 + +- 子节点未正确渲染 + - Space 会在内部隐藏 children 并通过 ReactSlot 渲染 targets，请确认是否正确使用插槽。 +- 分割面板为空 + - Splitter 依赖上下文提供的默认面板列表，若面板为空则不渲染；请检查插槽命名与上下文注册。 +- 栅格列未生效 + - 确认 Col 已在 Row/Col 的上下文中注册；检查断点配置与 span/offset 是否合理。 +- 布局容器类型错误 + - Layout.Base 仅支持 header/footer/content/layout 四种类型；传入其他值将回退为 Layout。 + +章节来源 + +- [space.tsx:1-29](file://frontend/antd/space/space.tsx#L1-L29) +- [splitter.tsx:1-38](file://frontend/antd/splitter/splitter.tsx#L1-L38) +- [layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) +- [context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +## 结论 + +本仓库的布局组件以“轻封装 + 上下文”为核心设计思路，既复用了 Ant Design 的成熟布局算法与样式体系，又在插槽渲染、动态组件选择与上下文收集方面提供了扩展能力。通过断点配置与合理的嵌套规则，可构建出兼顾桌面端与移动端的高质量页面布局。 + +## 附录：复杂页面布局示例与最佳实践 + +- 示例一：仪表盘页 + - 使用 Layout.Base 构建头部 + 侧边 + 主体；主体内使用 Flex 与 Space 组织卡片与操作区；底部使用 Divider 分隔。 + - 断点策略：小屏时将操作区折叠至卡片内或使用抽屉。 +- 示例二：内容编辑页 + - 使用 Splitter 将左侧目录树与右侧编辑器分割；编辑器内使用 Grid 实现表单栅格；底部使用 Space 放置操作按钮。 + - 断点策略：小屏时将目录树隐藏，编辑器全宽显示。 +- 示例三：对比展示页 + - 使用 Splitter 将左右两块内容并排；每块内容内部使用 Flex 与 Space 实现标题、描述与操作的对齐。 + - 断点策略：小屏时切换为纵向堆叠，保证阅读体验。 + +最佳实践 + +- 优先使用 Flex 与 Space 组织简单布局，复杂场景再引入 Splitter。 +- 在栅格系统中统一断点配置，避免同一页面出现多套断点策略。 +- 为布局容器注入语义化类名，便于样式覆盖与调试。 +- 移动端优先考虑触摸交互与可点击区域大小，适当增大间距与字号。 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\345\210\206\346\256\265\346\216\247\345\210\266\345\231\250\344\270\216\347\273\237\350\256\241\346\225\260\345\200\274\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\345\210\206\346\256\265\346\216\247\345\210\266\345\231\250\344\270\216\347\273\237\350\256\241\346\225\260\345\200\274\347\273\204\344\273\266.md" new file mode 100644 index 00000000..f8229279 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\345\210\206\346\256\265\346\216\247\345\210\266\345\231\250\344\270\216\347\273\237\350\256\241\346\225\260\345\200\274\347\273\204\344\273\266.md" @@ -0,0 +1,312 @@ +# 分段控制器与统计数值组件 + + +**本文引用的文件** +- [frontend/antd/segmented/segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js](file://backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js) +- [backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js](file://backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js) +- [frontend/antd/statistic/statistic.tsx](file://frontend/antd/statistic/statistic.tsx) +- [backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js](file://backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx](file://frontend/antd/statistic/countdown/statistic.countdown.tsx) +- [frontend/antd/statistic/timer/statistic.timer.tsx](file://frontend/antd/statistic/timer/statistic.timer.tsx) +- [docs/components/antd/segmented/README-zh_CN.md](file://docs/components/antd/segmented/README-zh_CN.md) +- [docs/components/antd/statistic/README-zh_CN.md](file://docs/components/antd/statistic/README-zh_CN.md) + + +## 目录 + +1. [引言](#引言) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 引言 + +本文件聚焦于两个前端组件：分段控制器（Segmented）与统计数值（Statistic）。前者用于在多个互斥选项中进行选择，后者用于展示数值、标题、前后缀以及支持倒计时与定时器功能。本文将从架构、数据流、处理逻辑、集成点、错误处理与性能特性等维度，系统性地阐述这两个组件的设计与使用方式，并提供可视化图示帮助理解。 + +## 项目结构 + +- 组件由前端适配层（React 包装 + Svelte 预处理）与后端模板渲染层（Svelte 运行时桥接）共同构成。 +- 分段控制器通过上下文注入选项集合，支持“选项组”（option）组合使用；统计数值组件支持插槽（slots）与函数式 formatter 的灵活扩展。 +- 文档侧提供了基础示例入口，便于快速上手。 + +```mermaid +graph TB +subgraph "前端适配层" +S_Tsx["segmented.tsx
React 包装 + 渲染选项"] +ST_Tsx["statistic.tsx
React 包装 + 插槽/formatter"] +CD_Tsx["countdown.tsx
React 包装 + 倒计时"] +TM_Tsx["timer.tsx
React 包装 + 定时器"] +end +subgraph "后端模板渲染层" +S_JS["segmented-Ds7q4Ezu.js
Svelte 运行时桥接"] +SO_JS["segmented.option-CS0TqVwO.js
选项项实现"] +ST_JS["statistic-DvxTRiyV.js
Svelte 运行时桥接"] +end +subgraph "外部依赖" +Antd["Ant Design 组件库"] +end +S_Tsx --> S_JS +ST_Tsx --> ST_JS +CD_Tsx --> Antd +TM_Tsx --> Antd +SO_JS --> S_JS +``` + +**图表来源** + +- [frontend/antd/segmented/segmented.tsx:1-47](file://frontend/antd/segmented/segmented.tsx#L1-L47) +- [backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js:695-719](file://backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js#L695-L719) +- [backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js:441-447](file://backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js#L441-L447) +- [frontend/antd/statistic/statistic.tsx:1-34](file://frontend/antd/statistic/statistic.tsx#L1-L34) +- [backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js:685-715](file://backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js#L685-L715) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:1-27](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L1-L27) +- [frontend/antd/statistic/timer/statistic.timer.tsx:1-29](file://frontend/antd/statistic/timer/statistic.timer.tsx#L1-L29) + +**章节来源** + +- [docs/components/antd/segmented/README-zh_CN.md:1-8](file://docs/components/antd/segmented/README-zh_CN.md#L1-L8) +- [docs/components/antd/statistic/README-zh_CN.md:1-9](file://docs/components/antd/statistic/README-zh_CN.md#L1-L9) + +## 核心组件 + +- 分段控制器（Segmented） + - 支持通过属性传入选项数组或通过“选项组”（option）插槽注入选项集合。 + - 提供值变更回调 onValueChange 与原生 onChange 的组合事件。 + - 支持禁用状态、块级显示（通过隐藏 children 实现）。 +- 统计数值（Statistic） + - 支持 title、prefix、suffix、formatter 等插槽与属性的组合使用。 + - 支持自定义格式化函数与 ReactSlot 插槽渲染。 +- 统计数值子组件 + - 倒计时（Countdown）：接收时间戳或毫秒值，自动转换为毫秒。 + - 定时器（Timer）：基于当前时间的定时器展示。 + +**章节来源** + +- [frontend/antd/segmented/segmented.tsx:10-44](file://frontend/antd/segmented/segmented.tsx#L10-L44) +- [frontend/antd/statistic/statistic.tsx:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:6-24](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L6-L24) +- [frontend/antd/statistic/timer/statistic.timer.tsx:10-26](file://frontend/antd/statistic/timer/statistic.timer.tsx#L10-L26) + +## 架构总览 + +下图展示了从 Svelte 模板到 React 包装再到 Ant Design 组件的完整调用链路，以及插槽与上下文如何参与渲染。 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 模板" +participant Bridge as "Svelte 运行时桥接" +participant ReactWrap as "React 包装层" +participant Antd as "Ant Design 组件" +Svelte->>Bridge : "生成节点/插槽映射" +Bridge->>ReactWrap : "创建 React 元素并注入上下文/插槽" +ReactWrap->>Antd : "传递属性/插槽/事件回调" +Antd-->>ReactWrap : "渲染结果" +ReactWrap-->>Bridge : "桥接 DOM/Portal" +Bridge-->>Svelte : "完成挂载/更新" +``` + +**图表来源** + +- [backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js:695-719](file://backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js#L695-L719) +- [backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js:685-715](file://backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js#L685-L715) +- [backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js:441-447](file://backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js#L441-L447) + +## 详细组件分析 + +### 分段控制器（Segmented）分析 + +- 选项配置与“选项组”组合 + - 通过上下文注入“options/default”两组插槽，优先使用 options，否则回退到 default。 + - 使用 useMemo 缓存选项列表，避免不必要的重渲染。 +- 受控与非受控模式 + - 外部可直接传入 value/onChange 实现受控；同时提供 onValueChange 作为内部值变更回调。 +- 禁用状态与块级显示 + - 通过隐藏 children 的方式保持结构一致性，不影响外层布局。 +- 动态更新与样式定制 + - 选项项（option）通过桥接运行时实现插槽与上下文的动态注入，支持样式与事件透传。 + +```mermaid +flowchart TD +Start(["进入 Segmented 渲染"]) --> CheckSlots["检查插槽: options vs default"] +CheckSlots --> HasOptions{"是否有 options?"} +HasOptions --> |是| UseOptions["使用 options 选项集"] +HasOptions --> |否| UseDefault["使用 default 选项集"] +UseOptions --> Resolve["渲染为 Antd 选项数组"] +UseDefault --> Resolve +Resolve --> Wrap["包装为 Antd Segmented 并绑定 onChange/onValueChange"] +Wrap --> End(["完成渲染"]) +``` + +**图表来源** + +- [frontend/antd/segmented/segmented.tsx:15-44](file://frontend/antd/segmented/segmented.tsx#L15-L44) +- [backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js:695-719](file://backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js#L695-L719) + +**章节来源** + +- [frontend/antd/segmented/segmented.tsx:10-44](file://frontend/antd/segmented/segmented.tsx#L10-L44) +- [backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js:695-719](file://backend/modelscope_studio/components/antd/segmented/templates/component/segmented-Ds7q4Ezu.js#L695-L719) +- [backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js:441-447](file://backend/modelscope_studio/components/antd/segmented/option/templates/component/segmented.option-CS0TqVwO.js#L441-L447) + +### 统计数值（Statistic）分析 + +- 数值显示、单位设置与格式化 + - 支持 title/prefix/suffix 的插槽与属性双通道；formatter 支持函数与插槽两种形式。 +- 倒计时（Countdown）与定时器（Timer） + - 倒计时与定时器均对 value 做毫秒转换，确保与 Antd 组件期望一致。 +- 插槽与函数式 formatter 的组合 + - 当存在 slots.formatter 时优先使用插槽渲染，否则回退到函数式 formatter。 + +```mermaid +sequenceDiagram +participant User as "用户代码" +participant Stat as "Statistic 包装层" +participant Slots as "插槽系统" +participant Antd as "Antd Statistic" +User->>Stat : "传入 value/title/prefix/suffix/formatter" +Stat->>Slots : "检测 slots.formatter/title/prefix/suffix" +alt 存在 slots.formatter +Slots-->>Stat : "返回插槽渲染函数" +else 不存在 slots.formatter +Stat-->>Stat : "使用 formatter 函数" +end +Stat->>Antd : "传递属性与渲染函数" +Antd-->>User : "渲染统计数值" +``` + +**图表来源** + +- [frontend/antd/statistic/statistic.tsx:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) +- [backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js:685-715](file://backend/modelscope_studio/components/antd/statistic/templates/component/statistic-DvxTRiyV.js#L685-L715) + +**章节来源** + +- [frontend/antd/statistic/statistic.tsx:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:6-24](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L6-L24) +- [frontend/antd/statistic/timer/statistic.timer.tsx:10-26](file://frontend/antd/statistic/timer/statistic.timer.tsx#L10-L26) + +### 组件类关系图（代码级） + +```mermaid +classDiagram +class SegmentedWrapper { ++props : GetProps
封装 Ant Design Image"] +PG_IDX["preview-group/Index.svelte
预览组入口"] +PG_IMPL["preview-group/image.preview-group.tsx
预览组实现"] +end +subgraph "列表组件" +LIST_TS["list.tsx
封装 Ant Design List"] +ITEM_IDX["item/Index.svelte
列表项入口"] +ITEM_IMPL["item/list.item.tsx
列表项实现"] +end +subgraph "工具与钩子" +USE_FN["useFunction.ts
函数包装"] +USE_TGT["useTargets.ts
目标节点提取"] +RENDER_SLOT["renderParamsSlot.tsx
参数化插槽渲染"] +end +IMG_TS --> PG_IMPL +PG_IDX --> PG_IMPL +LIST_TS --> ITEM_IMPL +ITEM_IDX --> ITEM_IMPL +IMG_TS --> USE_FN +PG_IMPL --> USE_FN +LIST_TS --> USE_FN +ITEM_IMPL --> USE_FN +LIST_TS --> RENDER_SLOT +ITEM_IMPL --> RENDER_SLOT +ITEM_IMPL --> USE_TGT +``` + +**图表来源** + +- [frontend/antd/image/image.tsx:1-89](file://frontend/antd/image/image.tsx#L1-L89) +- [frontend/antd/image/preview-group/Index.svelte:1-72](file://frontend/antd/image/preview-group/Index.svelte#L1-L72) +- [frontend/antd/image/preview-group/image.preview-group.tsx:1-55](file://frontend/antd/image/preview-group/image.preview-group.tsx#L1-L55) +- [frontend/antd/list/list.tsx:1-36](file://frontend/antd/list/list.tsx#L1-L36) +- [frontend/antd/list/item/Index.svelte:1-60](file://frontend/antd/list/item/Index.svelte#L1-L60) +- [frontend/antd/list/item/list.item.tsx:1-29](file://frontend/antd/list/item/list.item.tsx#L1-L29) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/hooks/useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +**章节来源** + +- [frontend/antd/image/image.tsx:1-89](file://frontend/antd/image/image.tsx#L1-L89) +- [frontend/antd/image/preview-group/Index.svelte:1-72](file://frontend/antd/image/preview-group/Index.svelte#L1-L72) +- [frontend/antd/image/preview-group/image.preview-group.tsx:1-55](file://frontend/antd/image/preview-group/image.preview-group.tsx#L1-L55) +- [frontend/antd/list/list.tsx:1-36](file://frontend/antd/list/list.tsx#L1-L36) +- [frontend/antd/list/item/Index.svelte:1-60](file://frontend/antd/list/item/Index.svelte#L1-L60) +- [frontend/antd/list/item/list.item.tsx:1-29](file://frontend/antd/list/item/list.item.tsx#L1-L29) + +## 核心组件 + +- 图片(Image)：通过 sveltify 包装 Ant Design 的 Image 组件，支持占位符、预览配置与插槽扩展。预览组提供批量查看能力，支持自定义遮罩、关闭图标与工具栏。 +- 列表(List)：通过 sveltify 包装 Ant Design 的 List 组件，支持页眉/页脚、加载更多与自定义渲染项。列表项支持额外区域与动作集合，并通过 useTargets 自动提取带特定 slotKey 的子节点。 + +**章节来源** + +- [frontend/antd/image/image.tsx:14-86](file://frontend/antd/image/image.tsx#L14-L86) +- [frontend/antd/image/preview-group/image.preview-group.tsx:13-52](file://frontend/antd/image/preview-group/image.preview-group.tsx#L13-L52) +- [frontend/antd/list/list.tsx:8-33](file://frontend/antd/list/list.tsx#L8-L33) +- [frontend/antd/list/item/list.item.tsx:6-26](file://frontend/antd/list/item/list.item.tsx#L6-L26) + +## 架构总览 + +下图展示图片与列表组件在前端层的调用链与插槽扩展点： + +```mermaid +sequenceDiagram +participant U as "用户" +participant IMG as "Image 组件
image.tsx" +participant PG as "预览组
image.preview-group.tsx" +participant LIST as "List 组件
list.tsx" +participant ITEM as "ListItem 组件
list.item.tsx" +U->>IMG : "点击图片" +IMG->>PG : "触发预览组" +PG-->>U : "批量查看/工具栏/遮罩" +U->>LIST : "渲染列表" +LIST->>ITEM : "逐项渲染" +ITEM-->>U : "额外区域/动作集合" +``` + +**图表来源** + +- [frontend/antd/image/image.tsx:24-85](file://frontend/antd/image/image.tsx#L24-L85) +- [frontend/antd/image/preview-group/image.preview-group.tsx:18-51](file://frontend/antd/image/preview-group/image.preview-group.tsx#L18-L51) +- [frontend/antd/list/list.tsx:11-32](file://frontend/antd/list/list.tsx#L11-L32) +- [frontend/antd/list/item/list.item.tsx:9-25](file://frontend/antd/list/item/list.item.tsx#L9-L25) + +## 详细组件分析 + +### 图片组件（Image） + +- 批量查看（预览组） + - 预览组通过延迟导入与条件渲染实现按需加载，避免首屏负担。 + - 支持自定义遮罩、关闭图标与工具栏，工具栏与图像渲染可通过插槽传入或函数回调形式注入。 + - 预览容器的挂载位置可通过 getContainer 函数定制，便于嵌入到指定 DOM 容器。 +- 懒加载与错误处理 + - 当前实现未显式声明懒加载与错误处理逻辑；若需要，可在上层业务中结合浏览器原生属性或第三方库进行增强。 +- 图片裁剪 + - 该实现未暴露裁剪相关参数；如需裁剪，可在上层业务中对资源进行预处理或引入专门的裁剪库。 +- 缩放控制、旋转功能与下载支持 + - 当前实现未内置缩放、旋转与下载按钮；可通过自定义工具栏插槽添加相应控件，并结合外部库实现交互。 +- 插槽与函数包装 + - 使用 useFunction 对传入的函数进行稳定化处理，renderParamsSlot 支持将参数传递给插槽渲染函数，提升灵活性。 + +```mermaid +flowchart TD +Start(["进入 Image 渲染"]) --> CheckPreview["检测是否启用预览"] +CheckPreview --> |是| BuildPreview["构建预览配置
合并插槽与函数"] +CheckPreview --> |否| SkipPreview["禁用预览"] +BuildPreview --> SlotsCheck{"是否存在自定义插槽？"} +SlotsCheck --> |是| RenderSlots["渲染自定义插槽"] +SlotsCheck --> |否| UseDefault["使用默认预览行为"] +RenderSlots --> End(["完成"]) +UseDefault --> End +SkipPreview --> End +``` + +**图表来源** + +- [frontend/antd/image/image.tsx:24-85](file://frontend/antd/image/image.tsx#L24-L85) +- [frontend/antd/image/preview-group/image.preview-group.tsx:18-51](file://frontend/antd/image/preview-group/image.preview-group.tsx#L18-L51) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/renderParamsSlot.tsx:5-50](file://frontend/utils/renderParamsSlot.tsx#L5-L50) + +**章节来源** + +- [frontend/antd/image/image.tsx:14-86](file://frontend/antd/image/image.tsx#L14-L86) +- [frontend/antd/image/preview-group/image.preview-group.tsx:13-52](file://frontend/antd/image/preview-group/image.preview-group.tsx#L13-L52) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +### 列表组件（List） + +- 基础列表结构与动态数据绑定 + - 通过 sveltify 包装 Ant Design List，支持页眉/页脚、加载更多与自定义渲染项。 + - 渲染项可通过插槽传入，或以函数形式注入，实现灵活的数据绑定与视图渲染。 +- 列表项（Item）与元数据（meta） + - 列表项支持“额外区域”与“动作集合”，动作集合通过 useTargets 自动从子节点中提取带特定 slotKey 的元素，保证顺序与索引可控。 +- 垂直列表布局 + - 默认沿用 Ant Design 的垂直布局策略，适用于大多数场景；如需横向或网格布局，可在上层业务中结合样式或布局组件实现。 + +```mermaid +classDiagram +class List_tsx { ++slots : footer/header/loadMore/renderItem ++render() : ReactNode +} +class ListItem_tsx { ++slots : extra/actions ++useTargets(children, slotKey) ++render() : ReactNode +} +List_tsx --> ListItem_tsx : "逐项渲染" +``` + +**图表来源** + +- [frontend/antd/list/list.tsx:8-33](file://frontend/antd/list/list.tsx#L8-L33) +- [frontend/antd/list/item/list.item.tsx:6-26](file://frontend/antd/list/item/list.item.tsx#L6-L26) +- [frontend/utils/hooks/useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) + +**章节来源** + +- [frontend/antd/list/list.tsx:8-33](file://frontend/antd/list/list.tsx#L8-L33) +- [frontend/antd/list/item/list.item.tsx:6-26](file://frontend/antd/list/item/list.item.tsx#L6-L26) +- [frontend/utils/hooks/useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) + +### 预览组（Preview Group） + +- 批量查看与可见性控制 + - 预览组入口通过 Svelte 的延迟导入与可见性判断，仅在需要时渲染实际组件，减少初始开销。 + - 支持通过 props 控制预览可见性变化事件，便于与上层状态联动。 +- 插槽与容器挂载 + - 支持自定义遮罩与关闭图标；容器挂载位置通过 getContainer 函数定制，便于嵌入到指定容器。 + +```mermaid +sequenceDiagram +participant IDX as "预览组入口
Index.svelte" +participant CMP as "预览组实现
image.preview-group.tsx" +IDX->>IDX : "检查可见性" +IDX->>CMP : "按需导入并渲染" +CMP-->>IDX : "输出预览组" +``` + +**图表来源** + +- [frontend/antd/image/preview-group/Index.svelte:55-71](file://frontend/antd/image/preview-group/Index.svelte#L55-L71) +- [frontend/antd/image/preview-group/image.preview-group.tsx:18-51](file://frontend/antd/image/preview-group/image.preview-group.tsx#L18-L51) + +**章节来源** + +- [frontend/antd/image/preview-group/Index.svelte:14-71](file://frontend/antd/image/preview-group/Index.svelte#L14-L71) +- [frontend/antd/image/preview-group/image.preview-group.tsx:18-52](file://frontend/antd/image/preview-group/image.preview-group.tsx#L18-L52) + +## 依赖关系分析 + +- 组件与工具函数 + - 图片与列表组件均依赖 useFunction 进行函数稳定化，确保回调在 props 变更时不重复创建。 + - 列表项依赖 useTargets 提取带特定 slotKey 的子节点，实现动作集合的自动装配。 + - renderParamsSlot 提供参数化插槽渲染能力，支持向插槽传参并强制克隆，保证多次渲染的一致性。 +- 组件间耦合 + - 图片预览组与图片组件解耦：预览组作为独立组件存在，通过 props 与插槽与图片组件协作。 + - 列表项与列表组件解耦：列表项通过延迟导入与插槽机制实现独立渲染，降低耦合度。 + +```mermaid +graph LR +IMG["image.tsx"] --> UF["useFunction.ts"] +PG["image.preview-group.tsx"] --> UF +LIST["list.tsx"] --> UF +ITEM["list.item.tsx"] --> UF +ITEM --> UT["useTargets.ts"] +LIST --> RS["renderParamsSlot.tsx"] +ITEM --> RS +``` + +**图表来源** + +- [frontend/antd/image/image.tsx:3-4](file://frontend/antd/image/image.tsx#L3-L4) +- [frontend/antd/image/preview-group/image.preview-group.tsx:3-4](file://frontend/antd/image/preview-group/image.preview-group.tsx#L3-L4) +- [frontend/antd/list/list.tsx:4-5](file://frontend/antd/list/list.tsx#L4-L5) +- [frontend/antd/list/item/list.item.tsx:3-4](file://frontend/antd/list/item/list.item.tsx#L3-L4) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/hooks/useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +**章节来源** + +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/hooks/useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +## 性能考量 + +- 按需加载与延迟导入 + - 预览组与列表项均采用延迟导入策略，仅在可见时渲染，有助于减少首屏负载与内存占用。 +- 函数稳定化 + - 使用 useFunction 对回调进行 memo 化，避免因 props 变更导致的重复创建，降低重渲染成本。 +- 插槽渲染优化 + - renderParamsSlot 强制克隆与参数透传，确保插槽渲染的确定性与可复用性，减少不必要的重复计算。 + +**章节来源** + +- [frontend/antd/image/preview-group/Index.svelte:55-71](file://frontend/antd/image/preview-group/Index.svelte#L55-L71) +- [frontend/antd/list/item/Index.svelte:46-59](file://frontend/antd/list/item/Index.svelte#L46-L59) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/renderParamsSlot.tsx:23-49](file://frontend/utils/renderParamsSlot.tsx#L23-L49) + +## 故障排查指南 + +- 预览组不显示 + - 检查可见性 props 与入口组件的可见性判断逻辑，确认预览组已按需导入并渲染。 + - 若使用自定义遮罩或关闭图标，请确认插槽是否正确传入且未被覆盖。 +- 工具栏/图像渲染无效 + - 确认传入的函数是否通过 useFunction 包装，避免因函数引用变化导致的失效。 + - 若使用插槽，请确认 renderParamsSlot 的参数传递是否正确。 +- 列表项动作集合为空 + - 检查子节点是否带有正确的 slotKey 与索引信息，确保 useTargets 能够正确提取。 +- 性能问题 + - 若出现频繁重渲染，检查是否在父组件中频繁变更回调或插槽内容；建议使用 useFunction 或稳定化策略。 + +**章节来源** + +- [frontend/antd/image/preview-group/Index.svelte:55-71](file://frontend/antd/image/preview-group/Index.svelte#L55-L71) +- [frontend/antd/image/preview-group/image.preview-group.tsx:18-51](file://frontend/antd/image/preview-group/image.preview-group.tsx#L18-L51) +- [frontend/antd/list/item/list.item.tsx:10-21](file://frontend/antd/list/item/list.item.tsx#L10-L21) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/renderParamsSlot.tsx:23-49](file://frontend/utils/renderParamsSlot.tsx#L23-L49) + +## 结论 + +- 图片组件通过预览组实现了批量查看与灵活的插槽扩展，当前未内置懒加载、错误处理、裁剪、缩放、旋转与下载功能，但具备良好的扩展空间。 +- 列表组件提供了基础的结构与动态绑定能力，列表项的动作集合通过 useTargets 自动装配，适合在上层业务中结合样式与布局实现响应式与自适应显示。 +- 在性能方面，组件普遍采用延迟导入与函数稳定化策略，有助于在复杂场景下保持良好的运行效率。 + +## 附录 + +- 扩展建议 + - 图片：在上层业务中引入懒加载与错误处理策略；若需裁剪、缩放、旋转与下载，可结合外部库与自定义工具栏插槽实现。 + - 列表：在上层业务中引入虚拟滚动与无限加载；数据过滤可通过外部状态与渲染条件实现；响应式布局可通过样式与断点策略适配多端设备。 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\345\244\264\345\203\217\344\270\216\345\276\275\346\240\207\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\345\244\264\345\203\217\344\270\216\345\276\275\346\240\207\347\273\204\344\273\266.md" new file mode 100644 index 00000000..3f5e3380 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\345\244\264\345\203\217\344\270\216\345\276\275\346\240\207\347\273\204\344\273\266.md" @@ -0,0 +1,328 @@ +# 头像与徽标组件 + + +**本文引用的文件** +- [avatar.tsx](file://frontend/antd/avatar/avatar.tsx) +- [avatar 组合入口 Index.svelte](file://frontend/antd/avatar/group/Index.svelte) +- [avatar.group.tsx](file://frontend/antd/avatar/group/avatar.group.tsx) +- [avatar.group.less](file://frontend/antd/avatar/group/avatar.group.less) +- [badge.tsx](file://frontend/antd/badge/badge.tsx) +- [badge 组合入口 Index.svelte](file://frontend/antd/badge/ribbon/Index.svelte) +- [ribbon.badge.tsx](file://frontend/antd/badge/ribbon/badge.ribbon.tsx) +- [avatar 文档 README.md](file://docs/components/antd/avatar/README.md) +- [badge 文档 README.md](file://docs/components/antd/badge/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件聚焦于头像（Avatar）与徽标数（Badge）两大组件族，系统梳理其尺寸控制、形状设置、头像组（Avatar.Group）的堆叠与遮罩、徽标数的计数显示与红点标记、徽标组（Badge.Ribbon）的缎带效果等能力，并给出占位符处理、阈值设置、自定义样式方案以及响应式与多布局适配建议。文档以仓库中实际实现为依据，配合可视化图示帮助读者快速理解与正确使用。 + +## 项目结构 + +- 头像组件位于 frontend/antd/avatar 下，包含单个头像与头像组两个子模块；头像组通过组合入口 Svelte 文件动态导入内部实现。 +- 徽标组件位于 frontend/antd/badge 下，包含基础徽标与缎带徽标（Ribbon）两个子模块；缎带徽标同样通过组合入口 Svelte 文件动态导入内部实现。 +- 文档示例位于 docs/components/antd/avatar 与 docs/components/antd/badge，分别提供基础与组合用法的演示入口。 + +```mermaid +graph TB +subgraph "头像组件" +AV["avatar.tsx"] +AGI["avatar/group/Index.svelte"] +AGC["avatar/group/avatar.group.tsx"] +AGL["avatar/group/avatar.group.less"] +end +subgraph "徽标组件" +BD["badge.tsx"] +RBDI["badge/ribbon/Index.svelte"] +RBD["badge/ribbon/badge.ribbon.tsx"] +end +AV --> |"封装 Ant Design"| AV +AGI --> |"动态导入"| AGC +AGC --> |"渲染"| AV +AGC --> |"样式"| AGL +BD --> |"封装 Ant Design"| BD +RBDI --> |"动态导入"| RBD +RBD --> |"包裹内容"| RBD +``` + +**图表来源** + +- [avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [avatar 组合入口 Index.svelte:1-62](file://frontend/antd/avatar/group/Index.svelte#L1-L62) +- [avatar.group.tsx:1-52](file://frontend/antd/avatar/group/avatar.group.tsx#L1-L52) +- [avatar.group.less:1-12](file://frontend/antd/avatar/group/avatar.group.less#L1-L12) +- [badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) +- [badge 组合入口 Index.svelte:1-62](file://frontend/antd/badge/ribbon/Index.svelte#L1-L62) +- [ribbon.badge.tsx:1-22](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L1-L22) + +**章节来源** + +- [avatar 文档 README.md:1-9](file://docs/components/antd/avatar/README.md#L1-L9) +- [badge 文档 README.md:1-9](file://docs/components/antd/badge/README.md#L1-L9) + +## 核心组件 + +- 头像（Avatar） + - 支持图标、图片与字符展示，具备尺寸与形状配置能力；通过插槽机制支持 icon 与 src 的动态传入。 + - 提供占位符处理：当未提供图标或图片时，可由子节点作为后备内容。 +- 头像组（Avatar.Group） + - 实现头像堆叠与遮罩效果，支持最大数量阈值与弹出层提示；通过 less 变量控制重叠间距。 + - 支持对“超出数量”的弹出层标题与内容进行插槽化定制。 +- 徽标数（Badge） + - 支持数字计数与文本标记；count 与 text 均可通过插槽注入自定义内容。 + - 支持红点标记与阈值上限（超过阈值显示 n+）。 +- 缎带徽标（Badge.Ribbon） + - 在目标元素上叠加“缎带”式徽标，支持文本插槽；通常用于强调状态或标识。 + +**章节来源** + +- [avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [avatar.group.tsx:1-52](file://frontend/antd/avatar/group/avatar.group.tsx#L1-L52) +- [avatar.group.less:1-12](file://frontend/antd/avatar/group/avatar.group.less#L1-L12) +- [badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) +- [ribbon.badge.tsx:1-22](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L1-L22) + +## 架构总览 + +下图展示了从 Svelte 入口到具体 Ant Design 组件的调用链路，以及插槽与属性透传的关键路径。 + +```mermaid +sequenceDiagram +participant U as "用户代码" +participant S as "Svelte 组合入口(Index)" +participant C as "内部组件(tsx)" +participant A as "Ant Design 组件" +U->>S : 传入属性与插槽 +S->>C : 动态导入并传递属性/插槽 +C->>A : 透传属性/插槽 +A-->>U : 渲染结果 +``` + +**图表来源** + +- [avatar 组合入口 Index.svelte:48-61](file://frontend/antd/avatar/group/Index.svelte#L48-L61) +- [avatar.group.tsx:12-49](file://frontend/antd/avatar/group/avatar.group.tsx#L12-L49) +- [badge 组合入口 Index.svelte:48-61](file://frontend/antd/badge/ribbon/Index.svelte#L48-L61) +- [ribbon.badge.tsx:6-18](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L6-L18) + +## 详细组件分析 + +### 头像（Avatar） + +- 封装方式 + - 使用 sveltify 将 Ant Design 的 Avatar 包装为 Svelte 组件，同时保留 icon 与 src 的插槽能力。 + - 当存在插槽时优先使用插槽内容，否则回退到属性值；无插槽时子节点作为默认内容。 +- 占位符处理 + - 通过隐藏容器与条件渲染，确保在未提供图标或图片时仍能渲染子节点作为占位内容。 +- 形状与尺寸 + - 通过 Ant Design 原生属性控制形状（如圆形/方形）与尺寸（如小/中/大），具体参数遵循 Antd 规范。 + +```mermaid +flowchart TD +Start(["进入 Avatar 渲染"]) --> CheckIconSrc["检查是否存在 icon 或 src 插槽"] +CheckIconSrc --> HasSlot{"有插槽？"} +HasSlot --> |是| UseSlot["使用插槽内容作为图标/图片"] +HasSlot --> |否| UseProp["使用属性值作为图标/图片"] +UseSlot --> Render["渲染 Ant Design Avatar"] +UseProp --> Render +Render --> End(["完成"]) +``` + +**图表来源** + +- [avatar.tsx:6-25](file://frontend/antd/avatar/avatar.tsx#L6-L25) + +**章节来源** + +- [avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) + +### 头像组（Avatar.Group） + +- 堆叠与遮罩 + - 内部使用 Ant Design 的 Group 能力实现头像堆叠；通过 less 变量控制相邻头像的起始边距，形成视觉上的遮挡与层级。 +- 阈值与弹出层 + - 支持设置 max.count 作为阈值；当超出阈值时，会显示“还有 n 个”等提示。 + - 弹出层的标题与内容可通过插槽覆盖，若未提供插槽则回退到属性配置。 +- 子项渲染 + - 通过 useTargets 与 ReactSlot 将子项映射为 ReactSlot，保证每个子头像按序渲染。 + +```mermaid +flowchart TD +Enter(["进入 Avatar.Group"]) --> ComputeMax["计算 max 配置
含 count 与 popover"] +ComputeMax --> OverLimit{"是否超出阈值？"} +OverLimit --> |是| Popover["显示弹出层标题/内容可插槽"] +OverLimit --> |否| RenderList["逐个渲染子头像"] +Popover --> RenderList +RenderList --> Exit(["完成"]) +``` + +**图表来源** + +- [avatar.group.tsx:12-49](file://frontend/antd/avatar/group/avatar.group.tsx#L12-L49) +- [avatar.group.less:1-12](file://frontend/antd/avatar/group/avatar.group.less#L1-L12) + +**章节来源** + +- [avatar 组合入口 Index.svelte:1-62](file://frontend/antd/avatar/group/Index.svelte#L1-L62) +- [avatar.group.tsx:1-52](file://frontend/antd/avatar/group/avatar.group.tsx#L1-L52) +- [avatar.group.less:1-12](file://frontend/antd/avatar/group/avatar.group.less#L1-L12) + +### 徽标数（Badge） + +- 计数与文本 + - count 与 text 均支持插槽注入，便于在徽标内放置复杂内容（如图标、自定义文案）。 +- 红点标记 + - 通过 Ant Design 原生能力实现红点标记；当 count 为 0 且不显示数字时呈现纯红点。 +- 阈值设置 + - 支持设置最大值，超过阈值时显示 n+；该能力由底层 Antd 组件提供，组件层直接透传属性。 + +```mermaid +flowchart TD +Start(["进入 Badge 渲染"]) --> CheckCountText["检查 count 与 text 插槽"] +CheckCountText --> HasCount{"count 有插槽？"} +HasCount --> |是| UseCountSlot["使用插槽 count"] +HasCount --> |否| UseCountProp["使用属性 count"] +CheckCountText --> HasText{"text 有插槽？"} +HasText --> |是| UseTextSlot["使用插槽 text"] +HasText --> |否| UseTextProp["使用属性 text"] +UseCountSlot --> Render["渲染 Ant Design Badge"] +UseCountProp --> Render +UseTextSlot --> Render +UseTextProp --> Render +Render --> End(["完成"]) +``` + +**图表来源** + +- [badge.tsx:6-17](file://frontend/antd/badge/badge.tsx#L6-L17) + +**章节来源** + +- [badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) + +### 缎带徽标（Badge.Ribbon） + +- 特殊效果 + - Ribbon 在父容器上绘制“缎带”式徽标，常用于强调状态或标注新功能；文本内容可通过插槽自定义。 +- 使用场景 + - 适合在卡片、按钮、列表项等容器上添加醒目标识，注意避免与已有装饰冲突。 + +```mermaid +sequenceDiagram +participant U as "用户代码" +participant S as "Ribbon 组合入口" +participant C as "内部 Ribbon 组件" +participant A as "Ant Design Ribbon" +U->>S : 传入属性与插槽(text) +S->>C : 动态导入并传递属性/插槽 +C->>A : 透传属性/插槽 +A-->>U : 在容器上渲染缎带徽标 +``` + +**图表来源** + +- [badge 组合入口 Index.svelte:48-61](file://frontend/antd/badge/ribbon/Index.svelte#L48-L61) +- [ribbon.badge.tsx:6-18](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L6-L18) + +**章节来源** + +- [badge 组合入口 Index.svelte:1-62](file://frontend/antd/badge/ribbon/Index.svelte#L1-L62) +- [ribbon.badge.tsx:1-22](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L1-L22) + +## 依赖关系分析 + +- 组件封装 + - 所有组件均通过 sveltify 将 Ant Design 对应组件桥接为 Svelte 组件，保持属性与事件的透传一致性。 +- 插槽机制 + - 通过 ReactSlot 将 Svelte 插槽转换为 React Slot，确保与 Antd 组件的插槽约定兼容。 +- 动态导入 + - 组合入口使用 importComponent 与 import 动态导入内部实现，减少首屏体积并提升按需加载效率。 +- 样式耦合 + - 头像组通过 less 变量控制重叠间距，避免硬编码，便于主题统一管理。 + +```mermaid +graph LR +Svelte["Svelte 组合入口"] --> Sveltify["sveltify 封装"] +Sveltify --> Antd["Ant Design 组件"] +Svelte --> ReactSlot["ReactSlot 插槽桥接"] +Svelte --> DynamicImport["动态导入内部实现"] +Antd --> Less["less 变量控制样式"] +``` + +**图表来源** + +- [avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [avatar.group.tsx:1-52](file://frontend/antd/avatar/group/avatar.group.tsx#L1-L52) +- [badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) +- [ribbon.badge.tsx:1-22](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L1-L22) + +**章节来源** + +- [avatar 组合入口 Index.svelte:1-62](file://frontend/antd/avatar/group/Index.svelte#L1-L62) +- [avatar.group.tsx:1-52](file://frontend/antd/avatar/group/avatar.group.tsx#L1-L52) +- [badge 组合入口 Index.svelte:1-62](file://frontend/antd/badge/ribbon/Index.svelte#L1-L62) +- [ribbon.badge.tsx:1-22](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L1-L22) + +## 性能考量 + +- 按需加载 + - 组合入口采用动态导入策略，仅在需要时加载内部实现，降低初始包体与首屏渲染压力。 +- 插槽渲染 + - 插槽内容延迟到渲染阶段再注入，避免不必要的预处理开销。 +- 样式变量 + - 通过 less 变量集中管理重叠间距等样式细节，减少重复计算与样式抖动。 + +[本节为通用性能建议，无需特定文件引用] + +## 故障排查指南 + +- 头像未显示图标或图片 + - 检查是否正确传入 icon 或 src 属性；若使用插槽，请确认插槽名称与类型匹配。 + - 若未提供图标/图片，组件会回退到子节点作为占位内容，确认子节点是否可见。 +- 头像组阈值无效或弹出层不显示 + - 确认 max.count 是否为数值型；当 count 为数值时，内部会自动加一以补偿自身占用。 + - 弹出层标题与内容可通过插槽覆盖，若未提供插槽，将回退到属性配置。 +- 徽标数阈值不生效 + - 确认传入的阈值属性是否被正确透传至底层组件；Antd 默认支持 n+ 显示逻辑。 +- 缎带徽标位置异常 + - 确认 Ribbon 的父容器具备定位上下文；必要时手动设置容器相对定位以确保叠加效果稳定。 + +**章节来源** + +- [avatar.tsx:6-25](file://frontend/antd/avatar/avatar.tsx#L6-L25) +- [avatar.group.tsx:18-40](file://frontend/antd/avatar/group/avatar.group.tsx#L18-L40) +- [badge.tsx:6-17](file://frontend/antd/badge/badge.tsx#L6-L17) +- [ribbon.badge.tsx:6-18](file://frontend/antd/badge/ribbon/badge.ribbon.tsx#L6-L18) + +## 结论 + +本组件体系以 Ant Design 为核心，通过 Svelte 封装与插槽桥接，提供了灵活的头像与徽标能力。头像组的堆叠遮罩、徽标数的计数与阈值、以及缎带徽标的强调效果均可在不破坏语义的前提下进行高度定制。建议在实际项目中结合主题变量与布局规范，统一管理尺寸、间距与颜色，以获得一致的用户体验。 + +[本节为总结性内容，无需特定文件引用] + +## 附录 + +- 示例入口 + - 头像组件示例入口参见文档目录下的 demo 标签。 + - 徽标组件示例入口参见文档目录下的 demo 标签。 +- 相关文档 + - 头像组件文档概览：[avatar 文档 README.md:1-9](file://docs/components/antd/avatar/README.md#L1-L9) + - 徽标组件文档概览：[badge 文档 README.md:1-9](file://docs/components/antd/badge/README.md#L1-L9) + +**章节来源** + +- [avatar 文档 README.md:1-9](file://docs/components/antd/avatar/README.md#L1-L9) +- [badge 文档 README.md:1-9](file://docs/components/antd/badge/README.md#L1-L9) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\217\217\350\277\260\345\210\227\350\241\250\344\270\216\347\251\272\347\212\266\346\200\201\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\217\217\350\277\260\345\210\227\350\241\250\344\270\216\347\251\272\347\212\266\346\200\201\347\273\204\344\273\266.md" new file mode 100644 index 00000000..b4839963 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\217\217\350\277\260\345\210\227\350\241\250\344\270\216\347\251\272\347\212\266\346\200\201\347\273\204\344\273\266.md" @@ -0,0 +1,350 @@ +# 描述列表与空状态组件 + + +**本文引用的文件** +- [frontend/antd/descriptions/descriptions.tsx](file://frontend/antd/descriptions/descriptions.tsx) +- [frontend/antd/descriptions/item/Index.svelte](file://frontend/antd/descriptions/item/Index.svelte) +- [frontend/antd/descriptions/context.ts](file://frontend/antd/descriptions/context.ts) +- [frontend/antd/empty/empty.tsx](file://frontend/antd/empty/empty.tsx) +- [frontend/antd/grid/row/row.tsx](file://frontend/antd/grid/row/row.tsx) +- [frontend/antd/grid/col/col.tsx](file://frontend/antd/grid/col/col.tsx) +- [frontend/antd/grid/context.ts](file://frontend/antd/grid/context.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) +- [docs/components/antd/descriptions/README.md](file://docs/components/antd/descriptions/README.md) + + +## 目录 + +1. [引言](#引言) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 引言 + +本文件聚焦于两个常用 UI 组件：描述列表（Descriptions）与空状态（Empty）。我们将从系统架构、组件关系、数据流与处理逻辑、集成点与错误处理、性能特征等方面进行深入解析，并结合仓库中的实现细节，给出可操作的使用建议与最佳实践。同时覆盖以下主题： + +- 描述列表的键值对展示、响应式布局、标签对齐方式与描述项的自定义配置 +- 空状态的默认图标、自定义图标、辅助文字与操作按钮的组合使用 +- 描述列表在表单详情页的应用场景、标签的多语言支持与空状态的国际化处理 +- 描述列表的栅格化布局与空状态在数据加载失败时的用户体验优化 + +## 项目结构 + +本项目采用分层与按组件组织的前端结构，描述列表与空状态分别位于 antd 前端组件目录下，并通过通用工具与上下文机制实现灵活的插槽与子项管理。 + +```mermaid +graph TB +subgraph "描述列表" +DRoot["descriptions.tsx"] +DItem["item/Index.svelte"] +DContext["context.ts"] +end +subgraph "空状态" +ERoot["empty.tsx"] +end +subgraph "栅格系统" +GRow["grid/row/row.tsx"] +GCol["grid/col/col.tsx"] +GContext["grid/context.ts"] +end +subgraph "通用工具" +Ctx["utils/createItemsContext.tsx"] +Locales["config-provider/locales.ts"] +end +DRoot --> DContext +DItem --> DContext +DContext --> Ctx +GRow --> GContext +GCol --> GContext +GContext --> Ctx +ERoot --> Locales +``` + +图表来源 + +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [frontend/antd/descriptions/item/Index.svelte:1-83](file://frontend/antd/descriptions/item/Index.svelte#L1-L83) +- [frontend/antd/descriptions/context.ts:1-7](file://frontend/antd/descriptions/context.ts#L1-L7) +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) +- [frontend/antd/grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [frontend/antd/grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) + +章节来源 + +- [docs/components/antd/descriptions/README.md:1-9](file://docs/components/antd/descriptions/README.md#L1-L9) + +## 核心组件 + +- 描述列表（Descriptions） + - 负责将一组键值对以只读形式分组展示，支持标题、额外区域与插槽化的内容注入。 + - 通过上下文与子项处理器收集内部的描述项，最终渲染为 Ant Design 的 Descriptions 组件。 +- 描述项（Descriptions.Item） + - 作为描述列表的子项，负责接收可见性、样式、ID、类名等属性，并将子内容以插槽形式传递给底层组件。 +- 空状态（Empty） + - 提供默认、简单或自定义图标的空状态占位，支持自定义描述文本与样式函数，便于在数据为空或加载失败时提升体验。 +- 栅格系统（Grid.Row/Col） + - 通过上下文机制将列子项收集并映射到 Ant Design 的 Row/Col，实现描述列表的栅格化布局。 + +章节来源 + +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [frontend/antd/descriptions/item/Index.svelte:1-83](file://frontend/antd/descriptions/item/Index.svelte#L1-L83) +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) +- [frontend/antd/grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [frontend/antd/grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) + +## 架构总览 + +描述列表与空状态均基于统一的“插槽与子项上下文”机制工作： + +- 上下文提供者负责收集来自子项的结构化信息（props、slots、元素等），并在渲染阶段将其转换为 Ant Design 所需的数据结构。 +- 插槽（slots）允许用户以 ReactSlot 或 Svelte Slot 的形式注入自定义内容，如标题、额外区域、描述项内容等。 +- 空状态组件在渲染时根据传入的 image 类型或插槽选择合适的图标，并将样式函数与内联样式合并。 + +```mermaid +sequenceDiagram +participant U as "用户代码" +participant D as "Descriptions(React)" +participant Ctx as "ItemsContextProvider" +participant Item as "Descriptions.Item(Svelte)" +participant AD as "Antd.Descriptions" +U->>D : 渲染 Descriptions 并传入 props/slots +D->>Ctx : 使用上下文提供者包装 +U->>Item : 在 Descriptions 内部放置多个 Item +Item->>Ctx : 通过 ItemHandler 注册子项 +Ctx-->>D : 汇总 items 列表 +D->>AD : 将 items、title、extra 传给 Antd.Descriptions +AD-->>U : 渲染完成 +``` + +图表来源 + +- [frontend/antd/descriptions/descriptions.tsx:10-38](file://frontend/antd/descriptions/descriptions.tsx#L10-L38) +- [frontend/antd/descriptions/context.ts:1-7](file://frontend/antd/descriptions/context.ts#L1-L7) +- [frontend/antd/descriptions/item/Index.svelte:56-76](file://frontend/antd/descriptions/item/Index.svelte#L56-L76) +- [frontend/utils/createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) + +## 详细组件分析 + +### 描述列表（Descriptions） + +- 键值对展示 + - 通过上下文收集子项，最终生成 Ant Design Descriptions 所需的 items 数组；支持直接传入 items 或由子项自动聚合。 +- 响应式布局 + - 可配合栅格系统（Grid.Row/Col）实现响应式布局；在 Row 中将列子项映射为 Antd Col，从而实现断点下的自适应排列。 +- 标签对齐方式 + - 该组件本身不直接控制标签对齐，但可通过传入的 props 交由 Antd Descriptions 处理；在 Svelte 层面保持透传。 +- 描述项（Item）的自定义配置 + - 支持 visible 控制显示、elem_id/elem_classes/elem_style 设置 DOM 属性与样式、additionalProps 附加属性、as_item 自定义渲染类型等。 +- 插槽与标题/额外区域 + - 支持 title 与 extra 插槽，用于注入自定义标题与额外操作区；若未提供则回退到 props。 + +```mermaid +classDiagram +class Descriptions { ++props : "Antd Descriptions Props" ++slots : "title, extra, default" ++items : "数组或子项集合" ++render() +} +class DescriptionsItem { ++visible : "是否可见" ++elem_id : "DOM ID" ++elem_classes : "CSS 类" ++elem_style : "内联样式" ++additionalProps : "附加属性" ++as_item : "渲染类型" ++slots : "children 等" ++itemIndex : "索引" ++itemSlotKey : "插槽键" +} +class ItemsContext { ++items : "按插槽分组的子项" ++setItem() ++initial : "初始化标记" +} +Descriptions --> ItemsContext : "使用" +DescriptionsItem --> ItemsContext : "注册/收集" +``` + +图表来源 + +- [frontend/antd/descriptions/descriptions.tsx:10-38](file://frontend/antd/descriptions/descriptions.tsx#L10-L38) +- [frontend/antd/descriptions/item/Index.svelte:18-76](file://frontend/antd/descriptions/item/Index.svelte#L18-L76) +- [frontend/antd/descriptions/context.ts:1-7](file://frontend/antd/descriptions/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:40-95](file://frontend/utils/createItemsContext.tsx#L40-L95) + +章节来源 + +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [frontend/antd/descriptions/item/Index.svelte:1-83](file://frontend/antd/descriptions/item/Index.svelte#L1-L83) +- [frontend/antd/descriptions/context.ts:1-7](file://frontend/antd/descriptions/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +### 空状态（Empty） + +- 默认图标与自定义图标 + - 支持三种内置图标类型，也支持传入自定义 image；当存在 image 插槽时优先使用插槽内容。 +- 辅助文字 + - description 插槽优先级高于 props.description，便于动态渲染本地化文案或复杂内容。 +- 样式与布局 + - 支持传入样式函数或对象，内部会将 image 样式设置为 inline-block，确保图标与文字的排版一致。 +- 操作按钮组合 + - 可通过 description 插槽组合按钮等交互元素，实现“空状态 + 操作”的完整闭环。 + +```mermaid +flowchart TD +Start(["进入 Empty 渲染"]) --> CheckImage["检查是否存在 image 插槽"] +CheckImage --> |是| UseSlotImage["使用插槽 image"] +CheckImage --> |否| SwitchImage["根据 props.image 选择类型"] +SwitchImage --> |内置常量| UseAntdDefault["使用 Antd 内置图标"] +SwitchImage --> |简单内置| UseAntdSimple["使用 Antd 简单图标"] +SwitchImage --> |其他| UseCustom["使用自定义 image"] +UseSlotImage --> RenderDesc["渲染 description 插槽或 props.description"] +UseAntdDefault --> RenderDesc +UseAntdSimple --> RenderDesc +UseCustom --> RenderDesc +RenderDesc --> MergeStyles["合并样式函数与对象
确保图标 inline-block"] +MergeStyles --> End(["完成渲染"]) +``` + +图表来源 + +- [frontend/antd/empty/empty.tsx:9-49](file://frontend/antd/empty/empty.tsx#L9-L49) + +章节来源 + +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) + +### 栅格化布局（Grid.Row/Col） + +- Row 将收集到的列子项映射为 Antd Col，并在 Row 中渲染，实现响应式栅格布局。 +- Col 通过 ItemHandler 接收列的 props 与插槽，再转交给 Antd Col。 +- 与描述列表结合时，可在 Row/Col 内部嵌套描述项，形成“栅格化的描述列表”。 + +```mermaid +sequenceDiagram +participant U as "用户代码" +participant R as "Grid.Row(React)" +participant Ctx as "Grid ItemsContext" +participant C as "Grid.Col(React)" +participant AD as "Antd.Row/Col" +U->>R : 渲染 Row +R->>Ctx : 使用上下文提供者 +U->>C : 在 Row 内放置多个 Col +C->>Ctx : 通过 ItemHandler 注册列子项 +Ctx-->>R : 汇总列 items +R->>AD : 渲染 Row 并映射 Col +AD-->>U : 完成栅格布局 +``` + +图表来源 + +- [frontend/antd/grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [frontend/antd/grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) + +章节来源 + +- [frontend/antd/grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [frontend/antd/grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) + +## 依赖关系分析 + +- 描述列表依赖 + - 使用 createItemsContext 提供的上下文能力，将 Svelte 插槽与 React 组件桥接，实现 items 的收集与渲染。 + - 通过 withItemsContextProvider 包装组件，确保子项注册与更新。 +- 空状态依赖 + - 依赖 Ant Design 的 Empty 组件与内置图标常量；通过样式函数与对象合并，保证图标与文字的排版一致性。 +- 国际化依赖 + - 通过 config-provider 的 locales 提供多语言环境，支持 Antd 与 dayjs 的本地化切换。 + +```mermaid +graph LR +D["Descriptions"] --> Ctx["createItemsContext"] +DItem["Descriptions.Item"] --> Ctx +E["Empty"] --> AD["Antd.Empty"] +E --> Locales["locales.ts"] +subgraph "上下文工具" +Ctx +end +subgraph "Antd 组件" +AD +end +subgraph "国际化" +Locales +end +``` + +图表来源 + +- [frontend/antd/descriptions/descriptions.tsx:1-10](file://frontend/antd/descriptions/descriptions.tsx#L1-L10) +- [frontend/antd/descriptions/item/Index.svelte:1-15](file://frontend/antd/descriptions/item/Index.svelte#L1-L15) +- [frontend/antd/empty/empty.tsx:1-9](file://frontend/antd/empty/empty.tsx#L1-L9) +- [frontend/antd/config-provider/locales.ts:1-10](file://frontend/antd/config-provider/locales.ts#L1-L10) + +章节来源 + +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) + +## 性能考量 + +- 子项收集与渲染 + - 描述列表与栅格系统均通过上下文收集子项，避免不必要的重渲染；在 items 更新时仅触发对应组件的重新计算。 +- 插槽与样式 + - 插槽内容延迟渲染，仅在可见时挂载；样式函数与对象合并发生在渲染阶段，建议尽量复用样式对象以减少开销。 +- 图标与描述 + - 空状态的图标选择与样式合并逻辑简单，性能开销较低；建议在大量空状态场景中统一使用内置图标以减少资源加载。 + +## 故障排查指南 + +- 描述列表无内容显示 + - 检查是否正确使用 withItemsContextProvider 包裹 Descriptions，并在内部放置 Descriptions.Item。 + - 确认子项已通过 ItemHandler 注册，且 items 非空。 +- 描述项不生效 + - 检查 visible、elem_id、elem_classes、elem_style、additionalProps 等属性是否正确传入。 + - 确认插槽 children 是否被正确绑定与渲染。 +- 空状态图标不显示 + - 若传入 image 插槽，请确认插槽内容有效；否则检查 props.image 是否为内置常量或合法的自定义值。 + - 确认样式函数返回的对象包含正确的 image 样式。 +- 栅格布局异常 + - 检查 Grid.Row/Col 的子项是否正确注册；确认列的 props 与插槽传递无误。 + +章节来源 + +- [frontend/antd/descriptions/descriptions.tsx:10-38](file://frontend/antd/descriptions/descriptions.tsx#L10-L38) +- [frontend/antd/descriptions/item/Index.svelte:56-76](file://frontend/antd/descriptions/item/Index.svelte#L56-L76) +- [frontend/antd/empty/empty.tsx:9-49](file://frontend/antd/empty/empty.tsx#L9-L49) +- [frontend/antd/grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [frontend/antd/grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) + +## 结论 + +描述列表与空状态组件通过统一的上下文与插槽机制，实现了灵活的内容注入与渲染。描述列表支持键值对展示与栅格化布局，空状态提供默认与自定义图标的占位方案，并可与操作按钮组合优化用户体验。结合国际化工具，两者均可在多语言环境下稳定运行。建议在表单详情页中优先使用描述列表展示只读信息，在数据为空或加载失败时使用空状态组件提升可用性。 + +## 附录 + +- 应用场景建议 + - 表单详情页：使用描述列表展示只读字段，必要时配合栅格系统实现响应式布局。 + - 数据加载失败：使用空状态组件展示提示与重试按钮，提升用户信心。 +- 多语言支持 + - 通过 config-provider 的 locales 切换 Antd 与 dayjs 的本地化，确保描述列表与空状态中的文案与格式符合目标语言。 +- 最佳实践 + - 合理使用插槽与 props，避免在渲染函数中频繁创建新对象。 + - 对于大量空状态场景，优先使用内置图标以降低资源开销。 + - 在栅格化布局中，合理划分列宽与断点，确保在不同设备上的可读性。 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266.md" new file mode 100644 index 00000000..88949211 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266.md" @@ -0,0 +1,664 @@ +# 数据展示组件 + + +**本文引用的文件** +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [frontend/antd/avatar/avatar.tsx](file://frontend/antd/avatar/avatar.tsx) +- [frontend/antd/badge/badge.tsx](file://frontend/antd/badge/badge.tsx) +- [frontend/antd/calendar/calendar.tsx](file://frontend/antd/calendar/calendar.tsx) +- [frontend/antd/card/card.tsx](file://frontend/antd/card/card.tsx) +- [frontend/antd/carousel/carousel.tsx](file://frontend/antd/carousel/carousel.tsx) +- [frontend/antd/collapse/collapse.tsx](file://frontend/antd/collapse/collapse.tsx) +- [frontend/antd/descriptions/descriptions.tsx](file://frontend/antd/descriptions/descriptions.tsx) +- [frontend/antd/empty/empty.tsx](file://frontend/antd/empty/empty.tsx) +- [frontend/antd/image/image.tsx](file://frontend/antd/image/image.tsx) +- [frontend/antd/list/list.tsx](file://frontend/antd/list/list.tsx) +- [frontend/antd/popover/popover.tsx](file://frontend/antd/popover/popover.tsx) +- [frontend/antd/qr_code/qr-code.tsx](file://frontend/antd/qr_code/qr-code.tsx) +- [frontend/antd/segmented/segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [frontend/antd/statistic/statistic.tsx](file://frontend/antd/statistic/statistic.tsx) +- [frontend/antd/table/table.tsx](file://frontend/antd/table/table.tsx) +- [frontend/antd/tabs/tabs.tsx](file://frontend/antd/tabs/tabs.tsx) +- [frontend/antd/tag/tag.tsx](file://frontend/antd/tag/tag.tsx) +- [frontend/antd/timeline/timeline.tsx](file://frontend/antd/timeline/timeline.tsx) +- [frontend/antd/tooltip/tooltip.tsx](file://frontend/antd/tooltip/tooltip.tsx) +- [frontend/antd/tour/tour.tsx](file://frontend/antd/tour/tour.tsx) +- [frontend/antd/tree/tree.tsx](file://frontend/antd/tree/tree.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向 Ant Design 数据展示类组件，系统梳理头像(Avatar)、徽标数(Badge)、日历(Calendar)、卡片(Card)、走马灯(Carousel)、折叠面板(Collapse)、描述列表(Descriptions)、空状态(Empty)、图片(Image)、列表(List)、气泡卡片(Popover)、二维码(QRCode)、分段控制器(Segmented)、统计数值(Statistic)、表格(Table)、标签页(Tabs)、标签(Tag)、时间轴(Timeline)、文字提示(Tooltip)、漫游式引导(Tour)、树形控件(Tree)等组件在本仓库中的实现与使用方式。重点说明： + +- 数据渲染：如何通过 slots 与 items 将子节点映射为 Ant Design 组件的 children/items。 +- 交互行为：事件回调（如 onChange/onSelect）与函数包装（useFunction）的统一处理。 +- 动画效果：由 Ant Design 原生提供，组件层不做额外动画封装。 +- 大数据量优化：建议采用虚拟滚动、分页、懒加载等策略，并结合组件的可扩展性进行二次封装。 +- 主题定制与样式覆盖：通过 Ant Design 的主题变量与 CSS 变量体系实现。 +- 响应式与移动端适配：遵循 Ant Design 的栅格与断点策略，结合 Svelte 组件的尺寸控制。 + +## 项目结构 + +该仓库采用“后端 Python 模块 + 前端 Svelte 包”的双层封装模式： + +- 后端模块负责导出各组件类，便于在 Python 环境中统一引用。 +- 前端 Svelte 包通过 sveltify 将 Ant Design React 组件桥接为 Svelte 组件，支持 slots 与 items 的声明式渲染。 + +```mermaid +graph TB +subgraph "后端" +PY_API["Python 导出模块
__init__.py / components.py"] +end +subgraph "前端" +PKG["Svelte 包
package.json"] +AVATAR["Avatar
avatar.tsx"] +BADGE["Badge
badge.tsx"] +CALENDAR["Calendar
calendar.tsx"] +CARD["Card
card.tsx"] +CAROUSEL["Carousel
carousel.tsx"] +COLLAPSE["Collapse
collapse.tsx"] +DESC["Descriptions
descriptions.tsx"] +EMPTY["Empty
empty.tsx"] +IMAGE["Image
image.tsx"] +LIST["List
list.tsx"] +POPOVER["Popover
popover.tsx"] +QRCODE["QRCode
qr-code.tsx"] +SEG["Segmented
segmented.tsx"] +STAT["Statistic
statistic.tsx"] +TABLE["Table
table.tsx"] +TABS["Tabs
tabs.tsx"] +TAG["Tag
tag.tsx"] +TIME["Timeline
timeline.tsx"] +TT["Tooltip
tooltip.tsx"] +TOUR["Tour
tour.tsx"] +TREE["Tree
tree.tsx"] +end +PY_API --> AVATAR +PY_API --> BADGE +PY_API --> CALENDAR +PY_API --> CARD +PY_API --> CAROUSEL +PY_API --> COLLAPSE +PY_API --> DESC +PY_API --> EMPTY +PY_API --> IMAGE +PY_API --> LIST +PY_API --> POPOVER +PY_API --> QRCODE +PY_API --> SEG +PY_API --> STAT +PY_API --> TABLE +PY_API --> TABS +PY_API --> TAG +PY_API --> TIME +PY_API --> TT +PY_API --> TOUR +PY_API --> TREE +PKG --> AVATAR +PKG --> BADGE +PKG --> CALENDAR +PKG --> CARD +PKG --> CAROUSEL +PKG --> COLLAPSE +PKG --> DESC +PKG --> EMPTY +PKG --> IMAGE +PKG --> LIST +PKG --> POPOVER +PKG --> QRCODE +PKG --> SEG +PKG --> STAT +PKG --> TABLE +PKG --> TABS +PKG --> TAG +PKG --> TIME +PKG --> TT +PKG --> TOUR +PKG --> TREE +``` + +图示来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) + +章节来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) + +## 核心组件 + +本节概述各组件在前端的桥接方式与关键特性： + +- 统一桥接：所有组件均通过 sveltify 将 Ant Design React 组件包裹为 Svelte 组件，支持 slots 与 items 的声明式渲染。 +- 函数回调：使用 useFunction 对 onChange/onSelect 等回调进行包装，确保在 Svelte 上下文中正确执行。 +- 日期与范围：对日期型 props 进行格式化与转换，保证与上层传入的时间戳一致。 +- 子项渲染：通过 renderItems 与 useTargets 实现 items 与 children 的统一映射。 + +章节来源 + +- [frontend/antd/avatar/avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [frontend/antd/badge/badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [frontend/antd/card/card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) +- [frontend/antd/carousel/carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [frontend/antd/collapse/collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) + +## 架构总览 + +下图展示了从后端导出到前端组件桥接的整体流程，以及组件间共享的工具函数与上下文。 + +```mermaid +sequenceDiagram +participant Py as "后端导出模块" +participant Svelte as "Svelte 组件" +participant AD as "Ant Design React" +participant Util as "工具函数" +Py->>Svelte : 导出组件类 +Svelte->>Util : useFunction/useTargets/renderItems +Svelte->>AD : sveltify 包装并传递 props/slots +AD-->>Svelte : 渲染结果与回调触发 +Svelte-->>Py : 通过 slots/items 完成数据展示 +``` + +图示来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [frontend/antd/avatar/avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [frontend/antd/card/card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) +- [frontend/antd/carousel/carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [frontend/antd/collapse/collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) + +## 详细组件分析 + +### 头像 Avatar + +- 数据渲染：支持通过 slots 渲染 icon 与 src；若未提供，则回退到 children。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供，组件层不额外封装。 + +```mermaid +flowchart TD +Start(["进入 Avatar"]) --> CheckSlots["检查 slots: icon / src"] +CheckSlots --> HasSlots{"存在 slots?"} +HasSlots --> |是| RenderSlots["渲染 slots 内容"] +HasSlots --> |否| Fallback["回退到 children"] +RenderSlots --> Render["渲染 Ant Design Avatar"] +Fallback --> Render +Render --> End(["完成"]) +``` + +图示来源 + +- [frontend/antd/avatar/avatar.tsx:6-25](file://frontend/antd/avatar/avatar.tsx#L6-L25) + +章节来源 + +- [frontend/antd/avatar/avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) + +### 徽标数 Badge + +- 数据渲染：count 与 text 支持通过 slots 自定义。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +```mermaid +flowchart TD +Start(["进入 Badge"]) --> CountSlot["count 是否有 slot?"] +CountSlot --> |是| RenderCount["渲染 count slot"] +CountSlot --> |否| UseCount["使用 props.count"] +TextSlot["text 是否有 slot?"] +TextSlot --> |是| RenderText["渲染 text slot"] +TextSlot --> |否| UseText["使用 props.text"] +RenderCount --> Render["渲染 Ant Design Badge"] +UseCount --> Render +RenderText --> Render +UseText --> Render +Render --> End(["完成"]) +``` + +图示来源 + +- [frontend/antd/badge/badge.tsx:6-18](file://frontend/antd/badge/badge.tsx#L6-L18) + +章节来源 + +- [frontend/antd/badge/badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) + +### 日历 Calendar + +- 数据渲染：value/defaultValue/validRange 使用 dayjs 格式化；cellRender/fullCellRender/headerRender 支持 slots。 +- 交互行为：onChange/onPanelChange/onSelect 回调统一通过 useFunction 包装；内部将日期转为秒级时间戳返回给上层。 +- 动画效果：由 Ant Design 提供。 + +```mermaid +sequenceDiagram +participant UI as "用户界面" +participant Comp as "Calendar 组件" +participant Util as "useFunction/formatDayjs" +participant AD as "Ant Design Calendar" +UI->>Comp : 传入 value/defaultValue/validRange +Comp->>Util : 格式化日期 +Comp->>AD : 渲染并绑定回调 +AD-->>Comp : onChange/onPanelChange/onSelect 触发 +Comp->>UI : 转换为秒级时间戳并回调 +``` + +图示来源 + +- [frontend/antd/calendar/calendar.tsx:17-99](file://frontend/antd/calendar/calendar.tsx#L17-L99) + +章节来源 + +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) + +### 卡片 Card + +- 数据渲染：title/extra/cover/tabBarExtraContent 支持 slots；actions 通过 useTargets 自动收集；tabList 通过 renderItems 渲染。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +```mermaid +flowchart TD +Start(["进入 Card"]) --> Actions["收集 actions slots"] +Actions --> Tabs["解析 tabList 与 tabProps"] +Tabs --> Slots["解析 title/extra/cover 等 slots"] +Slots --> Render["渲染 Ant Design Card"] +Render --> End(["完成"]) +``` + +图示来源 + +- [frontend/antd/card/card.tsx:37-147](file://frontend/antd/card/card.tsx#L37-L147) + +章节来源 + +- [frontend/antd/card/card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) + +### 走马灯 Carousel + +- 数据渲染：children 通过 useTargets 收集，再以 ReactSlot 克隆渲染。 +- 交互行为：afterChange/beforeChange 通过 useFunction 包装。 +- 动画效果：由 Ant Design 提供。 + +```mermaid +sequenceDiagram +participant Comp as "Carousel 组件" +participant Util as "useTargets/useFunction" +participant AD as "Ant Design Carousel" +Comp->>Util : 收集 children 并克隆 +Comp->>AD : 渲染并绑定回调 +AD-->>Comp : 切换前后回调 +Comp-->>Comp : 执行包装后的回调 +``` + +图示来源 + +- [frontend/antd/carousel/carousel.tsx:8-29](file://frontend/antd/carousel/carousel.tsx#L8-L29) + +章节来源 + +- [frontend/antd/carousel/carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) + +### 折叠面板 Collapse + +- 数据渲染：items 通过 renderItems 渲染；expandIcon 支持 slot。 +- 交互行为：onChange 通过 useFunction 包装。 +- 动画效果：由 Ant Design 提供。 + +```mermaid +flowchart TD +Start(["进入 Collapse"]) --> Items["解析 items 或 slots.default/items"] +Items --> ExpandIcon["expandIcon 是否有 slot?"] +ExpandIcon --> |是| RenderIcon["渲染 slot"] +ExpandIcon --> |否| UseIcon["使用 props.expandIcon"] +RenderIcon --> Render["渲染 Ant Design Collapse"] +UseIcon --> Render +Render --> End(["完成"]) +``` + +图示来源 + +- [frontend/antd/collapse/collapse.tsx:11-50](file://frontend/antd/collapse/collapse.tsx#L11-L50) + +章节来源 + +- [frontend/antd/collapse/collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) + +### 描述列表 Descriptions + +- 数据渲染：title/extra 支持 slot；items 通过 renderItems 渲染。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +```mermaid +flowchart TD +Start(["进入 Descriptions"]) --> Resolve["解析 items 或 slots.default/items"] +Resolve --> Render["渲染 Ant Design Descriptions"] +Render --> End(["完成"]) +``` + +图示来源 + +- [frontend/antd/descriptions/descriptions.tsx:10-38](file://frontend/antd/descriptions/descriptions.tsx#L10-L38) + +章节来源 + +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) + +### 空状态 Empty + +- 数据渲染：description/image 支持 slot；image 支持默认值与自定义。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +```mermaid +flowchart TD +Start(["进入 Empty"]) --> Desc["description 是否有 slot?"] +Desc --> |是| RenderDesc["渲染 slot"] +Desc --> |否| UseDesc["使用 props.description"] +Image["image 是否有 slot?"] +Image --> |是| RenderImg["渲染 slot"] +Image --> |否| CheckDefault["判断默认值或自定义"] +RenderDesc --> Render["渲染 Ant Design Empty"] +UseDesc --> Render +RenderImg --> Render +CheckDefault --> Render +Render --> End(["完成"]) +``` + +图示来源 + +- [frontend/antd/empty/empty.tsx:6-49](file://frontend/antd/empty/empty.tsx#L6-L49) + +章节来源 + +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) + +### 图片 Image + +- 数据渲染：支持预览组与 slots。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +章节来源 + +- [frontend/antd/image/image.tsx:1-200](file://frontend/antd/image/image.tsx#L1-L200) + +### 列表 List + +- 数据渲染：支持自定义渲染项与操作区。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +章节来源 + +- [frontend/antd/list/list.tsx:1-200](file://frontend/antd/list/list.tsx#L1-L200) + +### 气泡卡片 Popover + +- 数据渲染：支持触发器与内容区的 slots。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +章节来源 + +- [frontend/antd/popover/popover.tsx:1-200](file://frontend/antd/popover/popover.tsx#L1-L200) + +### 二维码 QRCode + +- 数据渲染：支持内容与样式配置。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +章节来源 + +- [frontend/antd/qr_code/qr-code.tsx:1-200](file://frontend/antd/qr_code/qr-code.tsx#L1-L200) + +### 分段控制器 Segmented + +- 数据渲染：支持选项与 slots。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +章节来源 + +- [frontend/antd/segmented/segmented.tsx:1-200](file://frontend/antd/segmented/segmented.tsx#L1-L200) + +### 统计数值 Statistic + +- 数据渲染：支持标题与数值的自定义。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +章节来源 + +- [frontend/antd/statistic/statistic.tsx:1-200](file://frontend/antd/statistic/statistic.tsx#L1-L200) + +### 表格 Table + +- 数据渲染：支持列定义、展开行、选择行等复杂结构。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +章节来源 + +- [frontend/antd/table/table.tsx:1-200](file://frontend/antd/table/table.tsx#L1-L200) + +### 标签页 Tabs + +- 数据渲染：支持标签项与额外内容的 slots。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +章节来源 + +- [frontend/antd/tabs/tabs.tsx:1-200](file://frontend/antd/tabs/tabs.tsx#L1-L200) + +### 标签 Tag + +- 数据渲染：支持可勾选标签与 slots。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +章节来源 + +- [frontend/antd/tag/tag.tsx:1-200](file://frontend/antd/tag/tag.tsx#L1-L200) + +### 时间轴 Timeline + +- 数据渲染：支持时间轴项与 slots。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +章节来源 + +- [frontend/antd/timeline/timeline.tsx:1-200](file://frontend/antd/timeline/timeline.tsx#L1-L200) + +### 文字提示 Tooltip + +- 数据渲染：支持触发器与内容区的 slots。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +章节来源 + +- [frontend/antd/tooltip/tooltip.tsx:1-200](file://frontend/antd/tooltip/tooltip.tsx#L1-L200) + +### 漫游式引导 Tour + +- 数据渲染：支持步骤与插槽。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +章节来源 + +- [frontend/antd/tour/tour.tsx:1-200](file://frontend/antd/tour/tour.tsx#L1-L200) + +### 树形控件 Tree + +- 数据渲染：支持目录树与节点渲染。 +- 交互行为：无交互事件。 +- 动画效果：由 Ant Design 提供。 + +章节来源 + +- [frontend/antd/tree/tree.tsx:1-200](file://frontend/antd/tree/tree.tsx#L1-L200) + +## 依赖分析 + +- 组件耦合：各组件均依赖 Ant Design React 版本；通过 sveltify 统一封装，降低直接使用 React 的复杂度。 +- 工具函数：useFunction/useTargets/renderItems/renderParamsSlot 等工具贯穿多个组件，提升复用性与一致性。 +- 上下文：部分组件（如 Collapse/Descriptions/Tabs）引入 items 上下文，统一 items 的声明与渲染。 + +```mermaid +graph LR +Util["工具函数
useFunction/useTargets/renderItems"] --> AV["Avatar"] +Util --> BG["Badge"] +Util --> CA["Calendar"] +Util --> CR["Card"] +Util --> CL["Carousel"] +Util --> CP["Collapse"] +Util --> DS["Descriptions"] +Util --> EM["Empty"] +Util --> IM["Image"] +Util --> LI["List"] +Util --> PP["Popover"] +Util --> QC["QRCode"] +Util --> SG["Segmented"] +Util --> ST["Statistic"] +Util --> TB["Table"] +Util --> TS["Tabs"] +Util --> TG["Tag"] +Util --> TM["Timeline"] +Util --> TT["Tooltip"] +Util --> TR["Tree"] +``` + +图示来源 + +- [frontend/antd/avatar/avatar.tsx:1-28](file://frontend/antd/avatar/avatar.tsx#L1-L28) +- [frontend/antd/badge/badge.tsx:1-21](file://frontend/antd/badge/badge.tsx#L1-L21) +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [frontend/antd/card/card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) +- [frontend/antd/carousel/carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [frontend/antd/collapse/collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [frontend/antd/descriptions/descriptions.tsx:1-41](file://frontend/antd/descriptions/descriptions.tsx#L1-L41) +- [frontend/antd/empty/empty.tsx:1-52](file://frontend/antd/empty/empty.tsx#L1-L52) +- [frontend/antd/image/image.tsx:1-200](file://frontend/antd/image/image.tsx#L1-L200) +- [frontend/antd/list/list.tsx:1-200](file://frontend/antd/list/list.tsx#L1-L200) +- [frontend/antd/popover/popover.tsx:1-200](file://frontend/antd/popover/popover.tsx#L1-L200) +- [frontend/antd/qr_code/qr-code.tsx:1-200](file://frontend/antd/qr_code/qr-code.tsx#L1-L200) +- [frontend/antd/segmented/segmented.tsx:1-200](file://frontend/antd/segmented/segmented.tsx#L1-L200) +- [frontend/antd/statistic/statistic.tsx:1-200](file://frontend/antd/statistic/statistic.tsx#L1-L200) +- [frontend/antd/table/table.tsx:1-200](file://frontend/antd/table/table.tsx#L1-L200) +- [frontend/antd/tabs/tabs.tsx:1-200](file://frontend/antd/tabs/tabs.tsx#L1-L200) +- [frontend/antd/tag/tag.tsx:1-200](file://frontend/antd/tag/tag.tsx#L1-L200) +- [frontend/antd/timeline/timeline.tsx:1-200](file://frontend/antd/timeline/timeline.tsx#L1-L200) +- [frontend/antd/tooltip/tooltip.tsx:1-200](file://frontend/antd/tooltip/tooltip.tsx#L1-L200) +- [frontend/antd/tree/tree.tsx:1-200](file://frontend/antd/tree/tree.tsx#L1-L200) + +章节来源 + +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) + +## 性能考虑 + +- 大数据量展示建议 + - 虚拟滚动：优先使用具备虚拟滚动能力的容器组件（如 List/Table），仅渲染可视区域元素。 + - 分页与懒加载：对长列表采用分页或滚动触底加载，减少一次性渲染压力。 + - 事件节流：对高频交互（如滚动、缩放）使用节流/防抖，避免频繁重渲染。 + - 渲染优化：尽量将复杂计算移至后台或缓存，前端仅做轻量渲染。 +- 动画与过渡 + - Ant Design 组件自带平滑过渡，组件层不额外添加动画，避免叠加导致性能下降。 +- 主题与样式 + - 使用 Ant Design 的主题变量与 CSS 变量体系，减少重复样式计算。 + - 避免在组件内动态生成大量内联样式，优先使用类名与 CSS Modules。 + +## 故障排查指南 + +- 日期参数异常 + - 现象：日历组件日期显示或回调时间戳不一致。 + - 排查：确认传入 value/defaultValue/validRange 是否为合法时间戳或可被 dayjs 解析的值；检查格式化逻辑是否生效。 +- 回调未触发 + - 现象：onChange/onSelect 等回调未执行。 + - 排查：确认 useFunction 是否正确包裹回调；检查 slots 与 props 的优先级关系。 +- slots 未生效 + - 现象：title/extra/actions 等未按预期渲染。 + - 排查：确认 slots 名称与组件约定一致；检查 renderItems 与 useTargets 的使用是否正确。 +- 样式覆盖无效 + - 现象：自定义样式未生效。 + - 排查：确认 CSS 作用域与 !important 使用；优先使用主题变量与受控样式对象。 + +章节来源 + +- [frontend/antd/calendar/calendar.tsx:17-99](file://frontend/antd/calendar/calendar.tsx#L17-L99) +- [frontend/antd/card/card.tsx:37-147](file://frontend/antd/card/card.tsx#L37-L147) +- [frontend/antd/carousel/carousel.tsx:8-29](file://frontend/antd/carousel/carousel.tsx#L8-L29) +- [frontend/antd/collapse/collapse.tsx:11-50](file://frontend/antd/collapse/collapse.tsx#L11-L50) +- [frontend/antd/descriptions/descriptions.tsx:10-38](file://frontend/antd/descriptions/descriptions.tsx#L10-L38) +- [frontend/antd/empty/empty.tsx:6-49](file://frontend/antd/empty/empty.tsx#L6-L49) + +## 结论 + +本仓库通过统一的 sveltify 桥接与工具函数，将 Ant Design React 组件无缝集成到 Svelte 生态中，实现了： + +- 声明式的数据渲染（slots/items） +- 一致的交互回调（useFunction） +- 易于扩展的主题与样式覆盖 +- 良好的性能与可维护性 + +对于大数据量场景，建议结合虚拟滚动、分页与懒加载策略，进一步提升用户体验与性能表现。 + +## 附录 + +- 组件清单与对应文件路径 + - 头像(Avatar): [frontend/antd/avatar/avatar.tsx](file://frontend/antd/avatar/avatar.tsx) + - 徽标数(Badge): [frontend/antd/badge/badge.tsx](file://frontend/antd/badge/badge.tsx) + - 日历(Calendar): [frontend/antd/calendar/calendar.tsx](file://frontend/antd/calendar/calendar.tsx) + - 卡片(Card): [frontend/antd/card/card.tsx](file://frontend/antd/card/card.tsx) + - 走马灯(Carousel): [frontend/antd/carousel/carousel.tsx](file://frontend/antd/carousel/carousel.tsx) + - 折叠面板(Collapse): [frontend/antd/collapse/collapse.tsx](file://frontend/antd/collapse/collapse.tsx) + - 描述列表(Descriptions): [frontend/antd/descriptions/descriptions.tsx](file://frontend/antd/descriptions/descriptions.tsx) + - 空状态(Empty): [frontend/antd/empty/empty.tsx](file://frontend/antd/empty/empty.tsx) + - 图片(Image): [frontend/antd/image/image.tsx](file://frontend/antd/image/image.tsx) + - 列表(List): [frontend/antd/list/list.tsx](file://frontend/antd/list/list.tsx) + - 气泡卡片(Popover): [frontend/antd/popover/popover.tsx](file://frontend/antd/popover/popover.tsx) + - 二维码(QRCode): [frontend/antd/qr_code/qr-code.tsx](file://frontend/antd/qr_code/qr-code.tsx) + - 分段控制器(Segmented): [frontend/antd/segmented/segmented.tsx](file://frontend/antd/segmented/segmented.tsx) + - 统计数值(Statistic): [frontend/antd/statistic/statistic.tsx](file://frontend/antd/statistic/statistic.tsx) + - 表格(Table): [frontend/antd/table/table.tsx](file://frontend/antd/table/table.tsx) + - 标签页(Tabs): [frontend/antd/tabs/tabs.tsx](file://frontend/antd/tabs/tabs.tsx) + - 标签(Tag): [frontend/antd/tag/tag.tsx](file://frontend/antd/tag/tag.tsx) + - 时间轴(Timeline): [frontend/antd/timeline/timeline.tsx](file://frontend/antd/timeline/timeline.tsx) + - 文字提示(Tooltip): [frontend/antd/tooltip/tooltip.tsx](file://frontend/antd/tooltip/tooltip.tsx) + - 漫游式引导(Tour): [frontend/antd/tour/tour.tsx](file://frontend/antd/tour/tour.tsx) + - 树形控件(Tree): [frontend/antd/tree/tree.tsx](file://frontend/antd/tree/tree.tsx) +- 后端导出 + - [backend/modelscope_studio/components/antd/**init**.py](file://backend/modelscope_studio/components/antd/__init__.py) + - [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- 前端包信息 + - [frontend/antd/package.json](file://frontend/antd/package.json) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\226\207\345\255\227\346\217\220\347\244\272\344\270\216\346\274\253\346\270\270\345\274\225\345\257\274\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\226\207\345\255\227\346\217\220\347\244\272\344\270\216\346\274\253\346\270\270\345\274\225\345\257\274\347\273\204\344\273\266.md" new file mode 100644 index 00000000..75f7dadf --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\226\207\345\255\227\346\217\220\347\244\272\344\270\216\346\274\253\346\270\270\345\274\225\345\257\274\347\273\204\344\273\266.md" @@ -0,0 +1,304 @@ +# 文字提示与漫游引导组件 + + +**本文档引用的文件** +- [tooltip.tsx](file://frontend/antd/tooltip/tooltip.tsx) +- [tour.tsx](file://frontend/antd/tour/tour.tsx) +- [context.ts](file://frontend/antd/tour/context.ts) +- [Index.svelte（Tour）](file://frontend/antd/tour/Index.svelte) +- [Index.svelte（Tour Step）](file://frontend/antd/tour/step/Index.svelte) +- [tour.step.tsx](file://frontend/antd/tour/step/tour.step.tsx) +- [README.md（Tooltip 文档）](file://docs/components/antd/tooltip/README.md) +- [README.md（Tour 文档）](file://docs/components/antd/tour/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向“文字提示（Tooltip）”和“漫游式引导（Tour）”两个 Ant Design 组件在本仓库中的封装与使用，重点覆盖以下方面： + +- 文字提示：触发方式、位置偏移、延迟显示、多行文本支持、嵌套使用、HTML 内容支持、无障碍访问优化 +- 漫游引导：步骤（step）配置、路径规划、焦点区域、用户交互控制、条件判断、用户偏好记忆、引导流程自定义 + +## 项目结构 + +本项目采用 Svelte + React 预处理（svelte-preprocess-react）的方式，将 Ant Design 的 React 组件以 Svelte 组件形式暴露给前端生态。Tooltip 和 Tour 的封装均位于 frontend/antd 下，Tour 的 Step 子组件位于 frontend/antd/tour/step。 + +```mermaid +graph TB +subgraph "Ant Design 封装层" +T["Tooltip
tooltip.tsx"] +TR["Tour
tour.tsx"] +TS["Tour Step
step/tour.step.tsx"] +end +subgraph "Svelte 包装层" +TI["Tour 包装
tour/Index.svelte"] +TSI["Tour Step 包装
step/Index.svelte"] +end +subgraph "上下文与工具" +CTX["Items 上下文
tour/context.ts"] +U1["useFunction 钩子"] +U2["renderItems / renderParamsSlot 工具"] +end +T --> |"调用 Antd Tooltip"| T +TR --> |"调用 Antd Tour"| TR +TR --> CTX +TR --> U1 +TR --> U2 +TI --> TR +TSI --> TS +``` + +图表来源 + +- [tooltip.tsx:1-29](file://frontend/antd/tooltip/tooltip.tsx#L1-L29) +- [tour.tsx:1-87](file://frontend/antd/tour/tour.tsx#L1-L87) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) +- [Index.svelte（Tour）:1-60](file://frontend/antd/tour/Index.svelte#L1-L60) +- [Index.svelte（Tour Step）:1-82](file://frontend/antd/tour/step/Index.svelte#L1-L82) +- [tour.step.tsx:1-14](file://frontend/antd/tour/step/tour.step.tsx#L1-L14) + +章节来源 + +- [tooltip.tsx:1-29](file://frontend/antd/tooltip/tooltip.tsx#L1-L29) +- [tour.tsx:1-87](file://frontend/antd/tour/tour.tsx#L1-L87) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) +- [Index.svelte（Tour）:1-60](file://frontend/antd/tour/Index.svelte#L1-L60) +- [Index.svelte（Tour Step）:1-82](file://frontend/antd/tour/step/Index.svelte#L1-L82) +- [tour.step.tsx:1-14](file://frontend/antd/tour/step/tour.step.tsx#L1-L14) + +## 核心组件 + +- Tooltip：对 Ant Design Tooltip 的轻量封装，保留 title 属性与插槽化标题渲染能力，并通过 useFunction 将回调函数安全注入 React 组件。 +- Tour：对 Ant Design Tour 的增强封装，支持通过插槽注入 steps、关闭图标、指示器与操作区，内部使用 Items 上下文与渲染工具解析步骤列表，同时提供 onChange/onClose 回调桥接。 + +章节来源 + +- [tooltip.tsx:7-26](file://frontend/antd/tooltip/tooltip.tsx#L7-L26) +- [tour.tsx:11-84](file://frontend/antd/tour/tour.tsx#L11-L84) + +## 架构总览 + +下图展示 Tooltip 与 Tour 在本仓库中的调用链路与数据流： + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant SvelteUI as "Svelte 组件包装层" +participant TourComp as "Tour 组件" +participant TourStep as "Tour Step 组件" +participant Ctx as "Items 上下文" +participant Antd as "Ant Design Tour/Tooltip" +Dev->>SvelteUI : 渲染 Tour 或 Tooltip +SvelteUI->>TourComp : 传递属性与插槽 +TourComp->>Ctx : 读取 steps/default 插槽项 +TourComp->>Antd : 渲染 Tour 并传入 steps、回调 +TourComp->>TourStep : 逐个渲染步骤项 +TourStep->>Antd : 渲染单步 TourStep +Dev->>TourComp : 触发 onChange/onClose +TourComp-->>Dev : 回调通知 +``` + +图表来源 + +- [tour.tsx:17-83](file://frontend/antd/tour/tour.tsx#L17-L83) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) +- [Index.svelte（Tour）:46-59](file://frontend/antd/tour/Index.svelte#L46-L59) +- [Index.svelte（Tour Step）:61-81](file://frontend/antd/tour/step/Index.svelte#L61-L81) +- [tour.step.tsx:7-11](file://frontend/antd/tour/step/tour.step.tsx#L7-L11) + +## 详细组件分析 + +### 文字提示（Tooltip） + +- 触发方式 + - 支持标准的鼠标悬停触发；通过 Ant Design Tooltip 原生行为实现。 + - 可通过插槽化标题实现动态内容渲染，便于在标题中嵌入 HTML 结构或复杂组件。 +- 位置偏移 + - 通过 Ant Design Tooltip 的原生偏移参数进行微调，满足不同布局需求。 +- 延迟显示 + - 使用 Ant Design Tooltip 的延迟参数，避免频繁触发导致的闪烁或误触。 +- 多行文本支持 + - 通过插槽化标题与 Ant Design Tooltip 的换行机制，天然支持多行文本与富文本。 +- 嵌套使用 + - 可在 Tooltip 内部再包裹其他可交互元素（如按钮、链接），实现复合交互。 +- HTML 内容支持 + - 通过插槽将 React 节点注入 title，从而在 Tooltip 中渲染 HTML 片段。 +- 无障碍访问优化 + - 保持原生语义标签与键盘可达性；确保标题内容具备可读性与可理解性。 + +```mermaid +flowchart TD +Start(["进入 Tooltip 渲染"]) --> CheckSlot["检查是否存在 title 插槽"] +CheckSlot --> |是| RenderSlot["渲染插槽内容为标题"] +CheckSlot --> |否| UseProp["使用 title 属性作为标题"] +RenderSlot --> PassProps["透传到 Antd Tooltip"] +UseProp --> PassProps +PassProps --> End(["完成渲染"]) +``` + +图表来源 + +- [tooltip.tsx:17-19](file://frontend/antd/tooltip/tooltip.tsx#L17-L19) + +章节来源 + +- [tooltip.tsx:7-26](file://frontend/antd/tooltip/tooltip.tsx#L7-L26) + +### 漫游式引导（Tour） + +- 步骤（step）配置 + - 支持直接传入 steps 数组，或通过插槽注入 steps/default 项，内部统一由渲染工具解析为 Ant Design Tour 所需的步骤格式。 +- 路径规划 + - 通过 Ant Design Tour 的内置导航逻辑实现步骤跳转；可通过 onChange 获取当前步骤索引，结合业务逻辑实现条件判断与路径变更。 +- 焦点区域 + - 每个步骤可绑定目标元素选择器或函数，用于定位焦点区域；支持动态计算目标元素。 +- 用户交互控制 + - 提供 closeIcon、indicatorsRender、actionsRender 插槽，允许自定义关闭图标、指示器与操作区。 + - 通过 onClose 回调在关闭时执行清理或记录用户偏好。 +- 条件判断 + - 在 onChange 中根据当前步骤与业务状态决定是否允许下一步、是否跳过某些步骤。 +- 用户偏好记忆 + - 在 onClose 中持久化用户偏好（例如“不再显示”），并在下次初始化 Tour 时根据偏好决定是否展示。 +- 引导流程自定义 + - 通过插槽与回调组合，实现自定义的引导文案、样式与交互行为。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Tour as "Tour 组件" +participant Steps as "Steps 列表" +participant Ctx as "Items 上下文" +participant Antd as "Antd Tour" +Dev->>Tour : 传入 steps 或插槽项 +Tour->>Ctx : 读取 steps/default +Tour->>Steps : 使用渲染工具解析为 Antd 步骤 +Tour->>Antd : 渲染 Tour 并传入步骤列表 +Dev->>Tour : 触发 onChange/onClose +Tour-->>Dev : 返回当前步骤索引/关闭事件 +``` + +图表来源 + +- [tour.tsx:33-48](file://frontend/antd/tour/tour.tsx#L33-L48) +- [tour.tsx:49-78](file://frontend/antd/tour/tour.tsx#L49-L78) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) + +章节来源 + +- [tour.tsx:11-84](file://frontend/antd/tour/tour.tsx#L11-L84) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) + +#### Tour Step 组件 + +- 作用 + - 作为单个步骤的容器，负责将外部传入的属性与插槽映射到 Ant Design TourStep。 +- 关键点 + - 支持 target 函数或选择器，用于定位焦点区域。 + - 支持 next_button_click/prev_button_click 等交互属性的桥接。 + - 通过 ItemHandler 接入 Items 上下文，实现步骤项的注册与管理。 + +```mermaid +classDiagram +class TourStep { ++props : TourStepProps ++target : string|function ++itemIndex : number ++slots : object +} +class ItemHandler { ++register(item) ++unregister(id) +} +TourStep --> ItemHandler : "注册/管理步骤项" +``` + +图表来源 + +- [tour.step.tsx:7-11](file://frontend/antd/tour/step/tour.step.tsx#L7-L11) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) + +章节来源 + +- [Index.svelte（Tour Step）:1-82](file://frontend/antd/tour/step/Index.svelte#L1-L82) +- [tour.step.tsx:1-14](file://frontend/antd/tour/step/tour.step.tsx#L1-L14) + +## 依赖关系分析 + +- Tooltip 依赖 Ant Design Tooltip，通过 sveltify 适配 React 组件到 Svelte。 +- Tour 依赖 Ant Design Tour，同时引入 Items 上下文与渲染工具，实现插槽到步骤数组的转换。 +- Svelte 包装层负责属性与插槽的透传、类名与可见性控制，以及异步加载底层组件。 + +```mermaid +graph LR +A["tooltip.tsx"] --> AD1["Antd Tooltip"] +B["tour.tsx"] --> AD2["Antd Tour"] +B --> C["context.ts"] +D["tour/Index.svelte"] --> B +E["step/Index.svelte"] --> F["step/tour.step.tsx"] +``` + +图表来源 + +- [tooltip.tsx:1-29](file://frontend/antd/tooltip/tooltip.tsx#L1-L29) +- [tour.tsx:1-87](file://frontend/antd/tour/tour.tsx#L1-L87) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) +- [Index.svelte（Tour）:1-60](file://frontend/antd/tour/Index.svelte#L1-L60) +- [Index.svelte（Tour Step）:1-82](file://frontend/antd/tour/step/Index.svelte#L1-L82) +- [tour.step.tsx:1-14](file://frontend/antd/tour/step/tour.step.tsx#L1-L14) + +章节来源 + +- [tooltip.tsx:1-29](file://frontend/antd/tooltip/tooltip.tsx#L1-L29) +- [tour.tsx:1-87](file://frontend/antd/tour/tour.tsx#L1-L87) +- [context.ts:1-7](file://frontend/antd/tour/context.ts#L1-L7) +- [Index.svelte（Tour）:1-60](file://frontend/antd/tour/Index.svelte#L1-L60) +- [Index.svelte（Tour Step）:1-82](file://frontend/antd/tour/step/Index.svelte#L1-L82) +- [tour.step.tsx:1-14](file://frontend/antd/tour/step/tour.step.tsx#L1-L14) + +## 性能考虑 + +- 使用 useMemo 缓存步骤数组，避免不必要的重渲染。 +- 仅在可见时渲染 Tour 与 Step，减少 DOM 开销。 +- 合理使用插槽与动态渲染，避免一次性渲染过多复杂节点。 +- 在 onChange/onClose 中尽量避免重型同步操作，必要时使用异步处理。 + +## 故障排查指南 + +- 标题不显示或为空 + - 检查是否正确传入 title 或使用了 title 插槽；确认插槽内容已被正确渲染。 +- 步骤未生效 + - 确认 steps 或插槽项已正确注入；检查 Items 上下文是否被正确提供。 +- 目标元素无法聚焦 + - 检查 target 选择器或函数返回值；确保元素在页面中已渲染且可访问。 +- 回调未触发 + - 确认 onChange/onClose 是否被正确传入；检查 useFunction 是否正确包裹回调。 + +章节来源 + +- [tour.tsx:33-48](file://frontend/antd/tour/tour.tsx#L33-L48) +- [tour.tsx:49-78](file://frontend/antd/tour/tour.tsx#L49-L78) +- [Index.svelte（Tour）:46-59](file://frontend/antd/tour/Index.svelte#L46-L59) +- [Index.svelte（Tour Step）:69-73](file://frontend/antd/tour/step/Index.svelte#L69-L73) + +## 结论 + +本仓库对 Tooltip 与 Tour 的封装遵循“轻量、可扩展、易集成”的原则：在保留 Ant Design 原生能力的同时，通过插槽与上下文机制增强了步骤配置、交互定制与渲染灵活性。建议在实际使用中结合业务场景合理设置步骤路径、目标区域与用户偏好，以获得更佳的用户体验。 + +## 附录 + +- 示例与文档入口 + - Tooltip 文档示例入口：[Tooltip 文档:1-8](file://docs/components/antd/tooltip/README.md#L1-L8) + - Tour 文档示例入口：[Tour 文档:1-8](file://docs/components/antd/tour/README.md#L1-L8) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\227\245\345\216\206\344\270\216\345\215\241\347\211\207\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\227\245\345\216\206\344\270\216\345\215\241\347\211\207\347\273\204\344\273\266.md" new file mode 100644 index 00000000..ea32b9ca --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\227\245\345\216\206\344\270\216\345\215\241\347\211\207\347\273\204\344\273\266.md" @@ -0,0 +1,358 @@ +# 日历与卡片组件 + + +**本文档引用的文件** +- [frontend/antd/calendar/Index.svelte](file://frontend/antd/calendar/Index.svelte) +- [frontend/antd/calendar/calendar.tsx](file://frontend/antd/calendar/calendar.tsx) +- [frontend/antd/card/Index.svelte](file://frontend/antd/card/Index.svelte) +- [frontend/antd/card/card.tsx](file://frontend/antd/card/card.tsx) +- [frontend/antd/card/grid/Index.svelte](file://frontend/antd/card/grid/Index.svelte) +- [frontend/antd/card/grid/card.grid.tsx](file://frontend/antd/card/grid/card.grid.tsx) +- [frontend/antd/card/meta/Index.svelte](file://frontend/antd/card/meta/Index.svelte) +- [frontend/antd/card/meta/card.meta.tsx](file://frontend/antd/card/meta/card.meta.tsx) +- [frontend/antd/grid/col/col.tsx](file://frontend/antd/grid/col/col.tsx) +- [frontend/antd/grid/row/row.tsx](file://frontend/antd/grid/row/row.tsx) +- [frontend/antd/grid/context.ts](file://frontend/antd/grid/context.ts) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) + +## 简介 + +本文件面向日历（Calendar）与卡片（Card）组件，提供从架构到实现细节的完整说明。重点涵盖： + +- 日历组件：日程安排、事件标记、日期选择、面板切换、通知日历的特殊功能（通过插槽与回调扩展） +- 卡片组件：基础结构、卡片网格（Card.Grid）的响应式布局、卡片元数据（Card.Meta）的内容组织、自定义卡片内容的实现方法 +- 本地化配置：基于 ConfigProvider 的多语言支持与日期本地化 +- 交互与回调：事件回调处理、值变更传播 +- 适配性：不同屏幕尺寸下的适配策略与动态更新机制 + +## 项目结构 + +日历与卡片组件位于前端 Ant Design 生态中，采用 Svelte + React 包装器（sveltify）的方式桥接 Svelte 组件与 Ant Design 的 React 实现。每个组件均提供： + +- Svelte 入口文件（Index.svelte）：负责属性透传、可见性控制、插槽收集与异步加载 React 实现 +- React 包装器（\*.tsx）：使用 sveltify 将 Ant Design 组件包装为可被 Svelte 使用的形式，并处理函数型回调、插槽渲染与值格式化 + +```mermaid +graph TB +subgraph "日历组件" +C_Index["calendar/Index.svelte"] +C_Tsx["calendar/calendar.tsx"] +end +subgraph "卡片组件" +K_Index["card/Index.svelte"] +K_Tsx["card/card.tsx"] +end +subgraph "卡片子组件" +G_Index["card/grid/Index.svelte"] +G_Tsx["card/grid/card.grid.tsx"] +M_Index["card/meta/Index.svelte"] +M_Tsx["card/meta/card.meta.tsx"] +end +subgraph "栅格系统" +R_Tsx["grid/row/row.tsx"] +C_Tsx2["grid/col/col.tsx"] +Ctx["grid/context.ts"] +end +subgraph "本地化" +CP_Tsx["config-provider/config-provider.tsx"] +Locales["config-provider/locales.ts"] +end +C_Index --> C_Tsx +K_Index --> K_Tsx +G_Index --> G_Tsx +M_Index --> M_Tsx +R_Tsx --> C_Tsx2 +Ctx --> R_Tsx +CP_Tsx --> Locales +``` + +**图表来源** + +- [frontend/antd/calendar/Index.svelte:1-85](file://frontend/antd/calendar/Index.svelte#L1-L85) +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [frontend/antd/card/Index.svelte:1-68](file://frontend/antd/card/Index.svelte#L1-L68) +- [frontend/antd/card/card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) +- [frontend/antd/card/grid/Index.svelte:1-63](file://frontend/antd/card/grid/Index.svelte#L1-L63) +- [frontend/antd/card/grid/card.grid.tsx:1-7](file://frontend/antd/card/grid/card.grid.tsx#L1-L7) +- [frontend/antd/card/meta/Index.svelte:1-60](file://frontend/antd/card/meta/Index.svelte#L1-L60) +- [frontend/antd/card/meta/card.meta.tsx:1-32](file://frontend/antd/card/meta/card.meta.tsx#L1-L32) +- [frontend/antd/grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [frontend/antd/grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts:1-800](file://frontend/antd/config-provider/locales.ts#L1-L800) + +**章节来源** + +- [frontend/antd/calendar/Index.svelte:1-85](file://frontend/antd/calendar/Index.svelte#L1-L85) +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [frontend/antd/card/Index.svelte:1-68](file://frontend/antd/card/Index.svelte#L1-L68) +- [frontend/antd/card/card.tsx:1-150](file://frontend/antd/card/card.tsx#L1-L150) +- [frontend/antd/card/grid/Index.svelte:1-63](file://frontend/antd/card/grid/Index.svelte#L1-L63) +- [frontend/antd/card/grid/card.grid.tsx:1-7](file://frontend/antd/card/grid/card.grid.tsx#L1-L7) +- [frontend/antd/card/meta/Index.svelte:1-60](file://frontend/antd/card/meta/Index.svelte#L1-L60) +- [frontend/antd/card/meta/card.meta.tsx:1-32](file://frontend/antd/card/meta/card.meta.tsx#L1-L32) +- [frontend/antd/grid/row/row.tsx:1-34](file://frontend/antd/grid/row/row.tsx#L1-L34) +- [frontend/antd/grid/col/col.tsx:1-14](file://frontend/antd/grid/col/col.tsx#L1-L14) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts:1-800](file://frontend/antd/config-provider/locales.ts#L1-L800) + +## 核心组件 + +- 日历（Calendar） + - 支持日期值格式化（秒级时间戳与 dayjs 转换）、禁用日期过滤、单元格渲染插槽（cellRender/fullCellRender/headerRender）、面板切换与选择事件回调 + - 值变更通过 onValueChange 向上层同步，便于 Gradio 等框架集成 +- 卡片（Card） + - 提供标题、额外内容、封面图、操作区等区域的插槽化渲染；支持标签页列表与标签栏扩展（tabProps.\* 插槽） + - 内部通过上下文收集子项，动态组合为 Ant Design 的 Card 组件 +- 卡片网格（Card.Grid） + - 作为卡片内部的网格容器，用于承载子内容并参与响应式布局 +- 卡片元数据（Card.Meta） + - 对标题、描述、头像进行插槽化渲染，便于灵活定制卡片元信息 +- 栅格系统（Row/Col） + - 通过上下文收集列项，将子节点映射为 Ant Design 的 Row/Col 结构，实现响应式布局 + +**章节来源** + +- [frontend/antd/calendar/calendar.tsx:10-15](file://frontend/antd/calendar/calendar.tsx#L10-L15) +- [frontend/antd/calendar/calendar.tsx:58-98](file://frontend/antd/calendar/calendar.tsx#L58-L98) +- [frontend/antd/card/card.tsx:36-146](file://frontend/antd/card/card.tsx#L36-L146) +- [frontend/antd/card/grid/card.grid.tsx:1-7](file://frontend/antd/card/grid/card.grid.tsx#L1-L7) +- [frontend/antd/card/meta/card.meta.tsx:5-29](file://frontend/antd/card/meta/card.meta.tsx#L5-L29) +- [frontend/antd/grid/row/row.tsx:7-31](file://frontend/antd/grid/row/row.tsx#L7-L31) +- [frontend/antd/grid/col/col.tsx:7-11](file://frontend/antd/grid/col/col.tsx#L7-L11) + +## 架构总览 + +下图展示了日历与卡片组件在 Svelte 与 Ant Design 之间的桥接关系，以及插槽与回调的关键流转。 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 组件
Index.svelte" +participant Wrapper as "React 包装器
sveltify" +participant Antd as "Ant Design 组件" +participant Util as "工具函数
useFunction/renderParamsSlot" +Svelte->>Wrapper : 透传属性/可见性/插槽 +Wrapper->>Util : useFunction 包装回调 +Wrapper->>Util : renderParamsSlot 渲染插槽 +Wrapper->>Antd : 渲染 Antd 组件并传递 props +Antd-->>Wrapper : 回调触发onChange/onPanelChange/onSelect +Wrapper-->>Svelte : onValueChange 同步值 +``` + +**图表来源** + +- [frontend/antd/calendar/Index.svelte:65-84](file://frontend/antd/calendar/Index.svelte#L65-L84) +- [frontend/antd/calendar/calendar.tsx:43-98](file://frontend/antd/calendar/calendar.tsx#L43-L98) +- [frontend/antd/card/Index.svelte:53-67](file://frontend/antd/card/Index.svelte#L53-L67) +- [frontend/antd/card/card.tsx:39-146](file://frontend/antd/card/card.tsx#L39-L146) + +## 详细组件分析 + +### 日历组件（Calendar） + +- 属性与回调 + - 输入值与默认值：支持秒级时间戳与 dayjs 对象，内部统一转换为 dayjs + - 有效范围：validRange 同样进行格式化处理 + - 回调：onChange/onPanelChange/onSelect 会将日期转换为秒级时间戳后返回 + - 插槽：cellRender/fullCellRender/headerRender 可通过 slots 注入自定义渲染 +- 事件标记与通知日历 + - 通过 cellRender/fullCellRender 插槽注入自定义标记或徽章 + - onPanelChange 可用于监听月份/年份切换，结合业务逻辑实现“通知日历”场景（如高亮特定日期） +- 日期选择与值同步 + - onValueChange 将当前选中日期以秒级时间戳回传给上层，便于状态管理与持久化 + +```mermaid +flowchart TD +Start(["进入日历组件"]) --> ParseValue["解析输入值
秒级时间戳 -> dayjs"] +ParseValue --> ParseRange["解析有效范围
数组 -> dayjs[]"] +ParseRange --> RenderCalendar["渲染 Antd Calendar"] +RenderCalendar --> OnChange{"用户选择日期?"} +OnChange --> |是| ConvertSec["日期转秒级时间戳"] +ConvertSec --> CallCb["触发 onChange/onSelect"] +CallCb --> OnValueChange["触发 onValueChange 同步值"] +OnValueChange --> End(["完成"]) +OnChange --> |否| End +``` + +**图表来源** + +- [frontend/antd/calendar/calendar.tsx:47-98](file://frontend/antd/calendar/calendar.tsx#L47-L98) + +**章节来源** + +- [frontend/antd/calendar/Index.svelte:13-84](file://frontend/antd/calendar/Index.svelte#L13-L84) +- [frontend/antd/calendar/calendar.tsx:10-15](file://frontend/antd/calendar/calendar.tsx#L10-L15) +- [frontend/antd/calendar/calendar.tsx:47-98](file://frontend/antd/calendar/calendar.tsx#L47-L98) + +### 卡片组件（Card） + +- 基础结构 + - 标题、额外内容、封面图、操作区均可通过插槽注入 + - 支持标签页列表 tabList 与标签栏扩展（tabProps.\* 插槽），包括指示器大小、更多菜单、左右附加内容等 +- 动态内容与上下文 + - 通过 useTabsItems 与 useTargets 收集子项，将 tabList 与 actions 动态注入 + - 当存在 Grid 子项时，通过 containsGrid 控制隐藏占位网格，确保布局正确 +- 自定义内容实现 + - 使用 ReactSlot 渲染插槽内容，支持复杂嵌套与条件渲染 + - actions 区域优先使用收集到的目标，其次回退到原生 props.actions + +```mermaid +classDiagram +class CardWrapper { ++props : AntdCardProps ++slots : Record
frontend/antd/tag/tag.tsx"] +CTAG["CheckableTag
frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx"] +CTAG_IDX["CheckableTag 包装
frontend/antd/tag/checkable-tag/Index.svelte"] +CTAG_GROUP["CheckableTagGroup
frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx"] +CTAG_GROUP_IDX["CheckableTagGroup 包装
frontend/antd/tag/checkable-tag-group/Index.svelte"] +CTAG_OPTION["CheckableTagGroupOption
frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx"] +CTAG_OPTION_IDX["CheckableTagGroupOption 包装
frontend/antd/tag/checkable-tag-group/option/Index.svelte"] +end +subgraph "时间轴组件" +TL["Timeline
frontend/antd/timeline/timeline.tsx"] +TL_ITEM["Timeline.Item
frontend/antd/timeline/item/Index.svelte"] +TL_CTX["Timeline 上下文
frontend/antd/timeline/context.ts"] +end +subgraph "工具库" +CREATE_ITEMS["createItemsContext
frontend/utils/createItemsContext.tsx"] +RENDER_ITEMS["renderItems
frontend/utils/renderItems.tsx"] +USE_TARGETS["useTargets
frontend/utils/hooks/useTargets.ts"] +end +TAG --> USE_TARGETS +CTAG --> USE_TARGETS +CTAG_GROUP --> CTAG_GROUP_IDX +CTAG_GROUP_IDX --> CTAG_GROUP +CTAG_OPTION --> CTAG_OPTION_IDX +CTAG_OPTION_IDX --> CTAG_OPTION +TL --> TL_CTX +TL_CTX --> CREATE_ITEMS +TL --> RENDER_ITEMS +TL_ITEM --> TL_CTX +``` + +**图表来源** + +- [frontend/antd/tag/tag.tsx:1-35](file://frontend/antd/tag/tag.tsx#L1-L35) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:1-35](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L1-L35) +- [frontend/antd/tag/checkable-tag/Index.svelte:1-77](file://frontend/antd/tag/checkable-tag/Index.svelte#L1-L77) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:1-51](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L1-L51) +- [frontend/antd/tag/checkable-tag-group/Index.svelte:1-79](file://frontend/antd/tag/checkable-tag-group/Index.svelte#L1-L79) +- [frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx:1-14](file://frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx#L1-L14) +- [frontend/antd/tag/checkable-tag-group/option/Index.svelte:1-74](file://frontend/antd/tag/checkable-tag-group/option/Index.svelte#L1-L74) +- [frontend/antd/timeline/timeline.tsx:1-50](file://frontend/antd/timeline/timeline.tsx#L1-L50) +- [frontend/antd/timeline/item/Index.svelte:1-65](file://frontend/antd/timeline/item/Index.svelte#L1-L65) +- [frontend/antd/timeline/context.ts:1-7](file://frontend/antd/timeline/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/hooks/useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) + +**章节来源** + +- [frontend/antd/tag/tag.tsx:1-35](file://frontend/antd/tag/tag.tsx#L1-L35) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:1-35](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L1-L35) +- [frontend/antd/tag/checkable-tag/Index.svelte:1-77](file://frontend/antd/tag/checkable-tag/Index.svelte#L1-L77) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:1-51](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L1-L51) +- [frontend/antd/tag/checkable-tag-group/Index.svelte:1-79](file://frontend/antd/tag/checkable-tag-group/Index.svelte#L1-L79) +- [frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx:1-14](file://frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx#L1-L14) +- [frontend/antd/tag/checkable-tag-group/option/Index.svelte:1-74](file://frontend/antd/tag/checkable-tag-group/option/Index.svelte#L1-L74) +- [frontend/antd/timeline/timeline.tsx:1-50](file://frontend/antd/timeline/timeline.tsx#L1-L50) +- [frontend/antd/timeline/item/Index.svelte:1-65](file://frontend/antd/timeline/item/Index.svelte#L1-L65) +- [frontend/antd/timeline/context.ts:1-7](file://frontend/antd/timeline/context.ts#L1-L7) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/hooks/useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) + +## 核心组件 + +- 标签(Tag) + - 普通标签：支持文本与图标、关闭图标插槽、值字段回退渲染。 + - 可选择标签(CheckableTag)：双向绑定选中状态，支持 label 文本回退、图标插槽、变更回调。 + - **新增**：可勾选标签组(CheckableTagGroup)：支持批量标签选择、动态选项管理、分组操作。 +- 时间轴(Timeline) + - 支持 items 动态注入与默认插槽回退；支持 pending/pendingDot 插槽；内部通过 Items 上下文收集子项并渲染。 + +**章节来源** + +- [frontend/antd/tag/tag.tsx:7-32](file://frontend/antd/tag/tag.tsx#L7-L32) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:7-32](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L7-L32) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:8-48](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L8-L48) +- [frontend/antd/timeline/timeline.tsx:9-47](file://frontend/antd/timeline/timeline.tsx#L9-L47) + +## 架构总览 + +标签与时间轴均通过 sveltify 将 Ant Design 的 React 组件桥接到 Svelte 生态，同时利用插槽与上下文实现灵活的动态渲染与属性透传。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Svelte as "Svelte 包装层" +participant Utils as "工具库" +participant Antd as "Ant Design 组件" +Dev->>Svelte : 传入 props 与 slots +Svelte->>Utils : 解析插槽/目标元素/上下文 +Utils-->>Svelte : 返回处理后的 props 与渲染函数 +Svelte->>Antd : 渲染最终组件树 +Antd-->>Dev : 输出 UI 结果 +``` + +**图表来源** + +- [frontend/antd/tag/tag.tsx:12-32](file://frontend/antd/tag/tag.tsx#L12-L32) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:13-32](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L13-L32) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:14-46](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L14-L46) +- [frontend/antd/timeline/timeline.tsx:15-46](file://frontend/antd/timeline/timeline.tsx#L15-L46) + +## 详细组件分析 + +### 标签组件（Tag） + +- 普通标签 + - 关键点：支持 icon/closeIcon 插槽；当存在目标子节点时优先渲染子节点，否则回退到 children + value。 + - 适用场景：分类标记、状态徽标、可关闭的临时标签。 +- 可选择标签（CheckableTag） + - 关键点：支持 checked/value 属性与 onValueChange 回调；支持 label 文本回退；onChange 链式触发。 + - 适用场景：多选筛选、偏好设置、分类勾选。 +- **新增**：可勾选标签组（CheckableTagGroup） + - 关键点：支持 options 数组或默认插槽回退；通过 ItemHandler 注入上下文，记录每个子项的 props、slots 与嵌套 children。 + - 适用场景：批量标签选择、分类筛选、多选项分组管理。 + +```mermaid +classDiagram +class Tag { ++props : 所有 Ant Design Tag 支持的属性 ++slots : icon, closeIcon ++value? : string +} +class CheckableTag { ++props : Ant Design Tag.CheckableTag 属性 ++slots : icon ++onValueChange(checked) ++label? : string +} +class CheckableTagGroup { ++props : Ant Design Tag.CheckableTagGroup 属性 ++slots : options, default ++onValueChange(value) ++options? : array +} +class CheckableTagGroupOption { ++props : 单个标签选项属性 ++slots : default ++itemIndex : number ++itemSlotKey : string +} +Tag --> "使用" useTargets +CheckableTag --> "使用" useTargets +CheckableTagGroup --> "使用" createItemsContext +CheckableTagGroupOption --> "使用" ItemHandler +``` + +**图表来源** + +- [frontend/antd/tag/tag.tsx:7-32](file://frontend/antd/tag/tag.tsx#L7-L32) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:7-32](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L7-L32) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:8-48](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L8-L48) +- [frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx:7-13](file://frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx#L7-L13) +- [frontend/utils/hooks/useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [frontend/antd/tag/checkable-tag-group/context.ts:3-4](file://frontend/antd/tag/checkable-tag-group/context.ts#L3-L4) + +**章节来源** + +- [frontend/antd/tag/tag.tsx:7-32](file://frontend/antd/tag/tag.tsx#L7-L32) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:7-32](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L7-L32) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:8-48](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L8-L48) +- [frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx:7-13](file://frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx#L7-L13) +- [frontend/utils/hooks/useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [frontend/antd/tag/checkable-tag-group/context.ts:3-4](file://frontend/antd/tag/checkable-tag-group/context.ts#L3-L4) + +#### 交互与状态 + +- 普通标签 + - 点击事件：由 Antd 原生事件处理；可通过 props 透传 onClick 等。 + - 删除：通过 closeIcon 插槽与 closeIcon 属性组合实现可关闭效果。 +- 可选择标签 + - 选中状态：value/checked 双向绑定；onValueChange 回调用于同步状态。 + - 批量操作：可在上层容器中统一管理多个 CheckableTag 的 value 并批量更新。 +- **新增**：可勾选标签组 + - 选中状态：支持单选和多选模式；onValueChange 返回选中值数组或单个值。 + - 动态选项：通过 options 属性或默认插槽动态添加/删除标签选项。 + - 分组管理：支持嵌套标签组和分组级别的批量操作。 + +**章节来源** + +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:23-26](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L23-L26) +- [frontend/antd/tag/checkable-tag/Index.svelte:69-71](file://frontend/antd/tag/checkable-tag/Index.svelte#L69-L71) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:39-42](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L39-L42) +- [frontend/antd/tag/checkable-tag-group/Index.svelte:71-73](file://frontend/antd/tag/checkable-tag-group/Index.svelte#L71-L73) + +#### 颜色配置与动态管理 + +- 颜色：通过 color 属性支持预设色板与自定义十六进制色值。 +- 动态：结合后端组件桥接与前端 props 透传，可实现运行时动态切换颜色与文案。 +- **新增**：标签组颜色：支持为整个标签组设置统一颜色主题，同时保留单个标签的颜色覆盖。 + +**章节来源** + +- [docs/components/antd/tag/demos/checkable_tag.py:10-15](file://docs/components/antd/tag/demos/checkable_tag.py#L10-L15) + +#### 在搜索结果中的应用 + +- 建议：对搜索结果中的条目添加 Tag 作为分类/状态标识；使用可选择标签实现多维筛选；通过 closeIcon 实现一键移除筛选条件。 +- **新增**：使用可勾选标签组实现高级筛选：支持多维度标签组合筛选、批量操作和筛选条件保存。 + +### 时间轴组件（Timeline） + +- 时间轴主体 + - 支持 items 数组或默认插槽回退；pending/pendingDot 插槽可自定义"进行中"状态。 + - 内部通过 Items 上下文收集子项，再用 renderItems 转换为 Antd 所需的数据结构。 +- **更新**：时间轴项（Timeline.Item） + - **简化实现**：移除了复杂的属性处理逻辑，直接透传所有属性和插槽。 + - 通过 ItemHandler 注入上下文，记录每个子项的 props、slots 与嵌套 children。 + - 支持自定义 dot 插槽以替换时间点图标。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant TL as "Timeline" +participant Ctx as "Items 上下文" +participant Item as "Timeline.Item" +participant Render as "renderItems" +Dev->>TL : 设置 items 或填充默认插槽 +TL->>Ctx : withItemsContextProvider 包裹 +TL->>Item : 渲染子项并注入上下文 +Item->>Ctx : ItemHandler 记录 props/slots/children +TL->>Render : 使用 renderItems 转换为 Antd 数据结构 +Render-->>TL : 返回 items 数组 +TL-->>Dev : 渲染时间轴 +``` + +**图表来源** + +- [frontend/antd/timeline/timeline.tsx:13-46](file://frontend/antd/timeline/timeline.tsx#L13-L46) +- [frontend/antd/timeline/context.ts:3-4](file://frontend/antd/timeline/context.ts#L3-L4) +- [frontend/utils/createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) +- [frontend/utils/renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) +- [frontend/antd/timeline/item/Index.svelte:49-64](file://frontend/antd/timeline/item/Index.svelte#L49-L64) + +**章节来源** + +- [frontend/antd/timeline/timeline.tsx:13-46](file://frontend/antd/timeline/timeline.tsx#L13-L46) +- [frontend/antd/timeline/context.ts:3-4](file://frontend/antd/timeline/context.ts#L3-L4) +- [frontend/utils/createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) +- [frontend/utils/renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) +- [frontend/antd/timeline/item/Index.svelte:49-64](file://frontend/antd/timeline/item/Index.svelte#L49-L64) + +#### 方向控制与样式自定义 + +- 方向控制：通过 mode 属性（如 alternate）控制时间点交替显示。 +- 样式自定义：支持 color 属性为节点着色；通过 dot 插槽自定义时间点图标；pending/pendingDot 插槽自定义"进行中"状态。 + +**章节来源** + +- [docs/components/antd/timeline/demos/basic.py:18-38](file://docs/components/antd/timeline/demos/basic.py#L18-L38) + +#### 反转显示与时间线样式调整 + +- 反转显示：可通过 mode 或外部布局实现逆序展示；若需要完全倒序，可在上层对 items 进行 reverse 处理后再传入。 +- 线条样式：Antd Timeline 默认样式可通过主题变量或覆盖类名进行调整；也可在上层容器中包裹自定义样式。 + +#### 时间点自定义图标 + +- 自定义图标：通过 Timeline.Item 的 dot 插槽注入任意图标组件，实现个性化时间点视觉表达。 + +**章节来源** + +- [docs/components/antd/timeline/demos/basic.py:27-37](file://docs/components/antd/timeline/demos/basic.py#L27-L37) + +#### 在项目进度中的可视化展示 + +- 建议：将里程碑、任务节点、版本发布等事件以 Timeline.Item 表达；使用 color 标注优先级/状态；使用 dot 插槽插入状态图标；使用 pending/pendingDot 插槽突出当前阶段。 + +## 依赖关系分析 + +- 标签组件 + - useTargets：解析子节点中的目标元素，决定是否回退到 children + value。 + - **新增**：createItemsContext：为标签组提供上下文支持，管理选项列表和状态。 +- 时间轴组件 + - createItemsContext：提供 Items 上下文，负责收集与合并子项。 + - renderItems：将上下文中的 Item 结构转换为 Antd 所需的 items 数组。 + - useItems：在 Timeline 中读取已收集的 items 并传递给 Antd Timeline。 + +```mermaid +graph LR +USE_TARGETS["useTargets"] --> TAG["Tag"] +USE_TARGETS --> CTAG["CheckableTag"] +CREATE_ITEMS["createItemsContext"] --> CTAG_GROUP["CheckableTagGroup"] +CREATE_ITEMS --> TL["Timeline"] +TL --> RENDER_ITEMS["renderItems"] +TL --> TL_ITEM["Timeline.Item"] +CTAG_GROUP --> CTAG_OPTION["CheckableTagGroupOption"] +CTAG_OPTION --> CREATE_ITEMS +TL_ITEM --> CREATE_ITEMS +``` + +**图表来源** + +- [frontend/utils/hooks/useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [frontend/antd/tag/tag.tsx:12-32](file://frontend/antd/tag/tag.tsx#L12-L32) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:13-32](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L13-L32) +- [frontend/antd/tag/checkable-tag-group/context.ts:1-7](file://frontend/antd/tag/checkable-tag-group/context.ts#L1-L7) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:6-6](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L6-L6) +- [frontend/antd/timeline/timeline.tsx:7-7](file://frontend/antd/timeline/timeline.tsx#L7-L7) +- [frontend/utils/createItemsContext.tsx:97-106](file://frontend/utils/createItemsContext.tsx#L97-L106) +- [frontend/antd/timeline/item/Index.svelte:13-13](file://frontend/antd/timeline/item/Index.svelte#L13-L13) + +**章节来源** + +- [frontend/utils/hooks/useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [frontend/antd/tag/tag.tsx:12-32](file://frontend/antd/tag/tag.tsx#L12-L32) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:13-32](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L13-L32) +- [frontend/antd/tag/checkable-tag-group/context.ts:1-7](file://frontend/antd/tag/checkable-tag-group/context.ts#L1-L7) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:6-6](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L6-L6) +- [frontend/antd/timeline/timeline.tsx:7-7](file://frontend/antd/timeline/timeline.tsx#L7-L7) +- [frontend/utils/createItemsContext.tsx:97-106](file://frontend/utils/createItemsContext.tsx#L97-L106) +- [frontend/antd/timeline/item/Index.svelte:13-13](file://frontend/antd/timeline/item/Index.svelte#L13-L13) + +## 性能考量 + +- 渲染优化 + - useTargets 对子节点排序与过滤仅在 children 变化时重新计算，避免不必要的重排。 + - renderItems 通过 memoizedEqualValue 与 useMemoizedFn 控制上下文更新频率。 + - **新增**：CheckableTagGroup 通过 clone: true 参数确保选项克隆，避免状态污染。 +- 上下文稳定性 + - withItemsContextProvider 与 useItems 通过 useMemo 与 useRef 保持上下文引用稳定，减少子树重渲染。 + - **新增**：标签组上下文通过 createItemsContext 提供稳定的选项管理。 +- 插槽克隆策略 + - renderItems 支持 clone/forceClone 参数，按需控制节点克隆，平衡性能与作用域隔离。 + +**章节来源** + +- [frontend/utils/hooks/useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [frontend/utils/createItemsContext.tsx:113-156](file://frontend/utils/createItemsContext.tsx#L113-L156) +- [frontend/utils/renderItems.tsx:62-94](file://frontend/utils/renderItems.tsx#L62-L94) +- [frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx:33-36](file://frontend/antd/tag/checkable-tag-group/tag.checkable-tag-group.tsx#L33-L36) + +## 故障排查指南 + +- 标签不显示 value + - 检查 children 是否包含可识别的目标节点；若存在目标节点，将优先渲染子节点而非回退到 value。 + - 参考路径：[frontend/antd/tag/tag.tsx:22-29](file://frontend/antd/tag/tag.tsx#L22-L29) +- CheckableTag 未触发 onValueChange + - 确认是否正确传入 onValueChange；onChange 会先于 onValueChange 触发，确保回调链路完整。 + - 参考路径：[frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:23-26](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L23-L26) +- **新增**：CheckableTagGroup 选项不显示 + - 确认是否正确使用 CheckableTagGroupOption 并通过插槽注入内容；检查标签组上下文是否生效。 + - 参考路径：[frontend/antd/tag/checkable-tag-group/option/Index.svelte:55-73](file://frontend/antd/tag/checkable-tag-group/option/Index.svelte#L55-L73) +- **新增**：标签组值未更新 + - 确认 onValueChange 回调是否正确处理返回值；检查标签组的 value 属性绑定。 + - 参考路径：[frontend/antd/tag/checkable-tag-group/Index.svelte:71-73](file://frontend/antd/tag/checkable-tag-group/Index.svelte#L71-L73) +- Timeline 未显示任何节点 + - 确认是否正确使用 Timeline.Item 并通过插槽注入内容；检查 Items 上下文是否生效。 + - 参考路径：[frontend/antd/timeline/item/Index.svelte:49-64](file://frontend/antd/timeline/item/Index.svelte#L49-L64) +- 自定义 dot 未生效 + - 确保在 Timeline.Item 内部正确声明 dot 插槽；检查 slotKey 与上下文匹配。 + - 参考路径：[frontend/antd/timeline/item/Index.svelte:58-63](file://frontend/antd/timeline/item/Index.svelte#L58-L63) + +**章节来源** + +- [frontend/antd/tag/tag.tsx:22-29](file://frontend/antd/tag/tag.tsx#L22-L29) +- [frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx:23-26](file://frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx#L23-L26) +- [frontend/antd/tag/checkable-tag-group/option/Index.svelte:55-73](file://frontend/antd/tag/checkable-tag-group/option/Index.svelte#L55-L73) +- [frontend/antd/tag/checkable-tag-group/Index.svelte:71-73](file://frontend/antd/tag/checkable-tag-group/Index.svelte#L71-L73) +- [frontend/antd/timeline/item/Index.svelte:49-64](file://frontend/antd/timeline/item/Index.svelte#L49-L64) +- [frontend/antd/timeline/item/Index.svelte:58-63](file://frontend/antd/timeline/item/Index.svelte#L58-L63) + +## 结论 + +- 标签组件通过插槽与目标元素解析实现了灵活的内容回退与图标扩展；CheckableTag 提供了简洁的双向绑定与回调机制，适合多选与筛选场景。 +- **新增**：CheckableTagGroup 通过完整的上下文系统和选项管理，提供了强大的批量标签选择能力，适合复杂的筛选和分组场景。 +- 时间轴组件借助 Items 上下文与 renderItems，将复杂的嵌套结构转换为 Antd 所需的数组形式，具备良好的扩展性与自定义能力。 +- 在实际业务中，可结合后端组件桥接与前端 props 透传，实现动态标签与进度时间轴的联动展示。 + +## 附录 + +- 示例参考 + - 可选择标签示例：[docs/components/antd/tag/demos/checkable_tag.py:1-19](file://docs/components/antd/tag/demos/checkable_tag.py#L1-L19) + - 时间轴基础示例：[docs/components/antd/timeline/demos/basic.py:1-41](file://docs/components/antd/timeline/demos/basic.py#L1-L41) +- **新增**：可勾选标签组示例 + - 标签组基本用法：支持 options 数组和动态选项管理 + - 标签组批量操作：支持多选模式和批量状态管理 + - 标签组嵌套使用：支持在表单和筛选器中集成标签组组件 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\240\221\345\275\242\346\216\247\344\273\266\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\240\221\345\275\242\346\216\247\344\273\266\347\273\204\344\273\266.md" new file mode 100644 index 00000000..631fc8a1 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\240\221\345\275\242\346\216\247\344\273\266\347\273\204\344\273\266.md" @@ -0,0 +1,348 @@ +# 树形控件组件 + + +**本文引用的文件** +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [Index.svelte](file://frontend/antd/tree/Index.svelte) +- [context.ts](file://frontend/antd/tree/context.ts) +- [tree.tree-node.tsx](file://frontend/antd/tree/tree-node/tree.tree-node.tsx) +- [directory-tree/Index.svelte](file://frontend/antd/tree/directory-tree/Index.svelte) +- [folder.tsx](file://frontend/antdx/folder/folder.tsx) +- [context.ts（文件夹上下文）](file://frontend/antdx/folder/context.ts) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件系统性梳理树形控件（Tree）组件的设计与实现，覆盖基础结构、节点展开/收起、目录树（DirectoryTree）的特殊能力、异步加载数据源、选择模式与多选/半选、禁用配置、搜索过滤、节点拖拽、右键菜单、批量操作、虚拟滚动与大数据优化、动态增删改查，以及在文件管理、组织架构与分类体系中的典型应用与性能策略。 + +## 项目结构 + +树形控件由 Svelte 前端包装层与 React 组件桥接层组成，并通过“项上下文”机制支持树节点的声明式嵌套与数据注入。目录树作为树的特化形态，复用同一桥接层并启用目录树组件。 + +```mermaid +graph TB +subgraph "前端包装层" +T_Index["Tree/Index.svelte"] +DT_Index["DirectoryTree/Index.svelte"] +TN_Node["TreeNode/tree.tree-node.tsx"] +end +subgraph "桥接与上下文" +Bridge["Tree/tree.tsx"] +Ctx["Tree/context.ts"] +end +subgraph "外部依赖" +AntD["Ant Design Tree/DirectoryTree"] +end +T_Index --> Bridge +DT_Index --> Bridge +TN_Node --> Ctx +Bridge --> AntD +``` + +图表来源 + +- [Index.svelte:1-80](file://frontend/antd/tree/Index.svelte#L1-L80) +- [directory-tree/Index.svelte:1-83](file://frontend/antd/tree/directory-tree/Index.svelte#L1-L83) +- [tree.tree-node.tsx:1-22](file://frontend/antd/tree/tree-node/tree.tree-node.tsx#L1-L22) +- [tree.tsx:1-150](file://frontend/antd/tree/tree.tsx#L1-L150) +- [context.ts:1-7](file://frontend/antd/tree/context.ts#L1-L7) + +章节来源 + +- [Index.svelte:1-80](file://frontend/antd/tree/Index.svelte#L1-L80) +- [directory-tree/Index.svelte:1-83](file://frontend/antd/tree/directory-tree/Index.svelte#L1-L83) +- [tree.tsx:1-150](file://frontend/antd/tree/tree.tsx#L1-L150) +- [context.ts:1-7](file://frontend/antd/tree/context.ts#L1-L7) + +## 核心组件 + +- Tree 包装器：负责将 Ant Design 的 Tree/DirectoryTree 桥接到 Svelte 生态，支持插槽扩展、事件透传、异步加载、拖拽与标题渲染等。 +- Tree 节点：通过 ItemHandler 将子节点以“default”插槽注入，形成树形嵌套。 +- 目录树：在 Tree 基础上启用目录树模式，提供文件夹风格的交互与行为。 +- 项上下文：统一管理树节点与目录图标等“项”的收集与注入。 + +章节来源 + +- [tree.tsx:14-148](file://frontend/antd/tree/tree.tsx#L14-L148) +- [tree.tree-node.tsx:7-18](file://frontend/antd/tree/tree-node/tree.tree-node.tsx#L7-L18) +- [directory-tree/Index.svelte:65-82](file://frontend/antd/tree/directory-tree/Index.svelte#L65-L82) +- [context.ts:3-4](file://frontend/antd/tree/context.ts#L3-L4) + +## 架构总览 + +下图展示从 Svelte 到 React 的调用链路，以及目录树与普通树的切换逻辑。 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 包装层" +participant Bridge as "Tree 桥接层" +participant AntD as "Ant Design 组件库" +Svelte->>Bridge : 传递属性与插槽 +Bridge->>Bridge : 解析 treeData/插槽/事件 +alt 目录树模式 +Bridge->>AntD : 使用 DirectoryTree +else 普通树模式 +Bridge->>AntD : 使用 Tree +end +AntD-->>Bridge : 渲染结果与回调 +Bridge-->>Svelte : 事件透传/数据回传 +``` + +图表来源 + +- [tree.tsx:52-115](file://frontend/antd/tree/tree.tsx#L52-L115) +- [Index.svelte:67-78](file://frontend/antd/tree/Index.svelte#L67-L78) +- [directory-tree/Index.svelte:66-81](file://frontend/antd/tree/directory-tree/Index.svelte#L66-L81) + +## 详细组件分析 + +### 基础结构与数据模型 + +- 数据源来源 + - 显式 treeData：直接传入 AntD 所需的树节点数组。 + - 插槽 treeData/default：通过项上下文收集子节点，自动转换为 treeData。 +- 关键字段 + - 标识与层级：key/value/title 等用于标识与显示。 + - 展开状态：expandedKeys 控制初始展开；onExpand 回调响应用户操作。 + - 选择与勾选：selectedKeys/checkedKeys 支持单选/多选；半选通过内部算法计算。 + - 禁用：disabled 字段禁用节点交互。 +- 插槽扩展 + - switcherIcon/switcherLoadingIcon：自定义展开/加载图标。 + - showLine.showLeafIcon：自定义连线末端图标。 + - icon：节点图标。 + - draggable.icon/nodeDraggable：拖拽图标与节点级可拖拽开关。 + - titleRender：自定义标题渲染函数。 + +章节来源 + +- [tree.tsx:56-126](file://frontend/antd/tree/tree.tsx#L56-L126) +- [context.ts:3-4](file://frontend/antd/tree/context.ts#L3-L4) + +### 展开/收起与异步加载 + +- 展开/收起 + - 通过 onExpand 获取当前展开集合，结合 treeData 的 children 实现层级展开。 +- 异步加载 + - 通过 loadData/onLoadData 提供懒加载钩子，按需请求子节点数据。 + - 目录树模式下同样支持异步加载，适合大目录场景。 + +```mermaid +flowchart TD +Start(["用户点击展开"]) --> CheckLoaded{"是否已加载子节点？"} +CheckLoaded --> |否| Load["触发 onLoadData/loadData 请求"] +Load --> Update["更新 treeData 子节点"] +CheckLoaded --> |是| Render["直接渲染子节点"] +Update --> Render +Render --> End(["完成"]) +``` + +图表来源 + +- [tree.tsx:114-114](file://frontend/antd/tree/tree.tsx#L114-L114) +- [tree.tsx:137-139](file://frontend/antd/tree/tree.tsx#L137-L139) + +章节来源 + +- [tree.tsx:38-42](file://frontend/antd/tree/tree.tsx#L38-L42) +- [tree.tsx:114-114](file://frontend/antd/tree/tree.tsx#L114-L114) + +### 目录树（DirectoryTree）特殊功能 + +- 模式切换 + - 通过 directory 属性在 Tree 与 DirectoryTree 之间切换。 +- 事件映射 + - dragStart/dragEnter/dragOver/dragLeave/dragEnd：拖拽生命周期事件。 + - rightClick：右键菜单触发。 + - loadData：目录树专用的懒加载钩子。 +- 文件夹风格 + - 更贴合文件系统浏览体验，支持目录层级与图标映射。 + +章节来源 + +- [tree.tsx:52-52](file://frontend/antd/tree/tree.tsx#L52-L52) +- [directory-tree/Index.svelte:18-25](file://frontend/antd/tree/directory-tree/Index.svelte#L18-L25) +- [directory-tree/Index.svelte:50-58](file://frontend/antd/tree/directory-tree/Index.svelte#L50-L58) + +### 选择模式、多选与半选 + +- 单选/多选 + - 通过 selectedKeys/onChange 实现单选或多选。 +- 多选联动 + - 勾选父节点影响子节点；取消勾选影响父节点状态。 +- 半选状态 + - 当子节点部分被勾选时，父节点呈现半选态，用于快速识别部分选择。 +- 禁用节点 + - disabled 字段阻止节点被选择或勾选。 + +章节来源 + +- [tree.tsx:134-142](file://frontend/antd/tree/tree.tsx#L134-L142) + +### 搜索过滤 + +- 过滤函数 + - filterTreeNode 接受节点与输入值，返回布尔决定是否显示。 +- 实践建议 + - 结合展开状态与高亮显示匹配项，提升可发现性。 + +章节来源 + +- [tree.tsx:132-132](file://frontend/antd/tree/tree.tsx#L132-L132) + +### 节点拖拽 + +- 拖拽开关 + - draggable 可为布尔或对象；nodeDraggable 支持节点级可拖拽。 +- 图标定制 + - draggable.icon 自定义拖拽手柄图标。 +- 事件透传 + - dragStart/dragEnd 等事件由底层组件触发，便于业务侧接入。 + +章节来源 + +- [tree.tsx:102-112](file://frontend/antd/tree/tree.tsx#L102-L112) +- [tree.tsx:48-50](file://frontend/antd/tree/tree.tsx#L48-L50) + +### 右键菜单与批量操作 + +- 右键菜单 + - rightClick 事件可用于弹出上下文菜单。 +- 批量操作 + - 结合多选与右键菜单，实现复制、移动、删除等批量动作。 +- 安全性 + - 对禁用节点进行拦截，避免误操作。 + +章节来源 + +- [directory-tree/Index.svelte:23-23](file://frontend/antd/tree/directory-tree/Index.svelte#L23-L23) +- [tree.tsx:134-142](file://frontend/antd/tree/tree.tsx#L134-L142) + +### 动态增删改查 + +- 新增/修改 + - 更新 treeData 或通过受控方式维护 selectedKeys/checkedKeys。 +- 删除 + - 移除对应节点并同步清理选中状态。 +- 查询 + - 通过 filterTreeNode 与搜索输入联动，实现即时筛选。 + +章节来源 + +- [tree.tsx:59-79](file://frontend/antd/tree/tree.tsx#L59-L79) + +### 虚拟滚动与大数据优化 + +- 虚拟滚动 + - 在超大树中启用虚拟滚动可显著降低 DOM 数量，提升渲染性能。 +- 其他优化 + - 懒加载（loadData/onLoadData）仅渲染可见层级。 + - 合理使用 disabled 与隐藏节点减少渲染负担。 + - 避免频繁重算 treeData，尽量使用浅比较与缓存。 + +章节来源 + +- [tree.tsx:114-114](file://frontend/antd/tree/tree.tsx#L114-L114) + +### 应用场景与最佳实践 + +- 文件管理 + - 目录树 + 拖拽 + 右键菜单 + 异步加载，构建类文件浏览器。 +- 组织架构 + - 以部门/团队为节点，支持折叠与搜索，便于导航。 +- 分类体系 + - 多级分类树，结合半选与批量操作，提升编辑效率。 + +章节来源 + +- [directory-tree/Index.svelte:65-82](file://frontend/antd/tree/directory-tree/Index.svelte#L65-L82) +- [tree.tsx:52-52](file://frontend/antd/tree/tree.tsx#L52-L52) + +## 依赖关系分析 + +- 组件耦合 + - Tree/Index.svelte 与 DirectoryTree/Index.svelte 均依赖 Tree 桥接层。 + - Tree 节点通过 ItemHandler 注入到上下文，形成树形嵌套。 +- 外部依赖 + - Ant Design Tree/DirectoryTree 提供核心交互与渲染。 +- 插槽与事件 + - 通过 slots 与事件透传实现高度可定制。 + +```mermaid +graph LR +T_Index["Tree/Index.svelte"] --> Bridge["Tree/tree.tsx"] +DT_Index["DirectoryTree/Index.svelte"] --> Bridge +TN_Node["TreeNode/tree.tree-node.tsx"] --> Ctx["Tree/context.ts"] +Bridge --> AntD["Ant Design Tree/DirectoryTree"] +``` + +图表来源 + +- [Index.svelte:10-10](file://frontend/antd/tree/Index.svelte#L10-L10) +- [directory-tree/Index.svelte:10-10](file://frontend/antd/tree/directory-tree/Index.svelte#L10-L10) +- [tree.tsx:1-11](file://frontend/antd/tree/tree.tsx#L1-L11) +- [tree.tree-node.tsx:5-5](file://frontend/antd/tree/tree-node/tree.tree-node.tsx#L5-L5) +- [context.ts:3-4](file://frontend/antd/tree/context.ts#L3-L4) + +章节来源 + +- [Index.svelte:1-80](file://frontend/antd/tree/Index.svelte#L1-L80) +- [directory-tree/Index.svelte:1-83](file://frontend/antd/tree/directory-tree/Index.svelte#L1-L83) +- [tree.tsx:1-150](file://frontend/antd/tree/tree.tsx#L1-L150) +- [tree.tree-node.tsx:1-22](file://frontend/antd/tree/tree-node/tree.tree-node.tsx#L1-L22) +- [context.ts:1-7](file://frontend/antd/tree/context.ts#L1-L7) + +## 性能考量 + +- 渲染优化 + - 使用虚拟滚动与懒加载，避免一次性渲染大量节点。 +- 数据结构 + - treeData 保持扁平化与稳定引用，减少不必要的重渲染。 +- 事件节流 + - 对高频事件（如拖拽、滚动）进行节流/防抖。 +- 选择与半选 + - 合理使用 checkedKeys 与半选状态，避免逐层递归计算。 + +## 故障排查指南 + +- 无法展开节点 + - 检查是否正确设置 treeData 的 children 或是否实现了异步加载。 +- 拖拽无效 + - 确认 draggable 为对象且包含 nodeDraggable 或 draggable.icon 已正确注入。 +- 右键菜单不出现 + - 确认 rightClick 事件已绑定并在目录树模式下生效。 +- 选择状态异常 + - 检查 selectedKeys/checkedKeys 是否与 treeData 同步更新。 + +章节来源 + +- [tree.tsx:102-112](file://frontend/antd/tree/tree.tsx#L102-L112) +- [tree.tsx:134-142](file://frontend/antd/tree/tree.tsx#L134-L142) +- [directory-tree/Index.svelte:23-23](file://frontend/antd/tree/directory-tree/Index.svelte#L23-L23) + +## 结论 + +该树形控件通过 Svelte 包装层与 React 桥接层的组合，提供了对 Ant Design Tree/DirectoryTree 的完整封装，具备良好的扩展性与可定制性。配合异步加载、虚拟滚动与丰富的交互能力，适用于文件管理、组织架构与分类体系等复杂场景。 + +## 附录 + +- 目录树与文件夹组件的关系 + - 目录树（DirectoryTree）用于树的目录模式；文件夹组件（antdx/folder）提供更丰富的文件系统能力（如图标映射、内容服务），两者可互补使用。 + +章节来源 + +- [directory-tree/Index.svelte:65-82](file://frontend/antd/tree/directory-tree/Index.svelte#L65-L82) +- [folder.tsx:48-86](file://frontend/antdx/folder/folder.tsx#L48-L86) +- [context.ts（文件夹上下文）:3-13](file://frontend/antdx/folder/context.ts#L3-L13) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\260\224\346\263\241\345\215\241\347\211\207\344\270\216\344\272\214\347\273\264\347\240\201\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\260\224\346\263\241\345\215\241\347\211\207\344\270\216\344\272\214\347\273\264\347\240\201\347\273\204\344\273\266.md" new file mode 100644 index 00000000..f6fead1b --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\346\260\224\346\263\241\345\215\241\347\211\207\344\270\216\344\272\214\347\273\264\347\240\201\347\273\204\344\273\266.md" @@ -0,0 +1,332 @@ +# 气泡卡片与二维码组件 + + +**本文档引用的文件** +- [popover.tsx](file://frontend/antd/popover/popover.tsx) +- [Index.svelte（Popover）](file://frontend/antd/popover/Index.svelte) +- [__init__.py（AntdPopover）](file://backend/modelscope_studio/components/antd/popover/__init__.py) +- [README-zh_CN.md（Popover 文档）](file://docs/components/antd/popover/README-zh_CN.md) +- [README.md（Popover 文档）](file://docs/components/antd/popover/README.md) +- [qr-code.tsx](file://frontend/antd/qr-code/qr-code.tsx) +- [Index.svelte（QRCode）](file://frontend/antd/qr-code/Index.svelte) +- [__init__.py（AntdQRCode）](file://backend/modelscope_studio/components/antd/qr_code/__init__.py) +- [README-zh_CN.md（QRCode 文档）](file://docs/components/antd/qr_code/README-zh_CN.md) +- [README.md（QRCode 文档）](file://docs/components/antd/qr_code/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向气泡卡片（Popover）与二维码（QRCode）两个组件，提供从底层实现到上层使用的完整说明。内容覆盖： + +- 气泡卡片：触发方式、位置控制、内容定制、动画联动、嵌套使用、延迟显示、无障碍支持等 +- 二维码：编码内容、尺寸与边距、颜色与背景、错误纠正级别、图标叠加、动态刷新、自定义样式与打印优化 +- 复杂布局定位策略与移动端扫描体验建议 + +## 项目结构 + +这两个组件遵循统一的“后端组件类 + 前端 Svelte 包装 + React 封装”的分层设计： + +- 后端组件类负责参数校验、事件绑定、示例值与渲染开关 +- 前端 Svelte 层负责属性透传、插槽处理、可见性控制 +- React 封装层负责与 Ant Design 组件桥接，并支持插槽与函数回调转换 + +```mermaid +graph TB +subgraph "后端" +BPY["AntdPopover.__init__"] +BQRY["AntdQRCode.__init__"] +end +subgraph "前端 Svelte" +PIdx["Popover/Index.svelte"] +QIdx["QRCode/Index.svelte"] +end +subgraph "React 封装" +PR["Popover/popover.tsx"] +QR["QRCode/qr-code.tsx"] +end +subgraph "Ant Design" +ADPop["antd.Popover"] +ADQR["antd.QRCode"] +end +BPY --> PIdx +BQRY --> QIdx +PIdx --> PR +QIdx --> QR +PR --> ADPop +QR --> ADQR +``` + +图表来源 + +- [**init**.py（AntdPopover）:10-124](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L124) +- [Index.svelte（Popover）:10-72](file://frontend/antd/popover/Index.svelte#L10-L72) +- [popover.tsx:7-34](file://frontend/antd/popover/popover.tsx#L7-L34) +- [**init**.py（AntdQRCode）:10-96](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L10-L96) +- [Index.svelte（QRCode）:10-63](file://frontend/antd/qr-code/Index.svelte#L10-L63) +- [qr-code.tsx:6-20](file://frontend/antd/qr-code/qr-code.tsx#L6-L20) + +章节来源 + +- [**init**.py（AntdPopover）:10-124](file://backend/modelscope_studio/components/antd/popover/__init__.py#L10-L124) +- [Index.svelte（Popover）:10-72](file://frontend/antd/popover/Index.svelte#L10-L72) +- [popover.tsx:7-34](file://frontend/antd/popover/popover.tsx#L7-L34) +- [**init**.py（AntdQRCode）:10-96](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L10-L96) +- [Index.svelte（QRCode）:10-63](file://frontend/antd/qr-code/Index.svelte#L10-L63) +- [qr-code.tsx:6-20](file://frontend/antd/qr-code/qr-code.tsx#L6-L20) + +## 核心组件 + +- 气泡卡片（Popover） + - 支持多种触发方式：悬停、聚焦、点击、右键菜单 + - 支持 12 种方位放置：上下左右及四个角 + - 支持标题与内容插槽，可注入任意内容 + - 支持打开状态变更事件绑定 + - 支持容器挂载点自定义与延迟显示控制 +- 二维码（QRCode） + - 支持 canvas/svg 两种输出类型 + - 支持前景色、背景色、边框、图标叠加、边距 + - 支持 L/M/Q/H 四级错误纠正 + - 支持状态渲染插槽与刷新事件绑定 + +章节来源 + +- [**init**.py（AntdPopover）:43-59](file://backend/modelscope_studio/components/antd/popover/__init__.py#L43-L59) +- [**init**.py（AntdQRCode）:29-40](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L29-L40) + +## 架构总览 + +下图展示从后端组件类到前端 Svelte 包装再到 React 封装与 Ant Design 的调用链路。 + +```mermaid +sequenceDiagram +participant Backend as "后端组件类" +participant Svelte as "Svelte 包装" +participant ReactWrap as "React 封装" +participant AntD as "Ant Design" +Backend->>Svelte : 传递参数与事件 +Svelte->>ReactWrap : 透传属性/插槽/可见性 +ReactWrap->>AntD : 渲染并绑定事件 +AntD-->>ReactWrap : 交互结果/状态变化 +ReactWrap-->>Svelte : 回传回调/状态 +Svelte-->>Backend : 触发事件/更新状态 +``` + +图表来源 + +- [**init**.py（AntdPopover）:14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) +- [Index.svelte（Popover）:24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- [popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) +- [**init**.py（AntdQRCode）:15-19](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L15-L19) +- [Index.svelte（QRCode）:22-45](file://frontend/antd/qr-code/Index.svelte#L22-L45) +- [qr-code.tsx:6-20](file://frontend/antd/qr-code/qr-code.tsx#L6-L20) + +## 详细组件分析 + +### 气泡卡片（Popover）组件 + +- 触发方式 + - 支持 hover/focus/click/contextMenu 及其组合 + - 可通过延迟参数控制进入/离开时延 +- 位置控制 + - 支持 top/left/right/bottom 及九宫格角位 + - 支持溢出自动调整与箭头配置 +- 内容定制 + - 支持 title/content 插槽，可渲染任意内容 + - 支持覆盖层样式与内部样式 +- 动画与事件 + - 提供 open_change 事件用于监听打开状态变化 + - 支持容器挂载点自定义，便于在复杂布局中定位 +- 嵌套使用 + - 通过自定义容器挂载点避免层级遮挡 + - 注意避免多层弹出同时激活导致的焦点问题 +- 延迟显示 + - 使用进入/离开时延参数控制显示节奏 +- 无障碍支持 + - 建议配合 aria-\* 属性与键盘导航 + - 在嵌套场景中注意标签与描述文本的语义化 + +```mermaid +classDiagram +class AntdPopover { ++EVENTS ++SLOTS ++placement ++trigger ++mouse_enter_delay ++mouse_leave_delay ++overlay_style ++overlay_inner_style ++get_popup_container ++open_change +} +class PopoverWrapper { ++slots ++afterOpenChange ++getPopupContainer ++children +} +AntdPopover --> PopoverWrapper : "参数透传" +``` + +图表来源 + +- [**init**.py（AntdPopover）:14-105](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L105) +- [popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) + +章节来源 + +- [**init**.py（AntdPopover）:23-105](file://backend/modelscope_studio/components/antd/popover/__init__.py#L23-L105) +- [Index.svelte（Popover）:24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- [popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) +- [README-zh_CN.md（Popover 文档）:1-8](file://docs/components/antd/popover/README-zh_CN.md#L1-L8) +- [README.md（Popover 文档）:1-8](file://docs/components/antd/popover/README.md#L1-L8) + +### 二维码（QRCode）组件 + +- 编码内容与尺寸 + - value：二维码编码内容 + - size：整体尺寸；margin_size：外边距；bordered：是否显示边框 +- 颜色与样式 + - color：前景色；bg_color：背景色；type：canvas/svg 输出 +- 错误纠正与增强 + - error_level：L/M/Q/H 四级纠错 + - boost_level：提升识别能力（布尔） +- 图标叠加与状态 + - icon：中心图标地址；icon_size：图标尺寸或尺寸配置 + - status：active/expired/loading/scanned 状态 + - statusRender：状态渲染插槽 +- 动态更新与事件 + - refresh 事件：用于触发重新生成二维码 +- 自定义样式与打印优化 + - 通过样式与类名进行主题适配 + - 打印场景建议固定尺寸与高对比度色彩 + +```mermaid +classDiagram +class AntdQRCode { ++EVENTS ++SLOTS ++value ++size ++color ++bg_color ++type ++bordered ++error_level ++boost_level ++icon ++icon_size ++margin_size ++status ++statusRender ++refresh +} +class QRWrapper { ++slots ++statusRender ++value +} +AntdQRCode --> QRWrapper : "参数透传" +``` + +图表来源 + +- [**init**.py（AntdQRCode）:15-77](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L15-L77) +- [qr-code.tsx:6-20](file://frontend/antd/qr-code/qr-code.tsx#L6-L20) + +章节来源 + +- [**init**.py（AntdQRCode）:24-77](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L24-L77) +- [Index.svelte（QRCode）:22-45](file://frontend/antd/qr-code/Index.svelte#L22-L45) +- [qr-code.tsx:6-20](file://frontend/antd/qr-code/qr-code.tsx#L6-L20) +- [README-zh_CN.md（QRCode 文档）:1-8](file://docs/components/antd/qr_code/README-zh_CN.md#L1-L8) +- [README.md（QRCode 文档）:1-8](file://docs/components/antd/qr_code/README.md#L1-L8) + +## 依赖关系分析 + +- 后端组件类与前端包装 + - 后端类定义参数与事件，前端 Svelte 负责属性与插槽的最终拼装 +- React 封装与 Ant Design + - React 封装层将插槽转换为可渲染节点，并将回调函数安全地传递给 Ant Design 组件 +- 事件绑定 + - 气泡卡片：open_change + - 二维码：refresh + +```mermaid +graph LR +BE["后端组件类"] --> FE["Svelte 包装"] +FE --> WR["React 封装"] +WR --> AD["Ant Design 组件"] +``` + +图表来源 + +- [**init**.py（AntdPopover）:14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) +- [Index.svelte（Popover）:24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- [popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) +- [**init**.py（AntdQRCode）:15-19](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L15-L19) +- [Index.svelte（QRCode）:22-45](file://frontend/antd/qr-code/Index.svelte#L22-L45) +- [qr-code.tsx:6-20](file://frontend/antd/qr-code/qr-code.tsx#L6-L20) + +章节来源 + +- [**init**.py（AntdPopover）:14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) +- [Index.svelte（Popover）:24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- [popover.tsx:10-34](file://frontend/antd/popover/popover.tsx#L10-L34) +- [**init**.py（AntdQRCode）:15-19](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L15-L19) +- [Index.svelte（QRCode）:22-45](file://frontend/antd/qr-code/Index.svelte#L22-L45) +- [qr-code.tsx:6-20](file://frontend/antd/qr-code/qr-code.tsx#L6-L20) + +## 性能考虑 + +- 气泡卡片 + - 合理设置触发方式与延迟，避免频繁重渲染 + - 复杂内容建议懒加载或按需渲染 + - 容器挂载点应尽量靠近目标元素，减少 DOM 层级 +- 二维码 + - canvas 输出在大尺寸时可能带来内存压力，必要时选择 svg 或降低 size + - 图标叠加会增加渲染开销，建议使用轻量图标 + - 状态渲染插槽仅在需要时启用，避免不必要的计算 + +## 故障排查指南 + +- 气泡卡片 + - 打开状态不生效：检查 open_change 事件绑定与 open 参数 + - 内容不显示：确认 title/content 插槽是否正确传递 + - 定位异常：检查 get_popup_container 是否返回有效容器 +- 二维码 + - 无法刷新：确认 refresh 事件是否绑定成功 + - 样式不生效：检查 color/bg_color 与 type 设置是否合理 + - 扫描困难：提高 error_level 或开启 boost_level + +章节来源 + +- [**init**.py（AntdPopover）:14-18](file://backend/modelscope_studio/components/antd/popover/__init__.py#L14-L18) +- [Index.svelte（Popover）:24-52](file://frontend/antd/popover/Index.svelte#L24-L52) +- [**init**.py（AntdQRCode）:15-19](file://backend/modelscope_studio/components/antd/qr_code/__init__.py#L15-L19) +- [Index.svelte（QRCode）:22-45](file://frontend/antd/qr-code/Index.svelte#L22-L45) + +## 结论 + +- 气泡卡片与二维码均采用一致的三层封装模式，具备良好的扩展性与可控性 +- 气泡卡片侧重交互与布局，二维码侧重数据与视觉表现 +- 建议在复杂布局与移动端场景中结合本文档提供的策略与注意事项进行优化 + +## 附录 + +- 示例入口参考 + - 气泡卡片示例：[README-zh_CN.md（Popover 文档）](file://docs/components/antd/popover/README-zh_CN.md#L7) + - 二维码示例：[README-zh_CN.md（QRCode 文档）](file://docs/components/antd/qr_code/README-zh_CN.md#L7) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\350\241\250\346\240\274\344\270\216\346\240\207\347\255\276\351\241\265\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\350\241\250\346\240\274\344\270\216\346\240\207\347\255\276\351\241\265\347\273\204\344\273\266.md" new file mode 100644 index 00000000..6297555e --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\350\241\250\346\240\274\344\270\216\346\240\207\347\255\276\351\241\265\347\273\204\344\273\266.md" @@ -0,0 +1,340 @@ +# 表格与标签页组件 + + +**本文档引用的文件** +- [table.tsx](file://frontend/antd/table/table.tsx) +- [context.ts](file://frontend/antd/table/context.ts) +- [table.column.tsx](file://frontend/antd/table/column/table.column.tsx) +- [table.column-group.tsx](file://frontend/antd/table/column-group/table.column-group.tsx) +- [table.expandable.tsx](file://frontend/antd/table/expandable/table.expandable.tsx) +- [table.row-selection.tsx](file://frontend/antd/table/row-selection/table.row-selection.tsx) +- [tabs.tsx](file://frontend/antd/tabs/tabs.tsx) +- [tabs.context.ts](file://frontend/antd/tabs/context.ts) +- [tabs.item.tsx](file://frontend/antd/tabs/item/tabs.item.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向表格（Table）与标签页（Tabs）两大组件体系，系统性梳理其高级能力与工程化实现方式。重点覆盖表格的列定义（column）、列组（column_group）、可展开行（expandable）与行选择（row_selection）；以及标签页的标签项（item）、位置控制、禁用状态与动态增删。同时提供大数据量处理、虚拟滚动、排序筛选与分页集成的实践建议；并涵盖标签页的内容懒加载、标签图标、关闭按钮与拖拽重排的扩展思路。最后给出响应式设计与复杂布局中的导航策略。 + +## 项目结构 + +两个组件均采用“容器组件 + 子项处理器”的分层设计： + +- 容器组件负责属性透传、插槽渲染、上下文合并与函数包装； +- 子项处理器（如 TableColumn、TabsItem 等）负责将子级元素注入到容器中，并在必要时对配置进行增强（如菜单、下拉、图标等）。 + +```mermaid +graph TB +subgraph "表格组件" +T["Table 容器
frontend/antd/table/table.tsx"] +CtxT["表格上下文
frontend/antd/table/context.ts"] +Col["列处理器
frontend/antd/table/column/table.column.tsx"] +ColG["列组处理器
frontend/antd/table/column-group/table.column-group.tsx"] +Exp["可展开处理器
frontend/antd/table/expandable/table.expandable.tsx"] +RSel["行选择处理器
frontend/antd/table/row-selection/table.row-selection.tsx"] +end +subgraph "标签页组件" +Tabs["Tabs 容器
frontend/antd/tabs/tabs.tsx"] +CtxTabs["标签页上下文
frontend/antd/tabs/context.ts"] +TabsItem["标签项处理器
frontend/antd/tabs/item/tabs.item.tsx"] +end +T --> CtxT +T --> Col +T --> ColG +T --> Exp +T --> RSel +Tabs --> CtxTabs +Tabs --> TabsItem +``` + +**图表来源** + +- [table.tsx:28-276](file://frontend/antd/table/table.tsx#L28-L276) +- [context.ts](file://frontend/antd/table/context.ts) +- [table.column.tsx:20-97](file://frontend/antd/table/column/table.column.tsx#L20-L97) +- [table.column-group.tsx:7-19](file://frontend/antd/table/column-group/table.column-group.tsx#L7-L19) +- [table.expandable.tsx:7-11](file://frontend/antd/table/expandable/table.expandable.tsx#L7-L11) +- [table.row-selection.tsx:13-35](file://frontend/antd/table/row-selection/table.row-selection.tsx#L13-L35) +- [tabs.tsx:12-118](file://frontend/antd/tabs/tabs.tsx#L12-L118) +- [tabs.context.ts](file://frontend/antd/tabs/context.ts) +- [tabs.item.tsx:7-11](file://frontend/antd/tabs/item/tabs.item.tsx#L7-L11) + +**章节来源** + +- [table.tsx:28-276](file://frontend/antd/table/table.tsx#L28-L276) +- [tabs.tsx:12-118](file://frontend/antd/tabs/tabs.tsx#L12-L118) + +## 核心组件 + +- 表格容器：负责 columns、rowSelection、expandable、sticky、showSorterTooltip、pagination、loading、footer、title 等属性的统一处理与插槽渲染。 +- 列处理器：增强列配置，支持过滤下拉菜单、自定义弹窗渲染、菜单扩展图标与溢出指示器。 +- 列组处理器：将一组列作为逻辑分组，便于表头合并与样式控制。 +- 可展开处理器：将展开区域配置注入表格。 +- 行选择处理器：将自定义选择项（如“全选”、“反选”）注入 rowSelection。 +- 标签页容器：负责 items、indicator、renderTabBar、more、tabBarExtraContent、addIcon、removeIcon 等属性的统一处理与插槽渲染。 +- 标签项处理器：将单个标签项注入 Tabs 的 items。 + +**章节来源** + +- [table.tsx:28-276](file://frontend/antd/table/table.tsx#L28-L276) +- [table.column.tsx:20-97](file://frontend/antd/table/column/table.column.tsx#L20-L97) +- [table.column-group.tsx:7-19](file://frontend/antd/table/column-group/table.column-group.tsx#L7-L19) +- [table.expandable.tsx:7-11](file://frontend/antd/table/expandable/table.expandable.tsx#L7-L11) +- [table.row-selection.tsx:13-35](file://frontend/antd/table/row-selection/table.row-selection.tsx#L13-L35) +- [tabs.tsx:12-118](file://frontend/antd/tabs/tabs.tsx#L12-L118) +- [tabs.item.tsx:7-11](file://frontend/antd/tabs/item/tabs.item.tsx#L7-L11) + +## 架构总览 + +下图展示表格与标签页容器与其子项处理器之间的依赖关系与职责划分。 + +```mermaid +classDiagram +class Table { ++属性 : columns,rowSelection,expandable,sticky,showSorterTooltip,pagination,loading,footer,title ++插槽 : title,footer,loading.tip,loading.indicator,pagination.showQuickJumper.goButton,pagination.itemRender,showSorterTooltip.title,summary +} +class TableColumn { ++增强 : filterDropdownProps.menu +} +class TableColumnGroup +class TableExpandable +class TableRowSelection +class Tabs { ++属性 : items,indicator,more,renderTabBar,tabBarExtraContent,addIcon,removeIcon ++插槽 : renderTabBar,tabBarExtraContent.left,right,more.icon +} +class TabsItem +Table --> TableColumn : "使用" +Table --> TableColumnGroup : "使用" +Table --> TableExpandable : "使用" +Table --> TableRowSelection : "使用" +Tabs --> TabsItem : "使用" +``` + +**图表来源** + +- [table.tsx:28-276](file://frontend/antd/table/table.tsx#L28-L276) +- [table.column.tsx:20-97](file://frontend/antd/table/column/table.column.tsx#L20-L97) +- [table.column-group.tsx:7-19](file://frontend/antd/table/column-group/table.column-group.tsx#L7-L19) +- [table.expandable.tsx:7-11](file://frontend/antd/table/expandable/table.expandable.tsx#L7-L11) +- [table.row-selection.tsx:13-35](file://frontend/antd/table/row-selection/table.row-selection.tsx#L13-L35) +- [tabs.tsx:12-118](file://frontend/antd/tabs/tabs.tsx#L12-L118) +- [tabs.item.tsx:7-11](file://frontend/antd/tabs/item/tabs.item.tsx#L7-L11) + +## 详细组件分析 + +### 表格组件（Table） + +- 列定义（column） + - 支持直接传入 columns 或通过 TableColumn 注入； + - 对特殊占位符（如 EXPAND_COLUMN、SELECTION_COLUMN）进行识别与转换； + - 增强 filterDropdownProps，支持菜单项、下拉渲染、弹窗渲染、菜单扩展图标与溢出指示器。 +- 列组（column_group） + - 将一组列作为逻辑分组，便于表头合并与样式控制； + - 仅允许 default 插槽。 +- 可展开行（expandable） + - 通过 TableExpandable 注入 expandable 配置； + - 支持自定义渲染展开内容。 +- 行选择（row_selection） + - 通过 TableRowSelection 注入 rowSelection； + - 支持 selections 自定义选择项（如“全选”、“反选”）。 +- 排序筛选与分页 + - 支持 showSorterTooltip 的插槽化标题； + - 支持 pagination 的插槽化跳转按钮与分页渲染； + - 支持 loading 的 tip 与 indicator 插槽； + - 支持 sticky 的容器获取函数； + - 支持 footer 与 summary 的插槽化渲染。 +- 大数据量与虚拟滚动 + - 建议结合外部虚拟滚动方案（如固定高度 + 滚动容器）以降低 DOM 节点数量； + - 使用 onScroll 与分页/无限滚动配合，避免一次性渲染大量行。 +- 响应式设计 + - 结合 sticky 与列宽设置，在小屏设备上优先显示关键列； + - 使用列的 responsive 配置或自定义断点策略。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant T as "Table 容器" +participant C as "Column/Expandable/RowSelection 处理器" +participant R as "Ant Design Table" +U->>T : 提供 columns/rowSelection/expandable/pagination 等属性 +T->>C : 注入子项并增强配置 +C-->>T : 返回增强后的配置 +T->>R : 透传属性与插槽渲染 +R-->>U : 渲染表格 UI +``` + +**图表来源** + +- [table.tsx:66-271](file://frontend/antd/table/table.tsx#L66-L271) +- [table.column.tsx:28-93](file://frontend/antd/table/column/table.column.tsx#L28-L93) +- [table.expandable.tsx:9-10](file://frontend/antd/table/expandable/table.expandable.tsx#L9-L10) +- [table.row-selection.tsx:21-32](file://frontend/antd/table/row-selection/table.row-selection.tsx#L21-L32) + +**章节来源** + +- [table.tsx:28-276](file://frontend/antd/table/table.tsx#L28-L276) +- [table.column.tsx:20-97](file://frontend/antd/table/column/table.column.tsx#L20-L97) +- [table.column-group.tsx:7-19](file://frontend/antd/table/column-group/table.column-group.tsx#L7-L19) +- [table.expandable.tsx:7-11](file://frontend/antd/table/expandable/table.expandable.tsx#L7-L11) +- [table.row-selection.tsx:13-35](file://frontend/antd/table/row-selection/table.row-selection.tsx#L13-L35) + +### 标签页组件（Tabs） + +- 标签项（item） + - 通过 TabsItem 注入单个标签项； + - 支持 disabled、closable、closeIcon 等基础属性。 +- 位置控制与动态增删 + - 通过 items 动态数组控制标签增删； + - indicator 控制底部条样式，支持 size 函数； + - addIcon/removeIcon 支持插槽化图标。 +- 内容懒加载 + - 建议仅在激活时渲染对应面板内容，避免一次性渲染所有面板； + - onChange 事件中按需加载数据与组件。 +- 标签图标与关闭按钮 + - 通过插槽 addIcon/removeIcon 自定义图标； + - closable 与 closeIcon 控制是否可关闭及关闭图标。 +- 拖拽重排 + - 可通过外部拖拽库与 onChange 配合实现； + - 注意维护 items 的顺序与 activeKey 的一致性。 +- 更多菜单与额外内容 + - more.icon 支持插槽化图标； + - tabBarExtraContent 支持左右两侧插槽化内容。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant Tabs as "Tabs 容器" +participant Item as "TabsItem 处理器" +participant AD as "Ant Design Tabs" +U->>Tabs : 提供 items/addIcon/removeIcon/more/tabBarExtraContent +Tabs->>Item : 注入标签项并增强配置 +Item-->>Tabs : 返回增强后的标签项 +Tabs->>AD : 透传属性与插槽渲染 +AD-->>U : 渲染标签页 UI +``` + +**图表来源** + +- [tabs.tsx:26-115](file://frontend/antd/tabs/tabs.tsx#L26-L115) +- [tabs.item.tsx:9-10](file://frontend/antd/tabs/item/tabs.item.tsx#L9-L10) + +**章节来源** + +- [tabs.tsx:12-118](file://frontend/antd/tabs/tabs.tsx#L12-L118) +- [tabs.item.tsx:7-11](file://frontend/antd/tabs/item/tabs.item.tsx#L7-L11) + +### 复杂布局中的导航策略 + +- 响应式导航 + - 在窄屏设备上启用 Tabs 的更多菜单（more），将不常用标签移入下拉； + - 使用 sticky 或固定头部，保证导航始终可见。 +- 嵌套使用 + - 在标签页内嵌套子标签页或子表格，注意层级与交互冲突； + - 使用独立的上下文与命名空间，避免事件冒泡与状态污染。 +- 导航一致性 + - 统一使用 onChange 与 activeKey 管理当前激活状态； + - 对于异步加载的数据，先显示骨架屏再切换至真实内容。 + +## 依赖关系分析 + +- 表格侧 + - Table 容器依赖上下文提供者（Column、Expandable、RowSelection）以收集子项； + - TableColumn 增强 filterDropdownProps 并复用菜单上下文； + - TableRowSelection 注入 selections。 +- 标签页侧 + - Tabs 容器依赖 Items 上下文收集标签项； + - TabsItem 注入单个标签项。 + +```mermaid +graph LR +subgraph "表格依赖" +CTX["表格上下文"] +COL["列处理器"] +COLG["列组处理器"] +EXP["可展开处理器"] +SEL["行选择处理器"] +TBL["表格容器"] +TBL --> CTX +TBL --> COL +TBL --> COLG +TBL --> EXP +TBL --> SEL +end +subgraph "标签页依赖" +CTXS["标签上下文"] +ITEM["标签项处理器"] +TABS["标签页容器"] +TABS --> CTXS +TABS --> ITEM +end +``` + +**图表来源** + +- [context.ts](file://frontend/antd/table/context.ts) +- [table.tsx:41-275](file://frontend/antd/table/table.tsx#L41-L275) +- [tabs.context.ts](file://frontend/antd/tabs/context.ts) +- [tabs.tsx:24-117](file://frontend/antd/tabs/tabs.tsx#L24-L117) + +**章节来源** + +- [table.tsx:41-275](file://frontend/antd/table/table.tsx#L41-L275) +- [tabs.tsx:24-117](file://frontend/antd/tabs/tabs.tsx#L24-L117) + +## 性能考虑 + +- 表格 + - 大数据量：固定高度 + 虚拟滚动（如外部库）减少 DOM 数量； + - 分页/无限滚动：结合后端分页，避免一次性渲染； + - 列渲染：仅渲染必要列，隐藏非关键列； + - 事件绑定：使用 onRow/onHeaderRow 的节流/防抖。 +- 标签页 + - 内容懒加载：仅在激活时渲染； + - 动态增删：批量更新 items，避免频繁重渲染； + - 图标与插槽：尽量使用轻量级组件，避免复杂计算。 + +## 故障排除指南 + +- 插槽未生效 + - 确认插槽键名与容器声明一致（如 pagination.showQuickJumper.goButton、more.icon 等）； + - 检查插槽是否正确包裹在子项中。 +- 属性未生效 + - 确认函数型属性已通过 useFunction 包装； + - 检查对象型属性（如 sticky、showSorterTooltip、pagination）是否被正确合并。 +- 样式异常 + - 检查 getPopupContainer/getContainer 是否返回正确的挂载节点； + - 确认插槽中的 ReactSlot 渲染目标容器存在且可见。 + +**章节来源** + +- [table.tsx:76-108](file://frontend/antd/table/table.tsx#L76-L108) +- [tabs.tsx:36-39](file://frontend/antd/tabs/tabs.tsx#L36-L39) + +## 结论 + +本文档从架构与实现角度系统梳理了表格与标签页组件的能力边界与扩展点。通过容器组件与子项处理器的协作，实现了属性透传、插槽渲染与配置增强。结合大数据量、虚拟滚动、懒加载与响应式策略，可在复杂布局中提供稳定、可维护的导航体验。 + +## 附录 + +- 关键实现要点 + - 表格：columns、rowSelection、expandable、sticky、showSorterTooltip、pagination、loading、footer、title 的插槽化与函数包装； + - 标签页：items、indicator、renderTabBar、more、tabBarExtraContent、addIcon、removeIcon 的插槽化与函数包装。 +- 扩展建议 + - 表格：引入虚拟滚动与分页联动；根据业务场景定制列组与展开内容； + - 标签页：结合路由与状态管理实现动态增删与持久化；支持拖拽重排与更多菜单。 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\350\275\256\346\222\255\344\270\216\346\212\230\345\217\240\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\350\275\256\346\222\255\344\270\216\346\212\230\345\217\240\347\273\204\344\273\266.md" new file mode 100644 index 00000000..14b726bc --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\261\225\347\244\272\347\273\204\344\273\266/\350\275\256\346\222\255\344\270\216\346\212\230\345\217\240\347\273\204\344\273\266.md" @@ -0,0 +1,317 @@ +# 轮播与折叠组件 + + +**本文引用的文件** +- [carousel.tsx](file://frontend/antd/carousel/carousel.tsx) +- [Index.svelte](file://frontend/antd/carousel/Index.svelte) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [useTargets.ts](file://frontend/utils/hooks/useTargets.ts) +- [renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) +- [collapse.tsx](file://frontend/antd/collapse/collapse.tsx) +- [Index.svelte](file://frontend/antd/collapse/Index.svelte) +- [context.ts](file://frontend/antd/collapse/context.ts) +- [collapse.item/Index.svelte](file://frontend/antd/collapse/item/Index.svelte) +- [__init__.py（carousel 后端）](file://backend/modelscope_studio/components/antd/carousel/__init__.py) +- [__init__.py（collapse 后端）](file://backend/modelscope_studio/components/antd/collapse/__init__.py) +- [basic.py（carousel 演示）](file://docs/components/antd/carousel/demos/basic.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向“轮播（Carousel）”和“折叠面板（Collapse）”两个 Ant Design 组件，提供从架构到实现细节的系统性说明。重点覆盖： + +- 轮播：自动播放、切换动画、指示器控制、垂直轮播的特殊配置；触摸滑动、键盘导航与无障碍支持的建议路径；以及与后端参数映射关系。 +- 折叠面板：单项折叠的展开/收起、手风琴效果、面板内容的动态加载、折叠状态持久化；受控与非受控模式、面板标题自定义、动画效果配置。 + +## 项目结构 + +- 前端 Svelte 包装层负责属性处理、插槽渲染与条件显示。 +- React 层通过 sveltify 将 Ant Design 组件桥接至 Svelte。 +- 工具层提供函数包装、目标节点提取、插槽渲染等通用能力。 +- 后端 Python 组件负责参数透传与前端目录解析。 + +```mermaid +graph TB +subgraph "前端" +A["carousel/Index.svelte"] +B["carousel/carousel.tsx"] +C["collapse/Index.svelte"] +D["collapse/collapse.tsx"] +E["collapse/item/Index.svelte"] +F["hooks/useFunction.ts"] +G["hooks/useTargets.ts"] +H["utils/renderItems.tsx"] +I["utils/renderParamsSlot.tsx"] +end +subgraph "后端" +J["backend/.../carousel/__init__.py"] +K["backend/.../collapse/__init__.py"] +end +A --> B +C --> D +E --> D +B --> F +B --> G +D --> F +D --> H +D --> I +J --> A +K --> C +``` + +**图表来源** + +- [Index.svelte:1-66](file://frontend/antd/carousel/Index.svelte#L1-L66) +- [carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [Index.svelte:1-66](file://frontend/antd/collapse/Index.svelte#L1-L66) +- [collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [collapse.item/Index.svelte:1-95](file://frontend/antd/collapse/item/Index.svelte#L1-L95) +- [useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [**init**.py（carousel 后端）:45-94](file://backend/modelscope_studio/components/antd/carousel/__init__.py#L45-L94) +- [**init**.py（collapse 后端）:54-98](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L54-L98) + +**章节来源** + +- [Index.svelte:1-66](file://frontend/antd/carousel/Index.svelte#L1-L66) +- [carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [Index.svelte:1-66](file://frontend/antd/collapse/Index.svelte#L1-L66) +- [collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [collapse.item/Index.svelte:1-95](file://frontend/antd/collapse/item/Index.svelte#L1-L95) +- [useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [**init**.py（carousel 后端）:45-94](file://backend/modelscope_studio/components/antd/carousel/__init__.py#L45-L94) +- [**init**.py（collapse 后端）:54-98](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L54-L98) + +## 核心组件 + +- 轮播（Carousel） + - 前端包装：接收属性与插槽，调用 Ant Design 的 Carousel，并通过 ReactSlot 渲染子项。 + - 关键点：afterChange/beforeChange 使用 useFunction 包装；子项顺序由 useTargets 提取并排序。 +- 折叠面板（Collapse） + - 前端包装：通过 withItemsContextProvider 注入 items 上下文，使用 renderItems 将插槽转换为 Ant Design 的 items 结构；支持 expandIcon 插槽或函数。 + - 折叠项（Collapse.Item）：负责将 label/extra/children 插槽克隆并传递给底层组件。 + +**章节来源** + +- [carousel.tsx:8-29](file://frontend/antd/carousel/carousel.tsx#L8-L29) +- [Index.svelte:48-61](file://frontend/antd/carousel/Index.svelte#L48-L61) +- [collapse.tsx:10-50](file://frontend/antd/collapse/collapse.tsx#L10-L50) +- [collapse.item/Index.svelte:60-88](file://frontend/antd/collapse/item/Index.svelte#L60-L88) + +## 架构总览 + +以下图展示从前端 Svelte 到 React Ant Design 组件的调用链路，以及关键工具函数的作用位置。 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 组件" +participant Wrapper as "sveltify 包装层" +participant UtilF as "useFunction" +participant UtilT as "useTargets" +participant AD as "Ant Design Carousel" +Svelte->>Wrapper : "渲染并传入属性/插槽" +Wrapper->>UtilF : "afterChange/beforeChange 包装" +Wrapper->>UtilT : "提取并排序子项目标" +Wrapper->>AD : "渲染并传入已包装回调与子项" +AD-->>Wrapper : "触发回调/切换事件" +Wrapper-->>Svelte : "回传结果如需要" +``` + +**图表来源** + +- [carousel.tsx:9-25](file://frontend/antd/carousel/carousel.tsx#L9-L25) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) + +## 详细组件分析 + +### 轮播（Carousel）组件 + +- 自动播放与切换动画 + - 支持 autoplay、autoplaySpeed、speed、easing、effect（如 fade）、wait_for_animate 等参数，对应后端映射见后端初始化参数。 + - 切换前后回调 afterChange、beforeChange 通过 useFunction 包装以确保在 React 环境中稳定执行。 +- 指示器控制 + - 支持 dots、dotPosition、dotPlacement 等配置；指示器样式可通过 root_class_name 或额外类名控制。 +- 垂直轮播 + - 可通过 effect 或相关布局配置实现纵向滚动（具体取决于 Ant Design 的支持与样式）。 +- 触摸滑动、键盘导航与无障碍 + - 建议开启 draggable 以支持触摸滑动；键盘导航与无障碍标签可结合 Ant Design 的默认行为与自定义 aria-\* 属性实现。 +- 子项渲染 + - 子项通过 useTargets 提取并按 slotIndex/subSlotIndex 排序，再以 ReactSlot 克隆渲染，保证顺序与可见性。 + +```mermaid +flowchart TD +Start(["开始渲染"]) --> Extract["提取子项
useTargets(children)"] +Extract --> Sort["按索引排序
slotIndex/subSlotIndex"] +Sort --> WrapCallbacks["包装回调
useFunction(afterChange/beforeChange)"] +WrapCallbacks --> Render["渲染 Ant Design Carousel"] +Render --> Children["克隆子项
ReactSlot"] +Children --> End(["完成"]) +``` + +**图表来源** + +- [carousel.tsx:9-25](file://frontend/antd/carousel/carousel.tsx#L9-L25) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) + +**章节来源** + +- [carousel.tsx:8-29](file://frontend/antd/carousel/carousel.tsx#L8-L29) +- [Index.svelte:48-61](file://frontend/antd/carousel/Index.svelte#L48-L61) +- [**init**.py（carousel 后端）:45-94](file://backend/modelscope_studio/components/antd/carousel/__init__.py#L45-L94) +- [basic.py（carousel 演示）:40-73](file://docs/components/antd/carousel/demos/basic.py#L40-L73) + +### 折叠面板（Collapse）组件 + +- 单项折叠与手风琴 + - 通过 accordion 控制是否启用手风琴模式；activeKey/defaultActiveKey 控制当前展开项（支持多选或单选）。 +- 面板内容动态加载 + - 通过 items 上下文与 renderItems 将插槽转换为 items；destroy_on_hidden/destroy_inactive_panel 可控制隐藏时销毁面板以节省资源。 +- 折叠状态持久化 + - 通过受控属性 activeKey 实现状态持久化；onChange 回调可用于记录状态变化。 +- 受控与非受控模式 + - 非受控：使用 defaultActiveKey；受控：使用 activeKey 并监听 onChange 更新。 +- 面板标题自定义 + - label 插槽用于自定义标题；extra 插槽用于右侧附加操作；expandIcon 插槽或函数可自定义展开图标。 +- 动画效果配置 + - size、bordered、ghost 等外观属性可配合动画与过渡效果；具体动画行为遵循 Ant Design 默认实现。 + +```mermaid +sequenceDiagram +participant S as "Svelte Collapse" +participant P as "withItemsContextProvider" +participant R as "renderItems" +participant RP as "renderParamsSlot" +participant C as "Ant Design Collapse" +S->>P : "注入 items 上下文" +P->>R : "将插槽转换为 items" +S->>RP : "expandIcon 插槽渲染" +S->>C : "传入 items、onChange、expandIcon" +C-->>S : "触发 onChange(key)" +S-->>S : "更新受控状态/持久化" +``` + +**图表来源** + +- [collapse.tsx:11-49](file://frontend/antd/collapse/collapse.tsx#L11-L49) +- [context.ts:1-7](file://frontend/antd/collapse/context.ts#L1-L7) +- [renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) +- [renderParamsSlot.tsx:5-49](file://frontend/utils/renderParamsSlot.tsx#L5-L49) + +**章节来源** + +- [collapse.tsx:10-50](file://frontend/antd/collapse/collapse.tsx#L10-L50) +- [collapse.item/Index.svelte:60-88](file://frontend/antd/collapse/item/Index.svelte#L60-L88) +- [context.ts:1-7](file://frontend/antd/collapse/context.ts#L1-L7) +- [**init**.py（collapse 后端）:54-98](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L54-L98) + +## 依赖关系分析 + +- 轮播 + - carousel.tsx 依赖 useFunction 与 useTargets；Index.svelte 负责属性与可见性处理。 +- 折叠面板 + - collapse.tsx 依赖 useFunction、renderItems、renderParamsSlot 与 items 上下文；collapse.item/Index.svelte 负责插槽克隆与传递。 +- 后端映射 + - 后端 Python 组件将参数映射到前端组件，避免 API 重复定义。 + +```mermaid +graph LR +CF["carousel.tsx"] --> UF["useFunction.ts"] +CF --> UT["useTargets.ts"] +CI["Index.svelte(轮播)"] --> CF +DF["collapse.tsx"] --> UF +DF --> RI["renderItems.tsx"] +DF --> RPS["renderParamsSlot.tsx"] +DI["Index.svelte(折叠)"] --> DF +DII["collapse.item/Index.svelte"] --> DF +``` + +**图表来源** + +- [carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [Index.svelte:1-66](file://frontend/antd/carousel/Index.svelte#L1-L66) +- [Index.svelte:1-66](file://frontend/antd/collapse/Index.svelte#L1-L66) +- [collapse.item/Index.svelte:1-95](file://frontend/antd/collapse/item/Index.svelte#L1-L95) + +**章节来源** + +- [carousel.tsx:1-32](file://frontend/antd/carousel/carousel.tsx#L1-L32) +- [collapse.tsx:1-53](file://frontend/antd/collapse/collapse.tsx#L1-L53) +- [Index.svelte:1-66](file://frontend/antd/carousel/Index.svelte#L1-L66) +- [Index.svelte:1-66](file://frontend/antd/collapse/Index.svelte#L1-L66) +- [collapse.item/Index.svelte:1-95](file://frontend/antd/collapse/item/Index.svelte#L1-L95) + +## 性能考量 + +- 轮播 + - 子项排序与目标提取在 useMemo 中进行，避免不必要的重排。 + - 使用 ReactSlot 克隆渲染，注意控制子项数量与复杂度。 +- 折叠面板 + - 通过 destroy_on_hidden/destroy_inactive_panel 控制面板销毁，减少内存占用。 + - renderItems 对嵌套插槽递归渲染，应避免过深层级。 +- 通用 + - useFunction 包装回调，确保函数引用稳定，减少副作用。 + +[本节为通用指导，不直接分析具体文件，故无“章节来源”] + +## 故障排查指南 + +- 轮播子项未显示 + - 检查 children 是否正确传入；确认 useTargets 过滤逻辑与 slotIndex 设置。 +- 轮播回调未触发 + - 确认 afterChange/beforeChange 通过 useFunction 包装；检查 Ant Design 版本兼容性。 +- 折叠面板 items 不生效 + - 确认通过插槽注入 items 或显式传入 items；检查 renderItems 的 key 生成与插槽键名。 +- 展开图标不显示 + - 若使用 expandIcon 插槽，确保插槽存在且 renderParamsSlot 正常渲染；否则检查 expandIcon 函数是否传入。 + +**章节来源** + +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [renderItems.tsx:8-113](file://frontend/utils/renderItems.tsx#L8-L113) +- [renderParamsSlot.tsx:5-49](file://frontend/utils/renderParamsSlot.tsx#L5-L49) + +## 结论 + +- 轮播与折叠面板均采用统一的“Svelte 包装 + Ant Design 组件 + 工具函数”的架构，具备良好的扩展性与可维护性。 +- 轮播侧重于自动播放、切换动画与指示器配置；折叠面板强调受控/非受控、动态加载与状态持久化。 +- 建议在实际项目中结合演示脚本与后端参数映射，快速落地功能需求。 + +[本节为总结，不直接分析具体文件，故无“章节来源”] + +## 附录 + +- 参数映射参考 + - 轮播：autoplay、autoplaySpeed、adaptiveHeight、dotPosition、dotPlacement、dots、draggable、fade、infinite、speed、easing、effect、afterChange、beforeChange、wait_for_animate、root_class_name。 + - 折叠：accordion、activeKey/defaultActiveKey、bordered、collapsible、destroy_on_hidden、destroy_inactive_panel、expand_icon、expand_icon_position、expand_icon_placement、ghost、items、size、root_class_name。 + +**章节来源** + +- [**init**.py（carousel 后端）:45-94](file://backend/modelscope_studio/components/antd/carousel/__init__.py#L45-L94) +- [**init**.py（collapse 后端）:54-98](file://backend/modelscope_studio/components/antd/collapse/__init__.py#L54-L98) +- [basic.py（carousel 演示）:40-73](file://docs/components/antd/carousel/demos/basic.py#L40-L73) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266.md" new file mode 100644 index 00000000..780cab52 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266.md" @@ -0,0 +1,520 @@ +# 数据录入组件 + + +**本文引用的文件** +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [frontend/antd/auto-complete/auto-complete.tsx](file://frontend/antd/auto-complete/auto-complete.tsx) +- [frontend/antd/cascader/cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [frontend/antd/checkbox/checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [frontend/antd/color-picker/color-picker.tsx](file://frontend/antd/color-picker/color-picker.tsx) +- [frontend/antd/date-picker/date-picker.tsx](file://frontend/antd/date-picker/date-picker.tsx) +- [frontend/antd/radio/radio.tsx](file://frontend/antd/radio/radio.tsx) +- [frontend/antd/rate/rate.tsx](file://frontend/antd/rate/rate.tsx) +- [frontend/antd/slider/slider.tsx](file://frontend/antd/slider/slider.tsx) +- [frontend/antd/switch/switch.tsx](file://frontend/antd/switch/switch.tsx) +- [frontend/antd/time-picker/time-picker.tsx](file://frontend/antd/time-picker/time-picker.tsx) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/form/item/form.item.tsx](file://frontend/antd/form/item/form.item.tsx) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) +- [frontend/antd/form/provider/form.provider.tsx](file://frontend/antd/form/provider/form.provider.tsx) +- [frontend/antd/input/input.tsx](file://frontend/antd/input/input.tsx) +- [frontend/antd/input/otp/input.otp.tsx](file://frontend/antd/input/otp/input.otp.tsx) +- [frontend/antd/input/password/input.password.tsx](file://frontend/antd/input/password/input.password.tsx) +- [frontend/antd/input/search/input.search.tsx](file://frontend/antd/input/search/input.search.tsx) +- [frontend/antd/input/textarea/input.textarea.tsx](file://frontend/antd/input/textarea/input.textarea.tsx) +- [frontend/antd/input-number/input-number.tsx](file://frontend/antd/input-number/input-number.tsx) +- [frontend/antd/select/select.tsx](file://frontend/antd/select/select.tsx) +- [frontend/antd/select/option/select.option.tsx](file://frontend/antd/select/option/select.option.tsx) +- [frontend/antd/transfer/transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [frontend/antd/tree-select/tree-select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [frontend/antd/upload/upload.tsx](file://frontend/antd/upload/upload.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能与大数据量优化](#性能与大数据量优化) +8. [可访问性与键盘操作](#可访问性与键盘操作) +9. [复杂表单设计模式与数据流](#复杂表单设计模式与数据流) +10. [故障排查指南](#故障排查指南) +11. [结论](#结论) + +## 简介 + +本文件面向使用 Ant Design 组件在前端进行数据录入的场景，系统梳理了自动完成、级联选择、多选框、颜色选择器、日期选择器、表单、输入框、数字输入框、提及、单选框、评分、选择器、滑动输入条、开关、时间选择器、穿梭框、树选择、上传等组件的封装与使用要点。重点覆盖以下方面： + +- 数据绑定：如何通过 onValueChange 实现受控/非受控双向绑定 +- 验证规则：Form.Item 与 FormItem.Rule 的组合使用 +- 格式化选项：日期时间类组件的内部格式转换与对外输出统一 +- 复杂表单设计模式：分步、联动、动态字段、条件渲染 +- 可访问性与键盘操作：语义化标签、焦点管理、键盘导航 +- 性能优化：虚拟滚动、懒加载、防抖节流、批量更新 + +## 项目结构 + +该项目采用“后端组件导出 + 前端 Svelte/React 封装”的双层结构： + +- 后端层负责将 Ant Design 组件以 Python 类的形式导出，便于在 Python 生态中统一调用与文档生成 +- 前端层基于 Svelte/React 封装，提供 slots 插槽、上下文注入、函数钩子、值变更桥接等能力，实现与后端一致的 API 体验 + +```mermaid +graph TB +subgraph "后端" +A["backend/modelscope_studio/components/antd/__init__.py
导出 Antd* 组件别名"] +end +subgraph "前端" +B["frontend/antd/*/*.tsx
各组件封装sveltify + hooks"] +C["frontend/antd/form/*
Form/FormItem/Rule/Provider"] +D["utils/*
hooks/renderItems/renderParamsSlot 等"] +end +A --> B +B --> D +C --> B +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [frontend/antd/auto-complete/auto-complete.tsx:1-151](file://frontend/antd/auto-complete/auto-complete.tsx#L1-L151) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/form/item/form.item.tsx](file://frontend/antd/form/item/form.item.tsx) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) +- [frontend/antd/form/provider/form.provider.tsx](file://frontend/antd/form/provider/form.provider.tsx) + +章节来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) + +## 核心组件 + +本节概览本次文档涉及的组件及其职责： + +- 表单体系：Form、FormItem、FormItem.Rule、FormProvider +- 输入类：Input、Input.TextArea、Input.Search、Input.Password、Input.OTP、InputNumber +- 选择类：Select、Select.Option、Cascader、TreeSelect、Transfer +- 时间类：DatePicker、TimePicker +- 滑动与评分：Slider、Rate +- 开关与选择：Switch、Radio、Checkbox +- 颜色：ColorPicker +- 提及：Mentions（支持关键词提及与选项的动态渲染，包含 Option 子组件） + +章节来源 + +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/form/item/form.item.tsx](file://frontend/antd/form/item/form.item.tsx) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) +- [frontend/antd/form/provider/form.provider.tsx](file://frontend/antd/form/provider/form.provider.tsx) +- [frontend/antd/input/input.tsx](file://frontend/antd/input/input.tsx) +- [frontend/antd/input/otp/input.otp.tsx](file://frontend/antd/input/otp/input.otp.tsx) +- [frontend/antd/input/password/input.password.tsx](file://frontend/antd/input/password/input.password.tsx) +- [frontend/antd/input/search/input.search.tsx](file://frontend/antd/input/search/input.search.tsx) +- [frontend/antd/input/textarea/input.textarea.tsx](file://frontend/antd/input/textarea/input.textarea.tsx) +- [frontend/antd/input-number/input-number.tsx](file://frontend/antd/input-number/input-number.tsx) +- [frontend/antd/select/select.tsx](file://frontend/antd/select/select.tsx) +- [frontend/antd/select/option/select.option.tsx](file://frontend/antd/select/option/select.option.tsx) +- [frontend/antd/cascader/cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [frontend/antd/tree-select/tree-select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [frontend/antd/transfer/transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [frontend/antd/date-picker/date-picker.tsx](file://frontend/antd/date-picker/date-picker.tsx) +- [frontend/antd/time-picker/time-picker.tsx](file://frontend/antd/time-picker/time-picker.tsx) +- [frontend/antd/slider/slider.tsx](file://frontend/antd/slider/slider.tsx) +- [frontend/antd/rate/rate.tsx](file://frontend/antd/rate/rate.tsx) +- [frontend/antd/switch/switch.tsx](file://frontend/antd/switch/switch.tsx) +- [frontend/antd/radio/radio.tsx](file://frontend/antd/radio/radio.tsx) +- [frontend/antd/checkbox/checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [frontend/antd/color-picker/color-picker.tsx](file://frontend/antd/color-picker/color-picker.tsx) + +## 架构总览 + +前端组件普遍采用 sveltify 包裹 Ant Design 原生组件，并通过 hooks 完成： + +- 值变更桥接：useValueChange 将 onChange 与 onValueChange 对接，确保外部统一接收 value +- 函数参数化：useFunction 将传入的函数包装为稳定引用，避免闭包陷阱 +- 插槽渲染：renderItems/renderParamsSlot 支持 children 与 slots 的灵活组合 +- 上下文注入：withItemsContextProvider 为子项组件（如 Option/Marks/Preset）注入 items + +```mermaid +sequenceDiagram +participant U as "用户" +participant C as "封装组件(如 AutoComplete)" +participant R as "React/antd 组件" +participant H as "hooks(onValueChange/useFunction)" +participant P as "父组件(Form/页面)" +U->>C : 触发交互 +C->>R : 调用原生组件事件 +R-->>C : 回调值 +C->>H : onValueChange(value) +H-->>C : 更新内部状态 +C-->>P : onValueChange(value) +Note over C,P : 父组件可结合 Form/FormItem 进行校验与联动 +``` + +图表来源 + +- [frontend/antd/auto-complete/auto-complete.tsx:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) +- [frontend/antd/cascader/cascader.tsx:39-204](file://frontend/antd/cascader/cascader.tsx#L39-L204) +- [frontend/antd/checkbox/checkbox.tsx:4-19](file://frontend/antd/checkbox/checkbox.tsx#L4-L19) +- [frontend/antd/color-picker/color-picker.tsx:24-103](file://frontend/antd/color-picker/color-picker.tsx#L24-L103) +- [frontend/antd/date-picker/date-picker.tsx:40-231](file://frontend/antd/date-picker/date-picker.tsx#L40-L231) +- [frontend/antd/radio/radio.tsx:6-29](file://frontend/antd/radio/radio.tsx#L6-L29) +- [frontend/antd/rate/rate.tsx:12-42](file://frontend/antd/rate/rate.tsx#L12-L42) +- [frontend/antd/slider/slider.tsx:37-94](file://frontend/antd/slider/slider.tsx#L37-L94) +- [frontend/antd/switch/switch.tsx:6-39](file://frontend/antd/switch/switch.tsx#L6-L39) +- [frontend/antd/time-picker/time-picker.tsx:37-198](file://frontend/antd/time-picker/time-picker.tsx#L37-L198) + +## 组件详解 + +### 自动完成 AutoComplete + +- 数据绑定：通过 onValueChange 接收字符串值；onChange 透传原生回调 +- 插槽：支持 children、dropdownRender、popupRender、notFoundContent、allowClear.clearIcon +- 选项：支持通过 options 或 slots.children 渲染 +- 过滤：filterOption 可自定义过滤逻辑或使用默认行为 + +```mermaid +flowchart TD +Start(["开始"]) --> Bind["绑定 onValueChange"] +Bind --> Render["渲染选项/插槽"] +Render --> UserInput["用户输入"] +UserInput --> Filter{"是否自定义过滤?"} +Filter -- 是 --> UseFn["使用 filterOption 函数"] +Filter -- 否 --> Default["默认过滤"] +UseFn --> Change["触发 onChange 并更新 value"] +Default --> Change +Change --> End(["结束"]) +``` + +图表来源 + +- [frontend/antd/auto-complete/auto-complete.tsx:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) + +章节来源 + +- [frontend/antd/auto-complete/auto-complete.tsx:1-151](file://frontend/antd/auto-complete/auto-complete.tsx#L1-L151) + +### 级联选择 Cascader + +- 数据绑定：onValueChange 接收数组（路径值），onChange 透传 +- 插槽：suffixIcon、prefix、removeIcon、expandIcon、displayRender、tagRender、dropdownRender、popupRender、showSearch.render、maxTagPlaceholder +- 搜索：showSearch 支持对象配置与插槽渲染 +- 动态加载：onLoadData 对应原生 loadData + +```mermaid +sequenceDiagram +participant U as "用户" +participant C as "Cascader" +participant R as "Antd Cascader" +U->>C : 展开/选择节点 +C->>R : 渲染面板/搜索 +R-->>C : 返回选中值 +C-->>U : onValueChange(路径数组) +``` + +图表来源 + +- [frontend/antd/cascader/cascader.tsx:19-204](file://frontend/antd/cascader/cascader.tsx#L19-L204) + +章节来源 + +- [frontend/antd/cascader/cascader.tsx:1-207](file://frontend/antd/cascader/cascader.tsx#L1-L207) + +### 多选框 Checkbox + +- 数据绑定：onValueChange 接收布尔值 +- 事件：onChange 透传原生事件 + +章节来源 + +- [frontend/antd/checkbox/checkbox.tsx:1-22](file://frontend/antd/checkbox/checkbox.tsx#L1-L22) + +### 颜色选择器 ColorPicker + +- 数据绑定：onValueChange 接收字符串或渐变颜色数组；value_format 控制输出格式（rgb/hex/hsb） +- 插槽：panelRender、showText +- 渐变：当 isGradient() 时，按 value_format 输出每段颜色 + +章节来源 + +- [frontend/antd/color-picker/color-picker.tsx:1-106](file://frontend/antd/color-picker/color-picker.tsx#L1-L106) + +### 日期选择器 DatePicker + +- 数据绑定：onValueChange 接收秒级时间戳（含数组场景）；onChange/onPanelChange 透传 +- 内部格式：统一使用 dayjs 转换，对外输出秒级时间戳 +- 插槽：renderExtraFooter、cellRender、panelRender、prevIcon/prefix/nextIcon/suffixIcon/superNextIcon/superPrevIcon、allowClear.clearIcon +- 预设：presets 通过 renderItems 渲染 + +```mermaid +flowchart TD +In(["输入日期"]) --> Parse["dayjs 解析"] +Parse --> Normalize["标准化为秒级时间戳"] +Normalize --> Emit["onValueChange/onChange"] +Emit --> Out(["输出到父组件"]) +``` + +图表来源 + +- [frontend/antd/date-picker/date-picker.tsx:14-38](file://frontend/antd/date-picker/date-picker.tsx#L14-L38) +- [frontend/antd/date-picker/date-picker.tsx:126-170](file://frontend/antd/date-picker/date-picker.tsx#L126-L170) + +章节来源 + +- [frontend/antd/date-picker/date-picker.tsx:1-234](file://frontend/antd/date-picker/date-picker.tsx#L1-L234) + +### 表单 Form / FormItem / FormItem.Rule / FormProvider + +- Form：容器，提供 Provider 注入与布局能力 +- FormItem：字段容器，承载 label、help、required、validateStatus 等 +- FormItem.Rule：校验规则，支持必填、正则、自定义函数、异步校验 +- FormProvider：全局配置与上下文 + +```mermaid +classDiagram +class Form { ++provider() ++submit() ++resetFields() +} +class FormItem { ++label ++help ++required ++validateStatus +} +class FormItemRule { ++rules ++trigger +} +class FormProvider { ++config +} +Form --> FormItem : "包含" +FormItem --> FormItemRule : "使用" +Form --> FormProvider : "注入" +``` + +图表来源 + +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/form/item/form.item.tsx](file://frontend/antd/form/item/form.item.tsx) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) +- [frontend/antd/form/provider/form.provider.tsx](file://frontend/antd/form/provider/form.provider.tsx) + +章节来源 + +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/form/item/form.item.tsx](file://frontend/antd/form/item/form.item.tsx) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) +- [frontend/antd/form/provider/form.provider.tsx](file://frontend/antd/form/provider/form.provider.tsx) + +### 输入框 Input / TextArea / Search / Password / OTP + +- 统一模式：均通过 onValueChange 接收最新值，onChange 透传原生事件 +- 扩展：Search、Password、OTP 分别提供特定行为与样式 + +章节来源 + +- [frontend/antd/input/input.tsx](file://frontend/antd/input/input.tsx) +- [frontend/antd/input/otp/input.otp.tsx](file://frontend/antd/input/otp/input.otp.tsx) +- [frontend/antd/input/password/input.password.tsx](file://frontend/antd/input/password/input.password.tsx) +- [frontend/antd/input/search/input.search.tsx](file://frontend/antd/input/search/input.search.tsx) +- [frontend/antd/input/textarea/input.textarea.tsx](file://frontend/antd/input/textarea/input.textarea.tsx) + +### 数字输入框 InputNumber + +- 数据绑定：onValueChange 接收数值；onChange 透传 +- 场景：步进、范围、精度控制 + +章节来源 + +- [frontend/antd/input-number/input-number.tsx](file://frontend/antd/input-number/input-number.tsx) + +### 选择器 Select / Option + +- 数据绑定：onValueChange 接收字符串/数字/数组；onChange 透传 +- 子项：Option 通过 renderItems 注入，支持禁用、分组等 + +章节来源 + +- [frontend/antd/select/select.tsx](file://frontend/antd/select/select.tsx) +- [frontend/antd/select/option/select.option.tsx](file://frontend/antd/select/option/select.option.tsx) + +### 滑动输入条 Slider / Marks + +- 数据绑定：onValueChange 接收 number 或 number[]；onChange 透传 +- 标记：marks 通过 slots.children 或 slots.label 渲染 + +章节来源 + +- [frontend/antd/slider/slider.tsx:1-97](file://frontend/antd/slider/slider.tsx#L1-L97) + +### 单选框 Radio + +- 数据绑定：onValueChange 接收布尔值；onChange 透传 +- 主题：通过 token.lineWidth 注入样式变量 + +章节来源 + +- [frontend/antd/radio/radio.tsx:1-32](file://frontend/antd/radio/radio.tsx#L1-L32) + +### 评分 Rate + +- 数据绑定：onValueChange 接收数值；onChange 透传 +- 插槽：character 支持自定义评分图标 + +章节来源 + +- [frontend/antd/rate/rate.tsx:1-45](file://frontend/antd/rate/rate.tsx#L1-L45) + +### 开关 Switch + +- 数据绑定：onValueChange 接收布尔值；onChange 透传 +- 插槽：checkedChildren、unCheckedChildren + +章节来源 + +- [frontend/antd/switch/switch.tsx:1-42](file://frontend/antd/switch/switch.tsx#L1-L42) + +### 时间选择器 TimePicker + +- 数据绑定：onValueChange 接收秒级时间戳；onChange/onPanelChange/onCalendarChange 透传 +- 内部格式：统一 dayjs 转换 + +章节来源 + +- [frontend/antd/time-picker/time-picker.tsx:1-201](file://frontend/antd/time-picker/time-picker.tsx#L1-L201) + +### 穿梭框 Transfer + +- 数据绑定：onValueChange 接收目标列表键值；onChange 透传 +- 场景：多选移动、排序、搜索 + +章节来源 + +- [frontend/antd/transfer/transfer.tsx](file://frontend/antd/transfer/transfer.tsx) + +### 树选择 TreeSelect + +- 数据绑定：onValueChange 接收字符串/数组；onChange 透传 +- 子项：TreeNode 通过 renderItems 注入 + +章节来源 + +- [frontend/antd/tree-select/tree-select.tsx](file://frontend/antd/tree-select/tree-select.tsx) + +### 上传 Upload + +- 数据绑定：onValueChange 接收文件列表；onChange 透传 +- 场景：拖拽、预览、限制大小/类型 + +章节来源 + +- [frontend/antd/upload/upload.tsx](file://frontend/antd/upload/upload.tsx) + +## 依赖关系分析 + +- 组件间耦合：多数组件通过 hooks 与工具函数解耦，降低对具体实现的耦合度 +- 插槽与上下文：withItemsContextProvider 与 renderItems 使子项组件可被统一注入与渲染 +- 事件桥接：useValueChange 将 onChange 与 onValueChange 对齐，保证父组件统一订阅 + +```mermaid +graph LR +Utils["utils/*
hooks/renderItems/renderParamsSlot"] --> Auto["AutoComplete"] +Utils --> Cascader +Utils --> ColorPicker +Utils --> DatePicker +Utils --> Slider +Utils --> TimePicker +Form["Form/FormItem/Rule/Provider"] --> Auto +Form --> Cascader +Form --> DatePicker +Form --> TimePicker +``` + +图表来源 + +- [frontend/antd/auto-complete/auto-complete.tsx:1-151](file://frontend/antd/auto-complete/auto-complete.tsx#L1-L151) +- [frontend/antd/cascader/cascader.tsx:1-207](file://frontend/antd/cascader/cascader.tsx#L1-L207) +- [frontend/antd/color-picker/color-picker.tsx:1-106](file://frontend/antd/color-picker/color-picker.tsx#L1-L106) +- [frontend/antd/date-picker/date-picker.tsx:1-234](file://frontend/antd/date-picker/date-picker.tsx#L1-L234) +- [frontend/antd/slider/slider.tsx:1-97](file://frontend/antd/slider/slider.tsx#L1-L97) +- [frontend/antd/time-picker/time-picker.tsx:1-201](file://frontend/antd/time-picker/time-picker.tsx#L1-L201) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/form/item/form.item.tsx](file://frontend/antd/form/item/form.item.tsx) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) +- [frontend/antd/form/provider/form.provider.tsx](file://frontend/antd/form/provider/form.provider.tsx) + +## 性能与大数据量优化 + +- 列表渲染 + - 使用虚拟滚动：在 Select/Cascader/TreeSelect 中优先考虑虚拟化方案，减少 DOM 节点数量 + - 懒加载：Cascader 的 onLoadData 仅在展开时请求数据，避免一次性加载全部 +- 输入性能 + - 防抖/节流：在 AutoComplete 的 filterOption 或搜索型输入中加入防抖 + - 批量更新：Form 中使用 batch 提交，减少重渲染次数 +- 日期时间 + - 内部统一 dayjs，对外统一秒级时间戳，避免重复解析 + - 预设与面板渲染使用 memo 化，减少不必要的重算 +- 图形与颜色 + - ColorPicker 在渐变场景下按 value_format 计算输出，避免重复格式化 + +## 可访问性与键盘操作 + +- 语义化标签：Radio/Checkbox/Switch 等提供明确的 aria 属性与 label 关联 +- 键盘导航：DatePicker/TimePicker/Select/Slider 支持 Tab/Enter/方向键等标准操作 +- 焦点管理：getPopupContainer 将弹层挂载到容器内，避免焦点丢失 +- 屏幕阅读器：FormItem 提供 help/status 文本，辅助说明错误与提示信息 + +## 复杂表单设计模式与数据流 + +- 分步表单：使用 FormProvider 全局配置，配合 onPanelChange 与联动字段 +- 条件渲染：根据某字段值动态显示/隐藏区域，结合 FormItem 的 required 与 Rule +- 动态字段：通过 renderItems 注入 Option/TreeNode/Mark，实现动态增删改 +- 联动与计算：在 onValueChange 中触发副作用（如计算总价、填充地址），并通过 Form.setFieldsValue 更新其他字段 + +```mermaid +sequenceDiagram +participant F as "Form" +participant I1 as "FormItem A" +participant I2 as "FormItem B" +F->>I1 : 用户输入 +I1-->>F : onValueChange(newValueA) +F->>I2 : setFieldsValue(联动字段) +I2-->>F : onValueChange(newValueB) +F-->>F : 校验与提交 +``` + +图表来源 + +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/antd/form/item/form.item.tsx](file://frontend/antd/form/item/form.item.tsx) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) + +## 故障排查指南 + +- 事件未触发 + - 检查 onValueChange 是否正确传入；确认 onChange 是否被覆盖 +- 值不更新 + - 确认受控模式下父组件是否及时 setState；检查 useValueChange 的依赖 +- 插槽不生效 + - 确认 slots.key 是否与组件约定一致；检查 renderParamsSlot 的 key +- 校验不生效 + - 检查 FormItem.Rule 的 trigger 与 rules 配置；确认 Form.validateFields 调用时机 +- 日期异常 + - 确认输入为秒级时间戳；检查 dayjs 转换链路与 defaultValue/defaultPickerValue + +章节来源 + +- [frontend/antd/auto-complete/auto-complete.tsx:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) +- [frontend/antd/date-picker/date-picker.tsx:126-170](file://frontend/antd/date-picker/date-picker.tsx#L126-L170) +- [frontend/antd/time-picker/time-picker.tsx:109-143](file://frontend/antd/time-picker/time-picker.tsx#L109-L143) +- [frontend/antd/form/item/rule/form.item.rule.tsx](file://frontend/antd/form/item/rule/form.item.rule.tsx) + +## 结论 + +本项目通过统一的封装模式与 hooks 工具，实现了 Ant Design 组件在前端的高一致性与强扩展性。围绕数据绑定、验证规则、格式化选项与复杂表单设计，提供了清晰的实践路径。建议在实际业务中结合虚拟滚动、懒加载与防抖策略，持续优化性能；同时完善可访问性与键盘操作，提升用户体验。 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\346\227\245\346\234\237\346\227\266\351\227\264\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\346\227\245\346\234\237\346\227\266\351\227\264\347\273\204\344\273\266.md" new file mode 100644 index 00000000..29b90e6b --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\346\227\245\346\234\237\346\227\266\351\227\264\347\273\204\344\273\266.md" @@ -0,0 +1,463 @@ +# 日期时间组件 + + +**本文引用的文件** +- [frontend/antd/date-picker/date-picker.tsx](file://frontend/antd/date-picker/date-picker.tsx) +- [frontend/antd/date-picker/context.ts](file://frontend/antd/date-picker/context.ts) +- [frontend/antd/date-picker/preset/date-picker.preset.tsx](file://frontend/antd/date-picker/preset/date-picker.preset.tsx) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx) +- [frontend/antd/time-picker/time-picker.tsx](file://frontend/antd/time-picker/time-picker.tsx) +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx) +- [frontend/antd/calendar/calendar.tsx](file://frontend/antd/calendar/calendar.tsx) +- [frontend/antd/statistic/statistic.tsx](file://frontend/antd/statistic/statistic.tsx) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx](file://frontend/antd/statistic/countdown/statistic.countdown.tsx) +- [frontend/antd/statistic/timer/statistic.timer.tsx](file://frontend/antd/statistic/timer/statistic.timer.tsx) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件系统性梳理模型空间工作室前端中与“日期时间”相关的组件与能力，覆盖以下主题： + +- 日期选择器（DatePicker）与日期范围选择（DateRangePicker） +- 时间选择器（TimePicker）与时间范围选择（TimeRangePicker） +- 日历（Calendar） +- 统计数值（Statistic）中的倒计时（Countdown）与定时器（Timer） +- 日期格式化、时区与时间单位转换、范围选择、快捷选项（预设）、禁用日期/时间 +- 本地化（ConfigProvider）与国际化配置（locales） +- 验证规则与业务场景应用 +- 可访问性与键盘导航 +- 复杂日期时间场景的处理模式与最佳实践 + +## 项目结构 + +围绕日期时间组件的前端实现主要位于 antd 前缀目录下，采用 Svelte + React 包装（sveltify）的方式桥接 Ant Design 组件，统一通过 ConfigProvider 提供主题与国际化。 + +```mermaid +graph TB +subgraph "日期时间组件" +DP["DatePicker
日期选择器"] +DRP["DateRangePicker
日期范围选择器"] +TP["TimePicker
时间选择器"] +TRP["TimeRangePicker
时间范围选择器"] +CAL["Calendar
日历"] +STAT["Statistic
统计数值"] +CD["Statistic.Countdown
倒计时"] +TM["Statistic.Timer
定时器"] +end +subgraph "桥接层" +Sveltify["sveltify 包装"] +Slots["插槽渲染
renderParamsSlot/ReactSlot"] +Hooks["工具钩子
useFunction/useMemo"] +end +subgraph "国际化与主题" +CP["ConfigProvider
主题/弹窗容器/渲染空态"] +LOCALES["locales.ts
多语言映射与按需加载"] +end +DP --> Sveltify +DRP --> Sveltify +TP --> Sveltify +TRP --> Sveltify +CAL --> Sveltify +STAT --> Sveltify +CD --> Sveltify +TM --> Sveltify +Sveltify --> Slots +Sveltify --> Hooks +CP --> LOCALES +CP --> Sveltify +``` + +图表来源 + +- [frontend/antd/date-picker/date-picker.tsx:40-231](file://frontend/antd/date-picker/date-picker.tsx#L40-L231) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:29-245](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L29-L245) +- [frontend/antd/time-picker/time-picker.tsx:37-198](file://frontend/antd/time-picker/time-picker.tsx#L37-L198) +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx:26-207](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx#L26-L207) +- [frontend/antd/calendar/calendar.tsx:17-99](file://frontend/antd/calendar/calendar.tsx#L17-L99) +- [frontend/antd/statistic/statistic.tsx:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:6-24](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L6-L24) +- [frontend/antd/statistic/timer/statistic.timer.tsx:10-26](file://frontend/antd/statistic/timer/statistic.timer.tsx#L10-L26) +- [frontend/antd/config-provider/config-provider.tsx:53-151](file://frontend/antd/config-provider/config-provider.tsx#L53-L151) +- [frontend/antd/config-provider/locales.ts:89-863](file://frontend/antd/config-provider/locales.ts#L89-L863) + +章节来源 + +- [frontend/antd/date-picker/date-picker.tsx:1-234](file://frontend/antd/date-picker/date-picker.tsx#L1-L234) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:1-248](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L1-L248) +- [frontend/antd/time-picker/time-picker.tsx:1-201](file://frontend/antd/time-picker/time-picker.tsx#L1-L201) +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx:1-211](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx#L1-L211) +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [frontend/antd/statistic/statistic.tsx:1-34](file://frontend/antd/statistic/statistic.tsx#L1-L34) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:1-27](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L1-L27) +- [frontend/antd/statistic/timer/statistic.timer.tsx:1-29](file://frontend/antd/statistic/timer/statistic.timer.tsx#L1-L29) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) + +## 核心组件 + +- 日期选择器（DatePicker）：支持日期与时间选择、范围选择、预设快捷项、禁用日期/时间、面板切换回调、弹窗容器自定义等。 +- 时间选择器（TimePicker）：支持时间选择、范围选择、禁用时间、面板切换与日历联动回调。 +- 日历（Calendar）：提供完整月份视图，支持单元格自定义渲染、头部渲染、有效范围限制。 +- 统计数值（Statistic）：基础统计展示；Countdown 倒计时与 Timer 定时器均以秒为输入单位，内部自动转换毫秒传递给底层组件。 + +章节来源 + +- [frontend/antd/date-picker/date-picker.tsx:40-170](file://frontend/antd/date-picker/date-picker.tsx#L40-L170) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:29-177](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L29-L177) +- [frontend/antd/time-picker/time-picker.tsx:37-143](file://frontend/antd/time-picker/time-picker.tsx#L37-L143) +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx:26-146](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx#L26-L146) +- [frontend/antd/calendar/calendar.tsx:17-94](file://frontend/antd/calendar/calendar.tsx#L17-L94) +- [frontend/antd/statistic/statistic.tsx:8-31](file://frontend/antd/statistic/statistic.tsx#L8-L31) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:6-21](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L6-L21) +- [frontend/antd/statistic/timer/statistic.timer.tsx:10-23](file://frontend/antd/statistic/timer/statistic.timer.tsx#L10-L23) + +## 架构总览 + +组件统一通过 sveltify 包装 Ant Design 组件，使用 dayjs 进行日期解析与格式化，对外暴露统一的秒级时间戳接口，内部再转换为毫秒传递给底层组件。ConfigProvider 负责主题算法、弹窗容器、渲染空态以及国际化（Antd 语言包与 dayjs 语言包）。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant C as "组件(如 DatePicker)" +participant F as "格式化函数(formatDayjs/formatDate)" +participant D as "dayjs" +participant A as "Antd 组件" +U->>C : 选择日期/时间 +C->>F : 输入值(可能为秒/毫秒/字符串) +F->>D : 解析为 dayjs 对象 +D-->>F : dayjs 实例 +F-->>C : 格式化为秒级时间戳 +C->>A : 传入毫秒级值与回调参数 +A-->>C : 回调触发(onChange/onPanelChange) +C-->>U : 触发 onValueChange/onChange(秒级时间戳) +``` + +图表来源 + +- [frontend/antd/date-picker/date-picker.tsx:14-38](file://frontend/antd/date-picker/date-picker.tsx#L14-L38) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:14-27](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L14-L27) +- [frontend/antd/time-picker/time-picker.tsx:11-35](file://frontend/antd/time-picker/time-picker.tsx#L11-L35) +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx:11-24](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx#L11-L24) + +## 详细组件分析 + +### 日期选择器（DatePicker） + +- 数据流与格式化 + - 输入支持数字（秒）、字符串、dayjs 对象；内部统一转为 dayjs。 + - 输出统一为秒级时间戳，便于后端或跨组件传递。 +- 关键能力 + - showTime 支持对象形式，默认时间 defaultValue 也会被格式化。 + - disabledDate/disabledTime 自定义禁用逻辑。 + - presets 快捷预设：通过上下文注入，支持动态渲染与格式化。 + - cellRender/panelRender 插槽化渲染。 + - getPopupContainer 自定义弹出容器。 +- 事件回调 + - onValueChange：统一的值变更回调（秒级）。 + - onChange/onPanelChange：原生回调与二次封装回调均可使用。 + +```mermaid +flowchart TD +Start(["开始"]) --> Parse["解析输入为 dayjs"] +Parse --> ShowTime{"是否启用时间?"} +ShowTime --> |是| FormatST["格式化默认时间"] +ShowTime --> |否| SkipST["跳过默认时间"] +FormatST --> Presets["合并/格式化预设项"] +SkipST --> Presets +Presets --> Render["渲染组件并绑定回调"] +Render --> End(["结束"]) +``` + +图表来源 + +- [frontend/antd/date-picker/date-picker.tsx:91-161](file://frontend/antd/date-picker/date-picker.tsx#L91-L161) + +章节来源 + +- [frontend/antd/date-picker/date-picker.tsx:1-234](file://frontend/antd/date-picker/date-picker.tsx#L1-L234) +- [frontend/antd/date-picker/context.ts:1-7](file://frontend/antd/date-picker/context.ts#L1-L7) +- [frontend/antd/date-picker/preset/date-picker.preset.tsx:1-14](file://frontend/antd/date-picker/preset/date-picker.preset.tsx#L1-L14) + +### 日期范围选择器（DateRangePicker） + +- 数据流 + - 输入/输出均为双元素数组 [开始, 结束]，元素为秒级时间戳。 + - 默认值、当前值、面板值均进行 dayjs 格式化与数组映射。 +- 关键能力 + - showTime 的 defaultValue 支持数组映射。 + - presets 同样支持数组格式化。 + - separator 插槽化分隔符。 +- 事件回调 + - onValueChange、onChange、onPanelChange、onCalendarChange 均返回秒级数组。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant RP as "DateRangePicker" +participant F as "formatDates" +participant A as "Antd.RangePicker" +U->>RP : 选择起止日期 +RP->>F : 输入 [开始, 结束](可能为 dayjs/秒) +F-->>RP : 返回 [开始, 结束](秒) +RP->>A : 传入毫秒值与回调 +A-->>RP : 回调触发 +RP-->>U : onValueChange/onChange(秒级数组) +``` + +图表来源 + +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:21-27](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L21-L27) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:165-177](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L165-L177) + +章节来源 + +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:1-248](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L1-L248) + +### 时间选择器（TimePicker） + +- 数据流 + - 输入支持数字（秒）、字符串、dayjs；统一格式化为 dayjs。 + - 输出为秒级数值（number 或 string），onValueChange 保证统一。 +- 关键能力 + - disabledTime/disabledDate 控制可用时间段。 + - cellRender/panelRender 插槽化。 + - onCalendarChange 与 onPanelChange。 +- 事件回调 + - onValueChange 接收秒级值；onChange/onPanelChange 也进行格式化后再回调。 + +```mermaid +flowchart TD +S(["开始"]) --> V["校验/格式化输入为 dayjs"] +V --> DT{"禁用时间?"} +DT --> |是| Block["阻止选择"] +DT --> |否| RenderT["渲染 TimePicker"] +RenderT --> Evt["触发 onChange/onPanelChange/onCalendarChange"] +Evt --> Out["格式化为秒级并回调 onValueChange"] +Out --> End(["结束"]) +``` + +图表来源 + +- [frontend/antd/time-picker/time-picker.tsx:88-143](file://frontend/antd/time-picker/time-picker.tsx#L88-L143) + +章节来源 + +- [frontend/antd/time-picker/time-picker.tsx:1-201](file://frontend/antd/time-picker/time-picker.tsx#L1-L201) + +### 时间范围选择器（TimeRangePicker） + +- 数据流 + - 输入/输出为 [开始, 结束] 数组，元素为秒级时间戳。 + - 默认值、当前值、面板值均进行数组映射格式化。 +- 关键能力 + - disabledTime/disabledDate 控制可用时间段。 + - separator 插槽化分隔符。 +- 事件回调 + - onValueChange、onChange、onPanelChange、onCalendarChange 均返回秒级数组。 + +章节来源 + +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx:1-211](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx#L1-L211) + +### 日历（Calendar） + +- 数据流 + - 输入/输出统一为秒级时间戳；内部转换为毫秒传递给 Antd Calendar。 +- 关键能力 + - validRange 限制有效范围。 + - cellRender/fullCellRender/headerRender 插槽化。 + - onSelect/onPanelChange/onChange 统一回调秒级值。 +- 注意 + - 未直接暴露 disabledDate，可通过外部逻辑控制传入值。 + +章节来源 + +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) + +### 统计数值（Statistic）与倒计时/定时器 + +- Statistic + - 支持 title/prefix/suffix/formatter 插槽化。 +- Statistic.Countdown + - 输入 value 支持秒或毫秒；内部将秒转换为毫秒。 + - 支持 title/prefix/suffix 插槽化。 +- Statistic.Timer + - 输入 value 支持秒或毫秒；内部将秒转换为毫秒。 + - 支持 title/prefix/suffix 插槽化。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant CD as "Countdown" +participant TM as "Timer" +participant A as "Antd.Statistic" +U->>CD : 设置目标时间(秒) +CD->>CD : 秒转毫秒 +CD->>A : 渲染倒计时 +A-->>U : 展示剩余时间 +U->>TM : 设置初始值(秒) +TM->>TM : 秒转毫秒 +TM->>A : 渲染定时器 +A-->>U : 展示累计时间 +``` + +图表来源 + +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:11-21](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L11-L21) +- [frontend/antd/statistic/timer/statistic.timer.tsx:13-23](file://frontend/antd/statistic/timer/statistic.timer.tsx#L13-L23) + +章节来源 + +- [frontend/antd/statistic/statistic.tsx:1-34](file://frontend/antd/statistic/statistic.tsx#L1-L34) +- [frontend/antd/statistic/countdown/statistic.countdown.tsx:1-27](file://frontend/antd/statistic/countdown/statistic.countdown.tsx#L1-L27) +- [frontend/antd/statistic/timer/statistic.timer.tsx:1-29](file://frontend/antd/statistic/timer/statistic.timer.tsx#L1-L29) + +## 依赖关系分析 + +- 组件到工具 + - 使用 dayjs 进行日期解析与格式化。 + - 使用 useFunction/useMemo 将回调与计算稳定化。 + - 使用 renderParamsSlot/ReactSlot 实现插槽化渲染。 +- 组件到上下文 + - DatePicker 预设通过 createItemsContext 注入与消费。 +- 国际化与主题 + - ConfigProvider 负责： + - 主题算法（暗色/紧凑）。 + - 弹窗容器与目标容器函数。 + - 渲染空态。 + - 国际化：Antd 语言包与 dayjs 语言包按需加载。 + - locales.ts 提供语言码到语言包的映射与异步加载。 + +```mermaid +graph LR +DP["DatePicker"] --> Dayjs["dayjs"] +DRP["DateRangePicker"] --> Dayjs +TP["TimePicker"] --> Dayjs +TRP["TimeRangePicker"] --> Dayjs +CAL["Calendar"] --> Dayjs +DP --> Hooks["useFunction/useMemo"] +DRP --> Hooks +TP --> Hooks +TRP --> Hooks +CAL --> Hooks +DP --> Slots["renderParamsSlot/ReactSlot"] +DRP --> Slots +TP --> Slots +TRP --> Slots +CAL --> Slots +CP["ConfigProvider"] --> LOCALES["locales.ts"] +CP --> Theme["主题算法/容器/空态"] +``` + +图表来源 + +- [frontend/antd/date-picker/date-picker.tsx:1-11](file://frontend/antd/date-picker/date-picker.tsx#L1-L11) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:1-7](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L1-L7) +- [frontend/antd/time-picker/time-picker.tsx:1-6](file://frontend/antd/time-picker/time-picker.tsx#L1-L6) +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx:1-6](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx#L1-L6) +- [frontend/antd/calendar/calendar.tsx:1-6](file://frontend/antd/calendar/calendar.tsx#L1-L6) +- [frontend/antd/config-provider/config-provider.tsx:1-11](file://frontend/antd/config-provider/config-provider.tsx#L1-L11) +- [frontend/antd/config-provider/locales.ts:1-10](file://frontend/antd/config-provider/locales.ts#L1-L10) + +章节来源 + +- [frontend/antd/date-picker/date-picker.tsx:1-234](file://frontend/antd/date-picker/date-picker.tsx#L1-L234) +- [frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx:1-248](file://frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx#L1-L248) +- [frontend/antd/time-picker/time-picker.tsx:1-201](file://frontend/antd/time-picker/time-picker.tsx#L1-L201) +- [frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx:1-211](file://frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx#L1-L211) +- [frontend/antd/calendar/calendar.tsx:1-102](file://frontend/antd/calendar/calendar.tsx#L1-L102) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:1-863](file://frontend/antd/config-provider/locales.ts#L1-L863) + +## 性能考量 + +- 格式化与缓存 + - 使用 useMemo 缓存格式化后的 dayjs 值，避免重复计算。 + - useFunction 稳定回调引用，减少不必要的重渲染。 +- 按需加载 + - ConfigProvider 在 locale 变更时按语言包异步加载 Antd 与 dayjs 语言资源，降低首屏体积。 +- 渲染优化 + - 插槽化渲染仅在需要时挂载，减少无关节点开销。 +- 建议 + - 大范围选择或频繁更新时，尽量在上层做节流/防抖。 + - 预设项较多时，建议懒加载与虚拟化渲染。 + +## 故障排查指南 + +- 日期不显示或显示异常 + - 检查输入是否为秒级时间戳；组件内部会将其转换为毫秒。 + - 确认 dayjs 语言已正确设置（ConfigProvider 已自动设置）。 +- 国际化未生效 + - 确认 locale 参数格式符合规范（如 zh_CN、en_US），locales.ts 内有对应映射。 + - 若语言包未加载成功，检查网络与打包配置。 +- 预设项不显示 + - 确认通过上下文注入了预设项，并确保 value 格式为 dayjs。 +- 禁用逻辑无效 + - disabledDate/disabledTime 应为函数；确保通过 useFunction 包装后引用稳定。 +- 回调未触发 + - 确认未同时使用 onValueChange 与 onChange 导致状态不同步。 + - 检查 getPopupContainer 是否正确返回容器。 + +章节来源 + +- [frontend/antd/config-provider/config-provider.tsx:96-105](file://frontend/antd/config-provider/config-provider.tsx#L96-L105) +- [frontend/antd/date-picker/date-picker.tsx:86-90](file://frontend/antd/date-picker/date-picker.tsx#L86-L90) +- [frontend/antd/time-picker/time-picker.tsx:83-87](file://frontend/antd/time-picker/time-picker.tsx#L83-L87) + +## 结论 + +该日期时间组件体系以 Ant Design 为基础，通过统一的格式化与插槽化机制，提供了从日期、时间到日历与统计倒计时/定时器的完整能力。配合 ConfigProvider 的主题与国际化支持，能够满足多语言、多主题场景下的复杂业务需求。建议在实际使用中遵循“统一秒级时间戳”的数据契约，结合 useMemo/useFunction 优化性能，并通过插槽化扩展 UI 表达力。 + +## 附录 + +### 本地化与国际化配置 + +- ConfigProvider + - 支持 themeMode 切换暗色/紧凑算法。 + - 支持 getPopupContainer/getTargetContainer 自定义容器。 + - 支持 renderEmpty 自定义空态。 + - locale 参数支持语言码，locales.ts 提供映射与异步加载。 +- locales.ts + - 提供 80+ 语言码映射，按需加载 Antd 与 dayjs 语言包。 + - 默认语言为 en_US，dayjs 默认语言为 en。 + +章节来源 + +- [frontend/antd/config-provider/config-provider.tsx:53-151](file://frontend/antd/config-provider/config-provider.tsx#L53-L151) +- [frontend/antd/config-provider/locales.ts:89-863](file://frontend/antd/config-provider/locales.ts#L89-L863) + +### 可访问性与键盘导航 + +- 建议 + - 使用标准语义化标签与原生交互，确保键盘可达。 + - 通过 getPopupContainer 将弹出层挂载到可聚焦容器内。 + - 在自定义 cellRender/headerRender 中保留焦点管理与无障碍属性。 + - 对于倒计时/定时器，提供清晰的标题与单位提示，便于读屏软件识别。 + +### 复杂场景处理模式与最佳实践 + +- 跨时区场景 + - 建议统一存储与传输 UTC 秒级时间戳，在展示层根据 ConfigProvider 的 dayjs 语言与地区设置进行本地化显示。 +- 范围选择 + - 使用 DateRangePicker/TimeRangePicker 并在上层校验起止顺序与有效性。 +- 快捷选项 + - 通过 DatePickerPreset 注入预设项，确保 value 为 dayjs，避免格式不一致导致的显示异常。 +- 验证规则 + - 结合 disabledDate/disabledTime 与最小/最大日期限制，形成“禁用 + 校验”的双重保障。 +- 性能 + - 大列表/高频更新场景下，优先使用 useMemo/useCallback 稳定 props 与回调，减少重渲染。 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\350\276\223\345\205\245\347\261\273\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\350\276\223\345\205\245\347\261\273\347\273\204\344\273\266.md" new file mode 100644 index 00000000..88003baf --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\350\276\223\345\205\245\347\261\273\347\273\204\344\273\266.md" @@ -0,0 +1,516 @@ +# 输入类组件 + + +**本文引用的文件** +- [input.tsx](file://frontend/antd/input/input.tsx) +- [input-number.tsx](file://frontend/antd/input-number/input-number.tsx) +- [auto-complete.tsx](file://frontend/antd/auto-complete/auto-complete.tsx) +- [mentions.tsx](file://frontend/antd/mentions/mentions.tsx) +- [input.password.tsx](file://frontend/antd/input/password/input.password.tsx) +- [input.search.tsx](file://frontend/antd/input/search/input.search.tsx) +- [input.textarea.tsx](file://frontend/antd/input/textarea/input.textarea.tsx) +- [input.otp.tsx](file://frontend/antd/input/otp/input.otp.tsx) +- [context.ts](file://frontend/antd/auto-complete/context.ts) +- [hooks/useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [renderItems.ts](file://frontend/utils/renderItems.ts) +- [renderParamsSlot.ts](file://frontend/utils/renderParamsSlot.ts) +- [omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) + +## 简介 + +本章节面向“输入类数据录入组件”的使用与扩展，覆盖以下组件：文本输入框（Input）、数字输入框（InputNumber）、自动完成（AutoComplete）、提及（Mentions）、密码输入框（InputPassword）、搜索框（InputSearch）、多行文本域（InputTextarea）、一次性密码输入框（InputOTP）。文档重点阐述： + +- 输入验证、格式化、防抖处理、字符限制等能力在组件中的实现方式与最佳实践 +- 可访问性与键盘导航支持 +- 与表单验证的集成模式 +- 大数据输入场景下的性能优化策略 + +## 项目结构 + +输入类组件均位于前端 Ant Design 生态封装层，采用统一的“sveltify 包装 + React Slot 插槽 + Hooks 值同步”模式，确保与 Ant Design 组件属性对齐的同时，提供更灵活的插槽化与函数式回调能力。 + +```mermaid +graph TB +subgraph "Antd 输入组件封装" +A["Input
文本输入框"] +B["InputNumber
数字输入框"] +C["AutoComplete
自动完成"] +D["Mentions
提及"] +E["InputPassword
密码输入框"] +F["InputSearch
搜索框"] +G["InputTextarea
多行文本域"] +H["InputOTP
一次性密码输入框"] +end +subgraph "通用工具与钩子" +U1["useValueChange
值变更同步"] +U2["useFunction
函数包装"] +U3["renderItems
选项渲染"] +U4["renderParamsSlot
参数化插槽"] +U5["omitUndefinedProps
属性裁剪"] +end +A --> U1 +A --> U2 +A --> U4 +A --> U5 +B --> U1 +B --> U2 +B --> U4 +C --> U1 +C --> U2 +C --> U3 +C --> U4 +C --> U5 +C -.-> X["AutoComplete 上下文"] +D --> U1 +D --> U2 +D --> U3 +D --> U4 +D --> U5 +E --> U1 +E --> U2 +E --> U4 +E --> U5 +F --> U1 +F --> U2 +F --> U4 +F --> U5 +G --> U1 +G --> U2 +G --> U4 +G --> U5 +H --> U1 +H --> U2 +H --> U4 +``` + +图表来源 + +- [input.tsx:10-116](file://frontend/antd/input/input.tsx#L10-L116) +- [input-number.tsx:7-89](file://frontend/antd/input-number/input-number.tsx#L7-L89) +- [auto-complete.tsx:32-148](file://frontend/antd/auto-complete/auto-complete.tsx#L32-L148) +- [mentions.tsx:11-77](file://frontend/antd/mentions/mentions.tsx#L11-L77) +- [input.password.tsx:10-126](file://frontend/antd/input/password/input.password.tsx#L10-L126) +- [input.search.tsx:10-123](file://frontend/antd/input/search/input.search.tsx#L10-L123) +- [input.textarea.tsx:10-88](file://frontend/antd/input/textarea/input.textarea.tsx#L10-L88) +- [input.otp.tsx:7-54](file://frontend/antd/input/otp/input.otp.tsx#L7-L54) +- [context.ts](file://frontend/antd/auto-complete/context.ts) +- [hooks/useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [renderItems.ts](file://frontend/utils/renderItems.ts) +- [renderParamsSlot.ts](file://frontend/utils/renderParamsSlot.ts) +- [omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +章节来源 + +- [input.tsx:1-119](file://frontend/antd/input/input.tsx#L1-L119) +- [input-number.tsx:1-92](file://frontend/antd/input-number/input-number.tsx#L1-L92) +- [auto-complete.tsx:1-151](file://frontend/antd/auto-complete/auto-complete.tsx#L1-L151) +- [mentions.tsx:1-80](file://frontend/antd/mentions/mentions.tsx#L1-L80) +- [input.password.tsx:1-129](file://frontend/antd/input/password/input.password.tsx#L1-L129) +- [input.search.tsx:1-126](file://frontend/antd/input/search/input.search.tsx#L1-L126) +- [input.textarea.tsx:1-91](file://frontend/antd/input/textarea/input.textarea.tsx#L1-L91) +- [input.otp.tsx:1-57](file://frontend/antd/input/otp/input.otp.tsx#L1-L57) + +## 核心组件 + +本节概述各组件的关键职责与共性设计： + +- 值同步与回调：通过统一的 useValueChange 钩子，将受控值与 onValueChange 回调解耦，保证输入事件与外部状态一致更新。 +- 函数包装：useFunction 将传入的函数（如 formatter、parser、filterOption）转换为稳定引用，避免不必要的重渲染。 +- 插槽系统：通过 ReactSlot 与 renderParamsSlot 支持 slot 自定义渲染（如前缀/后缀、清除图标、下拉项、分隔符等），并允许传参。 +- 属性裁剪：omitUndefinedProps 仅传递有效配置，避免无效属性影响渲染或行为。 +- 选项渲染：renderItems 将插槽中的选项节点转换为 Ant Design 所需的 options 数组，支持默认与自定义选项集合。 + +章节来源 + +- [input.tsx:39-42](file://frontend/antd/input/input.tsx#L39-L42) +- [input-number.tsx:32-35](file://frontend/antd/input-number/input-number.tsx#L32-L35) +- [auto-complete.tsx:63-66](file://frontend/antd/auto-complete/auto-complete.tsx#L63-L66) +- [mentions.tsx:34-37](file://frontend/antd/mentions/mentions.tsx#L34-L37) +- [hooks/useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [renderItems.ts](file://frontend/utils/renderItems.ts) +- [renderParamsSlot.ts](file://frontend/utils/renderParamsSlot.ts) +- [omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +## 架构总览 + +输入组件的统一架构由“封装层 + 工具层 + AntD 原生组件”构成，形成清晰的职责边界与复用路径。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant S as "Svelte 组件(封装)" +participant H as "Hooks/工具" +participant R as "AntD 原生组件" +U->>S : 输入/选择/按键 +S->>H : 触发值同步/函数包装/插槽渲染 +H-->>S : 返回稳定值/函数/渲染结果 +S->>R : 渲染原生组件(带值/回调/插槽) +R-->>S : 触发 onChange/回调 +S->>H : 更新受控值(onValueChange) +H-->>S : 完成同步 +S-->>U : UI 更新 +``` + +图表来源 + +- [input.tsx:47-54](file://frontend/antd/input/input.tsx#L47-L54) +- [input-number.tsx:39-46](file://frontend/antd/input-number/input-number.tsx#L39-L46) +- [auto-complete.tsx:76-104](file://frontend/antd/auto-complete/auto-complete.tsx#L76-L104) +- [mentions.tsx:44-61](file://frontend/antd/mentions/mentions.tsx#L44-L61) +- [hooks/useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) + +## 详细组件分析 + +### 文本输入框（Input） + +- 功能要点 + - 受控值：通过 useValueChange 同步 props.value 与内部状态，onChange 时触发 onValueChange。 + - 字符计数：showCount 支持函数化 formatter；count 支持 strategy/exceedFormatter/show 的组合配置，使用 useMemo 与 omitUndefinedProps 裁剪无效字段。 + - 插槽化装饰：addonBefore/After、prefix/suffix、allowClear.clearIcon 可通过 slots 注入自定义节点。 +- 输入验证与格式化 + - 无内置正则校验，建议结合表单校验器或 onValueChange 内部校验。 + - formatter/parser 由上层传入，此处不涉及。 +- 防抖与字符限制 + - 未内置防抖；可在 onValueChange 中自行实现节流/防抖。 + - maxLength 由 AntD 原生支持，配合 showCount 使用。 +- 可访问性与键盘导航 + - 保持原生 input 行为，遵循浏览器默认键盘交互。 +- 与表单验证集成 + - 推荐在 onValueChange 中进行即时校验，并通过表单上下文暴露的 setFieldError/setFieldValue 更新状态。 +- 性能优化 + - 使用 useMemo 缓存 count 配置，减少重渲染。 + - 仅在 slots 存在时渲染对应装饰节点，避免空分支开销。 + +章节来源 + +- [input.tsx:39-84](file://frontend/antd/input/input.tsx#L39-L84) +- [input.tsx:85-112](file://frontend/antd/input/input.tsx#L85-L112) + +### 数字输入框（InputNumber） + +- 功能要点 + - 受控值与回调：同上，使用 useValueChange 同步值。 + - 格式化/解析：formatter/parser 作为函数传入，useFunction 包装以稳定引用。 + - 控件图标：controls.upIcon/controls.downIcon 支持插槽注入。 + - 装饰与前后缀：addonBefore/After、prefix/suffix 支持插槽。 +- 输入验证与格式化 + - 无内置校验；建议在 onChange 或 onValueChange 中进行范围与格式校验。 + - formatter/parser 用于显示与解析，避免用户输入非数字字符。 +- 防抖与字符限制 + - 未内置防抖；可在 onValueChange 中实现。 +- 可访问性与键盘导航 + - 保持原生数字输入行为，支持上下键增减。 +- 与表单验证集成 + - 在 onValueChange 中执行数值范围与精度校验，联动表单状态。 +- 性能优化 + - formatter/parser 与 controls 图标按需渲染，减少不必要开销。 + +章节来源 + +- [input-number.tsx:32-35](file://frontend/antd/input-number/input-number.tsx#L32-L35) +- [input-number.tsx:47-64](file://frontend/antd/input-number/input-number.tsx#L47-L64) +- [input-number.tsx:79-84](file://frontend/antd/input-number/input-number.tsx#L79-L84) + +### 自动完成（AutoComplete） + +- 功能要点 + - 值同步：useValueChange 同步 value 与 onValueChange。 + - 选项渲染：优先使用传入 options；否则从插槽中提取并使用 renderItems 转换。 + - 下拉渲染：dropdownRender/popupRender 支持插槽与函数两种形式。 + - 过滤逻辑：filterOption 支持函数或布尔值；getPopupContainer 指定弹出容器。 + - 清除与装饰：allowClear.clearIcon、notFoundContent、addonBefore/After、prefix/suffix 支持插槽。 +- 输入验证与格式化 + - 无内置校验；通过 filterOption 与 validateSearch 控制候选集。 + - 建议在 onChange/onValueChange 中进行二次校验。 +- 防抖与字符限制 + - 未内置防抖；可在 onValueChange 中实现。 +- 可访问性与键盘导航 + - 支持键盘上下选择、回车确认、Tab 切换。 +- 与表单验证集成 + - 结合表单上下文在 onValueChange 中设置错误信息。 +- 性能优化 + - 使用 useMemo 缓存 options；仅在 slots 存在时渲染装饰节点。 + +```mermaid +flowchart TD +Start(["输入事件"]) --> Filter["应用 filterOption/validateSearch"] +Filter --> HasOptions{"是否有匹配项?"} +HasOptions -- 是 --> RenderList["渲染候选列表
dropdownRender/popupRender"] +HasOptions -- 否 --> NotFound["渲染 notFoundContent"] +RenderList --> Select["用户选择/回车确认"] +NotFound --> Select +Select --> Sync["useValueChange 同步值"] +Sync --> End(["完成"]) +``` + +图表来源 + +- [auto-complete.tsx:89-100](file://frontend/antd/auto-complete/auto-complete.tsx#L89-L100) +- [auto-complete.tsx:114-135](file://frontend/antd/auto-complete/auto-complete.tsx#L114-L135) +- [mentions.tsx:48-57](file://frontend/antd/mentions/mentions.tsx#L48-L57) + +章节来源 + +- [auto-complete.tsx:63-66](file://frontend/antd/auto-complete/auto-complete.tsx#L63-L66) +- [auto-complete.tsx:89-100](file://frontend/antd/auto-complete/auto-complete.tsx#L89-L100) +- [auto-complete.tsx:114-135](file://frontend/antd/auto-complete/auto-complete.tsx#L114-L135) +- [context.ts](file://frontend/antd/auto-complete/context.ts) + +### 提及（Mentions） + +- 功能要点 + - 值同步：useValueChange 同步 value 与 onValueChange。 + - 选项渲染：优先 options，否则使用插槽 renderItems。 + - 过滤与校验：filterOption、validateSearch 支持函数化。 + - 弹出容器：getPopupContainer 指定容器。 + - 清除与占位：allowClear.clearIcon、notFoundContent 支持插槽。 +- 输入验证与格式化 + - 无内置校验；通过 validateSearch 与 filterOption 控制输入与候选。 +- 防抖与字符限制 + - 未内置防抖；可在 onValueChange 中实现。 +- 可访问性与键盘导航 + - 支持键盘选择与确认。 +- 与表单验证集成 + - 在 onValueChange 中进行格式与内容校验。 +- 性能优化 + - useMemo 缓存 options；按需渲染装饰节点。 + +章节来源 + +- [mentions.tsx:34-37](file://frontend/antd/mentions/mentions.tsx#L34-L37) +- [mentions.tsx:48-57](file://frontend/antd/mentions/mentions.tsx#L48-L57) +- [mentions.tsx:62-71](file://frontend/antd/mentions/mentions.tsx#L62-L71) + +### 密码输入框（InputPassword） + +- 功能要点 + - 受控值：useValueChange 同步 value 与 onValueChange。 + - 显示/隐藏切换：iconRender 支持插槽与函数。 + - 字符计数：showCount/formatter 与 count 配置支持函数化与裁剪。 + - 装饰与清除：addonBefore/After、prefix/suffix、allowClear.clearIcon 支持插槽。 +- 输入验证与格式化 + - 无内置校验；建议在 onValueChange 中进行强度与长度校验。 +- 防抖与字符限制 + - 未内置防抖；可在 onValueChange 中实现。 +- 可访问性与键盘导航 + - 保持原生密码输入行为。 +- 与表单验证集成 + - 在 onValueChange 中执行密码策略校验。 +- 性能优化 + - 使用 useMemo 缓存 count 配置与 iconRender。 + +章节来源 + +- [input.password.tsx:42-45](file://frontend/antd/input/password/input.password.tsx#L42-L45) +- [input.password.tsx:65-79](file://frontend/antd/input/password/input.password.tsx#L65-L79) +- [input.password.tsx:80-94](file://frontend/antd/input/password/input.password.tsx#L80-L94) +- [input.password.tsx:95-122](file://frontend/antd/input/password/input.password.tsx#L95-L122) + +### 搜索框（InputSearch） + +- 功能要点 + - 受控值：useValueChange 同步 value 与 onValueChange。 + - 字符计数：showCount/formatter 与 count 配置支持函数化与裁剪。 + - 搜索按钮：enterButton 支持插槽与文本。 + - 装饰与清除：addonBefore/After、prefix/suffix、allowClear.clearIcon 支持插槽。 +- 输入验证与格式化 + - 无内置校验；建议在 onValueChange 中进行长度与内容校验。 +- 防抖与字符限制 + - 未内置防抖；可在 onValueChange 中实现。 +- 可访问性与键盘导航 + - 支持回车触发搜索。 +- 与表单验证集成 + - 在 onValueChange 中进行搜索词校验。 +- 性能优化 + - 使用 useMemo 缓存 count 配置与 enterButton。 + +章节来源 + +- [input.search.tsx:40-43](file://frontend/antd/input/search/input.search.tsx#L40-L43) +- [input.search.tsx:70-78](file://frontend/antd/input/search/input.search.tsx#L70-L78) +- [input.search.tsx:85-91](file://frontend/antd/input/search/input.search.tsx#L85-L91) +- [input.search.tsx:92-118](file://frontend/antd/input/search/input.search.tsx#L92-L118) + +### 多行文本域（InputTextarea） + +- 功能要点 + - 受控值：useValueChange 同步 value 与 onValueChange。 + - 字符计数：showCount/formatter 与 count 配置支持函数化与裁剪。 + - 清除：allowClear.clearIcon 支持插槽。 +- 输入验证与格式化 + - 无内置校验；建议在 onValueChange 中进行长度与内容校验。 +- 防抖与字符限制 + - 未内置防抖；可在 onValueChange 中实现。 +- 可访问性与键盘导航 + - 支持多行输入与滚动。 +- 与表单验证集成 + - 在 onValueChange 中进行内容与长度校验。 +- 性能优化 + - 使用 useMemo 缓存 count 配置。 + +章节来源 + +- [input.textarea.tsx:32-35](file://frontend/antd/input/textarea/input.textarea.tsx#L32-L35) +- [input.textarea.tsx:62-76](file://frontend/antd/input/textarea/input.textarea.tsx#L62-L76) +- [input.textarea.tsx:77-83](file://frontend/antd/input/textarea/input.textarea.tsx#L77-L83) + +### 一次性密码输入框（InputOTP） + +- 功能要点 + - 受控值：useValueChange 同步 value 与 onValueChange。 + - 分隔符：separator 支持插槽与函数。 + - 格式化：formatter 支持函数。 +- 输入验证与格式化 + - 无内置校验；建议在 onValueChange 中进行长度与字符类型校验。 +- 防抖与字符限制 + - 未内置防抖；可在 onValueChange 中实现。 +- 可访问性与键盘导航 + - 支持逐格输入与自动焦点移动。 +- 与表单验证集成 + - 在 onValueChange 中进行 OTP 校验。 +- 性能优化 + - 使用 useMemo 缓存 formatter 与 separator。 + +章节来源 + +- [input.otp.tsx:25-28](file://frontend/antd/input/otp/input.otp.tsx#L25-L28) +- [input.otp.tsx:38-44](file://frontend/antd/input/otp/input.otp.tsx#L38-L44) +- [input.otp.tsx:46-49](file://frontend/antd/input/otp/input.otp.tsx#L46-L49) + +## 依赖关系分析 + +- 组件到工具层 + - 所有输入组件均依赖 useValueChange 实现受控值同步。 + - useFunction 用于稳定函数引用，避免重渲染。 + - renderItems/renderParamsSlot 用于插槽选项与参数化渲染。 + - omitUndefinedProps 用于裁剪无效属性。 +- 组件间差异 + - AutoComplete/Mentions 依赖上下文与插槽选项渲染。 + - InputNumber/InputPassword/InputSearch/InputTextarea/InputOTP 对 showCount/count/formatter 等配置进行函数化与缓存。 + +```mermaid +graph LR +subgraph "组件" +I["Input"] +N["InputNumber"] +AC["AutoComplete"] +M["Mentions"] +P["InputPassword"] +S["InputSearch"] +T["InputTextarea"] +O["InputOTP"] +end +subgraph "工具" +V["useValueChange"] +F["useFunction"] +RI["renderItems"] +RP["renderParamsSlot"] +OD["omitUndefinedProps"] +end +I --> V +I --> F +I --> RP +I --> OD +N --> V +N --> F +N --> RP +AC --> V +AC --> F +AC --> RI +AC --> RP +AC --> OD +M --> V +M --> F +M --> RI +M --> RP +M --> OD +P --> V +P --> F +P --> RP +P --> OD +S --> V +S --> F +S --> RP +S --> OD +T --> V +T --> F +T --> RP +T --> OD +O --> V +O --> F +O --> RP +``` + +图表来源 + +- [input.tsx:39-84](file://frontend/antd/input/input.tsx#L39-L84) +- [input-number.tsx:32-84](file://frontend/antd/input-number/input-number.tsx#L32-L84) +- [auto-complete.tsx:63-100](file://frontend/antd/auto-complete/auto-complete.tsx#L63-L100) +- [mentions.tsx:34-57](file://frontend/antd/mentions/mentions.tsx#L34-L57) +- [input.password.tsx:42-94](file://frontend/antd/input/password/input.password.tsx#L42-L94) +- [input.search.tsx:40-84](file://frontend/antd/input/search/input.search.tsx#L40-L84) +- [input.textarea.tsx:32-76](file://frontend/antd/input/textarea/input.textarea.tsx#L32-L76) +- [input.otp.tsx:25-44](file://frontend/antd/input/otp/input.otp.tsx#L25-L44) +- [hooks/useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [renderItems.ts](file://frontend/utils/renderItems.ts) +- [renderParamsSlot.ts](file://frontend/utils/renderParamsSlot.ts) +- [omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +## 性能考虑 + +- 受控值同步 + - 使用 useValueChange 统一管理受控值，避免外部状态与组件内部状态不一致导致的重复渲染。 +- 函数引用稳定化 + - useFunction 包装传入函数，减少因 props 变更导致的重新渲染。 +- 插槽渲染优化 + - 仅在 slots 存在时渲染对应节点，避免空分支开销。 +- 配置缓存 + - 使用 useMemo 缓存 showCount/count/formatter 等配置，降低渲染成本。 +- 大数据输入处理 + - 避免在 onValueChange 中执行重型计算；必要时拆分为微任务或使用 Web Worker。 + - 对高频输入（如搜索、自动完成）建议在上游增加防抖/节流策略。 + - 对长文本输入，优先使用 TextArea 并开启必要的字符限制与计数提示。 + +## 故障排查指南 + +- 输入值不同步 + - 检查是否正确传入 onValueChange 且未被覆盖。 + - 确认 useValueChange 的 value 与 props.value 是否一致。 +- 插槽不生效 + - 确认 slots 键名与组件支持的插槽一致（如 allowClear.clearIcon、prefix、suffix、enterButton、separator 等）。 + - 检查 renderParamsSlot 的 key 是否正确。 +- 选项不显示 + - AutoComplete/Mentions 需要提供 options 或通过插槽提供选项；检查 renderItems 的 children 名称与结构。 +- 格式化异常 + - formatter/parser/filterOption 等函数需返回期望类型；使用 useFunction 包装以稳定引用。 +- 计数配置无效 + - 确认 showCount 为对象时提供 formatter；count 配置使用 omitUndefinedProps 裁剪无效字段。 + +章节来源 + +- [hooks/useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [renderItems.ts](file://frontend/utils/renderItems.ts) +- [renderParamsSlot.ts](file://frontend/utils/renderParamsSlot.ts) +- [omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) + +## 结论 + +输入类组件通过统一的封装模式实现了与 Ant Design 的深度兼容与灵活扩展。借助 useValueChange、useFunction、renderItems、renderParamsSlot、omitUndefinedProps 等工具，组件在保证性能的同时提供了强大的插槽化与函数化能力。在实际业务中，建议结合表单验证体系在 onValueChange 中实现输入验证、格式化与防抖策略，并针对大数据输入场景采取缓存与异步处理手段，以获得更佳的用户体验与稳定性。 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\351\200\211\346\213\251\347\261\273\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\351\200\211\346\213\251\347\261\273\347\273\204\344\273\266.md" new file mode 100644 index 00000000..e2aeb43a --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\351\200\211\346\213\251\347\261\273\347\273\204\344\273\266.md" @@ -0,0 +1,673 @@ +# 选择类组件 + + +**本文引用的文件** +- [select.tsx](file://frontend/antd/select/select.tsx) +- [option.tsx](file://frontend/antd/select/option/option.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [group.tsx](file://frontend/antd/checkbox/group/checkbox.group.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [radio.group.tsx](file://frontend/antd/radio/group/radio.group.tsx) +- [switch.tsx](file://frontend/antd/switch/switch.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [option.tsx](file://frontend/antd/segmented/option/segmented.option.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [tree.node.tsx](file://frontend/antd/tree/tree-node/tree.node.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [tree.node.tsx](file://frontend/antd/tree-select/tree-node/tree.node.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [panel.tsx](file://frontend/antd/cascader/panel/panel.tsx) +- [option.tsx](file://frontend/antd/cascader/option/option.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) +- [context.ts](file://frontend/antd/select/context.ts) +- [context.ts](file://frontend/antd/checkbox/context.ts) +- [context.ts](file://frontend/antd/radio/context.ts) +- [context.ts](file://frontend/antd/segmented/context.ts) +- [context.ts](file://frontend/antd/tree/context.ts) +- [context.ts](file://frontend/antd/tree-select/context.ts) +- [context.ts](file://frontend/antd/cascader/context.ts) +- [context.ts](file://frontend/antd/rate/context.ts) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能与虚拟滚动](#性能与虚拟滚动) +8. [可访问性与键盘操作](#可访问性与键盘操作) +9. [故障排查指南](#故障排查指南) +10. [结论](#结论) + +## 简介 + +本文件系统化梳理模型空间前端组件库中的“选择类”组件，覆盖下拉选择器（Select）、多选框（Checkbox）、单选框（Radio）、开关（Switch）、分段控制器（Segmented）、树选择（TreeSelect）、级联选择（Cascader）、穿梭框（Transfer）、树形控件（Tree）与评分（Rate）。文档从数据绑定、选项配置、多选模式、禁用状态等维度展开，并结合复杂场景的设计模式与数据流管理，同时给出可访问性支持与键盘操作建议，以及针对大量选项的虚拟滚动与性能优化策略。 + +## 项目结构 + +选择类组件主要位于前端 Ant Design 组件目录中，采用按功能模块拆分的组织方式：每个组件以独立目录存放，包含入口组件文件与子组件（如 Option、Group、Panel 等），并通过上下文文件（context.ts）统一管理共享状态与配置。 + +```mermaid +graph TB +subgraph "选择类组件目录" +S["select.tsx"] +C["checkbox.tsx"] +R["radio.tsx"] +SW["switch.tsx"] +SG["segmented.tsx"] +TS["tree-select.tsx"] +CA["cascader.tsx"] +T["tree.tsx"] +TR["transfer.tsx"] +RA["rate.tsx"] +end +subgraph "子组件" +SO["option.tsx (select)"] +CO["checkbox.group.tsx"] +RO["radio.group.tsx"] +SGO["segmented.option.tsx"] +TSN["tree.node.tsx (tree-select)"] +TN["tree.node.tsx (tree)"] +CAP["panel.tsx (cascader)"] +CAO["option.tsx (cascader)"] +end +subgraph "上下文" +SC["context.ts (select)"] +CC["context.ts (checkbox)"] +RC["context.ts (radio)"] +SGC["context.ts (segmented)"] +TSC["context.ts (tree-select)"] +CAC["context.ts (cascader)"] +TC["context.ts (tree)"] +RAC["context.ts (rate)"] +end +S --> SO +S --> SC +C --> CO +C --> CC +R --> RO +R --> RC +SG --> SGO +SG --> SGC +TS --> TSN +TS --> TSC +T --> TN +T --> TC +CA --> CAP +CA --> CAO +CA --> CAC +TR --> TR +RA --> RAC +``` + +图表来源 + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [switch.tsx](file://frontend/antd/switch/switch.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) + +章节来源 + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [switch.tsx](file://frontend/antd/switch/switch.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) + +## 核心组件 + +本节概述各组件的关键能力与通用特性： + +- 数据绑定：受控/非受控两种模式，通过 value/checked 等属性与外部状态联动。 +- 选项配置：通过子项组件（Option/Segmented.Option/Tree.Node 等）声明式定义选项集合。 +- 多选模式：Checkbox 支持多选；Select/Cascader/TreeSelect 可配置多选；Transfer 提供左右列表交互。 +- 禁用状态：支持整体禁用与单项禁用，保证不可用选项不响应交互。 +- 受控更新：onChange 回调返回当前选中值，驱动上层状态同步。 + +章节来源 + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [switch.tsx](file://frontend/antd/switch/switch.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) + +## 架构总览 + +选择类组件遵循统一的“容器-子项-上下文”架构： + +- 容器组件负责渲染、状态管理与事件分发； +- 子项组件承载具体选项的展示与交互； +- 上下文文件集中处理默认值、禁用态、多选策略等共享逻辑。 + +```mermaid +classDiagram +class Select { ++value ++mode ++disabled ++onChange() +} +class Option { ++label ++value ++disabled +} +class Checkbox { ++checked ++disabled ++onChange() +} +class CheckboxGroup { ++options[] ++value[] ++disabled ++onChange() +} +class Radio { ++checked ++disabled ++onChange() +} +class RadioGroup { ++options[] ++value ++disabled ++onChange() +} +class Switch { ++checked ++disabled ++onChange() +} +class Segmented { ++value ++disabled ++onChange() +} +class SegmentedOption { ++label ++value ++disabled +} +class Tree { ++treeData[] ++expandedKeys[] ++selectedKeys[] ++multiple ++onChange() +} +class TreeNode { ++title ++key ++disabled +} +class TreeSelect { ++treeData[] ++value ++treeDefaultExpandAll ++onChange() +} +class Cascader { ++options[] ++value[] ++onChange() +} +class CascaderPanel { ++options[] ++onChange() +} +class Transfer { ++dataSource[] ++targetKeys[] ++onChange() +} +class Rate { ++value ++allowHalf ++disabled ++onChange() +} +Select --> Option : "包含" +Checkbox --> CheckboxGroup : "组合" +Radio --> RadioGroup : "组合" +Segmented --> SegmentedOption : "包含" +Tree --> TreeNode : "包含" +TreeSelect --> TreeNode : "包含" +Cascader --> CascaderPanel : "包含" +``` + +图表来源 + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [option.tsx](file://frontend/antd/select/option/option.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [group.tsx](file://frontend/antd/checkbox/group/checkbox.group.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [radio.group.tsx](file://frontend/antd/radio/group/radio.group.tsx) +- [switch.tsx](file://frontend/antd/switch/switch.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [option.tsx](file://frontend/antd/segmented/option/segmented.option.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [tree.node.tsx](file://frontend/antd/tree/tree-node/tree.node.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [tree.node.tsx](file://frontend/antd/tree-select/tree-node/tree.node.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [panel.tsx](file://frontend/antd/cascader/panel/panel.tsx) +- [option.tsx](file://frontend/antd/cascader/option/option.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) + +## 详细组件分析 + +### 下拉选择器（Select） + +- 数据绑定：支持受控 value 与非受控默认值；onChange 返回选中值或值数组（多选）。 +- 选项配置：通过 Option 子项声明 label/value/disabled；支持搜索过滤与标签回填。 +- 多选模式：开启多选时，支持标签化展示与清除单个标签。 +- 禁用状态：容器与单项均可禁用；禁用时不可展开、不可切换。 +- 上下文：context.ts 统一处理默认值、禁用态、多选策略与受控校验。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant S as "Select" +participant O as "Option" +participant C as "Context" +U->>S : 展开下拉 +S->>C : 读取默认值/禁用态 +U->>O : 点击某选项 +O-->>S : 触发选择回调 +S->>S : 更新内部状态 +S-->>U : 关闭下拉并显示选中项 +S->>C : 触发 onChange(value) +``` + +图表来源 + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [option.tsx](file://frontend/antd/select/option/option.tsx) +- [context.ts](file://frontend/antd/select/context.ts) + +章节来源 + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [option.tsx](file://frontend/antd/select/option/option.tsx) +- [context.ts](file://frontend/antd/select/context.ts) + +### 多选框（Checkbox） + +- 数据绑定：单个 Checkbox 为受控 checked；Checkbox.Group 接收 value[] 并通过 onChange 同步。 +- 选项配置：Group 的 options[] 支持直接传入 label/value/disabled；也可使用子项 Checkbox。 +- 多选模式：Group 默认多选；支持全选/反选与半选状态。 +- 禁用状态：Group 级禁用影响全部子项；子项也可单独禁用。 +- 上下文：context.ts 负责默认值、禁用态与多选策略。 + +```mermaid +flowchart TD +Start(["进入 Checkbox.Group"]) --> LoadOptions["加载 options[] 或子项"] +LoadOptions --> Render["渲染子项 Checkbox"] +Render --> Interact{"用户交互？"} +Interact --> |勾选/取消| UpdateValue["更新 value[]"] +UpdateValue --> Callback["触发 onChange(value[])"] +Callback --> End(["完成"]) +``` + +图表来源 + +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [group.tsx](file://frontend/antd/checkbox/group/checkbox.group.tsx) +- [context.ts](file://frontend/antd/checkbox/context.ts) + +章节来源 + +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [group.tsx](file://frontend/antd/checkbox/group/checkbox.group.tsx) +- [context.ts](file://frontend/antd/checkbox/context.ts) + +### 单选框（Radio） + +- 数据绑定：单个 Radio 为受控 checked；Radio.Group 接收 value 并通过 onChange 同步。 +- 选项配置：Group 的 options[] 支持 label/value/disabled；也可使用子项 Radio。 +- 多选模式：Group 为单选；支持清空与禁用。 +- 禁用状态：Group 级禁用影响全部子项；子项也可单独禁用。 +- 上下文：context.ts 负责默认值、禁用态与单选策略。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant RG as "Radio.Group" +participant R as "Radio" +participant C as "Context" +U->>R : 点击选项 +R-->>RG : 触发选择回调 +RG->>C : 应用默认值/禁用态 +RG-->>U : 更新选中态并回调 onChange(value) +``` + +图表来源 + +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [radio.group.tsx](file://frontend/antd/radio/group/radio.group.tsx) +- [context.ts](file://frontend/antd/radio/context.ts) + +章节来源 + +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [radio.group.tsx](file://frontend/antd/radio/group/radio.group.tsx) +- [context.ts](file://frontend/antd/radio/context.ts) + +### 开关（Switch） + +- 数据绑定：受控 checked；onChange 返回新的布尔值。 +- 禁用状态：disabled 禁用交互；支持加载态 loading。 +- 场景：适合二元选择，如“启用/禁用”“是/否”。 + +章节来源 + +- [switch.tsx](file://frontend/antd/switch/switch.tsx) + +### 分段控制器（Segmented） + +- 数据绑定：受控 value；onChange 返回选中值。 +- 选项配置：支持 options[] 或子项 Segmented.Option；可禁用单项。 +- 场景：替代 Radio.Group 的紧凑型选择，适合少量离散选项。 + +```mermaid +classDiagram +class Segmented { ++value ++options[] ++disabled ++onChange() +} +class SegmentedOption { ++label ++value ++disabled +} +Segmented --> SegmentedOption : "包含" +``` + +图表来源 + +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [option.tsx](file://frontend/antd/segmented/option/segmented.option.tsx) +- [context.ts](file://frontend/antd/segmented/context.ts) + +章节来源 + +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [option.tsx](file://frontend/antd/segmented/option/segmented.option.tsx) +- [context.ts](file://frontend/antd/segmented/context.ts) + +### 树形控件（Tree） + +- 数据绑定：受控 selectedKeys/expandedKeys；onChange 返回选中键集合。 +- 选项配置：treeData[] 支持 title/key/children/disabled；支持拖拽、搜索与批量选择。 +- 多选模式：multiple=true 时支持多选；支持受控与非受控。 +- 禁用状态：节点级 disabled；支持批量禁用。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant T as "Tree" +participant TN as "TreeNode" +participant C as "Context" +U->>TN : 点击节点 +TN-->>T : 触发选择/展开 +T->>C : 应用多选/禁用策略 +T-->>U : 更新 selectedKeys/expandedKeys 并回调 +``` + +图表来源 + +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [tree.node.tsx](file://frontend/antd/tree/tree-node/tree.node.tsx) +- [context.ts](file://frontend/antd/tree/context.ts) + +章节来源 + +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [tree.node.tsx](file://frontend/antd/tree/tree-node/tree.node.tsx) +- [context.ts](file://frontend/antd/tree/context.ts) + +### 树选择（TreeSelect） + +- 数据绑定：受控 value；onChange 返回选中键。 +- 选项配置：treeData[] 与 Select 类似的选项声明；支持搜索过滤与标签回填。 +- 多选模式：支持多选与父子联动策略（如仅叶子）。 +- 禁用状态：支持整体与节点级禁用。 + +```mermaid +flowchart TD +Open["展开 TreeSelect"] --> Filter["输入搜索关键词"] +Filter --> List["渲染匹配节点"] +List --> Select["点击节点选择"] +Select --> Update["更新 value 并关闭面板"] +Update --> Callback["触发 onChange(value)"] +``` + +图表来源 + +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [tree.node.tsx](file://frontend/antd/tree-select/tree-node/tree.node.tsx) +- [context.ts](file://frontend/antd/tree-select/context.ts) + +章节来源 + +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [tree.node.tsx](file://frontend/antd/tree-select/tree-node/tree.node.tsx) +- [context.ts](file://frontend/antd/tree-select/context.ts) + +### 级联选择（Cascader） + +- 数据绑定：受控 value[]；onChange 返回完整路径值数组。 +- 选项配置：options[] 支持 label/value/children；支持异步加载子级。 +- 多选模式：通常为单选路径；可通过扩展实现多路径选择。 +- 禁用状态：支持禁用整树与节点级禁用。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant C as "Cascader" +participant P as "CascaderPanel" +participant O as "Option" +participant Ctx as "Context" +U->>C : 打开级联 +C->>Ctx : 读取默认值/禁用态 +U->>P : 选择一级 +P-->>C : 通知变更 +U->>P : 选择二级... +P-->>C : 通知变更 +C-->>U : 完成路径选择并回调 onChange(value[]) +``` + +图表来源 + +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [panel.tsx](file://frontend/antd/cascader/panel/panel.tsx) +- [option.tsx](file://frontend/antd/cascader/option/option.tsx) +- [context.ts](file://frontend/antd/cascader/context.ts) + +章节来源 + +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [panel.tsx](file://frontend/antd/cascader/panel/panel.tsx) +- [option.tsx](file://frontend/antd/cascader/option/option.tsx) +- [context.ts](file://frontend/antd/cascader/context.ts) + +### 穿梭框（Transfer） + +- 数据绑定：受控 targetKeys[]；onChange 返回目标列表键集合。 +- 选项配置：dataSource[] 支持 title/key；支持搜索过滤与批量操作。 +- 多选模式：左侧到右侧的双向移动；支持全选/反选。 +- 禁用状态：支持整体禁用与按钮禁用。 + +```mermaid +flowchart TD +Start(["打开 Transfer"]) --> SearchLeft["左侧搜索"] +SearchLeft --> Move["点击移动按钮"] +Move --> UpdateTarget["更新 targetKeys[]"] +UpdateTarget --> Callback["触发 onChange(targetKeys)"] +Callback --> End(["完成"]) +``` + +图表来源 + +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) + +章节来源 + +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) + +### 评分（Rate） + +- 数据绑定：受控 value；onChange 返回评分值。 +- 选项配置：支持 allowHalf 半星、count 总数、tooltips 文案。 +- 禁用状态：disabled 禁用交互；支持只读 readonly。 +- 场景：快速表达满意度、等级评价。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant RA as "Rate" +participant C as "Context" +U->>RA : 鼠标悬停/点击 +RA->>C : 应用禁用/只读策略 +RA-->>U : 更新 value 并回调 onChange(value) +``` + +图表来源 + +- [rate.tsx](file://frontend/antd/rate/rate.tsx) +- [context.ts](file://frontend/antd/rate/context.ts) + +章节来源 + +- [rate.tsx](file://frontend/antd/rate/rate.tsx) +- [context.ts](file://frontend/antd/rate/context.ts) + +## 依赖关系分析 + +- 组件间耦合度低：容器组件通过子项组件声明式组合，避免强耦合。 +- 上下文集中：各组件的 context.ts 聚合默认值、禁用态与多选策略，降低重复逻辑。 +- 事件链路清晰：从用户交互到容器更新再到回调，形成稳定的数据流。 + +```mermaid +graph LR +Select["Select"] --> Option["Option"] +Checkbox["Checkbox"] --> CheckboxGroup["Checkbox.Group"] +Radio["Radio"] --> RadioGroup["Radio.Group"] +Segmented["Segmented"] --> SegmentedOption["Segmented.Option"] +Tree["Tree"] --> TreeNode["TreeNode"] +TreeSelect["TreeSelect"] --> TreeNode +Cascader["Cascader"] --> Panel["Cascader.Panel"] +Cascader --> Option +Transfer["Transfer"] +Rate["Rate"] +``` + +图表来源 + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) + +章节来源 + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) + +## 性能与虚拟滚动 + +- 大量选项场景建议： + - 使用虚拟滚动：对长列表（如 Select/Tree/Transfer）采用虚拟滚动渲染，仅渲染可视区域内的节点，显著降低 DOM 数量与重排成本。 + - 懒加载与分页：对 TreeSelect/Cascader 支持异步加载子节点，减少初始渲染压力。 + - 缓存与去抖：对搜索过滤与 onChange 回调进行去抖处理，避免频繁重绘。 + - 受控更新优化：在上层表单中合并多次状态变更，减少不必要的重渲染。 +- 具体落地点： + - Select：对 Option 列表启用虚拟滚动与搜索过滤。 + - Tree/TreeSelect：对节点渲染启用虚拟滚动与懒加载。 + - Transfer：对左右列表启用虚拟滚动与批量操作优化。 + +[本节为通用性能指导，无需特定文件引用] + +## 可访问性与键盘操作 + +- 键盘支持： + - 使用 Tab/Shift+Tab 在选项间导航； + - 使用 Enter/Space 确认选择； + - 使用方向键在多选项中移动（如 Tree/Select/Cascader）。 +- 屏幕阅读器友好： + - 为每个选项提供语义化 label； + - 禁用态与错误态提供 aria-\* 属性与提示文案； + - 对评分（Rate）提供数值读屏与工具提示。 +- 建议： + - 为容器组件提供 aria-expanded/aria-controls； + - 为禁用选项提供 aria-disabled； + - 为必填字段提供 aria-required。 + +[本节为通用可访问性指导，无需特定文件引用] + +## 故障排查指南 + +- 常见问题与定位： + - 选中值未更新：检查是否正确传入受控 value 与 onChange；确认容器与子项的 value/checked 一致性。 + - 多选无效：确认 Group 的 options[] 结构与 value[] 类型；检查禁用态与半选状态。 + - 禁用不生效：核对 disabled 属性层级（容器 vs 子项）；检查 context 中的禁用策略。 + - 性能卡顿：对长列表启用虚拟滚动；减少不必要的重渲染与深层嵌套。 +- 调试建议： + - 在 onChange 中打印当前值，验证数据流； + - 使用浏览器开发者工具观察 DOM 数量与重排情况； + - 对 TreeSelect/Cascader 检查异步加载是否正确触发。 + +章节来源 + +- [select.tsx](file://frontend/antd/select/select.tsx) +- [checkbox.tsx](file://frontend/antd/checkbox/checkbox.tsx) +- [radio.tsx](file://frontend/antd/radio/radio.tsx) +- [segmented.tsx](file://frontend/antd/segmented/segmented.tsx) +- [tree.tsx](file://frontend/antd/tree/tree.tsx) +- [tree.select.tsx](file://frontend/antd/tree-select/tree-select.tsx) +- [cascader.tsx](file://frontend/antd/cascader/cascader.tsx) +- [transfer.tsx](file://frontend/antd/transfer/transfer.tsx) +- [rate.tsx](file://frontend/antd/rate/rate.tsx) + +## 结论 + +选择类组件在本项目中实现了统一的容器-子项-上下文架构，具备良好的可扩展性与可维护性。通过受控数据绑定、清晰的选项配置与完善的禁用策略，能够满足从简单二元选择到复杂树形/级联选择的多样化需求。配合虚拟滚动与可访问性设计，可在大规模数据与无障碍场景下保持良好体验。 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\351\242\234\350\211\262\346\226\207\344\273\266\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\351\242\234\350\211\262\346\226\207\344\273\266\347\273\204\344\273\266.md" new file mode 100644 index 00000000..6642a53d --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\346\225\260\346\215\256\345\275\225\345\205\245\347\273\204\344\273\266/\351\242\234\350\211\262\346\226\207\344\273\266\347\273\204\344\273\266.md" @@ -0,0 +1,364 @@ +# 颜色文件组件 + + +**本文引用的文件** +- [color-picker.tsx](file://frontend/antd/color-picker/color-picker.tsx) +- [context.ts（颜色选择器）](file://frontend/antd/color-picker/context.ts) +- [upload.tsx](file://frontend/antd/upload/upload.tsx) +- [upload.ts（工具函数）](file://frontend/utils/upload.ts) +- [slider.tsx](file://frontend/antd/slider/slider.tsx) +- [context.ts（滑动输入条）](file://frontend/antd/slider/context.ts) +- [form.tsx](file://frontend/antd/form/form.tsx) +- [README.md（颜色选择器文档）](file://docs/components/antd/color_picker/README.md) +- [README.md（上传文档）](file://docs/components/antd/upload/README.md) +- [README.md（滑动输入条文档）](file://docs/components/antd/slider/README.md) +- [README.md（表单文档）](file://docs/components/antd/form/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件聚焦于颜色文件与高级输入组件：颜色选择器（ColorPicker）、上传（Upload）、滑动输入条（Slider）、表单（Form）。内容涵盖： + +- 颜色格式转换（RGB、HEX、HSB），渐变色处理与预设色板 +- 上传配置、拖拽上传、文件预览、进度显示与错误处理 +- 表单整体设计模式、字段验证、动态表单与嵌套表单 +- 可访问性与键盘操作支持 +- 大文件处理、并发上传、错误重试等性能优化策略 +- 复杂表单场景的数据流管理与最佳实践 + +## 项目结构 + +这些组件位于前端 Svelte + Ant Design 生态中，通过 sveltify 将 Ant Design 组件桥接为 Svelte 使用，并在必要处封装状态与回调以适配 Gradio 数据域。 + +```mermaid +graph TB +subgraph "Antd 组件层" +CP["ColorPicker
颜色选择器"] +UP["Upload
上传"] +SL["Slider
滑动输入条"] +FM["Form
表单"] +end +subgraph "工具与上下文" +CTX_CP["ColorPicker 上下文"] +CTX_SL["Slider 上下文"] +UT["上传工具函数
URL 解析与拼装"] +end +CP --> CTX_CP +SL --> CTX_SL +UP --> UT +``` + +图示来源 + +- [color-picker.tsx:1-106](file://frontend/antd/color-picker/color-picker.tsx#L1-L106) +- [upload.tsx:1-282](file://frontend/antd/upload/upload.tsx#L1-L282) +- [slider.tsx:1-97](file://frontend/antd/slider/slider.tsx#L1-L97) +- [form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) + +章节来源 + +- [color-picker.tsx:1-106](file://frontend/antd/color-picker/color-picker.tsx#L1-L106) +- [upload.tsx:1-282](file://frontend/antd/upload/upload.tsx#L1-L282) +- [slider.tsx:1-97](file://frontend/antd/slider/slider.tsx#L1-L97) +- [form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) + +## 核心组件 + +- 颜色选择器（ColorPicker） + - 支持 RGB/HEX/HSB 三种颜色格式输出 + - 渐变色解析与多点颜色映射 + - 预设色板渲染与自定义面板/文本插槽 +- 上传（Upload） + - 自定义请求钩子与进度格式化 + - 文件列表规范化、最大数量控制 + - 拖拽/点击上传、预览与图标渲染插槽 +- 滑动输入条（Slider） + - 刻度标记渲染（支持标签插槽） + - 步长与提示容器自定义 +- 表单（Form） + - 值域绑定与变更通知 + - 手动触发重置/提交/校验动作 + - 必填标记与反馈图标插槽 + +章节来源 + +- [color-picker.tsx:11-103](file://frontend/antd/color-picker/color-picker.tsx#L11-L103) +- [upload.tsx:21-279](file://frontend/antd/upload/upload.tsx#L21-L279) +- [slider.tsx:37-94](file://frontend/antd/slider/slider.tsx#L37-L94) +- [form.tsx:15-76](file://frontend/antd/form/form.tsx#L15-L76) + +## 架构总览 + +组件采用“桥接 + 装饰”的架构：以 Ant Design 原生组件为核心，通过 sveltify 包裹并注入值变更回调、插槽渲染与上下文注入，实现与 Gradio 数据域的无缝对接。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant C as "ColorPicker" +participant A as "Antd ColorPicker" +participant F as "格式转换逻辑" +U->>C : 选择颜色/拖拽渐变 +C->>A : 触发 onChange(...) +A-->>C : 返回颜色对象/渐变信息 +C->>F : 根据 value_format 转换为 RGB/HEX/HSB +F-->>C : 输出统一格式数组或字符串 +C-->>U : 回调 onValueChange(...) +``` + +图示来源 + +- [color-picker.tsx:71-95](file://frontend/antd/color-picker/color-picker.tsx#L71-L95) + +章节来源 + +- [color-picker.tsx:1-106](file://frontend/antd/color-picker/color-picker.tsx#L1-L106) + +## 详细组件分析 + +### 颜色选择器（ColorPicker） + +- 功能要点 + - 颜色格式转换：RGB/HEX/HSB 三选一，按 value_format 输出 + - 渐变色处理：遍历渐变点，分别转换为指定格式并返回数组 + - 预设色板：支持传入 presets 或通过上下文注入 + - 插槽扩展：panelRender、showText 的插槽化渲染 +- 关键流程 + +```mermaid +flowchart TD +Start(["开始"]) --> IsGrad{"是否为渐变色？"} +IsGrad --> |是| Iterate["遍历渐变点"] +Iterate --> Convert["按 value_format 转换颜色"] +Convert --> EmitGrad["回调 onValueChange(数组)"] +IsGrad --> |否| Single["单色转换"] +Single --> EmitSingle["回调 onValueChange(字符串)"] +EmitGrad --> End(["结束"]) +EmitSingle --> End +``` + +图示来源 + +- [color-picker.tsx:71-95](file://frontend/antd/color-picker/color-picker.tsx#L71-L95) + +- 上下文与预设色板 + - 通过 createItemsContext 注入 marks/presets 等项集合 + - 预设色板优先使用外部传入，否则从上下文渲染 + +- 可访问性与键盘操作 + - 基于 Ant Design 原生组件，遵循其可访问性规范 + - 建议在业务侧补充 aria-label、aria-describedby 等属性 + +章节来源 + +- [color-picker.tsx:1-106](file://frontend/antd/color-picker/color-picker.tsx#L1-L106) +- [context.ts（颜色选择器）:1-7](file://frontend/antd/color-picker/context.ts#L1-L7) +- [README.md（颜色选择器文档）:1-9](file://docs/components/antd/color_picker/README.md#L1-L9) + +### 上传（Upload） + +- 功能要点 + - 自定义上传：upload(files) -> Promise
backend/modelscope_studio/components/antd/__init__.py"] --> B["前端桥接组件
frontend/antd/*/*.tsx"] +B --> C["配置容器
frontend/antd/config-provider/config-provider.tsx"] +C --> D["国际化与区域
frontend/antd/config-provider/locales.ts"] +E["基础组件
backend/modelscope_studio/components/base/__init__.py"] --> A +F["Pro 扩展组件
backend/modelscope_studio/components/pro/__init__.py"] --> A +G["文档与示例
docs/components/antd/*/demos/*.py"] --> A +G --> B +G --> C +H["版本管理
backend/modelscope_studio/version.py"] --> A +I["依赖锁定
pnpm-lock.yaml"] --> B +``` + +**图表来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/config-provider/locales.ts:313-465](file://frontend/antd/config-provider/locales.ts#L313-L465) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [docs/components/antd/button/demos/basic.py:1-26](file://docs/components/antd/button/demos/basic.py#L1-L26) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [pnpm-lock.yaml:2830](file://pnpm-lock.yaml#L2830-L2835) + +## 组件分类与组织结构 + +根据文档中的导航结构，Ant Design 组件被划分为六大类别，便于按功能域检索与使用： + +- 通用组件 + - 包含：Button、Icon、Typography 等 + - 示例：按钮、图标、排版 +- 布局组件 + - 包含：Divider、Flex、Grid、Layout、Space、Splitter 等 + - 示例：栅格、弹性布局、分割面板、页面布局 +- 导航组件 + - 包含：Anchor、Breadcrumb、Dropdown、Menu、Pagination、Steps 等 + - 示例：锚点、面包屑、下拉菜单、导航菜单、分页、步骤条 +- 数据录入组件 + - 包含：AutoComplete、Cascader、Checkbox、ColorPicker、DatePicker、Form、Input、InputNumber、Mentions、Radio、Rate、Select、Slider、Switch、TimePicker、Transfer、TreeSelect、Upload 等 + - 示例：表单、输入、选择、时间/日期、开关、滑块、上传 +- 数据展示组件 + - 包含：Avatar、Badge、Calendar、Card、Carousel、Collapse、Descriptions、Empty、Image、List、Popover、QRCode、Segmented、Statistic、Table、Tabs、Tag、Timeline、Tooltip、Tour、Tree 等 + - 示例：卡片、表格、标签、时间轴、树形控件、统计数值 +- 反馈组件 + - 包含：Alert、Drawer、Message、Modal、Notification 等 + - 示例：警告提示、抽屉、消息、模态框、通知 + +**更新** 所有组件均已适配 Ant Design 6.3.5 的新 API 和样式规范。 + +上述分类与示例均来自文档侧的导航与示例脚本，便于开发者快速定位组件与参考用法。 + +**章节来源** + +- [docs/app.py:200-399](file://docs/app.py#L200-L399) +- [docs/components/antd/button/demos/basic.py:1-26](file://docs/components/antd/button/demos/basic.py#L1-L26) +- [docs/components/antd/form/demos/basic.py:1-94](file://docs/components/antd/form/demos/basic.py#L1-L94) +- [docs/components/antd/layout/demos/basic.py:1-88](file://docs/components/antd/layout/demos/basic.py#L1-L88) + +## 组件使用原则与最佳实践 + +- 统一入口：通过导入 antd 模块获得所有组件，避免分散导入。 +- 包裹容器：所有 antd 组件必须置于 Application 与 ConfigProvider 之间，确保依赖与样式正常生效。 +- 加载态反馈：建议使用 AutoLoading 在请求期间自动显示加载动画，提升用户体验。 +- 事件绑定：事件采用 Gradio 6.0 的事件绑定形式，参数通过数组形式存储于特定字段，注意解构与处理。 +- 插槽机制：Python 无法直接传递组件作为参数，需使用 Slot 包裹模块；若仅为字符串或数字可直接作为属性传入。 +- 函数传参：将 JS 函数以字符串形式传入，前端会自动编译为函数；返回 ReactNode 的函数可通过两种方式处理：作为普通节点渲染或通过全局 React 对象生成。 +- 插槽兼容：部分组件插槽仅支持 modelscope_studio 组件，若要插入其他 Gradio 组件，需使用 Fragment 包裹。 + +**更新** 事件系统已完全适配 Gradio 6.0 的新事件模型，插槽机制也进行了相应优化。 + +**章节来源** + +- [docs/components/antd/overview/README.md:13-75](file://docs/components/antd/overview/README.md#L13-L75) +- [docs/components/base/fragment/README-zh_CN.md:1-10](file://docs/components/base/fragment/README-zh_CN.md#L1-L10) + +## 响应式设计与国际化 + +- 响应式设计：组件遵循 Ant Design 6.3.5 的响应式规范，结合 Flex、Grid 等布局组件实现自适应布局。 +- 国际化：ConfigProvider 支持多语言切换，内置大量语言与地区映射，自动加载对应语言包与日期库语言，满足多语言站点需求。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant CFG as "ConfigProvider" +participant L as "locales.ts" +participant D as "dayjs" +U->>CFG : 设置语言标识 +CFG->>L : 解析语言标识并加载对应语言包 +L-->>CFG : 返回 Antd 6.3.5 语言包与 dayjs 语言 +CFG->>D : 设置 dayjs 语言 +CFG-->>U : 应用语言配置 +``` + +**图表来源** + +- [frontend/antd/config-provider/config-provider.tsx:85-105](file://frontend/antd/config-provider/config-provider.tsx#L85-L105) +- [frontend/antd/config-provider/locales.ts:313-465](file://frontend/antd/config-provider/locales.ts#L313-L465) + +**章节来源** + +- [frontend/antd/config-provider/config-provider.tsx:15-27](file://frontend/antd/config-provider/config-provider.tsx#L15-L27) +- [frontend/antd/config-provider/locales.ts:313-465](file://frontend/antd/config-provider/locales.ts#L313-L465) + +## 主题定制与样式系统 + +- 主题模式：通过 ConfigProvider 的 themeMode 控制暗色/紧凑算法，支持动态切换。 +- 主题令牌：支持设置主色等令牌，结合算法实现主题风格统一。 +- 样式注入：使用样式提供器确保组件前缀与样式隔离，避免冲突。 + +```mermaid +flowchart TD +Start(["进入 ConfigProvider"]) --> Parse["解析 themeMode 与算法"] +Parse --> Merge["合并算法与主题令牌"] +Merge --> Apply["应用到 Ant Design 6.3.5 主题"] +Apply --> Inject["注入样式提供器"] +Inject --> End(["完成主题渲染"]) +``` + +**图表来源** + +- [frontend/antd/config-provider/config-provider.tsx:88-143](file://frontend/antd/config-provider/config-provider.tsx#L88-L143) + +**章节来源** + +- [frontend/antd/config-provider/config-provider.tsx:53-151](file://frontend/antd/config-provider/config-provider.tsx#L53-L151) + +## 典型应用场景与组合使用 + +- 快速开始：在 Application 与 ConfigProvider 包裹下，使用 Button、Icon、Typography 等通用组件构建基础界面。 +- 表单场景：使用 Form 与 Form.Item 组合 Input、Select、DatePicker、Upload 等数据录入组件，结合校验规则与提交回调。 +- 页面布局：使用 Layout、Grid、Flex、Space 等布局组件搭建页面骨架，配合 Sider、Header、Content、Footer 实现复杂页面结构。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant App as "Application" +participant Cfg as "ConfigProvider" +participant Btn as "Button" +participant Form as "Form" +participant Lay as "Layout" +Dev->>App : 创建应用上下文 +App->>Cfg : 注入全局配置(主题/语言) +Cfg->>Btn : 渲染按钮组件 +Cfg->>Form : 渲染表单组件 +Cfg->>Lay : 渲染布局组件 +Btn-->>Dev : 触发事件与交互 +Form-->>Dev : 收集数据与校验 +Lay-->>Dev : 布局结构输出 +``` + +**图表来源** + +- [docs/components/antd/button/demos/basic.py:5-26](file://docs/components/antd/button/demos/basic.py#L5-L26) +- [docs/components/antd/form/demos/basic.py:16-94](file://docs/components/antd/form/demos/basic.py#L16-L94) +- [docs/components/antd/layout/demos/basic.py:42-88](file://docs/components/antd/layout/demos/basic.py#L42-L88) + +**章节来源** + +- [docs/components/antd/button/demos/basic.py:1-26](file://docs/components/antd/button/demos/basic.py#L1-L26) +- [docs/components/antd/form/demos/basic.py:1-94](file://docs/components/antd/form/demos/basic.py#L1-L94) +- [docs/components/antd/layout/demos/basic.py:1-88](file://docs/components/antd/layout/demos/basic.py#L1-L88) + +## 组件依赖关系与集成模式 + +- 组件依赖：各组件通过后端导出模块统一暴露，前端以独立包管理版本与类型。 +- 插槽与上下文：前端通过插槽上下文与参数映射机制，支持复杂嵌套与动态渲染。 +- 初始化流程：组件加载前需等待初始化完成，确保全局对象可用。 +- 事件与属性映射：前端对属性与事件进行统一映射，保证与 Gradio 6.0 事件模型一致。 + +**更新** 依赖关系已更新以反映 Gradio 6.0 和 Ant Design 6.3.5 的新版本要求。 + +```mermaid +graph LR +PY["后端导出模块"] --> FE["前端组件实现"] +FE --> CTX["插槽上下文与参数映射"] +FE --> INIT["初始化流程"] +FE --> EVT["事件与属性映射"] +CTX --> REN["渲染管线"] +INIT --> REN +EVT --> REN +SUB["子包管理"] --> FE +LOCK["依赖锁定"] --> FE +``` + +**图表来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [frontend/svelte-preprocess-react/svelte-contexts/slot.svelte.ts:55-102](file://frontend/svelte-preprocess-react/svelte-contexts/slot.svelte.ts#L55-L102) +- [frontend/svelte-preprocess-react/component/import.ts:1-20](file://frontend/svelte-preprocess-react/component/import.ts#L1-L20) +- [frontend/svelte-preprocess-react/component/props.svelte.ts:258-312](file://frontend/svelte-preprocess-react/component/props.svelte.ts#L258-L312) +- [frontend/antd/button/package.json:1-15](file://frontend/antd/button/package.json#L1-L15) +- [pnpm-lock.yaml:2830](file://pnpm-lock.yaml#L2830-L2835) + +**章节来源** + +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/svelte-preprocess-react/svelte-contexts/slot.svelte.ts:55-102](file://frontend/svelte-preprocess-react/svelte-contexts/slot.svelte.ts#L55-L102) +- [frontend/svelte-preprocess-react/component/import.ts:1-20](file://frontend/svelte-preprocess-react/component/import.ts#L1-L20) +- [frontend/svelte-preprocess-react/component/props.svelte.ts:258-312](file://frontend/svelte-preprocess-react/component/props.svelte.ts#L258-L312) + +## 性能考量 + +- 按需渲染：通过插槽与条件渲染减少不必要的组件实例化。 +- 主题与国际化懒加载：语言包与主题算法按需加载，降低初始开销。 +- 事件与属性映射：统一映射减少重复计算与 DOM 操作。 +- 布局组件优化：优先使用 Flex、Grid 等现代布局，减少重排与回流。 + +**更新** 性能优化已针对 Gradio 6.0 的新架构进行调整，提供更好的渲染性能。 + +[本节为通用指导，无需具体文件引用] + +## 故障排查指南 + +- 页面未成功预览：确认所有组件均包裹在 Application 内。 +- 样式异常：确认 ConfigProvider 已正确包裹，且 themeMode、locale 设置符合预期。 +- 事件无响应：检查事件绑定是否采用 Gradio 6.0 形式，参数是否正确解构。 +- 插槽不生效：确认使用 Slot 包裹模块，或直接传入字符串/数字；若需插入其他 Gradio 组件，使用 Fragment 包裹。 +- 函数传参问题：将函数以字符串形式传入，前端会自动编译；返回 ReactNode 的函数可选择插槽或全局 React 对象生成。 + +**更新** 故障排查指南已更新以反映 Gradio 6.0 的新事件系统和组件生命周期变化。 + +**章节来源** + +- [docs/components/antd/overview/README.md:13-75](file://docs/components/antd/overview/README.md#L13-L75) +- [docs/components/base/fragment/README-zh_CN.md:1-10](file://docs/components/base/fragment/README-zh_CN.md#L1-L10) + +## 结论 + +modelscope_studio 将 Ant Design 6.3.5 组件与 Gradio 6.0 生态深度融合，提供统一的组件导出、配置容器与文档示例，帮助开发者快速构建美观、可维护的界面。通过明确的分类体系、严格的使用原则与完善的国际化、主题与插槽机制，组件库在易用性与扩展性之间取得良好平衡。建议在实际项目中遵循"Application + ConfigProvider"包裹原则，善用插槽与事件映射，结合布局组件实现响应式与可访问性友好的界面。 + +**更新** 版本升级带来了更好的性能、更稳定的事件系统和更现代化的主题支持，为开发者提供了更优质的开发体验。 diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Button \346\214\211\351\222\256.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Button \346\214\211\351\222\256.md" new file mode 100644 index 00000000..3830bb15 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Button \346\214\211\351\222\256.md" @@ -0,0 +1,312 @@ +# Button 按钮 + + +**本文引用的文件** +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/button/group/button.group.tsx](file://frontend/antd/button/group/button.group.tsx) +- [frontend/antd/button/group/Index.svelte](file://frontend/antd/button/group/Index.svelte) +- [backend/modelscope_studio/components/antd/button/__init__.py](file://backend/modelscope_studio/components/antd/button/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [docs/components/antd/button/README-zh_CN.md](file://docs/components/antd/button/README-zh_CN.md) +- [docs/components/antd/button/demos/basic.py](file://docs/components/antd/button/demos/basic.py) +- [docs/components/antd/button/app.py](file://docs/components/antd/button/app.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件系统性地介绍 Button 按钮组件，覆盖其核心功能、属性配置、事件处理机制，并重点说明类型(variant)、尺寸(size)、状态(state)等配置项；解释按钮组(group)的使用与布局控制；提供多种场景下的使用示例路径（如基础按钮、图标按钮、幽灵按钮、虚线按钮等变体）；阐述禁用、加载、危险等特殊状态的处理方式；说明样式定制、主题适配与响应式设计要点；并给出无障碍访问与键盘导航的最佳实践建议。 + +## 项目结构 + +Button 组件由后端 Python 组件类与前端 Svelte/React 包装层共同构成，遵循 Gradio 生态的“组件即上下文”的模式，通过 Slot 机制支持图标与加载态图标的自定义渲染。 + +```mermaid +graph TB +subgraph "后端" +PY_BTN["AntdButton
Python 组件类"] +PY_GROUP["AntdButtonGroup
Python 组件类"] +end +subgraph "前端" +IDX["Index.svelte
组件入口"] +BTN["button.tsx
React 包装"] +SLOT["Slot 处理
icon / loading.icon"] +GROUP_IDX["group/Index.svelte
按钮组入口"] +GROUP_BTN["group/button.group.tsx
Antd Button.Group 包装"] +end +PY_BTN --> IDX +PY_GROUP --> GROUP_IDX +IDX --> BTN +GROUP_IDX --> GROUP_BTN +BTN --> SLOT +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-138](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L138) +- [frontend/antd/button/Index.svelte:10-73](file://frontend/antd/button/Index.svelte#L10-L73) +- [frontend/antd/button/button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) +- [frontend/antd/button/group/Index.svelte:10-61](file://frontend/antd/button/group/Index.svelte#L10-L61) +- [frontend/antd/button/group/button.group.tsx:6-24](file://frontend/antd/button/group/button.group.tsx#L6-L24) + +章节来源 + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-138](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L138) +- [frontend/antd/button/Index.svelte:10-73](file://frontend/antd/button/Index.svelte#L10-L73) +- [frontend/antd/button/button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) +- [frontend/antd/button/group/Index.svelte:10-61](file://frontend/antd/button/group/Index.svelte#L10-L61) +- [frontend/antd/button/group/button.group.tsx:6-24](file://frontend/antd/button/group/button.group.tsx#L6-L24) + +## 核心组件 + +- 后端组件类：AntdButton 提供按钮的全部属性与事件定义，支持类型、变体、尺寸、颜色、形状、状态等配置，并声明支持的插槽（icon、loading.icon）。 +- 前端包装层：Index.svelte 将 Python 属性映射到 React 组件，注入样式与 ID；button.tsx 使用 sveltify 包装 Ant Design 的 Button，并对插槽进行解析与传递。 +- 按钮组：AntdButtonGroup 对应前端的 Button.Group 包装，支持组级样式与主题变量注入。 + +章节来源 + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-138](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L138) +- [frontend/antd/button/Index.svelte:10-73](file://frontend/antd/button/Index.svelte#L10-L73) +- [frontend/antd/button/button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) +- [frontend/antd/button/group/Index.svelte:10-61](file://frontend/antd/button/group/Index.svelte#L10-L61) +- [frontend/antd/button/group/button.group.tsx:6-24](file://frontend/antd/button/group/button.group.tsx#L6-L24) + +## 架构总览 + +下图展示了从 Python 组件到前端渲染的调用链路，以及 Slot 插槽在加载态与图标态的处理流程。 + +```mermaid +sequenceDiagram +participant Py as "Python : AntdButton" +participant Svelte as "Svelte : Index.svelte" +participant Wrap as "React : button.tsx" +participant AD as "Antd : Button" +participant Slot as "Slot 解析" +Py->>Svelte : 传入属性与值 +Svelte->>Wrap : 渲染 React 包装组件 +Wrap->>AD : 传递 props含 icon、loading +Wrap->>Slot : 解析 slots.icon / slots["loading.icon"] +Slot-->>Wrap : 返回 React 节点 +Wrap-->>AD : 注入图标/加载态图标 +AD-->>Svelte : 渲染最终按钮 +``` + +图表来源 + +- [frontend/antd/button/button.tsx:11-36](file://frontend/antd/button/button.tsx#L11-L36) +- [frontend/antd/button/Index.svelte:59-73](file://frontend/antd/button/Index.svelte#L59-L73) +- [backend/modelscope_studio/components/antd/button/**init**.py:41-49](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L49) + +## 详细组件分析 + +### 属性与配置项 + +- 类型与变体 + - type: 支持 primary、dashed、link、text、default + - variant: 支持 outlined、dashed、solid、filled、text、link + - color: 支持 default、primary、danger 与一组预设色名 +- 尺寸与形状 + - size: large、middle、small + - shape: default、circle、round +- 状态与行为 + - disabled：禁用态 + - danger：危险态 + - ghost：幽灵按钮（背景透明） + - loading：布尔或带延迟的加载对象 + - block：块级宽度 + - html_type：button、submit、reset + - href/target：链接按钮与跳转目标 +- 图标与插槽 + - icon：图标名称或节点 + - loading.icon：加载态自定义图标 +- 样式与标识 + - elem_id、elem_classes、elem_style + - class_names、styles、root_class_name + +章节来源 + +- [backend/modelscope_studio/components/antd/button/**init**.py:51-138](file://backend/modelscope_studio/components/antd/button/__init__.py#L51-L138) +- [frontend/antd/button/button.tsx:18-30](file://frontend/antd/button/button.tsx#L18-L30) + +### 事件处理机制 + +- click 事件：通过事件监听器绑定，触发时可更新内部状态以驱动 UI 变化。 +- 典型用法：在示例中为按钮注册点击回调，用于输出日志或触发业务逻辑。 + +章节来源 + +- [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) +- [docs/components/antd/button/demos/basic.py:9-10](file://docs/components/antd/button/demos/basic.py#L9-L10) + +### 插槽与图标处理 + +- 插槽定义：icon、loading.icon +- 渲染策略： + - 若存在 slots.icon，则以 ReactSlot 渲染并克隆 + - loading.icon 存在时，将该节点作为加载态图标，并保留 loading.delay 的数值（当 loading 为对象时） + - 若无插槽，则回退到 props.icon 或 props.loading + +```mermaid +flowchart TD +Start(["进入渲染"]) --> HasIcon{"是否存在 slots.icon?"} +HasIcon --> |是| RenderIcon["渲染 slots.icon克隆"] +HasIcon --> |否| UseIcon["使用 props.icon"] +RenderIcon --> Next1["继续处理 loading"] +UseIcon --> Next1 +Next1 --> HasLoadIcon{"是否存在 slots['loading.icon']?"} +HasLoadIcon --> |是| BuildLoadObj["构建 loading 对象
包含 icon 与 delay"] +HasLoadIcon --> |否| UseLoad["使用 props.loading"] +BuildLoadObj --> End(["完成"]) +UseLoad --> End +``` + +图表来源 + +- [frontend/antd/button/button.tsx:18-30](file://frontend/antd/button/button.tsx#L18-L30) + +章节来源 + +- [frontend/antd/button/button.tsx:11-36](file://frontend/antd/button/button.tsx#L11-L36) + +### 按钮组（Button.Group） + +- 组件入口：group/Index.svelte +- 包装实现：group/button.group.tsx +- 主题适配：通过 Ant Design 的 theme.token.lineWidth 注入 CSS 变量，统一组内边框与间距 +- 适用场景：多个按钮组合排列，共享同一主题风格 + +```mermaid +sequenceDiagram +participant Py as "Python : AntdButtonGroup" +participant Svelte as "Svelte : group/Index.svelte" +participant Wrap as "React : group/button.group.tsx" +participant AD as "Antd : Button.Group" +Py->>Svelte : 传入属性 +Svelte->>Wrap : 渲染包装组件 +Wrap->>AD : 传递 props 并注入主题变量 +AD-->>Svelte : 渲染按钮组 +``` + +图表来源 + +- [frontend/antd/button/group/Index.svelte:48-61](file://frontend/antd/button/group/Index.svelte#L48-L61) +- [frontend/antd/button/group/button.group.tsx:10-24](file://frontend/antd/button/group/button.group.tsx#L10-L24) + +章节来源 + +- [frontend/antd/button/group/Index.svelte:10-61](file://frontend/antd/button/group/Index.svelte#L10-L61) +- [frontend/antd/button/group/button.group.tsx:6-24](file://frontend/antd/button/group/button.group.tsx#L6-L24) + +### 示例与使用场景 + +以下示例均来自文档演示脚本，展示不同变体与状态的按钮用法： + +- 基础按钮：主按钮、默认按钮、虚线按钮、文字按钮、链接按钮 +- 变体与颜色：filled 变体配合 default/danger 颜色 +- 加载态与图标：在加载态下设置图标插槽 +- 块级按钮：block=True 使按钮占满容器宽度 + +示例路径 + +- [docs/components/antd/button/demos/basic.py:9-22](file://docs/components/antd/button/demos/basic.py#L9-L22) + +章节来源 + +- [docs/components/antd/button/demos/basic.py:5-25](file://docs/components/antd/button/demos/basic.py#L5-L25) + +### 样式定制、主题适配与响应式 + +- 样式注入：通过 elem_id、elem_classes、elem_style 为单个按钮或按钮组添加自定义样式 +- 主题变量：按钮组通过 Ant Design 的主题 token 注入 CSS 变量，确保组内边框一致 +- 响应式：结合 Flex/Space 等布局组件，按钮可在不同屏幕尺寸下自动换行与对齐 + +章节来源 + +- [frontend/antd/button/group/button.group.tsx:10-24](file://frontend/antd/button/group/button.group.tsx#L10-L24) +- [docs/components/antd/button/demos/basic.py](file://docs/components/antd/button/demos/basic.py#L8) + +### 无障碍访问与键盘导航 + +- 键盘可达性：按钮原生支持 Enter/Space 触发，建议在复杂交互中提供明确的焦点指示 +- 文字与图标：为图标按钮提供可读的文本替代（aria-label），避免仅靠图标传达关键信息 +- 禁用态与加载态：禁用与加载态应保持视觉一致性，确保用户感知当前不可交互状态 +- 组合按钮：按钮组中建议提供清晰的分组语义，必要时添加标题或分隔线 + +## 依赖关系分析 + +- 组件注册：AntdButton 与 AntdButtonGroup 在后端组件集中导出，便于统一导入与使用 +- 组件基类：ModelScopeLayoutComponent 提供通用的布局能力与事件钩子 +- 前端桥接：通过 sveltify 将 Ant Design 的 React 组件桥接到 Svelte 环境，同时保留 Slot 能力 + +```mermaid +graph LR +Export["components.py 导出"] --> Btn["AntdButton"] +Export --> BtnGroup["AntdButtonGroup"] +Btn --> Base["ModelScopeLayoutComponent"] +BtnGroup --> Base +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/components.py:14-15](file://backend/modelscope_studio/components/antd/components.py#L14-L15) +- [backend/modelscope_studio/utils/dev/component.py:11-27](file://backend/modelscope_studio/utils/dev/component.py#L11-L27) + +章节来源 + +- [backend/modelscope_studio/components/antd/components.py:14-15](file://backend/modelscope_studio/components/antd/components.py#L14-L15) +- [backend/modelscope_studio/utils/dev/component.py:11-27](file://backend/modelscope_studio/utils/dev/component.py#L11-L27) + +## 性能考量 + +- 按钮组主题变量注入：仅在组组件初始化时计算一次 token，避免重复计算开销 +- 插槽渲染：优先使用 slots.icon 与 slots["loading.icon"]，减少不必要的 props 传递 +- 延迟加载：loading 对象支持 delay 字段，避免频繁切换导致的闪烁 + +章节来源 + +- [frontend/antd/button/group/button.group.tsx:10-24](file://frontend/antd/button/group/button.group.tsx#L10-L24) +- [frontend/antd/button/button.tsx:21-29](file://frontend/antd/button/button.tsx#L21-L29) + +## 故障排查指南 + +- 插槽未生效 + - 检查是否正确使用 ms.Slot("icon") 或 ms.Slot("loading.icon") 包裹图标组件 + - 确认 slots 在前端被正确传递 +- 加载态图标不显示 + - 确保 slots["loading.icon"] 存在且为有效节点 + - 当 loading 为对象时，确认 delay 字段是否按预期设置 +- 按钮组样式异常 + - 检查主题 token 是否可用，确认 CSS 变量已注入 +- 事件未触发 + - 确认 click 事件监听器已绑定，且回调函数可执行 + +章节来源 + +- [frontend/antd/button/button.tsx:18-30](file://frontend/antd/button/button.tsx#L18-L30) +- [frontend/antd/button/group/button.group.tsx:10-24](file://frontend/antd/button/group/button.group.tsx#L10-L24) +- [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) + +## 结论 + +Button 按钮组件在本项目中实现了对 Ant Design 的完整封装，具备丰富的类型、变体、尺寸与状态配置，同时通过 Slot 机制灵活支持图标与加载态自定义。按钮组在主题适配与布局控制方面提供了良好的扩展性。结合示例脚本与最佳实践，开发者可以快速构建符合设计规范与无障碍要求的按钮交互。 + +## 附录 + +- 文档入口与示例 + - [docs/components/antd/button/README-zh_CN.md:1-8](file://docs/components/antd/button/README-zh_CN.md#L1-L8) + - [docs/components/antd/button/demos/basic.py:1-26](file://docs/components/antd/button/demos/basic.py#L1-L26) + - [docs/components/antd/button/app.py:1-7](file://docs/components/antd/button/app.py#L1-L7) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/FloatButton \346\202\254\346\265\256\346\214\211\351\222\256.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/FloatButton \346\202\254\346\265\256\346\214\211\351\222\256.md" new file mode 100644 index 00000000..b0ace760 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/FloatButton \346\202\254\346\265\256\346\214\211\351\222\256.md" @@ -0,0 +1,351 @@ +# FloatButton 悬浮按钮 + + +**本文引用的文件** +- [Index.svelte](file://frontend/antd/float-button/Index.svelte) +- [float-button.tsx](file://frontend/antd/float-button/float-button.tsx) +- [group/Index.svelte](file://frontend/antd/float-button/group/Index.svelte) +- [group/float-button.group.tsx](file://frontend/antd/float-button/group/float-button.group.tsx) +- [back-top/Index.svelte](file://frontend/antd/float-button/back-top/Index.svelte) +- [back-top/float-button.back-top.tsx](file://frontend/antd/float-button/back-top/float-button.back-top.tsx) +- [__init__.py](file://backend/modelscope_studio/components/antd/float_button/__init__.py) +- [README-zh_CN.md](file://docs/components/antd/float_button/README-zh_CN.md) +- [app.py](file://docs/components/antd/float_button/app.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +FloatButton 是一个“悬浮按钮”组件，用于在页面任意位置提供全局可访问的功能入口。它基于 Ant Design 的 FloatButton 实现，并通过 Gradio 前端桥接层在模型域中以统一的组件形态呈现。该组件支持图标、描述文本、气泡提示、徽标角标等扩展能力；同时提供“悬浮按钮组”和“回到顶部”两个增强子功能，分别用于组合多个动作以及快速回到页面顶部。 + +设计目标： + +- 在页面任何滚动状态下保持可见，提升用户可达性 +- 提供灵活的布局位置与尺寸控制，满足不同页面风格 +- 支持插槽化扩展（如自定义图标、描述、提示、角标） +- 与滚动容器、内容区域协同，避免遮挡关键信息 +- 覆盖移动端与响应式场景，保证交互体验一致 + +## 项目结构 + +FloatButton 组件由后端 Python 组件类与前端 Svelte/React 包装层共同组成，文档示例通过 docs 层进行演示。 + +```mermaid +graph TB +subgraph "后端" +PY["AntdFloatButton.__init__.py"] +end +subgraph "前端" +IDX["float-button/Index.svelte"] +CMP["float-button.tsx"] +GRP_IDX["float-button/group/Index.svelte"] +GRP_CMP["float-button/group/float-button.group.tsx"] +BT_IDX["float-button/back-top/Index.svelte"] +BT_CMP["float-button/back-top/float-button.back-top.tsx"] +end +subgraph "文档" +DOC_README["docs/.../float_button/README-zh_CN.md"] +DOC_APP["docs/.../float_button/app.py"] +end +PY --> IDX +PY --> GRP_IDX +PY --> BT_IDX +IDX --> CMP +GRP_IDX --> GRP_CMP +BT_IDX --> BT_CMP +DOC_README --> DOC_APP +``` + +图表来源 + +- [**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [Index.svelte:1-70](file://frontend/antd/float-button/Index.svelte#L1-L70) +- [float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [group/Index.svelte:1-72](file://frontend/antd/float-button/group/Index.svelte#L1-L72) +- [group/float-button.group.tsx:1-70](file://frontend/antd/float-button/group/float-button.group.tsx#L1-L70) +- [back-top/Index.svelte:1-73](file://frontend/antd/float-button/back-top/Index.svelte#L1-L73) +- [back-top/float-button.back-top.tsx:1-47](file://frontend/antd/float-button/back-top/float-button.back-top.tsx#L1-L47) +- [README-zh_CN.md:1-8](file://docs/components/antd/float_button/README-zh_CN.md#L1-L8) +- [app.py:1-7](file://docs/components/antd/float_button/app.py#L1-L7) + +章节来源 + +- [**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [README-zh_CN.md:1-8](file://docs/components/antd/float_button/README-zh_CN.md#L1-L8) +- [app.py:1-7](file://docs/components/antd/float_button/app.py#L1-L7) + +## 核心组件 + +- AntdFloatButton：后端组件类，声明事件、插槽与属性，负责将前端组件映射到 Gradio 生态。 +- FloatButton：前端包装器，对接 Ant Design 的 FloatButton，支持插槽注入与函数型回调处理。 +- FloatButton.Group：前端包装器，用于组合多个悬浮按钮，支持关闭图标、形状、主题变量等。 +- FloatButton.BackTop：前端包装器，提供“回到顶部”能力，支持自定义滚动容器获取逻辑。 + +章节来源 + +- [**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [float-button.tsx:14-75](file://frontend/antd/float-button/float-button.tsx#L14-L75) +- [group/float-button.group.tsx:10-70](file://frontend/antd/float-button/group/float-button.group.tsx#L10-L70) +- [back-top/float-button.back-top.tsx:7-47](file://frontend/antd/float-button/back-top/float-button.back-top.tsx#L7-L47) + +## 架构总览 + +下图展示了从后端组件类到前端包装器再到 Ant Design 组件的整体调用链路。 + +```mermaid +sequenceDiagram +participant Py as "后端 AntdFloatButton" +participant Svelte as "Svelte 入口 Index.svelte" +participant Wrap as "React 包装 float-button.tsx" +participant AD as "Ant Design FloatButton" +Py->>Svelte : 渲染组件并传递属性/插槽 +Svelte->>Wrap : 动态导入并传入 props +Wrap->>AD : 注入 icon/description/tooltip/badge 插槽 +AD-->>Wrap : 返回渲染结果 +Wrap-->>Svelte : 渲染完成 +Svelte-->>Py : 组件挂载完成 +``` + +图表来源 + +- [**init**.py:92-96](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L92-L96) +- [Index.svelte:10-69](file://frontend/antd/float-button/Index.svelte#L10-L69) +- [float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) + +## 详细组件分析 + +### 组件一：悬浮按钮（FloatButton） + +- 设计理念 + - 作为页面全局入口，确保在任意滚动位置都可点击触发 + - 通过插槽系统支持图标、描述、提示、角标等扩展 +- 关键特性 + - 插槽支持：icon、description、tooltip、tooltip.title、badge.count + - 回调函数安全处理：对 tooltip.afterOpenChange、tooltip.getPopupContainer 等函数型属性进行包装 + - 可见性控制：通过 visible 控制是否渲染 +- 使用场景 + - 快捷操作入口（如“回到顶部”、“分享”、“反馈”） + - 多状态切换或条件显示的入口按钮 +- 配置要点 + - 图标与形状：icon、shape + - 类型与样式：type、root_class_name、class_names、styles + - 链接与原生属性：href、href_target、html_type + - 角标与提示：badge、tooltip +- 交互行为 + - 支持 click 事件绑定 + - tooltip 支持延迟打开/关闭回调与弹出容器选择 + +```mermaid +classDiagram +class AntdFloatButton { ++EVENTS ++SLOTS ++__init__(...) ++FRONTEND_DIR +} +class FloatButton { ++插槽 : icon, description, tooltip, tooltip.title, badge.count ++函数包装 : afterOpenChange, getPopupContainer +} +AntdFloatButton --> FloatButton : "后端驱动前端" +``` + +图表来源 + +- [**init**.py:12-32](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L32) +- [float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) + +章节来源 + +- [**init**.py:12-110](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L12-L110) +- [Index.svelte:13-51](file://frontend/antd/float-button/Index.svelte#L13-L51) +- [float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) + +### 组件二：悬浮按钮组（FloatButton.Group） + +- 设计理念 + - 将多个悬浮按钮组合为一组，形成复合入口，减少页面元素数量 + - 支持关闭图标、形状（圆形/方形）与主题变量注入 +- 关键特性 + - 插槽支持：icon、closeIcon、description、tooltip、badge.count + - 形状与样式：shape、className、内联样式覆盖主题变量 + - 子项渲染：通过 useSlotsChildren 分离插槽与普通子节点 +- 使用场景 + - 多功能入口聚合（如“编辑/收藏/分享/更多”） + - 需要展开/收起的复合动作区 +- 配置要点 + - 组合形状：shape（circle/square） + - 主题变量：通过 CSS 变量注入圆角半径等 + - 插槽化图标与提示：支持每个子项独立配置 + +```mermaid +classDiagram +class FloatButtonGroup { ++插槽 : icon, closeIcon, description, tooltip, badge.count ++属性 : shape, className, style ++主题 : useToken() ++子项 : useSlotsChildren() +} +``` + +图表来源 + +- [group/float-button.group.tsx:10-67](file://frontend/antd/float-button/group/float-button.group.tsx#L10-L67) + +章节来源 + +- [group/Index.svelte:14-50](file://frontend/antd/float-button/group/Index.svelte#L14-L50) +- [group/float-button.group.tsx:10-67](file://frontend/antd/float-button/group/float-button.group.tsx#L10-L67) + +### 组件三：回到顶部（FloatButton.BackTop） + +- 设计理念 + - 在长页面中提供一键回到顶部的能力，提升导航效率 + - 支持自定义滚动容器获取逻辑，适配复杂布局 +- 关键特性 + - 插槽支持：icon、description、tooltip、badge.count + - 自定义目标容器：target 函数包装，支持动态选择滚动容器 +- 使用场景 + - 内容页、列表页、详情页等长内容页面 + - 需要频繁上下滚动的场景 +- 配置要点 + - 图标与提示：icon、tooltip + - 角标与描述：badge、description + - 滚动容器：target（函数），返回滚动容器 DOM 节点 + +```mermaid +sequenceDiagram +participant User as "用户" +participant BackTop as "BackTop 组件" +participant Target as "target 函数" +participant Scroll as "滚动容器" +User->>BackTop : 点击“回到顶部” +BackTop->>Target : 获取滚动容器 +Target-->>BackTop : 返回 DOM 节点 +BackTop->>Scroll : 平滑滚动至顶部 +Scroll-->>User : 页面回到顶部 +``` + +图表来源 + +- [back-top/float-button.back-top.tsx:7-44](file://frontend/antd/float-button/back-top/float-button.back-top.tsx#L7-L44) + +章节来源 + +- [back-top/Index.svelte:14-50](file://frontend/antd/float-button/back-top/Index.svelte#L14-L50) +- [back-top/float-button.back-top.tsx:7-44](file://frontend/antd/float-button/back-top/float-button.back-top.tsx#L7-L44) + +### 组件四：后端桥接与事件绑定 + +- 后端组件类 + - 定义事件：click（绑定内部事件处理器） + - 定义插槽：icon、description、tooltip、tooltip.title、badge.count + - 前端目录映射：resolve_frontend_dir("float-button") +- 文档与示例 + - README 中包含基础示例占位 + - app.py 用于启动文档站点 + +章节来源 + +- [**init**.py:22-32](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L22-L32) +- [**init**.py:92-96](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L92-L96) +- [README-zh_CN.md:1-8](file://docs/components/antd/float_button/README-zh_CN.md#L1-L8) +- [app.py:1-7](file://docs/components/antd/float_button/app.py#L1-L7) + +## 依赖关系分析 + +- 组件耦合 + - 后端 AntdFloatButton 仅负责属性与事件声明，不直接渲染，降低耦合度 + - 前端通过 Svelte 动态导入包装器，实现按需加载与解耦 +- 插槽与主题 + - Group 组件引入 Ant Design 主题 token，注入 CSS 变量以适配圆角等 +- 函数型属性 + - 通过 useFunction 对 tooltip 回调与 target 进行包装，确保在 React/Svelte 环境中稳定运行 + +```mermaid +graph LR +PY["后端 AntdFloatButton"] --> IDX["Svelte 入口"] +IDX --> WRAP["React 包装器"] +WRAP --> AD["Ant Design 组件"] +WRAP --> THEME["主题 Token 注入"] +WRAP --> FN["useFunction 包装回调"] +``` + +图表来源 + +- [**init**.py:92-96](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L92-L96) +- [Index.svelte:10-69](file://frontend/antd/float-button/Index.svelte#L10-L69) +- [float-button.tsx:20-28](file://frontend/antd/float-button/float-button.tsx#L20-L28) +- [group/float-button.group.tsx:16-31](file://frontend/antd/float-button/group/float-button.group.tsx#L16-L31) +- [back-top/float-button.back-top.tsx:11](file://frontend/antd/float-button/back-top/float-button.back-top.tsx#L11) + +章节来源 + +- [**init**.py:92-96](file://backend/modelscope_studio/components/antd/float_button/__init__.py#L92-L96) +- [float-button.tsx:20-28](file://frontend/antd/float-button/float-button.tsx#L20-L28) +- [group/float-button.group.tsx:16-31](file://frontend/antd/float-button/group/float-button.group.tsx#L16-L31) +- [back-top/float-button.back-top.tsx:11](file://frontend/antd/float-button/back-top/float-button.back-top.tsx#L11) + +## 性能考量 + +- 按需加载 + - Svelte 通过动态导入包装器，避免初始包体膨胀 +- 渲染开销 + - 插槽内容默认隐藏渲染，仅在需要时注入到 Ant Design 组件 +- 回调函数 + - 使用 useFunction 包装函数型属性，减少不必要的重新渲染 +- 主题注入 + - Group 组件通过 CSS 变量注入主题 token，避免重复计算样式 + +章节来源 + +- [Index.svelte:10-10](file://frontend/antd/float-button/Index.svelte#L10-L10) +- [float-button.tsx:30-71](file://frontend/antd/float-button/float-button.tsx#L30-L71) +- [group/float-button.group.tsx:16-31](file://frontend/antd/float-button/group/float-button.group.tsx#L16-L31) + +## 故障排查指南 + +- 无法显示悬浮按钮 + - 检查 visible 是否为 true + - 确认 FRONTEND_DIR 映射正确 +- 插槽未生效 + - 确保插槽名称与组件支持列表一致（icon、description、tooltip、tooltip.title、badge.count） + - Group 组件额外支持 closeIcon、badge.count +- 回到顶部无效 + - 检查 target 函数是否返回有效的滚动容器 DOM 节点 +- Tooltip 回调不触发 + - 确认 tooltip.afterOpenChange、tooltip.getPopupContainer 已通过 useFunction 包装 + +章节来源 + +- [Index.svelte:56-69](file://frontend/antd/float-button/Index.svelte#L56-L69) +- [float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) +- [group/float-button.group.tsx:10-67](file://frontend/antd/float-button/group/float-button.group.tsx#L10-L67) +- [back-top/float-button.back-top.tsx:7-44](file://frontend/antd/float-button/back-top/float-button.back-top.tsx#L7-L44) + +## 结论 + +FloatButton 悬浮按钮组件通过后端桥接与前端包装器的协作，实现了与 Ant Design 的无缝集成与扩展。其插槽化设计、主题注入与函数型属性包装，使得在复杂页面布局中仍能保持良好的可维护性与可扩展性。结合“悬浮按钮组”和“回到顶部”的增强能力，能够覆盖多种常见交互场景，提升用户体验与开发效率。 + +## 附录 + +- 示例与文档 + - 文档示例入口：docs/components/antd/float_button/README-zh_CN.md + - 文档站点启动：docs/components/antd/float_button/app.py + +章节来源 + +- [README-zh_CN.md:1-8](file://docs/components/antd/float_button/README-zh_CN.md#L1-L8) +- [app.py:1-7](file://docs/components/antd/float_button/app.py#L1-L7) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Icon \345\233\276\346\240\207.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Icon \345\233\276\346\240\207.md" new file mode 100644 index 00000000..b45b5a41 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Icon \345\233\276\346\240\207.md" @@ -0,0 +1,360 @@ +# 图标 + + +**本文引用的文件** +- [frontend/antd/icon/Index.svelte](file://frontend/antd/icon/Index.svelte) +- [frontend/antd/icon/icon.tsx](file://frontend/antd/icon/icon.tsx) +- [frontend/antd/icon/iconfont-provider/Index.svelte](file://frontend/antd/icon/iconfont-provider/Index.svelte) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx) +- [backend/modelscope_studio/components/antd/icon/__init__.py](file://backend/modelscope_studio/components/antd/icon/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [docs/components/antd/icon/README-zh_CN.md](file://docs/components/antd/icon/README-zh_CN.md) +- [docs/components/antd/icon/demos/basic.py](file://docs/components/antd/icon/demos/basic.py) +- [docs/components/antd/icon/demos/iconfont.py](file://docs/components/antd/icon/demos/iconfont.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能与优化](#性能与优化) +8. [无障碍与可访问性](#无障碍与可访问性) +9. [故障排查](#故障排查) +10. [结论](#结论) +11. [附录：使用示例与最佳实践](#附录使用示例与最佳实践) + +## 简介 + +本篇文档系统性介绍模型空间 Studio 前端生态中的 Icon 图标组件，涵盖： + +- 使用规范与常见场景（内联图标、按钮图标、导航图标） +- 支持的图标库与图标字体集成（Ant Design 内置图标、iconfont.cn） +- 尺寸、颜色、样式等配置项 +- IconFontProvider 的配置与使用 +- 性能优化、懒加载与缓存策略 +- 无障碍访问、语义化标记与屏幕阅读器兼容 +- 自定义图标库集成方案与最佳实践 + +## 项目结构 + +Icon 组件由“后端 Gradio 组件层”和“前端 Svelte/React 展示层”共同构成，并通过 Slot 机制支持自定义渲染。 + +```mermaid +graph TB +subgraph "后端" +PY_ICON["AntdIcon
Python 组件"] +PY_PROVIDER["AntdIconIconfontProvider
Python 组件"] +end +subgraph "前端" +SV_INDEX["Index.svelte
组件入口Svelte"] +TS_ICON["icon.tsx
React 实现Ant Design Icons"] +SV_PROVIDER_INDEX["iconfont-provider/Index.svelte
Provider 入口Svelte"] +TS_PROVIDER["iconfont-provider.tsx
React ProviderIconFont"] +end +PY_ICON --> SV_INDEX +PY_PROVIDER --> SV_PROVIDER_INDEX +SV_INDEX --> TS_ICON +SV_PROVIDER_INDEX --> TS_PROVIDER +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) +- [frontend/antd/icon/icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [frontend/antd/icon/iconfont-provider/Index.svelte:1-53](file://frontend/antd/icon/iconfont-provider/Index.svelte#L1-L53) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:1-44](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L1-L44) + +章节来源 + +- [backend/modelscope_studio/components/antd/icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) +- [frontend/antd/icon/icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [frontend/antd/icon/iconfont-provider/Index.svelte:1-53](file://frontend/antd/icon/iconfont-provider/Index.svelte#L1-L53) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:1-44](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L1-L44) + +## 核心组件 + +- AntdIcon（后端）：提供 value、spin、rotate、twoToneColor、component 等属性；支持 click 事件绑定；支持名为 “component” 的 Slot 以注入自定义渲染。 +- AntdIconIconfontProvider（后端）：提供 IconFont 上下文，用于在 iconfont.cn 等图标字体库中按 type 渲染图标。 +- 前端 Svelte 入口：负责将后端传入的属性与 Slot 转发给 React 实现。 +- 前端 React 实现：根据 value 选择内置 Ant Design 图标或通过 IconFont 上下文渲染自定义图标类型。 + +章节来源 + +- [backend/modelscope_studio/components/antd/icon/**init**.py:9-88](file://backend/modelscope_studio/components/antd/icon/__init__.py#L9-L88) +- [frontend/antd/icon/Index.svelte:1-67](file://frontend/antd/icon/Index.svelte#L1-L67) +- [frontend/antd/icon/icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [frontend/antd/icon/iconfont-provider/Index.svelte:1-53](file://frontend/antd/icon/iconfont-provider/Index.svelte#L1-L53) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:1-44](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L1-L44) + +## 架构总览 + +下图展示了从后端到前端再到图标渲染的关键调用链路： + +```mermaid +sequenceDiagram +participant Py as "后端 AntdIcon" +participant S as "前端 Index.svelte" +participant R as "React Icon 实现" +participant Ctx as "IconFont 上下文" +Py->>S : 传递 value/props/Slots +S->>R : 渲染 Icon 并透传属性 +alt 使用自定义组件 Slot +R->>R : 使用自定义组件渲染 +else 使用内置或 IconFont +R->>Ctx : 读取 IconFont 上下文 +alt 存在 IconFont +R->>Ctx : 调用 IconFont(type, props) +else 不存在 +R->>R : 渲染 Ant Design 内置图标 +end +end +``` + +图表来源 + +- [frontend/antd/icon/Index.svelte:52-66](file://frontend/antd/icon/Index.svelte#L52-L66) +- [frontend/antd/icon/icon.tsx:17-52](file://frontend/antd/icon/icon.tsx#L17-L52) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:36-41](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L36-L41) + +## 组件详解 + +### AntdIcon（后端） + +- 支持的属性 + - value：字符串，指定图标名称（如内置图标名或 IconFont 类型名） + - spin：布尔，是否旋转动画 + - rotate：角度数值，图标旋转角度 + - twoToneColor：两色图标主色 + - component：根节点组件占位符（用于替换默认容器） + - 元素级样式与类名：elem_style、elem_classes + - 可见性与渲染：visible、render +- 事件 + - click：绑定点击事件 +- Slot + - component：用于注入自定义渲染（例如文本表情、SVG 组件） + +章节来源 + +- [backend/modelscope_studio/components/antd/icon/**init**.py:27-68](file://backend/modelscope_studio/components/antd/icon/__init__.py#L27-L68) +- [backend/modelscope_studio/components/antd/icon/**init**.py:18-22](file://backend/modelscope_studio/components/antd/icon/__init__.py#L18-L22) + +### 前端 Svelte 入口（Index.svelte） + +- 将后端传入的 value、additionalProps、elem\_\* 等属性透传给 React Icon +- 通过 Slot 获取并转发给 React Icon +- 条件渲染：仅在 visible 为真时渲染 + +章节来源 + +- [frontend/antd/icon/Index.svelte:13-66](file://frontend/antd/icon/Index.svelte#L13-L66) + +### React 实现（icon.tsx） + +- 逻辑要点 + - 优先使用 “component” Slot 注入的自定义组件进行渲染 + - 否则若存在内置图标名，则渲染对应 Ant Design 图标 + - 若无内置图标且存在 IconFont 上下文，则通过 IconFont(type, props) 渲染 +- 关键上下文 + - useIconFontContext：获取 IconFont 上下文实例 + +章节来源 + +- [frontend/antd/icon/icon.tsx:17-52](file://frontend/antd/icon/icon.tsx#L17-L52) + +### AntdIconIconfontProvider（后端） + +- 提供 IconFont 上下文，使子级 Icon 能按 type 渲染自定义图标字体 +- 常见用法：包裹一组需要使用 iconfont.cn 的图标 + +章节来源 + +- [backend/modelscope_studio/components/antd/icon/**init**.py:16-16](file://backend/modelscope_studio/components/antd/icon/__init__.py#L16-L16) + +### 前端 Provider（iconfont-provider.tsx） + +- 功能 + - 基于 createFromIconfontCN 创建 IconFont 实例 + - 缓存实例：当 scriptUrl 与 extraCommonProps 不变时复用同一实例 + - 通过 IconFontContext.Provider 暴露给子树 +- 参数 + - scriptUrl：图标字体脚本地址（可为数组） + - extraCommonProps：额外通用属性（如 color、fontSize 等） + +章节来源 + +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:12-41](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L12-L41) + +### Provider 前端入口（iconfont-provider/Index.svelte） + +- 将后端传入的 Provider 属性透传给 React Provider 组件 +- 作为 Icon 的父级上下文容器 + +章节来源 + +- [frontend/antd/icon/iconfont-provider/Index.svelte:42-52](file://frontend/antd/icon/iconfont-provider/Index.svelte#L42-L52) + +## 依赖关系分析 + +- 组件耦合 + - AntdIcon 与 AntdIconIconfontProvider 在后端通过类关联 + - 前端 Svelte 入口与 React 实现解耦，通过属性与 Slot 通信 + - React Icon 依赖 Ant Design Icons 与 IconFont 上下文 +- 外部依赖 + - @ant-design/icons：内置图标库 + - lodash-es isEqual：用于 Provider 实例缓存判断 + +```mermaid +graph LR +PY_ICON["后端 AntdIcon"] --> SV_ICON["Svelte 入口"] +PY_PROVIDER["后端 IconFontProvider"] --> SV_PROVIDER["Svelte Provider 入口"] +SV_ICON --> REACT_ICON["React Icon 实现"] +SV_PROVIDER --> REACT_PROVIDER["React Provider 实现"] +REACT_ICON --> AD["@ant-design/icons"] +REACT_PROVIDER --> ADIF["createFromIconfontCN"] +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/icon/**init**.py:5-6](file://backend/modelscope_studio/components/antd/icon/__init__.py#L5-L6) +- [frontend/antd/icon/icon.tsx:5-5](file://frontend/antd/icon/icon.tsx#L5-L5) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:4-6](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L4-L6) + +章节来源 + +- [backend/modelscope_studio/components/antd/icon/**init**.py:5-6](file://backend/modelscope_studio/components/antd/icon/__init__.py#L5-L6) +- [frontend/antd/icon/icon.tsx:5-5](file://frontend/antd/icon/icon.tsx#L5-L5) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:4-6](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L4-L6) + +## 性能与优化 + +- 懒加载与异步渲染 + - Svelte 入口对 Icon 与 Provider 使用异步 import，避免首屏阻塞 +- 实例缓存 + - Provider 内部基于 scriptUrl 与 extraCommonProps 判等缓存 IconFont 实例，减少重复初始化 +- 渲染路径短路 + - 当存在自定义 Slot 时，直接渲染自定义组件，跳过内置图标解析 +- 建议 + - 对大量图标页面，优先使用 IconFont 并集中管理 scriptUrl + - 合理设置 extraCommonProps，避免频繁重建实例 + - 避免在同一 Provider 下混用过多不同脚本源，减少上下文切换成本 + +章节来源 + +- [frontend/antd/icon/Index.svelte:10-10](file://frontend/antd/icon/Index.svelte#L10-L10) +- [frontend/antd/icon/iconfont-provider/Index.svelte:8-9](file://frontend/antd/icon/iconfont-provider/Index.svelte#L8-L9) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:18-35](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L18-L35) + +## 无障碍与可访问性 + +- 语义化建议 + - 若图标承载交互语义（如“删除”、“搜索”），应配合可读文案或 aria-label + - 对于装饰性图标，可使用 aria-hidden 或不添加额外语义 +- 屏幕阅读器 + - 保持图标具备可替代文本（例如通过相邻文本或 title 属性） + - 避免仅依赖颜色传达信息 +- 样式与焦点 + - 点击类图标需保证可聚焦与键盘可达 + - 旋转/动画不应影响可访问性体验 + +[本节为通用指导，无需特定文件引用] + +## 故障排查 + +- 图标不显示 + - 检查 value 是否为有效内置图标名或 IconFont 类型名 + - 若使用 Provider，请确认 scriptUrl 正确且网络可访问 +- 自定义组件未生效 + - 确认已正确使用 “component” Slot 注入自定义渲染 + - 检查 Slot 名称大小写与传递路径 +- 重复请求或实例抖动 + - Provider 的 extraCommonProps 或 scriptUrl 发生频繁变化会导致实例重建 + - 建议固定参数或合并多个脚本源 + +章节来源 + +- [frontend/antd/icon/icon.tsx:32-51](file://frontend/antd/icon/icon.tsx#L32-L51) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:18-35](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L18-L35) + +## 结论 + +本组件以“后端组件 + 前端异步渲染”的模式，兼顾了 Ant Design 内置图标与 iconfont.cn 等自定义图标字体的统一接入。通过 Slot 机制与上下文缓存，既满足灵活扩展，又保障性能与可维护性。建议在工程中统一管理图标字体资源与样式参数，结合无障碍规范提升用户体验。 + +[本节为总结，无需特定文件引用] + +## 附录：使用示例与最佳实践 + +### 基础用法与内置图标 + +- 场景：内联图标、按钮图标、状态图标 +- 示例参考 + - [docs/components/antd/icon/demos/basic.py:9-17](file://docs/components/antd/icon/demos/basic.py#L9-L17) + +最佳实践 + +- 为交互型图标提供点击回调与可读文案 +- 使用 twoToneColor 控制双色图标主色，保持品牌一致性 + +章节来源 + +- [docs/components/antd/icon/demos/basic.py:9-17](file://docs/components/antd/icon/demos/basic.py#L9-L17) + +### 使用 iconfont.cn + +- 场景：企业图标库、第三方图标字体 +- 示例参考 + - [docs/components/antd/icon/demos/iconfont.py:9-18](file://docs/components/antd/icon/demos/iconfont.py#L9-L18) + +最佳实践 + +- 将多个脚本源合并为数组，减少请求数 +- 通过 extraCommonProps 统一设置 color、fontSize 等通用属性 +- 在 Provider 外层包裹需要使用该字体的图标集合 + +章节来源 + +- [docs/components/antd/icon/demos/iconfont.py:9-18](file://docs/components/antd/icon/demos/iconfont.py#L9-L18) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:29-33](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L29-L33) + +### 自定义图标库集成 + +- 方案一：使用 “component” Slot 注入任意自定义渲染（文本、SVG、组件） + - 示例参考 + - [docs/components/antd/icon/demos/basic.py:19-21](file://docs/components/antd/icon/demos/basic.py#L19-L21) +- 方案二：通过 IconFontProvider 接入自定义字体 + - 示例参考 + - [docs/components/antd/icon/demos/iconfont.py:9-18](file://docs/components/antd/icon/demos/iconfont.py#L9-L18) + +最佳实践 + +- Slot 渲染尽量轻量，避免在图标上执行复杂逻辑 +- 字体资源尽量本地化或使用稳定 CDN，降低加载失败风险 + +章节来源 + +- [docs/components/antd/icon/demos/basic.py:19-21](file://docs/components/antd/icon/demos/basic.py#L19-L21) +- [docs/components/antd/icon/demos/iconfont.py:9-18](file://docs/components/antd/icon/demos/iconfont.py#L9-L18) + +### 配置项速查 + +- AntdIcon（后端） + - value：图标名称 + - spin：旋转动画 + - rotate：旋转角度 + - twoToneColor：双色主色 + - component：根节点组件占位 + - elem_style/elem_classes：元素样式与类名 + - visible/render：可见性与渲染控制 +- AntdIconIconfontProvider（后端） + - script_url：图标字体脚本地址（数组） + - extra_common_props：通用属性（如 color、fontSize） + +章节来源 + +- [backend/modelscope_studio/components/antd/icon/**init**.py:27-68](file://backend/modelscope_studio/components/antd/icon/__init__.py#L27-L68) +- [frontend/antd/icon/iconfont-provider/iconfont-provider.tsx:12-12](file://frontend/antd/icon/iconfont-provider/iconfont-provider.tsx#L12-L12) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Typography \346\216\222\347\211\210.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Typography \346\216\222\347\211\210.md" new file mode 100644 index 00000000..5741f0c8 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/Typography \346\216\222\347\211\210.md" @@ -0,0 +1,251 @@ +# Typography 排版 + + +**本文引用的文件** +- [frontend/antd/typography/Base.svelte](file://frontend/antd/typography/Base.svelte) +- [frontend/antd/typography/typography.base.tsx](file://frontend/antd/typography/typography.base.tsx) +- [frontend/antd/typography/title/Index.svelte](file://frontend/antd/typography/title/Index.svelte) +- [frontend/antd/typography/paragraph/Index.svelte](file://frontend/antd/typography/paragraph/Index.svelte) +- [frontend/antd/typography/text/Index.svelte](file://frontend/antd/typography/text/Index.svelte) +- [frontend/antd/typography/link/Index.svelte](file://frontend/antd/typography/link/Index.svelte) +- [docs/components/antd/typography/README.md](file://docs/components/antd/typography/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Typography 排版组件用于在界面中呈现标题、段落、内联文本与链接等文本内容，统一设计系统中的文字层级、可读性与一致性。该组件基于 Ant Design 的 Typography 能力进行封装，提供复制（copyable）、编辑（editable）与省略（ellipsis）等交互能力，并通过 Svelte 组件体系与 Gradio 集成，支持动态值与插槽化扩展。 + +## 项目结构 + +Typography 在前端侧采用“子组件 + 基础桥接层”的组织方式： + +- Base.svelte：Svelte 层入口，负责属性处理、插槽透传与渲染条件控制 +- typography.base.tsx：React 桥接层，统一调度 Ant Design Typography 各类型组件，并注入 copyable/editable/ellipsis 等高级能力 +- title/paragraph/text/link：四个具体语义化子组件，分别映射到 Ant Design 的 Title/Paragraph/Text/Link + +```mermaid +graph TB +subgraph "Svelte 层" +Base["Base.svelte"] +Title["title/Index.svelte"] +Paragraph["paragraph/Index.svelte"] +Text["text/Index.svelte"] +Link["link/Index.svelte"] +end +subgraph "React 桥接层" +Bridge["typography.base.tsx"] +end +subgraph "Ant Design" +ADT["Typography.Title/Paragraph/Text/Link"] +end +Title --> Base +Paragraph --> Base +Text --> Base +Link --> Base +Base --> Bridge +Bridge --> ADT +``` + +图表来源 + +- [frontend/antd/typography/Base.svelte:11-84](file://frontend/antd/typography/Base.svelte#L11-L84) +- [frontend/antd/typography/typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) + +章节来源 + +- [frontend/antd/typography/Base.svelte:1-85](file://frontend/antd/typography/Base.svelte#L1-L85) +- [frontend/antd/typography/typography.base.tsx:1-170](file://frontend/antd/typography/typography.base.tsx#L1-L170) + +## 核心组件 + +- Base.svelte：负责从 Gradio 属性中提取并转换为 React 可消费的 props；处理可见性、DOM ID/类名、额外属性与插槽；按需渲染基础桥接层 +- typography.base.tsx：根据 component 类型选择对应 Ant Design 组件；统一处理 copyable、editable、ellipsis 的配置与插槽；将组件实例与样式类名注入输出 +- 四个语义化子组件：title、paragraph、text、link，均以 Base 为载体，仅指定 component 即可 + +章节来源 + +- [frontend/antd/typography/Base.svelte:15-62](file://frontend/antd/typography/Base.svelte#L15-L62) +- [frontend/antd/typography/typography.base.tsx:19-80](file://frontend/antd/typography/typography.base.tsx#L19-L80) +- [frontend/antd/typography/title/Index.svelte:1-12](file://frontend/antd/typography/title/Index.svelte#L1-L12) +- [frontend/antd/typography/paragraph/Index.svelte:1-12](file://frontend/antd/typography/paragraph/Index.svelte#L1-L12) +- [frontend/antd/typography/text/Index.svelte:1-12](file://frontend/antd/typography/text/Index.svelte#L1-L12) +- [frontend/antd/typography/link/Index.svelte:1-12](file://frontend/antd/typography/link/Index.svelte#L1-L12) + +## 架构总览 + +下图展示了从 Svelte 到 React 再到 Ant Design Typography 的调用链路，以及 copyable/editable/ellipsis 的装配过程。 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 子组件
title/paragraph/text/link" +participant Base as "Base.svelte" +participant Bridge as "typography.base.tsx" +participant AD as "Ant Design Typography" +Svelte->>Base : 传递 props + 插槽 +Base->>Bridge : 转换并合并 props +Bridge->>Bridge : 解析 copyable/editable/ellipsis 配置与插槽 +Bridge->>AD : 渲染对应组件(Title/Paragraph/Text/Link) +AD-->>Bridge : 返回已装配交互能力的组件 +Bridge-->>Base : 输出最终节点 +Base-->>Svelte : 渲染结果 +``` + +图表来源 + +- [frontend/antd/typography/Base.svelte:65-84](file://frontend/antd/typography/Base.svelte#L65-L84) +- [frontend/antd/typography/typography.base.tsx:69-163](file://frontend/antd/typography/typography.base.tsx#L69-L163) + +## 详细组件分析 + +### 基础桥接层（typography.base.tsx） + +- 组件选择逻辑：依据 component 值在 Title/Paragraph/Text/Link 中切换 +- 能力装配： + - 复制（copyable）：支持自定义图标、提示文案，或通过插槽注入 + - 编辑（editable）：支持编辑图标、提示与回车图标的插槽化替换 + - 省略（ellipsis）：支持省略号符号与工具提示的插槽化替换；对 link 组件有特殊开关行为 +- 插槽与目标解析：通过 useTargets 识别 children 中带特定插槽标记的目标，再用 ReactSlot 渲染 +- 类名与样式：在原 className 基础上追加命名空间类名，便于主题与覆盖 + +```mermaid +flowchart TD +Start(["进入桥接层"]) --> Choose["根据 component 选择 Ant Design 组件"] +Choose --> Copyable{"是否启用复制能力？"} +Copyable --> |是| BuildCopy["合并配置并注入图标/提示插槽"] +Copyable --> |否| SkipCopy["跳过复制配置"] +Choose --> Editable{"是否启用编辑能力？"} +Editable --> |是| BuildEdit["注入编辑图标/提示/回车图标插槽"] +Editable --> |否| SkipEdit["跳过编辑配置"] +Choose --> Ellipsis{"是否启用省略能力？"} +Ellipsis --> |是| BuildEllipsis["注入省略号符号/提示插槽"] +Ellipsis --> |否| SkipEllipsis["跳过省略配置"] +BuildCopy --> Render["渲染最终组件"] +BuildEdit --> Render +BuildEllipsis --> Render +SkipCopy --> Render +SkipEdit --> Render +SkipEllipsis --> Render +Render --> End(["返回渲染结果"]) +``` + +图表来源 + +- [frontend/antd/typography/typography.base.tsx:40-167](file://frontend/antd/typography/typography.base.tsx#L40-L167) + +章节来源 + +- [frontend/antd/typography/typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) + +### Svelte 入口（Base.svelte） + +- 属性处理：从 Gradio 获取组件属性，过滤内部字段，保留对外可用的 props +- 插槽处理：收集并透传插槽，同时将值与 children 进行区分渲染 +- 条件渲染：根据 visible 控制显示；支持 layout 模式下直接渲染 children +- DOM 属性：注入 elem_id、elem_classes、elem_style 等 + +章节来源 + +- [frontend/antd/typography/Base.svelte:15-62](file://frontend/antd/typography/Base.svelte#L15-L62) +- [frontend/antd/typography/Base.svelte:65-84](file://frontend/antd/typography/Base.svelte#L65-L84) + +### 语义化子组件（title/paragraph/text/link） + +- 统一通过 Base.svelte 渲染，仅设置 component 即可切换语义与层级 +- 支持 children 插槽与 value 动态值两种内容来源 +- 对 link 组件的 ellipsis 行为有独立开关逻辑 + +章节来源 + +- [frontend/antd/typography/title/Index.svelte:1-12](file://frontend/antd/typography/title/Index.svelte#L1-L12) +- [frontend/antd/typography/paragraph/Index.svelte:1-12](file://frontend/antd/typography/paragraph/Index.svelte#L1-L12) +- [frontend/antd/typography/text/Index.svelte:1-12](file://frontend/antd/typography/text/Index.svelte#L1-L12) +- [frontend/antd/typography/link/Index.svelte:1-12](file://frontend/antd/typography/link/Index.svelte#L1-L12) + +## 依赖关系分析 + +- 组件耦合 + - 子组件仅依赖 Base.svelte，保持低耦合与高内聚 + - Base.svelte 依赖桥接层，负责跨框架（Svelte → React）的适配 + - 桥接层依赖 Ant Design Typography，集中处理交互能力 +- 插槽与目标解析 + - 使用 useTargets 与 ReactSlot 实现插槽化能力注入，避免硬编码 +- 外部依赖 + - Ant Design Typography：提供标题、段落、文本、链接的基础能力 + - Gradio/Svelte 预处理工具：提供属性处理、插槽上下文与异步组件加载 + +```mermaid +graph LR +Title["title/Index.svelte"] --> Base["Base.svelte"] +Paragraph["paragraph/Index.svelte"] --> Base +Text["text/Index.svelte"] --> Base +Link["link/Index.svelte"] --> Base +Base --> Bridge["typography.base.tsx"] +Bridge --> AD["Ant Design Typography"] +``` + +图表来源 + +- [frontend/antd/typography/title/Index.svelte:9](file://frontend/antd/typography/title/Index.svelte#L9) +- [frontend/antd/typography/paragraph/Index.svelte:9](file://frontend/antd/typography/paragraph/Index.svelte#L9) +- [frontend/antd/typography/text/Index.svelte:9](file://frontend/antd/typography/text/Index.svelte#L9) +- [frontend/antd/typography/link/Index.svelte:9](file://frontend/antd/typography/link/Index.svelte#L9) +- [frontend/antd/typography/Base.svelte:11-13](file://frontend/antd/typography/Base.svelte#L11-L13) +- [frontend/antd/typography/typography.base.tsx:8](file://frontend/antd/typography/typography.base.tsx#L8) + +章节来源 + +- [frontend/antd/typography/Base.svelte:11-13](file://frontend/antd/typography/Base.svelte#L11-L13) +- [frontend/antd/typography/typography.base.tsx:8](file://frontend/antd/typography/typography.base.tsx#L8) + +## 性能考量 + +- 异步组件加载：Base.svelte 通过 importComponent 延迟加载桥接层，减少首屏体积 +- 条件渲染：仅在 visible 为真时渲染；对 ellipsis 的 tooltip 开关进行按需装配，降低不必要开销 +- 插槽渲染：通过 useTargets 与 ReactSlot 仅渲染实际命中插槽的内容，避免全量遍历 + +章节来源 + +- [frontend/antd/typography/Base.svelte:11-13](file://frontend/antd/typography/Base.svelte#L11-L13) +- [frontend/antd/typography/typography.base.tsx:51-64](file://frontend/antd/typography/typography.base.tsx#L51-L64) + +## 故障排查指南 + +- 文本未显示 + - 检查 Base.svelte 的 visible 字段是否为真 + - 确认 children 或 value 是否正确传入 +- 复制/编辑/省略按钮不生效 + - 确认 copyable/editable/ellipsis 的配置对象或插槽是否正确传入 + - 对于 link 组件，确认 ellipsis 的启用条件 +- 插槽图标/提示不出现 + - 检查插槽键名是否匹配（如 copyable.icon、copyable.tooltips、editable.icon 等） + - 确认 useTargets 能够正确识别 children 中的插槽标记 +- 样式异常 + - 确认是否正确注入 elem_classes 与 elem_style + - 检查命名空间类名是否被覆盖 + +章节来源 + +- [frontend/antd/typography/Base.svelte:30-62](file://frontend/antd/typography/Base.svelte#L30-L62) +- [frontend/antd/typography/typography.base.tsx:40-167](file://frontend/antd/typography/typography.base.tsx#L40-L167) + +## 结论 + +Typography 排版组件通过清晰的分层设计，将 Svelte 与 Ant Design 能力有效衔接，既保证了语义化与可维护性，又提供了复制、编辑、省略等丰富的交互能力。其插槽化与条件装配机制使得在不同场景下具备良好的可扩展性与性能表现。 + +## 附录 + +- 使用示例与说明可参考文档页的示例占位符 + - [docs/components/antd/typography/README.md:5-8](file://docs/components/antd/typography/README.md#L5-L8) diff --git "a/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/\351\200\232\347\224\250\347\273\204\344\273\266.md" "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/\351\200\232\347\224\250\347\273\204\344\273\266.md" new file mode 100644 index 00000000..0d5812a5 --- /dev/null +++ "b/.wiki/zh/Ant Design \347\273\204\344\273\266\345\272\223/\351\200\232\347\224\250\347\273\204\344\273\266/\351\200\232\347\224\250\347\273\204\344\273\266.md" @@ -0,0 +1,375 @@ +# 通用组件 + + +**本文引用的文件** +- [button.tsx](file://frontend/antd/button/button.tsx) +- [float-button.tsx](file://frontend/antd/float-button/float-button.tsx) +- [icon.tsx](file://frontend/antd/icon/icon.tsx) +- [typography.base.tsx](file://frontend/antd/typography/typography.base.tsx) +- [basic.py（按钮）](file://docs/components/antd/button/demos/basic.py) +- [basic.py（悬浮按钮）](file://docs/components/antd/float_button/demos/basic.py) +- [basic.py（图标）](file://docs/components/antd/icon/demos/basic.py) +- [basic.py（排版）](file://docs/components/antd/typography/demos/basic.py) +- [README-zh_CN.md（按钮）](file://docs/components/antd/button/README-zh_CN.md) +- [README-zh_CN.md（悬浮按钮）](file://docs/components/antd/float_button/README-zh_CN.md) +- [README-zh_CN.md（图标）](file://docs/components/antd/icon/README-zh_CN.md) +- [README-zh_CN.md（排版）](file://docs/components/antd/typography/README-zh_CN.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本章节面向 Ant Design 通用组件在本仓库中的实现与使用，重点覆盖以下基础通用组件：按钮（Button）、悬浮按钮（FloatButton）、图标（Icon）、排版（Typography）。文档将从系统架构、组件职责、数据与事件流、可访问性与键盘导航、样式与主题定制、组合使用最佳实践以及性能优化等方面进行深入解析，并通过示例路径指引读者快速上手。 + +## 项目结构 + +本项目采用“前端 Svelte 组件封装 + 后端 Gradio 示例演示”的组织方式： + +- 前端组件位于 frontend/antd 下，每个组件由一个 svelte 文件与一个 tsx 封装层组成，tsx 层负责将 Ant Design 的 React 组件桥接到 Svelte 生态，并通过插槽（slots）机制扩展图标、提示、徽标等子内容。 +- 文档示例位于 docs/components/antd 下，每个组件提供多份演示脚本（basic.py 等），用于展示不同属性与交互场景。 + +```mermaid +graph TB +subgraph "前端组件" +BTN["Button
button.tsx"] +FBTN["FloatButton
float-button.tsx"] +ICON["Icon
icon.tsx"] +TYPO["Typography.Base
typography.base.tsx"] +end +subgraph "文档示例" +DEMO_BTN["按钮示例
button/demos/basic.py"] +DEMO_FBTN["悬浮按钮示例
float_button/demos/basic.py"] +DEMO_ICON["图标示例
icon/demos/basic.py"] +DEMO_TYPO["排版示例
typography/demos/basic.py"] +end +BTN --> DEMO_BTN +FBTN --> DEMO_FBTN +ICON --> DEMO_ICON +TYPO --> DEMO_TYPO +``` + +图表来源 + +- [button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [typography.base.tsx:1-170](file://frontend/antd/typography/typography.base.tsx#L1-L170) +- [basic.py（按钮）:1-26](file://docs/components/antd/button/demos/basic.py#L1-L26) +- [basic.py（悬浮按钮）:1-30](file://docs/components/antd/float_button/demos/basic.py#L1-L30) +- [basic.py（图标）:1-24](file://docs/components/antd/icon/demos/basic.py#L1-L24) +- [basic.py（排版）:1-23](file://docs/components/antd/typography/demos/basic.py#L1-L23) + +章节来源 + +- [README-zh_CN.md（按钮）:1-8](file://docs/components/antd/button/README-zh_CN.md#L1-L8) +- [README-zh_CN.md（悬浮按钮）:1-8](file://docs/components/antd/float_button/README-zh_CN.md#L1-L8) +- [README-zh_CN.md（图标）:1-10](file://docs/components/antd/icon/README-zh_CN.md#L1-L10) +- [README-zh_CN.md（排版）:1-8](file://docs/components/antd/typography/README-zh_CN.md#L1-L8) + +## 核心组件 + +- 按钮（Button） + - 职责：封装 Ant Design 的 Button，支持通过插槽注入 icon 与自定义 loading 图标；支持 value 与 children 双入口渲染。 + - 关键点：使用 useTargets 提取插槽目标，动态决定渲染内容；对 loading 配置进行条件合并，兼容对象与布尔值。 +- 悬浮按钮（FloatButton） + - 职责：封装 Ant Design 的 FloatButton，支持 icon、description、tooltip、badge 等插槽化配置；对函数型配置项进行 useFunction 包装以保持响应式。 + - 关键点：tooltip 支持 title 与整体配置对象；badge 支持 count 插槽；description 支持插槽。 +- 图标（Icon） + - 职责：支持 Ant Design 内置图标名称映射与 IconFont 渲染；支持自定义 component 插槽作为 SVG 组件。 + - 关键点：slots.component 优先级最高；否则按 value 映射到内置图标；最后回退到 IconFont 类型。 +- 排版（Typography.Base） + - 职责：统一聚合 Title、Text、Paragraph、Link 四类排版组件，支持 copyable、editable、ellipsis 的插槽化配置。 + - 关键点：根据 component 动态选择具体 Typography 子组件；对多个插槽进行 useTargets 与 renderParamsSlot 处理，保证灵活性与可扩展性。 + +章节来源 + +- [button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [float-button.tsx:1-75](file://frontend/antd/float-button/float-button.tsx#L1-L75) +- [icon.tsx:1-55](file://frontend/antd/icon/icon.tsx#L1-L55) +- [typography.base.tsx:1-170](file://frontend/antd/typography/typography.base.tsx#L1-L170) + +## 架构总览 + +下图展示了通用组件的调用链路：文档示例通过 Gradio 应用启动，内部使用 ConfigProvider 进行全局主题配置，随后渲染各组件；组件内部通过 sveltify 将 Ant Design 的 React 组件桥接为 Svelte 组件，并利用 slots 机制注入图标、提示、徽标等内容。 + +```mermaid +sequenceDiagram +participant Demo as "示例脚本" +participant App as "Gradio 应用" +participant Provider as "ConfigProvider" +participant Comp as "组件封装层" +participant Antd as "Ant Design 组件" +Demo->>App : "构建 Blocks 并启动" +App->>Provider : "应用全局配置" +App->>Comp : "渲染组件实例" +Comp->>Antd : "传递属性与插槽" +Antd-->>Comp : "渲染结果" +Comp-->>App : "返回 Svelte 包装后的节点" +App-->>Demo : "完成一次渲染" +``` + +图表来源 + +- [basic.py（按钮）:5-25](file://docs/components/antd/button/demos/basic.py#L5-L25) +- [basic.py（悬浮按钮）:5-29](file://docs/components/antd/float_button/demos/basic.py#L5-L29) +- [basic.py（图标）:5-23](file://docs/components/antd/icon/demos/basic.py#L5-L23) +- [basic.py（排版）:10-22](file://docs/components/antd/typography/demos/basic.py#L10-L22) +- [button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) +- [float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) +- [icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- [typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) + +## 详细组件分析 + +### 按钮（Button） + +- 设计要点 + - 支持多种类型与变体：如 primary、dashed、text、link、filled 等；支持 block 布局与尺寸控制。 + - 插槽能力：通过 slots.icon 注入图标；通过 slots.loading.icon 注入加载态图标，支持延迟配置。 + - 内容入口：支持直接传入文本（children）或 value 字段；当存在插槽时优先渲染插槽内容。 +- 事件与交互 + - click 事件：示例中演示了点击回调绑定。 + - 加载态：可通过 loading=true 或传入对象配置延迟时间。 +- 样式与主题 + - 通过 ConfigProvider 全局主题生效；支持颜色与变体组合。 +- 使用示例（参考路径） + - 基础用法与变体：[basic.py（按钮）:8-22](file://docs/components/antd/button/demos/basic.py#L8-L22) + - 插槽图标与加载态：[basic.py（按钮）:18-22](file://docs/components/antd/button/demos/basic.py#L18-L22) + +```mermaid +sequenceDiagram +participant U as "用户" +participant Btn as "Button 封装层" +participant RBtn as "Antd Button" +U->>Btn : "点击触发 click 事件" +Btn->>RBtn : "转发点击事件" +RBtn-->>U : "执行回调并更新界面" +Note over Btn,RBtn : "插槽 icon/ loading.icon 由 slots 注入" +``` + +图表来源 + +- [button.tsx:11-36](file://frontend/antd/button/button.tsx#L11-L36) +- [basic.py（按钮）:10-10](file://docs/components/antd/button/demos/basic.py#L10-L10) + +章节来源 + +- [button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) +- [basic.py（按钮）:8-22](file://docs/components/antd/button/demos/basic.py#L8-L22) + +### 悬浮按钮（FloatButton） + +- 设计要点 + - 支持 Group、BackTop 等子组件；支持 icon、description、tooltip、badge 等插槽化配置。 + - tooltip 支持 title 与整体配置对象；badge 支持 count 插槽；description 支持插槽。 + - 对函数型配置项（如 afterOpenChange、getPopupContainer）使用 useFunction 包装，确保响应式更新。 +- 事件与交互 + - 支持点击、可见性控制（BackTop 的 visibility_height）等。 +- 样式与主题 + - 通过 elem_style 自定义位置与布局；结合 Group 实现多按钮编组。 +- 使用示例（参考路径） + - 基础用法与分组：[basic.py（悬浮按钮）:8-13](file://docs/components/antd/float_button/demos/basic.py#L8-L13) + - 徽标与图标：[basic.py（悬浮按钮）:10-12](file://docs/components/antd/float_button/demos/basic.py#L10-L12) + - BackTop 与 Tooltip 插槽：[basic.py（悬浮按钮）:13-13](file://docs/components/antd/float_button/demos/basic.py#L13-L13), [basic.py（悬浮按钮）:23-27](file://docs/components/antd/float_button/demos/basic.py#L23-L27) + +```mermaid +sequenceDiagram +participant U as "用户" +participant F as "FloatButton 封装层" +participant FB as "Antd FloatButton" +U->>F : "点击悬浮按钮" +F->>FB : "转发点击事件" +FB-->>U : "执行回调并显示/隐藏" +Note over F,FB : "tooltip.title/tooltip 插槽与 badge.count 插槽由 slots 注入" +``` + +图表来源 + +- [float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) +- [basic.py（悬浮按钮）:13-13](file://docs/components/antd/float_button/demos/basic.py#L13-L13) +- [basic.py（悬浮按钮）:23-27](file://docs/components/antd/float_button/demos/basic.py#L23-L27) + +章节来源 + +- [float-button.tsx:7-72](file://frontend/antd/float-button/float-button.tsx#L7-L72) +- [basic.py（悬浮按钮）:8-27](file://docs/components/antd/float_button/demos/basic.py#L8-L27) + +### 图标（Icon） + +- 设计要点 + - 支持内置图标名称映射（如 HomeOutlined、SettingFilled 等）；支持 spin、rotate、twoTone 等属性。 + - 支持 IconFont 回退渲染；支持 slots.component 注入自定义 SVG 组件。 +- 事件与交互 + - 示例中演示了点击事件绑定。 +- 样式与主题 + - 支持颜色、旋转角度、两色图标等样式控制。 +- 使用示例（参考路径） + - 基础图标与两色图标：[basic.py（图标）:9-16](file://docs/components/antd/icon/demos/basic.py#L9-L16) + - 自定义组件插槽：[basic.py（图标）:19-21](file://docs/components/antd/icon/demos/basic.py#L19-L21) + +```mermaid +flowchart TD +Start(["进入 Icon 渲染"]) --> CheckSlot["检查 slots.component 是否存在"] +CheckSlot --> |是| RenderCustom["渲染自定义组件"] +CheckSlot --> |否| CheckValue["根据 value 查找内置图标"] +CheckValue --> Found{"找到内置图标？"} +Found --> |是| RenderBuiltIn["渲染内置图标"] +Found --> |否| CheckIconFont["检查 IconFont 上下文"] +CheckIconFont --> HasFont{"有 IconFont？"} +HasFont --> |是| RenderIconFont["使用 IconFont 渲染"] +HasFont --> |否| Empty["不渲染空"] +RenderCustom --> End(["结束"]) +RenderBuiltIn --> End +RenderIconFont --> End +Empty --> End +``` + +图表来源 + +- [icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- [basic.py（图标）:9-16](file://docs/components/antd/icon/demos/basic.py#L9-L16) +- [basic.py（图标）:19-21](file://docs/components/antd/icon/demos/basic.py#L19-L21) + +章节来源 + +- [icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- [basic.py（图标）:9-21](file://docs/components/antd/icon/demos/basic.py#L9-L21) + +### 排版（Typography.Base） + +- 设计要点 + - 统一聚合 Title、Text、Paragraph、Link 四类组件，通过 component 参数切换。 + - 支持 copyable、editable、ellipsis 的插槽化配置，提升可定制性。 + - 使用 useSlotsChildren 与 useTargets 分离插槽内容与普通 children，避免重复渲染。 +- 事件与交互 + - editable_change 事件：示例中演示了编辑变更事件的绑定与输出更新。 +- 样式与主题 + - 通过 className 与组件名前缀生成类名，便于主题覆盖。 +- 使用示例（参考路径） + - 基础标题与文本：[basic.py（排版）:13-15](file://docs/components/antd/typography/demos/basic.py#L13-L15) + - 可复制段落与编辑事件：[basic.py（排版）:16-19](file://docs/components/antd/typography/demos/basic.py#L16-L19) + +```mermaid +sequenceDiagram +participant U as "用户" +participant T as "Typography.Base" +participant TT as "Antd Typography.*" +U->>T : "开始编辑" +T->>TT : "触发 editable 事件" +TT-->>T : "返回编辑结果" +T-->>U : "更新内容并关闭编辑" +Note over T,TT : "copyable/ editable/ ellipsis 插槽由 slots 注入" +``` + +图表来源 + +- [typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) +- [basic.py（排版）:16-19](file://docs/components/antd/typography/demos/basic.py#L16-L19) + +章节来源 + +- [typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) +- [basic.py（排版）:13-19](file://docs/components/antd/typography/demos/basic.py#L13-L19) + +## 依赖关系分析 + +- 组件间耦合 + - Button、FloatButton、Icon、Typography.Base 均通过 sveltify 将 Ant Design 的 React 组件桥接至 Svelte，彼此独立，耦合度低。 + - 插槽机制（slots）贯穿所有组件，用于注入图标、提示、徽标等子内容，提升可扩展性。 +- 外部依赖 + - Ant Design React 组件库：提供基础 UI 能力。 + - @svelte-preprocess-react：提供 sveltify 与 ReactSlot，实现 Svelte 与 React 的互操作。 + - lodash-es：提供工具函数（如 isObject）。 + - @utils/\*：提供 useTargets、useFunction、renderParamsSlot 等工具，增强插槽与事件处理能力。 +- 潜在循环依赖 + - 当前结构未发现循环依赖；组件均通过工具函数与上下文协作，保持单向依赖。 + +```mermaid +graph LR +BTN["Button.tsx"] --> AD["Ant Design Button"] +FBTN["FloatButton.tsx"] --> AD_FB["Ant Design FloatButton"] +ICON["Icon.tsx"] --> AD_Icons["Ant Design Icons"] +TYPO["Typography.Base.tsx"] --> AD_Typo["Ant Design Typography"] +BTN --> Utils["@utils/*"] +FBTN --> Utils +ICON --> Utils +TYPO --> Utils +Utils --> SveltePreprocess["@svelte-preprocess-react"] +AD --> React["React"] +AD_FB --> React +AD_Icons --> React +AD_Typo --> React +``` + +图表来源 + +- [button.tsx:1-6](file://frontend/antd/button/button.tsx#L1-L6) +- [float-button.tsx:1-5](file://frontend/antd/float-button/float-button.tsx#L1-L5) +- [icon.tsx:1-6](file://frontend/antd/icon/icon.tsx#L1-L6) +- [typography.base.tsx:1-10](file://frontend/antd/typography/typography.base.tsx#L1-L10) + +章节来源 + +- [button.tsx:1-6](file://frontend/antd/button/button.tsx#L1-L6) +- [float-button.tsx:1-5](file://frontend/antd/float-button/float-button.tsx#L1-L5) +- [icon.tsx:1-6](file://frontend/antd/icon/icon.tsx#L1-L6) +- [typography.base.tsx:1-10](file://frontend/antd/typography/typography.base.tsx#L1-L10) + +## 性能考虑 + +- 插槽渲染优化 + - 使用 useTargets 与 useSlotsChildren 分离插槽与普通 children，减少不必要的渲染开销。 + - 对 loading.icon、copyable.icon、editable.icon 等进行条件注入，避免无用节点挂载。 +- 函数型配置包装 + - 对 tooltip 的函数型配置（如 afterOpenChange、getPopupContainer）使用 useFunction 包装，确保响应式更新且避免闭包抖动。 +- 条件合并 + - 对 copyable、editable、ellipsis 等配置进行 getConfig 与 omitUndefinedProps 合并，仅在需要时启用对应能力，降低运行时负担。 +- 主题与样式 + - 通过 ConfigProvider 统一主题，避免重复计算与样式冲突；合理使用 className 前缀，便于精准覆盖。 + +## 故障排查指南 + +- 插槽未生效 + - 确认插槽名称是否正确（如 icon、loading.icon、copyable.icon、editable.icon、ellipsis.symbol 等）。 + - 确认 slots.component 优先级高于内置图标映射，若提供则会覆盖默认行为。 +- tooltip 无法打开或回调无效 + - 检查 tooltip 是否为对象配置；确保函数型配置项通过 useFunction 包装。 +- 图标不显示 + - 若未提供 slots.component，需确认 value 是否为内置图标名称；否则需正确配置 IconFont 上下文。 +- 编辑/复制/省略配置不生效 + - 确认 editable、copyable、ellipsis 任一存在即启用对应能力；若为对象配置，确保字段完整。 + +章节来源 + +- [float-button.tsx:14-72](file://frontend/antd/float-button/float-button.tsx#L14-L72) +- [icon.tsx:12-52](file://frontend/antd/icon/icon.tsx#L12-L52) +- [typography.base.tsx:19-167](file://frontend/antd/typography/typography.base.tsx#L19-L167) + +## 结论 + +本仓库通过统一的 sveltify 封装与插槽机制，将 Ant Design 的 React 组件无缝接入 Svelte/Gradio 生态，实现了按钮、悬浮按钮、图标与排版等通用组件的高可定制与易用性。借助 ConfigProvider、slots 与工具函数，开发者可以灵活地实现样式定制、交互扩展与无障碍访问需求。建议在实际项目中遵循插槽命名规范、合理使用函数型配置包装与条件渲染策略，以获得更佳的性能与可维护性。 + +## 附录 + +- 快速示例路径 + - 按钮：[basic.py（按钮）:8-22](file://docs/components/antd/button/demos/basic.py#L8-L22) + - 悬浮按钮：[basic.py（悬浮按钮）:8-27](file://docs/components/antd/float_button/demos/basic.py#L8-L27) + - 图标：[basic.py（图标）:9-21](file://docs/components/antd/icon/demos/basic.py#L9-L21) + - 排版：[basic.py（排版）:13-19](file://docs/components/antd/typography/demos/basic.py#L13-L19) +- 组件文档入口 + - 按钮：[README-zh_CN.md（按钮）:1-8](file://docs/components/antd/button/README-zh_CN.md#L1-L8) + - 悬浮按钮：[README-zh_CN.md（悬浮按钮）:1-8](file://docs/components/antd/float_button/README-zh_CN.md#L1-L8) + - 图标：[README-zh_CN.md（图标）:1-10](file://docs/components/antd/icon/README-zh_CN.md#L1-L10) + - 排版：[README-zh_CN.md（排版）:1-8](file://docs/components/antd/typography/README-zh_CN.md#L1-L8) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272.md" new file mode 100644 index 00000000..c597e469 --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272.md" @@ -0,0 +1,354 @@ +# Chatbot 聊天机器人 + + +**本文引用的文件** +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) +- [frontend/pro/chatbot/chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) +- [frontend/pro/chatbot/type.ts](file://frontend/pro/chatbot/type.ts) +- [frontend/pro/chatbot/message.tsx](file://frontend/pro/chatbot/message.tsx) +- [frontend/pro/chatbot/utils.ts](file://frontend/pro/chatbot/utils.ts) +- [frontend/pro/chatbot/hooks/useScroll.ts](file://frontend/pro/chatbot/hooks/useScroll.ts) +- [docs/layout_templates/chatbot/README.md](file://docs/layout_templates/chatbot/README.md) +- [docs/layout_templates/chatbot/app.py](file://docs/layout_templates/chatbot/app.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向需要在模型平台中构建智能聊天应用的开发者，系统性阐述 Chatbot 聊天机器人组件的设计与实现。该组件覆盖以下核心能力： + +- 消息处理：支持文本、工具（tool）、文件、建议（suggestion）等多种内容类型；支持消息状态（如 pending）与反馈标记。 +- 多模态支持：统一的消息内容归一化与渲染，支持文件上传、预览与下载链接生成。 +- 思维链展示：通过工具消息与建议提示，配合 Markdown 渲染，呈现推理与决策过程。 +- 工具调用：消息内容可嵌入工具执行结果，支持状态管理与标题标注。 +- 配置体系：提供欢迎页、Markdown 渲染、用户与机器人端消息样式与行为配置。 + +同时，文档提供完整使用示例、内部架构与消息流转机制说明、性能优化建议与常见问题解决方案。 + +## 项目结构 + +Chatbot 组件由后端 Python 数据类与前端 React/Svelte 双端实现构成，采用“数据类定义 + 前端渲染”的分层设计： + +- 后端：定义消息数据模型、前后处理逻辑与静态资源服务封装。 +- 前端：基于 @ant-design/x 的 Bubble 列表渲染消息，按内容类型分发到具体消息组件，提供滚动、编辑、复制、点赞/踩、重试等交互。 + +```mermaid +graph TB +subgraph "后端" +PY_INIT["Python 数据类与组件
backend/modelscope_studio/components/pro/chatbot/__init__.py"] +end +subgraph "前端" +TS_CHATBOT["React 组件 Chatbot
frontend/pro/chatbot/chatbot.tsx"] +TS_TYPE["类型定义与配置接口
frontend/pro/chatbot/type.ts"] +TS_MESSAGE["消息内容分发器
frontend/pro/chatbot/message.tsx"] +TS_UTILS["消息内容归一化与更新工具
frontend/pro/chatbot/utils.ts"] +TS_SCROLL["滚动控制 Hook
frontend/pro/chatbot/hooks/useScroll.ts"] +end +PY_INIT --> TS_CHATBOT +TS_TYPE --> TS_CHATBOT +TS_CHATBOT --> TS_MESSAGE +TS_MESSAGE --> TS_UTILS +TS_CHATBOT --> TS_SCROLL +``` + +**图表来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [frontend/pro/chatbot/chatbot.tsx:51-475](file://frontend/pro/chatbot/chatbot.tsx#L51-L475) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/message.tsx:25-184](file://frontend/pro/chatbot/message.tsx#L25-L184) +- [frontend/pro/chatbot/utils.ts:46-103](file://frontend/pro/chatbot/utils.ts#L46-L103) +- [frontend/pro/chatbot/hooks/useScroll.ts](file://frontend/pro/chatbot/hooks/useScroll.ts) + +**章节来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:1-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L1-L495) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [frontend/pro/chatbot/utils.ts:46-103](file://frontend/pro/chatbot/utils.ts#L46-L103) +- [frontend/pro/chatbot/hooks/useScroll.ts](file://frontend/pro/chatbot/hooks/useScroll.ts) + +## 核心组件 + +- 后端组件：ModelScopeProChatbot + - 定义消息数据模型与配置项，负责消息内容预处理、后处理与静态资源路径转换。 + - 提供事件绑定（change、copy、edit、delete、like、retry、suggestion_select、welcome_prompt_select）。 +- 前端组件：Chatbot（React） + - 将消息数组映射为 @ant-design/x 的 Bubble 列表，按角色与内容类型渲染。 + - 支持自动滚动、滚动到底部按钮、编辑、复制、点赞/踩、删除、重试、建议选择、欢迎提示选择等交互。 +- 类型与配置：type.ts + - 定义欢迎页、Markdown、用户/机器人配置、消息体、动作对象、内容类型与选项等接口。 +- 消息分发：message.tsx + - 归一化消息内容，根据类型分发到文本、工具、文件、建议消息组件。 +- 工具函数：utils.ts + - 归一化消息内容、批量更新内容值，支持字符串、数组、对象混合结构。 +- 滚动控制：useScroll.ts + - 控制列表滚动与“回到底部”按钮显示逻辑。 + +**章节来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L284) +- [frontend/pro/chatbot/chatbot.tsx:51-475](file://frontend/pro/chatbot/chatbot.tsx#L51-L475) +- [frontend/pro/chatbot/type.ts:27-197](file://frontend/pro/chatbot/type.ts#L27-L197) +- [frontend/pro/chatbot/message.tsx:25-184](file://frontend/pro/chatbot/message.tsx#L25-L184) +- [frontend/pro/chatbot/utils.ts:46-103](file://frontend/pro/chatbot/utils.ts#L46-L103) +- [frontend/pro/chatbot/hooks/useScroll.ts](file://frontend/pro/chatbot/hooks/useScroll.ts) + +## 架构总览 + +下图展示了从后端数据类到前端渲染的整体流程，以及事件回调的传递路径。 + +```mermaid +sequenceDiagram +participant Backend as "后端组件
ModelScopeProChatbot" +participant Frontend as "前端组件
Chatbot" +participant Message as "消息分发器
Message" +participant Utils as "工具函数
utils.ts" +Backend->>Frontend : "value : ChatbotMessages" +Frontend->>Frontend : "解析配置与消息数组" +Frontend->>Message : "逐条渲染消息" +Message->>Utils : "归一化消息内容" +Utils-->>Message : "标准化内容数组" +Message-->>Frontend : "返回对应内容组件" +Frontend-->>Backend : "事件回调copy/edit/delete/like/retry/suggestion/welcome" +``` + +**图表来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:418-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L418-L495) +- [frontend/pro/chatbot/chatbot.tsx:176-472](file://frontend/pro/chatbot/chatbot.tsx#L176-L472) +- [frontend/pro/chatbot/message.tsx:52-184](file://frontend/pro/chatbot/message.tsx#L52-L184) +- [frontend/pro/chatbot/utils.ts:46-103](file://frontend/pro/chatbot/utils.ts#L46-L103) + +## 详细组件分析 + +### 后端组件：ModelScopeProChatbot + +- 数据模型 + - ChatbotDataMessage：定义消息角色、键、状态、内容、动作、元信息等字段。 + - ChatbotDataMessages：消息根容器。 + - 配置类：ChatbotWelcomeConfig、ChatbotMarkdownConfig、ChatbotUserConfig、ChatbotBotConfig、ChatbotActionConfig 等。 +- 预处理与后处理 + - preprocess：将消息内容中的文件路径等进行预处理，便于前端渲染。 + - postprocess：将文件内容转换为 FileData，处理头像与静态资源路径。 +- 事件绑定 + - EVENTS：绑定 change、copy、edit、delete、like、retry、suggestion_select、welcome_prompt_select 等事件。 +- 前端目录 + - FRONTEND_DIR：指向前端 pro/chatbot 目录，确保组件正确加载。 + +```mermaid +classDiagram +class ModelScopeProChatbot { ++EVENTS ++FRONTEND_DIR ++data_model ++preprocess(payload) ++postprocess(value) +} +class ChatbotDataMessage { ++role ++status ++content ++actions ++meta +} +class ChatbotDataMessages { ++root : ChatbotDataMessage[] +} +class ChatbotWelcomeConfig +class ChatbotMarkdownConfig +class ChatbotUserConfig +class ChatbotBotConfig +class ChatbotActionConfig +ModelScopeProChatbot --> ChatbotDataMessages : "使用" +ChatbotDataMessages --> ChatbotDataMessage : "包含" +ModelScopeProChatbot --> ChatbotWelcomeConfig : "配置" +ModelScopeProChatbot --> ChatbotMarkdownConfig : "配置" +ModelScopeProChatbot --> ChatbotUserConfig : "配置" +ModelScopeProChatbot --> ChatbotBotConfig : "配置" +ChatbotUserConfig --> ChatbotActionConfig : "动作" +ChatbotBotConfig --> ChatbotActionConfig : "动作" +``` + +**图表来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L284) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) + +**章节来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L284) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) + +### 前端组件：Chatbot（React） + +- 角色与渲染 + - 使用 withRoleItemsContextProvider 为不同角色（用户、机器人、系统、分割线、欢迎页）提供渲染策略。 + - 默认跳过 system 与 divider，保留 chatbot-internal-welcome、user、assistant。 +- 内容渲染 + - 根据消息内容类型分发到文本、工具、文件、建议组件。 + - 支持编辑模式（仅 text/tool），编辑完成后触发 onValueChange 更新。 +- 交互事件 + - 复制、点赞/踩、删除、重试、建议选择、欢迎提示选择等事件通过回调传递给后端。 +- 滚动控制 + - useScroll 控制自动滚动与“回到底部”按钮显示阈值。 + +```mermaid +flowchart TD +Start(["进入 Chatbot 渲染"]) --> ResolveConfig["解析配置与消息数组"] +ResolveConfig --> RoleMap{"角色匹配"} +RoleMap --> |chatbot-internal-welcome| RenderWelcome["渲染欢迎页"] +RoleMap --> |user/assistant| RenderBubble["渲染气泡消息"] +RenderBubble --> ContentDispatch["消息内容分发"] +ContentDispatch --> TypeText["文本类型"] +ContentDispatch --> TypeTool["工具类型"] +ContentDispatch --> TypeFile["文件类型"] +ContentDispatch --> TypeSuggestion["建议类型"] +RenderWelcome --> End(["完成"]) +TypeText --> End +TypeTool --> End +TypeFile --> End +TypeSuggestion --> End +``` + +**图表来源** + +- [frontend/pro/chatbot/chatbot.tsx:107-472](file://frontend/pro/chatbot/chatbot.tsx#L107-L472) +- [frontend/pro/chatbot/message.tsx:52-184](file://frontend/pro/chatbot/message.tsx#L52-L184) + +**章节来源** + +- [frontend/pro/chatbot/chatbot.tsx:51-475](file://frontend/pro/chatbot/chatbot.tsx#L51-L475) +- [frontend/pro/chatbot/message.tsx:25-184](file://frontend/pro/chatbot/message.tsx#L25-L184) + +### 类型与配置：type.ts + +- 欢迎页配置 ChatbotWelcomeConfig：支持图标、标题、描述、额外信息、提示集合等。 +- Markdown 配置 ChatbotMarkdownConfig：控制是否渲染、换行、LaTeX 分隔符、HTML 清洗等。 +- 用户/机器人配置 ChatbotUserConfig/ChatbotBotConfig：动作列表、禁用动作、头像、变体、形状、放置位置、加载态等。 +- 动作对象 ChatbotActionConfig：支持 Tooltip 与 Popconfirm。 +- 消息内容类型：text、tool、file、suggestion；每种类型有对应的选项配置。 +- 事件数据结构：CopyData、EditData、DeleteData、LikeData、RetryData、SuggestionData、WelcomePromptData。 + +**章节来源** + +- [frontend/pro/chatbot/type.ts:27-197](file://frontend/pro/chatbot/type.ts#L27-L197) + +### 消息内容归一化与更新：utils.ts + +- normalizeMessageContent：将字符串、数组、对象统一为内容对象数组，便于渲染。 +- updateContent：对编辑后的值进行批量更新，支持字符串与对象混合结构。 + +**章节来源** + +- [frontend/pro/chatbot/utils.ts:46-103](file://frontend/pro/chatbot/utils.ts#L46-L103) + +### 滚动控制：useScroll.ts + +- 控制列表滚动至底部与按钮显示阈值，提升用户体验。 + +**章节来源** + +- [frontend/pro/chatbot/hooks/useScroll.ts](file://frontend/pro/chatbot/hooks/useScroll.ts) + +## 依赖分析 + +- 组件导出 + - 后端通过 components/pro/components.py 导出 ProChatbot，便于上层应用直接使用。 +- 文档模板 + - layout_templates/chatbot 提供应用模板与示例入口，便于快速演示与集成。 + +```mermaid +graph LR +BackendInit["后端初始化
backend/modelscope_studio/components/pro/chatbot/__init__.py"] --> Export["导出组件
backend/modelscope_studio/components/pro/components.py"] +Export --> App["应用模板入口
docs/layout_templates/chatbot/app.py"] +App --> Demo["示例页面
docs/layout_templates/chatbot/README.md"] +``` + +**图表来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:386-388](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L386-L388) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) +- [docs/layout_templates/chatbot/README.md:1-20](file://docs/layout_templates/chatbot/README.md#L1-L20) + +**章节来源** + +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [docs/layout_templates/chatbot/README.md:1-20](file://docs/layout_templates/chatbot/README.md#L1-L20) +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) + +## 性能考虑 + +- 消息渲染优化 + - 使用 useMemo 缓存配置解析与消息数组转换，减少不必要的重渲染。 + - 仅在最后一条消息或编辑状态时启用编辑输入框，避免全量渲染。 +- 文件处理 + - 在后端将文件路径转换为 FileData，前端按需渲染，避免重复请求。 +- 滚动控制 + - 通过阈值控制“回到底部”按钮显示，降低频繁滚动带来的开销。 +- 事件回调 + - 使用 useMemoizedFn 包装回调，减少事件处理器重建次数。 + +[本节为通用性能建议，不直接分析具体文件] + +## 故障排查指南 + +- 消息未显示或渲染异常 + - 检查消息内容是否符合 ChatbotDataMessage 结构，尤其是 content 的类型与 options。 + - 确认后端 postprocess 是否正确处理了文件路径与头像资源。 +- 文件无法预览或下载 + - 确认文件路径为本地文件或 HTTP 地址，后端会根据路径类型生成 FileData。 +- 编辑功能无效 + - 确认消息内容类型为 text 或 tool，且 editable 字段未被禁用。 +- 滚动按钮不出现 + - 检查 autoScroll 与 scroll_to_bottom_button_offset 配置，确认消息数量与高度设置合理。 +- 事件未触发 + - 确认前端已绑定相应事件回调，后端 EVENTS 中包含对应事件监听。 + +**章节来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:418-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L418-L495) +- [frontend/pro/chatbot/chatbot.tsx:176-472](file://frontend/pro/chatbot/chatbot.tsx#L176-L472) +- [frontend/pro/chatbot/message.tsx:37-184](file://frontend/pro/chatbot/message.tsx#L37-L184) + +## 结论 + +Chatbot 聊天机器人组件通过清晰的数据模型与前后端协作，实现了多模态消息处理、思维链展示与工具调用集成。其配置体系灵活，事件回调完善，适合在复杂对话场景中构建高质量的智能聊天应用。建议在实际项目中结合业务需求，合理配置欢迎页、Markdown 渲染与消息动作，以获得最佳用户体验。 + +[本节为总结性内容，不直接分析具体文件] + +## 附录 + +### 使用示例与最佳实践 + +- 基础聊天 + - 初始化 ModelScopeProChatbot，传入初始消息数组与基础配置。 + - 监听 change、copy、edit、delete、like、retry 等事件，实现业务逻辑。 +- 多模态输入 + - 使用 ChatbotDataMessageContent 的 file 类型承载附件列表，后端自动转换为 FileData。 + - 前端根据 options 中的 image/video/audioProps 进行预览。 +- 工具集成 + - 使用 tool 类型承载工具执行结果，配合 options.title 与 status 标注执行状态。 +- 思维链展示 + - 通过 suggestion 类型提供输入建议，结合 Markdown 渲染增强可读性。 +- 配置要点 + - 欢迎页：设置 icon、title、description、prompts 等。 + - Markdown：控制换行、LaTeX 分隔符、HTML 清洗与标签允许列表。 + - 用户/机器人：自定义动作、头像、变体与放置位置，提升界面一致性。 + +[本节为概念性说明，不直接分析具体文件] diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\345\237\272\347\241\200\344\275\277\347\224\250.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\345\237\272\347\241\200\344\275\277\347\224\250.md" new file mode 100644 index 00000000..39779bf6 --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\345\237\272\347\241\200\344\275\277\347\224\250.md" @@ -0,0 +1,388 @@ +# 基础使用 + + +**本文引用的文件** +- [frontend/pro/chatbot/Index.svelte](file://frontend/pro/chatbot/Index.svelte) +- [frontend/pro/chatbot/chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) +- [frontend/pro/chatbot/type.ts](file://frontend/pro/chatbot/type.ts) +- [frontend/pro/chatbot/utils.ts](file://frontend/pro/chatbot/utils.ts) +- [frontend/pro/chatbot/message.tsx](file://frontend/pro/chatbot/message.tsx) +- [frontend/pro/chatbot/chatbot-footer.tsx](file://frontend/pro/chatbot/chatbot-footer.tsx) +- [frontend/pro/chatbot/chatbot-header.tsx](file://frontend/pro/chatbot/chatbot-header.tsx) +- [frontend/pro/chatbot/messages/text.tsx](file://frontend/pro/chatbot/messages/text.tsx) +- [frontend/pro/chatbot/messages/file.tsx](file://frontend/pro/chatbot/messages/file.tsx) +- [frontend/pro/chatbot/messages/suggestion.tsx](file://frontend/pro/chatbot/messages/suggestion.tsx) +- [frontend/pro/chatbot/messages/tool.tsx](file://frontend/pro/chatbot/messages/tool.tsx) +- [docs/layout_templates/chatbot/README-zh_CN.md](file://docs/layout_templates/chatbot/README-zh_CN.md) +- [docs/layout_templates/chatbot/app.py](file://docs/layout_templates/chatbot/app.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本章节面向初学者，介绍 Chatbot 聊天机器人组件的基础概念与核心能力，帮助你快速上手并构建第一个聊天机器人应用。Chatbot 组件提供消息显示、用户交互、欢迎引导、滚动行为控制、Markdown 渲染、附件展示、建议提示、工具态展开收起等功能。通过统一的消息数据模型与可配置的角色样式，你可以灵活地定制用户与机器人消息的外观与交互。 + +## 项目结构 + +Chatbot 组件位于前端 Pro 区块中，采用 Svelte 作为桥接层，内部以 React 组件为核心实现，并通过 Ant Design X 的气泡列表（Bubble.List）承载消息渲染与交互。消息内容支持文本、工具态（可折叠）、文件、建议提示等多种类型；底部操作区支持复制、点赞/踩、重试、编辑、删除等动作；顶部标题支持 Markdown 渲染；欢迎区域支持引导文案与建议提示。 + +```mermaid +graph TB +A["Index.svelte
桥接层"] --> B["chatbot.tsx
主容器与逻辑"] +B --> C["message.tsx
消息分发器"] +C --> C1["messages/text.tsx
文本渲染"] +C --> C2["messages/tool.tsx
工具态折叠"] +C --> C3["messages/file.tsx
文件卡片"] +C --> C4["messages/suggestion.tsx
建议提示"] +B --> D["chatbot-header.tsx
标题渲染"] +B --> E["chatbot-footer.tsx
操作区"] +B --> F["utils.ts
工具函数"] +B --> G["type.ts
类型定义"] +``` + +图示来源 + +- [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [frontend/pro/chatbot/chatbot-header.tsx:1-23](file://frontend/pro/chatbot/chatbot-header.tsx#L1-L23) +- [frontend/pro/chatbot/chatbot-footer.tsx:1-363](file://frontend/pro/chatbot/chatbot-footer.tsx#L1-L363) +- [frontend/pro/chatbot/utils.ts:1-157](file://frontend/pro/chatbot/utils.ts#L1-L157) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/messages/text.tsx:1-19](file://frontend/pro/chatbot/messages/text.tsx#L1-L19) +- [frontend/pro/chatbot/messages/tool.tsx:1-46](file://frontend/pro/chatbot/messages/tool.tsx#L1-L46) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/pro/chatbot/messages/suggestion.tsx:1-37](file://frontend/pro/chatbot/messages/suggestion.tsx#L1-L37) + +章节来源 + +- [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) + +## 核心组件 + +- 主容器 Chatbot：负责消息列表渲染、滚动控制、欢迎区、Markdown 配置、用户/机器人角色配置、事件回调（复制、编辑、删除、点赞/踩、重试、建议选择、欢迎提示选择）。 +- 消息分发器 Message：根据消息内容类型（文本/工具/文件/建议）分派到对应子组件进行渲染。 +- 顶部标题 ChatbotHeader：支持 Markdown 渲染标题。 +- 底部操作区 ChatbotFooter：统一处理复制、点赞/踩、重试、编辑、删除等动作，支持禁用与二次确认。 +- 工具函数 utils：提供头像解析、消息内容归一化、复制文本提取、建议内容遍历等。 +- 类型定义 type：定义消息体、角色配置、Markdown 配置、文件/建议/工具内容配置、事件数据结构等。 +- 子消息组件：文本、工具态（可折叠）、文件卡片、建议提示。 + +章节来源 + +- [frontend/pro/chatbot/chatbot.tsx:51-475](file://frontend/pro/chatbot/chatbot.tsx#L51-L475) +- [frontend/pro/chatbot/message.tsx:25-184](file://frontend/pro/chatbot/message.tsx#L25-L184) +- [frontend/pro/chatbot/chatbot-header.tsx:6-23](file://frontend/pro/chatbot/chatbot-header.tsx#L6-L23) +- [frontend/pro/chatbot/chatbot-footer.tsx:34-363](file://frontend/pro/chatbot/chatbot-footer.tsx#L34-L363) +- [frontend/pro/chatbot/utils.ts:19-157](file://frontend/pro/chatbot/utils.ts#L19-L157) +- [frontend/pro/chatbot/type.ts:27-197](file://frontend/pro/chatbot/type.ts#L27-L197) + +## 架构总览 + +下图展示了从桥接层到 React 主容器、再到消息渲染与交互的整体流程： + +```mermaid +sequenceDiagram +participant UI as "Index.svelte
桥接层" +participant CB as "Chatbot
主容器" +participant MSG as "Message
消息分发器" +participant HDR as "ChatbotHeader
标题" +participant FTR as "ChatbotFooter
操作区" +participant UTIL as "utils.ts
工具函数" +UI->>CB : 传入 propsvalue、配置项、回调 +CB->>UTIL : 解析头像/复制文本/内容归一化 +CB->>HDR : 渲染标题可 Markdown +CB->>MSG : 渲染消息内容文本/工具/文件/建议 +MSG-->>FTR : 触发操作复制/点赞/重试/编辑/删除 +FTR-->>CB : 回调事件onCopy/onLike/onRetry/onEdit/onDelete +CB-->>UI : onValueChange 更新消息数组 +``` + +图示来源 + +- [frontend/pro/chatbot/Index.svelte:64-89](file://frontend/pro/chatbot/Index.svelte#L64-L89) +- [frontend/pro/chatbot/chatbot.tsx:107-472](file://frontend/pro/chatbot/chatbot.tsx#L107-L472) +- [frontend/pro/chatbot/message.tsx:39-184](file://frontend/pro/chatbot/message.tsx#L39-L184) +- [frontend/pro/chatbot/chatbot-header.tsx:11-22](file://frontend/pro/chatbot/chatbot-header.tsx#L11-L22) +- [frontend/pro/chatbot/chatbot-footer.tsx:255-362](file://frontend/pro/chatbot/chatbot-footer.tsx#L255-L362) +- [frontend/pro/chatbot/utils.ts:46-140](file://frontend/pro/chatbot/utils.ts#L46-L140) + +## 详细组件分析 + +### 主容器 Chatbot（属性与行为） + +- 关键属性 + - 尺寸与布局：height、minHeight、maxHeight + - 滚动行为：autoScroll、showScrollToBottomButton、scrollToBottomButtonOffset + - 角色配置：userConfig、botConfig（含头像、样式、类名、动作、禁用动作等） + - 内容配置：markdownConfig（是否渲染 Markdown、根路径、主题模式等） + - 欢迎配置：welcomeConfig（欢迎文案、图标、建议提示等） + - 数据与回调：value（消息数组）、onValueChange、onChange、onCopy、onEdit、onDelete、onLike、onRetry、onSuggestionSelect、onWelcomePromptSelect +- 行为特性 + - 自动滚动至底部与“回到底部”按钮 + - 欢迎区占位与引导 + - 复制、点赞/踩、重试、编辑、删除等交互 + - Markdown 渲染与主题适配 + - 消息索引与最后一条消息标记 + +```mermaid +classDiagram +class Chatbot { ++props : rootUrl, apiPrefix, themeMode ++props : role, autoScroll, showScrollToBottomButton, scrollToBottomButtonOffset ++props : height, minHeight, maxHeight ++props : userConfig, botConfig, markdownConfig, welcomeConfig ++props : value, onValueChange, onChange ++props : onCopy, onEdit, onDelete, onLike, onRetry ++props : onSuggestionSelect, onWelcomePromptSelect +} +class Message { ++props : index, isEditing, isLastMessage, markdownConfig, message ++props : rootUrl, apiPrefix, onEdit, onSuggestionSelect +} +class ChatbotFooter { ++props : isEditing, index, editValues, message ++props : actions, disabledActions, extra ++props : onCopy, onEdit, onDelete, onRetry, onLike +} +class ChatbotHeader { ++props : markdownConfig, title +} +Chatbot --> Message : "渲染消息" +Chatbot --> ChatbotFooter : "渲染底部操作" +Chatbot --> ChatbotHeader : "渲染标题" +``` + +图示来源 + +- [frontend/pro/chatbot/chatbot.tsx:51-107](file://frontend/pro/chatbot/chatbot.tsx#L51-L107) +- [frontend/pro/chatbot/message.tsx:25-49](file://frontend/pro/chatbot/message.tsx#L25-L49) +- [frontend/pro/chatbot/chatbot-footer.tsx:34-51](file://frontend/pro/chatbot/chatbot-footer.tsx#L34-L51) +- [frontend/pro/chatbot/chatbot-header.tsx:6-14](file://frontend/pro/chatbot/chatbot-header.tsx#L6-L14) + +章节来源 + +- [frontend/pro/chatbot/chatbot.tsx:51-475](file://frontend/pro/chatbot/chatbot.tsx#L51-L475) + +### 消息内容类型与渲染 + +- 文本消息：支持 Markdown 开关与 Markdown 参数透传 +- 工具消息：支持标题与状态（进行中/完成），默认折叠未完成项 +- 文件消息：支持图片/视频/音频预览卡片，自动解析可访问链接 +- 建议消息：支持多级提示，非最后一条消息时自动禁用点击 + +```mermaid +flowchart TD +Start(["进入 Message 渲染"]) --> Normalize["归一化消息内容"] +Normalize --> IsEditing{"处于编辑态？"} +IsEditing --> |是| RenderEdit["渲染编辑输入框"] +IsEditing --> |否| TypeSwitch{"内容类型判断"} +TypeSwitch --> |text| RenderText["渲染文本可 Markdown"] +TypeSwitch --> |tool| RenderTool["渲染工具态可折叠"] +TypeSwitch --> |file| RenderFile["渲染文件卡片"] +TypeSwitch --> |suggestion| RenderSuggest["渲染建议提示可禁用"] +RenderText --> End(["完成"]) +RenderTool --> End +RenderFile --> End +RenderSuggest --> End +RenderEdit --> End +``` + +图示来源 + +- [frontend/pro/chatbot/message.tsx:52-175](file://frontend/pro/chatbot/message.tsx#L52-L175) +- [frontend/pro/chatbot/messages/text.tsx:11-18](file://frontend/pro/chatbot/messages/text.tsx#L11-L18) +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) +- [frontend/pro/chatbot/messages/file.tsx:44-118](file://frontend/pro/chatbot/messages/file.tsx#L44-L118) +- [frontend/pro/chatbot/messages/suggestion.tsx:16-36](file://frontend/pro/chatbot/messages/suggestion.tsx#L16-L36) + +章节来源 + +- [frontend/pro/chatbot/message.tsx:25-184](file://frontend/pro/chatbot/message.tsx#L25-L184) +- [frontend/pro/chatbot/messages/text.tsx:1-19](file://frontend/pro/chatbot/messages/text.tsx#L1-L19) +- [frontend/pro/chatbot/messages/tool.tsx:1-46](file://frontend/pro/chatbot/messages/tool.tsx#L1-L46) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/pro/chatbot/messages/suggestion.tsx:1-37](file://frontend/pro/chatbot/messages/suggestion.tsx#L1-L37) + +### 欢迎区与建议提示 + +- 欢迎区：在无消息时显示，支持自定义样式、头像、提示文案与建议提示 +- 建议提示：在最后一条消息时启用点击，其他消息时自动禁用，避免误触发 + +章节来源 + +- [frontend/pro/chatbot/chatbot.tsx:306-328](file://frontend/pro/chatbot/chatbot.tsx#L306-L328) +- [frontend/pro/chatbot/messages/suggestion.tsx:16-36](file://frontend/pro/chatbot/messages/suggestion.tsx#L16-L36) + +### 操作区交互（复制/点赞/重试/编辑/删除） + +- 复制：根据内容类型提取可复制文本，支持文件链接 JSON 化 +- 点赞/踩：更新消息 meta 中的反馈状态，支持取消 +- 重试：触发外部 onRetry 回调 +- 编辑：进入编辑态，支持多段内容按序编辑，确认后回写 +- 删除：移除对应消息 + +```mermaid +sequenceDiagram +participant U as "用户" +participant F as "ChatbotFooter" +participant C as "Chatbot" +participant M as "Message" +U->>F : 点击“复制/点赞/重试/编辑/删除” +alt 复制 +F->>C : onCopy({index, value}) +else 点赞/踩 +F->>C : onLike({index, value, liked}) +C->>C : 更新消息 meta.feedback +else 重试 +F->>C : onRetry({index, value}) +else 编辑 +F->>C : 进入编辑态 +U->>M : 修改输入 +M-->>F : onEdit(index, value) +F->>C : onEdit({index, value, previous_value}) +C->>C : onValueChange 替换内容 +else 删除 +F->>C : onDelete({index, value}) +C->>C : onValueChange 移除消息 +end +``` + +图示来源 + +- [frontend/pro/chatbot/chatbot-footer.tsx:102-362](file://frontend/pro/chatbot/chatbot-footer.tsx#L102-L362) +- [frontend/pro/chatbot/chatbot.tsx:195-245](file://frontend/pro/chatbot/chatbot.tsx#L195-L245) +- [frontend/pro/chatbot/utils.ts:74-103](file://frontend/pro/chatbot/utils.ts#L74-L103) + +章节来源 + +- [frontend/pro/chatbot/chatbot-footer.tsx:34-363](file://frontend/pro/chatbot/chatbot-footer.tsx#L34-L363) +- [frontend/pro/chatbot/chatbot.tsx:172-245](file://frontend/pro/chatbot/chatbot.tsx#L172-L245) +- [frontend/pro/chatbot/utils.ts:74-140](file://frontend/pro/chatbot/utils.ts#L74-L140) + +## 依赖分析 + +- 桥接层：Index.svelte 使用 importComponent 将 React 组件动态导入，并传递 props、插槽与共享上下文（rootUrl、apiPrefix、theme）。 +- 主容器：chatbot.tsx 依赖 Ant Design X 的 Bubble.List 与 Antd 组件，结合 utils 与 type 完成渲染与交互。 +- 消息子组件：分别依赖 Markdown 渲染与 Antd 组件，文件消息依赖上传工具解析可访问链接。 +- 类型系统：统一定义消息体、角色配置、内容配置与事件数据，保证跨组件一致性。 + +```mermaid +graph LR +IDX["Index.svelte"] --> CB["chatbot.tsx"] +CB --> MSG["message.tsx"] +MSG --> TXT["messages/text.tsx"] +MSG --> TOOL["messages/tool.tsx"] +MSG --> FIL["messages/file.tsx"] +MSG --> SUG["messages/suggestion.tsx"] +CB --> HDR["chatbot-header.tsx"] +CB --> FTR["chatbot-footer.tsx"] +CB --> UTL["utils.ts"] +CB --> TYP["type.ts"] +``` + +图示来源 + +- [frontend/pro/chatbot/Index.svelte:12-87](file://frontend/pro/chatbot/Index.svelte#L12-L87) +- [frontend/pro/chatbot/chatbot.tsx:1-49](file://frontend/pro/chatbot/chatbot.tsx#L1-L49) +- [frontend/pro/chatbot/message.tsx:1-25](file://frontend/pro/chatbot/message.tsx#L1-L25) + +章节来源 + +- [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) + +## 性能考虑 + +- 消息列表优化：通过 useMemo 与浅比较减少重渲染；仅在 value 变更时触发 onChange。 +- 滚动控制：useScroll 提供平滑滚动与按钮显隐，避免频繁 DOM 计算。 +- 内容归一化：normalizeMessageContent 将字符串/数组/对象统一封装，降低分支复杂度。 +- Markdown 渲染：按需渲染，支持关闭 Markdown 以减少开销。 +- 文件链接：延迟解析与缓存策略，避免重复计算可访问 URL。 + +章节来源 + +- [frontend/pro/chatbot/chatbot.tsx:117-183](file://frontend/pro/chatbot/chatbot.tsx#L117-L183) +- [frontend/pro/chatbot/utils.ts:46-72](file://frontend/pro/chatbot/utils.ts#L46-L72) + +## 故障排查指南 + +- 消息不显示或空白 + - 检查 value 是否为空，若为空会显示欢迎区占位 + - 确认消息内容类型与 options 配置正确 +- 复制无效 + - 检查内容是否可复制（部分类型默认不可复制） + - 确认 rootUrl 与 apiPrefix 正确，以便生成可访问链接 +- 文件无法打开 + - 确认文件 URL 或路径已正确解析为可访问地址 +- 滚动异常 + - 调整 autoScroll、scrollToBottomButtonOffset 参数 + - 确保容器高度设置合理（height/minHeight/maxHeight） +- 操作按钮不生效 + - 检查 actions 与 disabled_actions 配置 + - 确认回调函数（onCopy/onLike/onRetry/onEdit/onDelete）已绑定 + +章节来源 + +- [frontend/pro/chatbot/chatbot.tsx:433-468](file://frontend/pro/chatbot/chatbot.tsx#L433-L468) +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) +- [frontend/pro/chatbot/messages/file.tsx:18-42](file://frontend/pro/chatbot/messages/file.tsx#L18-L42) + +## 结论 + +Chatbot 组件通过清晰的类型体系与模块化设计，提供了完整的聊天消息渲染与交互能力。借助统一的配置项与回调机制，你可以快速搭建具备欢迎引导、消息编辑、文件与建议提示、Markdown 渲染等能力的聊天界面。建议从最小可用 Demo 入手，逐步扩展角色样式与交互动作，以获得更好的用户体验。 + +## 附录 + +### 入门示例（步骤说明） + +- 创建一个最小聊天界面 + - 准备一个空的消息数组作为初始值 + - 设置容器高度与滚动行为 + - 绑定 onValueChange 以接收消息变更 + - 可选：配置 userConfig/botConfig 控制头像与样式 +- 添加第一条消息 + - 在消息数组中加入一条用户消息（role=user） + - 机器人回复时插入一条助手消息（role=assistant） +- 启动应用 + - 使用文档模板中的启动方式运行应用 + +章节来源 + +- [docs/layout_templates/chatbot/README-zh_CN.md:1-20](file://docs/layout_templates/chatbot/README-zh_CN.md#L1-L20) +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) + +### 常见属性与参数说明 + +- 尺寸与滚动 + - height/minHeight/maxHeight：容器尺寸控制 + - autoScroll：是否自动滚动到底部 + - showScrollToBottomButton/scrollToBottomButtonOffset：底部回到按钮显隐与偏移 +- 角色配置 + - userConfig/botConfig：头像、样式、类名、动作、禁用动作、额外头部/尾部内容 +- 内容配置 + - markdownConfig：是否渲染 Markdown、根路径、主题模式等 + - welcomeConfig：欢迎文案、图标、建议提示等 +- 事件回调 + - onValueChange：消息数组变更 + - onCopy/onEdit/onDelete/onLike/onRetry：对应操作回调 + - onSuggestionSelect/onWelcomePromptSelect：建议与欢迎提示选择回调 + +章节来源 + +- [frontend/pro/chatbot/chatbot.tsx:51-107](file://frontend/pro/chatbot/chatbot.tsx#L51-L107) +- [frontend/pro/chatbot/type.ts:86-119](file://frontend/pro/chatbot/type.ts#L86-L119) +- [frontend/pro/chatbot/type.ts:27-41](file://frontend/pro/chatbot/type.ts#L27-L41) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\345\244\232\346\250\241\346\200\201\346\224\257\346\214\201.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\345\244\232\346\250\241\346\200\201\346\224\257\346\214\201.md" new file mode 100644 index 00000000..8a9411b2 --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\345\244\232\346\250\241\346\200\201\346\224\257\346\214\201.md" @@ -0,0 +1,401 @@ +# 多模态支持 + + +**本文引用的文件** +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) +- [backend/modelscope_studio/components/pro/multimodal_input/__init__.py](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py) +- [frontend/pro/chatbot/index.svelte](file://frontend/pro/chatbot/index.svelte) +- [frontend/pro/multimodal-input/index.svelte](file://frontend/pro/multimodal-input/index.svelte) +- [frontend/pro/chatbot/type.ts](file://frontend/pro/chatbot/type.ts) +- [frontend/pro/chatbot/messages/file.tsx](file://frontend/pro/chatbot/messages/file.tsx) +- [frontend/antdx/attachments/attachments.tsx](file://frontend/antdx/attachments/attachments.tsx) +- [frontend/utils/upload.ts](file://frontend/utils/upload.ts) +- [docs/layout_templates/chatbot/demos/basic.py](file://docs/layout_templates/chatbot/demos/basic.py) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py](file://docs/layout_templates/chatbot/demos/fine_grained_control.py) +- [docs/components/pro/chatbot/demos/multimodal.py](file://docs/components/pro/chatbot/demos/multimodal.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本章节面向 Chatbot 聊天机器人组件的多模态支持能力，系统性说明其对图片、视频、音频、文件等多媒体内容的处理机制，涵盖消息结构定义、前后端数据流、上传/下载/预览流程、安全与性能优化策略。读者可据此在 Gradio/ModelScope 生态中构建具备多模态输入输出能力的对话应用。 + +## 项目结构 + +多模态支持由“后端组件 + 前端渲染 + 工具函数”三部分协同完成： + +- 后端组件负责消息数据模型、预处理/后处理逻辑、静态资源服务与事件绑定 +- 前端组件负责聊天气泡渲染、附件面板、文件卡片展示与交互 +- 工具函数负责文件 URL 解析与可拉取地址生成 + +```mermaid +graph TB +subgraph "后端" +BC["Chatbot 组件
消息模型与预/后处理"] +MI["MultimodalInput 组件
多模态输入与上传"] +end +subgraph "前端" +CI["chatbot/index.svelte
聊天容器"] +CT["chatbot/type.ts
消息类型定义"] +CF["messages/file.tsx
文件消息渲染"] +AI["attachments/attachments.tsx
附件面板"] +UF["utils/upload.ts
URL 解析工具"] +end +subgraph "文档示例" +DB["basic.py
基础多模态历史格式化"] +DF["fine_grained_control.py
细粒度控制示例"] +DM["multimodal.py
多模态提交与流式响应"] +end +BC --> CI +MI --> CI +CI --> CT +CI --> CF +CI --> AI +CF --> UF +MI --> AI +DB --> BC +DF --> BC +DM --> BC +``` + +**图表来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) +- [frontend/pro/chatbot/index.svelte:1-90](file://frontend/pro/chatbot/index.svelte#L1-L90) +- [frontend/pro/multimodal-input/index.svelte:1-99](file://frontend/pro/multimodal-input/index.svelte#L1-L99) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/utils/upload.ts:1-45](file://frontend/utils/upload.ts#L1-L45) +- [docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py:100-133](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L100-L133) +- [docs/components/pro/chatbot/demos/multimodal.py:82-118](file://docs/components/pro/chatbot/demos/multimodal.py#L82-L118) + +**章节来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) +- [frontend/pro/chatbot/index.svelte:1-90](file://frontend/pro/chatbot/index.svelte#L1-L90) +- [frontend/pro/multimodal-input/index.svelte:1-99](file://frontend/pro/multimodal-input/index.svelte#L1-L99) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/utils/upload.ts:1-45](file://frontend/utils/upload.ts#L1-L45) +- [docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py:100-133](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L100-L133) +- [docs/components/pro/chatbot/demos/multimodal.py:82-118](file://docs/components/pro/chatbot/demos/multimodal.py#L82-L118) + +## 核心组件 + +- Chatbot 组件（后端）：定义消息结构、支持文本/工具/文件/建议四种内容类型；提供预处理与后处理钩子，统一处理文件路径/URL、MIME 类型与静态资源服务。 +- MultimodalInput 组件（后端）：封装多模态输入，支持文本与文件列表；提供上传前/后处理、缓存下载、HTTP 链接解析与本地文件映射。 +- 前端渲染（chatbot）：根据消息类型渲染文本、工具、文件或建议；文件消息通过文件卡片组件展示图片/视频/音频，并提供预览与下载链接。 +- 附件面板（attachments）：提供拖拽/粘贴/选择上传、最大数量限制、占位符、图标渲染、预览配置等能力。 +- 工具函数（upload）：将相对路径转换为可拉取 URL，兼容 http/https 协议与后端 API 前缀。 + +**章节来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:229-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L229-L284) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:76-137](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L76-L137) +- [frontend/pro/chatbot/type.ts:43-135](file://frontend/pro/chatbot/type.ts#L43-L135) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/utils/upload.ts:12-44](file://frontend/utils/upload.ts#L12-L44) + +## 架构总览 + +下图展示了从用户输入到消息渲染的全链路：前端 MultimodalInput 将文本与文件上传至后端，后端组件进行预处理/后处理，最终以统一的消息结构传递给前端 Chatbot 渲染器。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant MUI as "MultimodalInput(前端)" +participant MI as "MultimodalInput(后端)" +participant CB as "Chatbot(后端)" +participant FE as "Chatbot(前端渲染)" +U->>MUI : 输入文本 + 选择/粘贴/拖拽文件 +MUI->>MI : 提交变更值 {text, files} +MI->>MI : 预处理/下载/映射文件 +MI-->>CB : 统一消息结构(含文件路径/URL/MIME) +CB-->>FE : 渲染消息(文本/文件/工具/建议) +FE-->>U : 展示聊天气泡与文件卡片 +``` + +**图表来源** + +- [frontend/pro/multimodal-input/index.svelte:68-75](file://frontend/pro/multimodal-input/index.svelte#L68-L75) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:418-488](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L418-L488) +- [frontend/pro/chatbot/index.svelte:67-89](file://frontend/pro/chatbot/index.svelte#L67-L89) + +## 详细组件分析 + +### 消息结构与内容类型 + +- 支持的内容类型：text、tool、file、suggestion +- 文件内容支持字符串路径、FileData 对象、附件对象与扩展属性（如 type） +- 文本内容支持 Markdown 渲染、LaTeX 定界符、HTML 清洗与标签白名单 +- 工具内容支持标题与状态（pending/done） +- 建议内容采用提示组配置，支持垂直/换行布局与样式 + +```mermaid +classDiagram +class ChatbotDataMessageContent { ++type ++content ++options ++copyable ++editable +} +class ChatbotDataFileContentOptions { ++vertical ++wrap ++justify ++align ++gap ++imageProps ++videoProps ++audioProps +} +class ChatbotDataToolContentOptions { ++title ++status +} +class ChatbotMarkdownConfig { ++render_markdown ++latex_delimiters ++sanitize_html ++allow_tags +} +class ChatbotDataMessage { ++role ++content ++status ++meta +} +ChatbotDataMessageContent --> ChatbotDataFileContentOptions : "文件选项" +ChatbotDataMessageContent --> ChatbotDataToolContentOptions : "工具选项" +ChatbotDataMessageContent --> ChatbotMarkdownConfig : "文本选项" +ChatbotDataMessage --> ChatbotDataMessageContent : "包含" +``` + +**图表来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:229-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L229-L284) +- [frontend/pro/chatbot/type.ts:54-135](file://frontend/pro/chatbot/type.ts#L54-L135) + +**章节来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:229-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L229-L284) +- [frontend/pro/chatbot/type.ts:43-135](file://frontend/pro/chatbot/type.ts#L43-L135) + +### 文件消息渲染与预览 + +- 文件消息通过文件卡片组件展示，支持图片缩略图、视频/音频播放器、文件大小与名称 +- 预览按钮使用可拉取 URL 打开新窗口，确保跨域安全 +- 图片/视频/音频的尺寸与样式可通过 options 注入 + +```mermaid +flowchart TD +Start(["进入文件消息渲染"]) --> Resolve["解析文件项
字符串/对象 -> 统一对象"] +Resolve --> BuildCard["构造文件卡片
name/size/type/src"] +BuildCard --> Preview["生成预览按钮
href=可拉取URL"] +Preview --> Style["注入样式与尺寸
imageProps/videoProps/audioProps"] +Style --> End(["渲染完成"]) +``` + +**图表来源** + +- [frontend/pro/chatbot/messages/file.tsx:18-118](file://frontend/pro/chatbot/messages/file.tsx#L18-L118) +- [frontend/utils/upload.ts:12-44](file://frontend/utils/upload.ts#L12-L44) + +**章节来源** + +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/utils/upload.ts:1-45](file://frontend/utils/upload.ts#L1-L45) + +### 附件面板与上传流程 + +- 支持拖拽、粘贴、选择上传，可配置最大数量、占位符、图标与预览行为 +- 上传时自动去重、临时状态与合并策略，支持单文件覆盖与多文件追加 +- 提供下载、预览、移除事件回调，便于集成业务逻辑 + +```mermaid +sequenceDiagram +participant U as "用户" +participant AT as "Attachments(附件面板)" +participant CL as "客户端上传" +participant ST as "存储/缓存" +U->>AT : 选择/拖拽/粘贴文件 +AT->>CL : 触发上传(过滤未完成文件) +CL->>ST : 保存文件 +ST-->>CL : 返回 FileData 列表 +CL-->>AT : 更新文件列表(合并/覆盖) +AT-->>U : 显示上传进度与结果 +``` + +**图表来源** + +- [frontend/antdx/attachments/attachments.tsx:275-354](file://frontend/antdx/attachments/attachments.tsx#L275-L354) +- [frontend/pro/multimodal-input/multimodal-input.tsx:181-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L181-L246) + +**章节来源** + +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/pro/multimodal-input/multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) + +### 历史消息格式化与多模态提交 + +- 历史消息需按角色与内容类型组织，用户消息可包含文本与文件数组 +- 文件项可为路径或 FileData，后端会统一转换为可拉取 URL 或本地路径 +- 示例演示了将图片转为 base64 的场景以及将文件与文本组合为多模态消息 + +```mermaid +flowchart TD +A["读取历史记录"] --> B{"角色为用户?"} +B -- 是 --> C["组装内容数组
[{type:text},{type:image_url}]"] +B -- 否 --> D["直接复制助手消息"] +C --> E["追加当前助手占位消息"] +D --> E +E --> F["提交给大模型/流式响应"] +``` + +**图表来源** + +- [docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py:100-133](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L100-L133) +- [docs/components/pro/chatbot/demos/multimodal.py:82-118](file://docs/components/pro/chatbot/demos/multimodal.py#L82-L118) + +**章节来源** + +- [docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py:100-133](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L100-L133) +- [docs/components/pro/chatbot/demos/multimodal.py:82-118](file://docs/components/pro/chatbot/demos/multimodal.py#L82-L118) + +### 前后端数据流与事件绑定 + +- Chatbot 组件暴露 change/copy/edit/delete/like/retry/suggestion_select/welcome_prompt_select 等事件监听 +- MultimodalInput 组件暴露 change/submit/cancel/keyDown/keyPress/focus/blur/upload/paste/paste_file/drop/download/preview/remove 等事件 +- 前端容器将 Gradio 共享上下文（rootUrl、apiPrefix）传递给渲染组件，用于文件 URL 解析与下载 + +**章节来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-314](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L314) +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:82-135](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L135) +- [frontend/pro/chatbot/index.svelte:76-84](file://frontend/pro/chatbot/index.svelte#L76-L84) +- [frontend/pro/multimodal-input/index.svelte:80-93](file://frontend/pro/multimodal-input/index.svelte#L80-L93) + +## 依赖分析 + +- 后端 Chatbot 组件依赖 Gradio 数据类与事件系统，负责消息结构化与静态资源服务 +- 后端 MultimodalInput 组件依赖 Gradio FileData 与缓存下载工具，负责文件上传与本地映射 +- 前端 Chatbot 渲染器依赖 Ant Design X 与 Ant Design 组件生态，负责消息渲染与交互 +- 附件面板与文件卡片组件复用 Ant Design X 的 Attachments 与 FileCard，提供一致的上传体验 +- 工具函数统一处理文件 URL 生成，保证跨域与可拉取性 + +```mermaid +graph LR +MI["MultimodalInput(后端)"] --> GR["Gradio FileData/Utils"] +BC["Chatbot(后端)"] --> GR +MUI["MultimodalInput(前端)"] --> AX["@ant-design/x"] +MUI --> AD["Ant Design"] +CB["Chatbot(前端)"] --> AX +CB --> AD +CB --> UF["upload.ts"] +MUI --> AT["Attachments(前端)"] +AT --> AX +``` + +**图表来源** + +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:1-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L1-L495) +- [frontend/pro/multimodal-input/multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/utils/upload.ts:1-45](file://frontend/utils/upload.ts#L1-L45) + +**章节来源** + +- [backend/modelscope_studio/components/pro/multimodal_input/**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:1-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L1-L495) +- [frontend/pro/multimodal-input/multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [frontend/antdx/attachments/attachments.tsx:1-413](file://frontend/antdx/attachments/attachments.tsx#L1-L413) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/utils/upload.ts:1-45](file://frontend/utils/upload.ts#L1-L45) + +## 性能考虑 + +- 文件上传 + - 使用 Gradio 缓存目录与下载工具，避免重复网络请求 + - 限制最大文件数量，启用单文件覆盖模式减少内存占用 +- 渲染优化 + - 文件卡片设置固定尺寸与圆角，避免布局抖动 + - 图片缩略图与媒体控件按需加载，减少首屏压力 +- 流式响应 + - 在后端将助手消息标记为 loading/pending，前端仅渲染已完成部分，提升感知速度 +- 资源服务 + - 通过统一的可拉取 URL 生成策略，减少跨域与权限问题 + +[本节为通用指导，无需特定文件引用] + +## 故障排查指南 + +- 文件无法预览 + - 检查文件是否为 http/https 链接或已通过后端 API 可拉取 + - 确认根路径与 API 前缀配置正确 + - 参考：[frontend/utils/upload.ts:12-44](file://frontend/utils/upload.ts#L12-L44) +- 上传失败或卡住 + - 查看上传禁用状态（disabled/loading/readOnly/uploading） + - 检查最大数量限制与 beforeUpload 回调返回值 + - 参考：[frontend/antdx/attachments/attachments.tsx:168-354](file://frontend/antdx/attachments/attachments.tsx#L168-L354) +- 历史消息格式错误 + - 用户消息需包含 type 与 content 数组，文件项应为路径或 FileData + - 参考：[docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- 事件未触发 + - 确认前端容器已绑定对应事件（如 suggestionSelect、welcomePromptSelect） + - 参考：[frontend/pro/chatbot/index.svelte:58-61](file://frontend/pro/chatbot/index.svelte#L58-L61) + +**章节来源** + +- [frontend/utils/upload.ts:12-44](file://frontend/utils/upload.ts#L12-L44) +- [frontend/antdx/attachments/attachments.tsx:168-354](file://frontend/antdx/attachments/attachments.tsx#L168-L354) +- [docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- [frontend/pro/chatbot/index.svelte:58-61](file://frontend/pro/chatbot/index.svelte#L58-L61) + +## 结论 + +该多模态支持方案以标准化的消息结构为核心，结合后端组件的数据处理与前端组件的渲染能力，实现了图片、视频、音频与文件的统一输入、上传、存储与展示。通过可配置的附件面板与文件卡片，开发者可在不牺牲用户体验的前提下，灵活扩展与定制多模态聊天机器人的表现形式。 + +[本节为总结性内容，无需特定文件引用] + +## 附录 + +- 多模态消息发送示例 + - 将文本与文件数组组合为用户消息，提交后端并等待流式响应 + - 参考：[docs/components/pro/chatbot/demos/multimodal.py:82-118](file://docs/components/pro/chatbot/demos/multimodal.py#L82-L118) +- 历史消息格式化 + - 用户消息包含文本与图片数组，图片可转为 base64 或保持路径 + - 参考：[docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- 细粒度控制 + - 自定义文件项字段（如 text/files），按需拼装消息 + - 参考：[docs/layout_templates/chatbot/demos/fine_grained_control.py:100-133](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L100-L133) + +**章节来源** + +- [docs/components/pro/chatbot/demos/multimodal.py:82-118](file://docs/components/pro/chatbot/demos/multimodal.py#L82-L118) +- [docs/layout_templates/chatbot/demos/basic.py:145-181](file://docs/layout_templates/chatbot/demos/basic.py#L145-L181) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py:100-133](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L100-L133) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\346\200\235\350\200\203\350\277\207\347\250\213\345\261\225\347\244\272.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\346\200\235\350\200\203\350\277\207\347\250\213\345\261\225\347\244\272.md" new file mode 100644 index 00000000..0fa0c52b --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\346\200\235\350\200\203\350\277\207\347\250\213\345\261\225\347\244\272.md" @@ -0,0 +1,329 @@ +# 思考过程展示 + + +**本文引用的文件** +- [backend/modelscope_studio/components/antdx/thought_chain/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py) +- [backend/modelscope_studio/components/antdx/think/__init__.py](file://backend/modelscope_studio/components/antdx/think/__init__.py) +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) +- [frontend/antdx/thought-chain/Index.svelte](file://frontend/antdx/thought-chain/Index.svelte) +- [frontend/antdx/thought-chain/thought-chain.tsx](file://frontend/antdx/thought-chain/thought-chain.tsx) +- [frontend/antdx/thought-chain/thought-chain-item/Index.svelte](file://frontend/antdx/thought-chain/thought-chain-item/Index.svelte) +- [frontend/pro/chatbot/chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) +- [frontend/pro/chatbot/message.tsx](file://frontend/pro/chatbot/message.tsx) +- [frontend/pro/chatbot/messages/tool.tsx](file://frontend/pro/chatbot/messages/tool.tsx) +- [frontend/pro/chatbot/type.ts](file://frontend/pro/chatbot/type.ts) +- [docs/components/antdx/thought_chain/README-zh_CN.md](file://docs/components/antdx/thought_chain/README-zh_CN.md) +- [docs/components/antdx/thought_chain/demos/basic.py](file://docs/components/antdx/thought_chain/demos/basic.py) +- [docs/components/pro/chatbot/demos/thinking.py](file://docs/components/pro/chatbot/demos/thinking.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件围绕 Chatbot 聊天机器人组件中的“思考过程展示”能力进行系统化说明，目标是帮助开发者正确配置与呈现 AI 的思考过程，包括中间推理结果、工具调用链路、状态切换与最终回复的时机控制。文档涵盖以下关键点： + +- 如何在 Chatbot 中插入“思考”消息（tool 类型），并以 ThoughtChain/Think 组件进行可视化展示 +- 思考链（Thought Chain）的配置项、状态管理与嵌套使用 +- 思考过程与最终回复的时序控制与交互设计 +- 可视化展示方案与调试优化建议 + +## 项目结构 + +该功能涉及后端 Python 组件与前端 Svelte/React 层的协同： + +- 后端：提供 ThoughtChain、ThoughtChainItem、Think 等组件类，负责属性透传与前端资源定位 +- 前端：Svelte 包装层将 Ant Design X 的 ThoughtChain/Item 渲染为可消费的组件；Chatbot 消息渲染器根据内容类型选择 ToolMessage 或其他消息类型 + +```mermaid +graph TB +subgraph "后端" +BT["AntdXThoughtChain
AntdXThoughtChainItem
AntdXThink"] +end +subgraph "前端" +FS["frontend/antdx/thought-chain/*
Svelte 包装层"] +FC["frontend/pro/chatbot/*
Chatbot 与消息渲染"] +end +BT --> FS +FS --> FC +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:51-80](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L51-L80) +- [backend/modelscope_studio/components/antdx/think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [frontend/antdx/thought-chain/Index.svelte:1-62](file://frontend/antdx/thought-chain/Index.svelte#L1-L62) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/message.tsx:1-133](file://frontend/pro/chatbot/message.tsx#L1-L133) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [frontend/antdx/thought-chain/Index.svelte:1-62](file://frontend/antdx/thought-chain/Index.svelte#L1-L62) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) + +## 核心组件 + +- ThoughtChain（后端类）：用于承载多个 ThoughtChainItem，支持展开/折叠、线条样式、根类名等配置 +- ThoughtChainItem（后端类）：单个思考节点，支持标题、描述、状态、可折叠、额外操作区、内容区、页脚区 +- Think（后端类）：用于在 Chatbot 中以“思考”形式展示中间推理或工具调用的 UI 片段 +- Chatbot（后端类）：消息容器，支持多种内容类型（text/tool/file/suggestion），并定义消息数据模型与预处理/后处理逻辑 +- 前端包装层：Svelte 将 Ant Design X 的 ThoughtChain/Item 组件桥接为可消费的组件，同时传递 slots 与 props +- ToolMessage：渲染 tool 类型消息，支持折叠/展开与 Markdown 渲染 + +**章节来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:51-80](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L51-L80) +- [backend/modelscope_studio/components/antdx/think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [frontend/pro/chatbot/messages/tool.tsx:1-46](file://frontend/pro/chatbot/messages/tool.tsx#L1-L46) + +## 架构总览 + +下图展示了从后端组件到前端渲染的整体流程，以及 Chatbot 中“思考”消息的插入与展示路径。 + +```mermaid +sequenceDiagram +participant Py as "后端组件
AntdXThoughtChain/Item
AntdXThink" +participant FE as "前端包装层
Svelte + TSX" +participant CB as "Chatbot
消息渲染" +participant TM as "ToolMessage
折叠/展开" +Py->>FE : "解析并传递属性与slots" +FE->>FE : "动态导入 Ant Design X 组件" +FE->>CB : "作为子组件注入到 Chatbot" +CB->>TM : "当 content.type='tool' 时渲染 ToolMessage" +TM-->>CB : "根据 options.status 控制折叠状态" +CB-->>Py : "最终值经后端预处理/后处理" +``` + +**图表来源** + +- [frontend/antdx/thought-chain/Index.svelte:1-62](file://frontend/antdx/thought-chain/Index.svelte#L1-L62) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/message.tsx:1-133](file://frontend/pro/chatbot/message.tsx#L1-L133) +- [frontend/pro/chatbot/messages/tool.tsx:1-46](file://frontend/pro/chatbot/messages/tool.tsx#L1-L46) + +## 组件详解 + +### ThoughtChain 与 ThoughtChainItem 配置与使用 + +- ThoughtChain 支持： + - expanded_keys/default_expanded_keys：控制初始展开项 + - line：连接线样式（实线/虚线/点线） + - items：显式传入节点列表 + - 根级样式/类名：styles/class_names/root_class_name + - 事件：expand（展开键变更回调） +- ThoughtChainItem 支持： + - title/description/status/prefixCls/icon/key/collapsible + - 插槽：extra/content/footer + - 通过 slots 注入复杂内容（如按钮、图标、段落等） + +```mermaid +classDiagram +class AntdXThoughtChain { ++expanded_keys ++default_expanded_keys ++line ++items ++styles ++class_names ++root_class_name ++EVENTS ++SLOTS +} +class AntdXThoughtChainItem { ++title ++description ++status ++key ++collapsible ++icon ++extra ++content ++footer ++blink ++SLOTS +} +AntdXThoughtChain --> AntdXThoughtChainItem : "包含多个节点" +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:30-67](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L30-L67) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:51-60](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L51-L60) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:12-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L12-L86) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:51-80](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L51-L80) +- [docs/components/antdx/thought_chain/README-zh_CN.md:1-10](file://docs/components/antdx/thought_chain/README-zh_CN.md#L1-L10) +- [docs/components/antdx/thought_chain/demos/basic.py:1-77](file://docs/components/antdx/thought_chain/demos/basic.py#L1-L77) + +### Think 组件在 Chatbot 中的应用 + +- Think 提供“思考”片段的 UI 片段，支持 loading、默认展开、闪烁等特性 +- 在 Chatbot 中，可通过向消息内容数组追加 type 为 tool 的条目来展示“思考”过程 +- 示例演示了在流式响应中，先插入一条“Thinking...”的 tool 消息，随后实时更新其内容；当首次出现最终回复片段时，将“思考”标题更新为“End of Thought (耗时)”并标记为完成态 + +```mermaid +sequenceDiagram +participant Demo as "示例逻辑
thinking.py" +participant Chatbot as "Chatbot" +participant OpenAI as "OpenAI 流式响应" +Demo->>Chatbot : "追加一条 type='tool' 的思考消息" +OpenAI-->>Demo : "delta.reasoning_content" +Demo->>Chatbot : "增量更新思考消息内容" +OpenAI-->>Demo : "delta.content最终回复片段" +Demo->>Chatbot : "更新思考消息标题与状态为 done" +Demo->>Chatbot : "追加最终回复文本消息" +``` + +**图表来源** + +- [docs/components/pro/chatbot/demos/thinking.py:82-118](file://docs/components/pro/chatbot/demos/thinking.py#L82-L118) +- [frontend/pro/chatbot/messages/tool.tsx:13-18](file://frontend/pro/chatbot/messages/tool.tsx#L13-L18) + +**章节来源** + +- [backend/modelscope_studio/components/antdx/think/**init**.py:8-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L8-L79) +- [docs/components/pro/chatbot/demos/thinking.py:82-118](file://docs/components/pro/chatbot/demos/thinking.py#L82-L118) +- [frontend/pro/chatbot/messages/tool.tsx:13-18](file://frontend/pro/chatbot/messages/tool.tsx#L13-L18) + +### Chatbot 消息类型与 ToolMessage 渲染 + +- Chatbot 支持的消息类型：text、tool、file、suggestion +- tool 类型消息由 ToolMessage 渲染，支持： + - options.title：标题（Markdown 渲染取决于 renderMarkdown） + - options.status：'pending'/'done' 决定是否折叠 + - 内容区域支持 Markdown 渲染或纯文本 +- Chatbot 的消息渲染器根据 content.type 分发到对应组件 + +```mermaid +flowchart TD +Start(["进入 Message 渲染"]) --> CheckType{"content.type"} +CheckType --> |text| RenderText["渲染 TextMessage"] +CheckType --> |tool| RenderTool["渲染 ToolMessage
根据 options.status 折叠/展开"] +CheckType --> |file| RenderFile["渲染 FileMessage"] +CheckType --> |suggestion| RenderSuggestion["渲染 SuggestionMessage"] +RenderTool --> End(["完成"]) +RenderText --> End +RenderFile --> End +RenderSuggestion --> End +``` + +**图表来源** + +- [frontend/pro/chatbot/message.tsx:39-133](file://frontend/pro/chatbot/message.tsx#L39-L133) +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) +- [frontend/pro/chatbot/type.ts:121-135](file://frontend/pro/chatbot/type.ts#L121-L135) + +**章节来源** + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [frontend/pro/chatbot/message.tsx:39-133](file://frontend/pro/chatbot/message.tsx#L39-L133) +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) +- [frontend/pro/chatbot/type.ts:54-66](file://frontend/pro/chatbot/type.ts#L54-L66) + +### 思考链（Thought Chain）的配置与使用 + +- 在 Chatbot 中，若需要以“思考链”的方式分步展示推理与工具调用，可使用 ThoughtChain/Item 组件 +- 通过后端组件类的 slots 机制，将多个 ThoughtChainItem 组合为一个链路 +- 支持在每个节点中放置 extra/content/footer 插槽，实现更丰富的交互与信息密度 + +**章节来源** + +- [docs/components/antdx/thought_chain/README-zh_CN.md:1-10](file://docs/components/antdx/thought_chain/README-zh_CN.md#L1-L10) +- [docs/components/antdx/thought_chain/demos/basic.py:24-77](file://docs/components/antdx/thought_chain/demos/basic.py#L24-L77) +- [frontend/antdx/thought-chain/Index.svelte:1-62](file://frontend/antdx/thought-chain/Index.svelte#L1-L62) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) + +## 依赖关系分析 + +- 后端组件类仅负责属性透传与前端目录解析，不直接参与业务逻辑 +- 前端 Svelte 包装层负责将 Ant Design X 的 ThoughtChain/Item 组件桥接为可消费的组件，并处理 slots 与 props +- Chatbot 通过消息类型分发到具体的消息组件（TextMessage/ToolMessage/FileMessage/SuggestionMessage） + +```mermaid +graph LR +PyTC["后端 ThoughtChain/Item"] --> Wrap["Svelte 包装层"] +PyThink["后端 Think"] --> Wrap +Wrap --> ADX["Ant Design X 组件库"] +ADX --> CB["Chatbot"] +CB --> Msg["消息渲染器"] +Msg --> Tool["ToolMessage"] +``` + +**图表来源** + +- [backend/modelscope_studio/components/antdx/thought_chain/**init**.py:68-86](file://backend/modelscope_studio/components/antdx/thought_chain/__init__.py#L68-L86) +- [backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/**init**.py:61-80](file://backend/modelscope_studio/components/antdx/thought_chain/thought_chain_item/__init__.py#L61-L80) +- [backend/modelscope_studio/components/antdx/think/**init**.py:61-79](file://backend/modelscope_studio/components/antdx/think/__init__.py#L61-L79) +- [frontend/antdx/thought-chain/Index.svelte:10-62](file://frontend/antdx/thought-chain/Index.svelte#L10-L62) +- [frontend/antdx/thought-chain/thought-chain.tsx:11-40](file://frontend/antdx/thought-chain/thought-chain.tsx#L11-L40) +- [frontend/pro/chatbot/chatbot.tsx:450-472](file://frontend/pro/chatbot/chatbot.tsx#L450-L472) + +**章节来源** + +- [frontend/antdx/thought-chain/Index.svelte:1-62](file://frontend/antdx/thought-chain/Index.svelte#L1-L62) +- [frontend/antdx/thought-chain/thought-chain.tsx:1-43](file://frontend/antdx/thought-chain/thought-chain.tsx#L1-L43) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) + +## 性能考量 + +- 流式更新策略：在 Chatbot 中采用增量更新的方式，避免频繁重绘整个消息列表 +- ToolMessage 折叠控制：通过 options.status 初始决定折叠状态，减少不必要的渲染 +- 合理使用 slots：在 ThoughtChain/Item 中仅注入必要内容，避免过深的嵌套层级 +- 后端预处理/后处理：对文件路径与头像等静态资源进行预处理，降低前端渲染成本 + +[本节为通用指导，无需特定文件引用] + +## 故障排查指南 + +- 思考消息未显示 + - 检查消息类型是否为 tool，且 content 中包含有效内容 + - 确认 options.status 是否被设置为 done 导致自动折叠 +- 思考标题未更新 + - 确认在首次收到 delta.content 时，已更新思考消息的 options.title 与 options.status +- ThoughtChain/Item 不生效 + - 确认后端组件类的 slots 正确传递，且前端包装层已正确解析 slots +- 性能问题 + - 减少每轮更新的数据量，合并多次增量更新 + - 对长内容启用 Markdown 渲染时注意文本大小 + +**章节来源** + +- [docs/components/pro/chatbot/demos/thinking.py:82-118](file://docs/components/pro/chatbot/demos/thinking.py#L82-L118) +- [frontend/pro/chatbot/messages/tool.tsx:13-18](file://frontend/pro/chatbot/messages/tool.tsx#L13-L18) + +## 结论 + +通过 ThoughtChain/Item 与 Think 组件，结合 Chatbot 的消息类型体系，可以清晰地展示 AI 的思考过程与工具调用链路。合理配置状态与插槽，配合流式更新策略，既能提升用户体验，也能保证良好的性能表现。在实际项目中，建议优先采用 tool 类型消息承载“思考”内容，并在最终回复到达时及时更新状态与标题，形成完整的“思考—执行—反馈”闭环。 + +[本节为总结性内容，无需特定文件引用] + +## 附录 + +- 示例参考 + - ThoughtChain 基础示例：[docs/components/antdx/thought_chain/demos/basic.py:1-77](file://docs/components/antdx/thought_chain/demos/basic.py#L1-L77) + - Chatbot 思考过程示例：[docs/components/pro/chatbot/demos/thinking.py:1-218](file://docs/components/pro/chatbot/demos/thinking.py#L1-L218) +- 组件文档 + - ThoughtChain 文档：[docs/components/antdx/thought_chain/README-zh_CN.md:1-10](file://docs/components/antdx/thought_chain/README-zh_CN.md#L1-L10) + +[本节为补充材料，无需特定文件引用] diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\346\225\260\346\215\256\346\250\241\345\236\213.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\346\225\260\346\215\256\346\250\241\345\236\213.md" new file mode 100644 index 00000000..c6891edf --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\346\225\260\346\215\256\346\250\241\345\236\213.md" @@ -0,0 +1,441 @@ +# 数据模型 + + +**本文引用的文件** +- [frontend/pro/chatbot/type.ts](file://frontend/pro/chatbot/type.ts) +- [frontend/pro/chatbot/utils.ts](file://frontend/pro/chatbot/utils.ts) +- [frontend/pro/chatbot/message.tsx](file://frontend/pro/chatbot/message.tsx) +- [frontend/pro/chatbot/messages/text.tsx](file://frontend/pro/chatbot/messages/text.tsx) +- [frontend/pro/chatbot/messages/tool.tsx](file://frontend/pro/chatbot/messages/tool.tsx) +- [frontend/pro/chatbot/messages/file.tsx](file://frontend/pro/chatbot/messages/file.tsx) +- [frontend/pro/chatbot/messages/suggestion.tsx](file://frontend/pro/chatbot/messages/suggestion.tsx) +- [docs/components/pro/chatbot/README.md](file://docs/components/pro/chatbot/README.md) +- [docs/components/pro/chatbot/demos/message_config.py](file://docs/components/pro/chatbot/demos/message_config.py) +- [docs/components/pro/chatbot/demos/chatbot_config.py](file://docs/components/pro/chatbot/demos/chatbot_config.py) + + +## 目录 + +1. [引言](#引言) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 引言 + +本章节面向 Chatbot 聊天机器人组件的数据模型，系统性梳理消息与内容的数据结构、字段定义、渲染行为、序列化与反序列化路径、以及验证与错误处理策略。重点覆盖以下核心类型： + +- ChatbotMessage：单条消息 +- ChatbotMessages：消息数组 +- ChatbotMessageContentObject：消息内容对象 +- 文本、工具、文件、建议四类内容的结构与配置 +- 前端渲染管线与后端 Python 模型之间的映射关系 + +## 项目结构 + +围绕数据模型的相关代码主要分布在前端 Pro Chatbot 组件与文档示例中： + +- 类型定义与配置：frontend/pro/chatbot/type.ts +- 消息内容归一化与复制逻辑：frontend/pro/chatbot/utils.ts +- 单条消息渲染入口：frontend/pro/chatbot/message.tsx +- 内容子组件：text.tsx、tool.tsx、file.tsx、suggestion.tsx +- 文档与示例（Python 后端模型）：docs/components/pro/chatbot/README.md、demos/\*.py + +```mermaid +graph TB +subgraph "前端类型与渲染" +T["type.ts
类型定义"] +U["utils.ts
内容归一化/复制/遍历"] +M["message.tsx
消息渲染入口"] +MT["messages/text.tsx"] +MU["messages/tool.tsx"] +MF["messages/file.tsx"] +MS["messages/suggestion.tsx"] +end +subgraph "文档与示例" +D1["README.md
Python 类型定义"] +E1["demos/message_config.py"] +E2["demos/chatbot_config.py"] +end +T --> M +U --> M +M --> MT +M --> MU +M --> MF +M --> MS +D1 --> E1 +D1 --> E2 +E1 --> M +E2 --> M +``` + +**图表来源** + +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/utils.ts:1-157](file://frontend/pro/chatbot/utils.ts#L1-L157) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [frontend/pro/chatbot/messages/text.tsx:1-19](file://frontend/pro/chatbot/messages/text.tsx#L1-L19) +- [frontend/pro/chatbot/messages/tool.tsx:1-46](file://frontend/pro/chatbot/messages/tool.tsx#L1-L46) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/pro/chatbot/messages/suggestion.tsx:1-37](file://frontend/pro/chatbot/messages/suggestion.tsx#L1-L37) +- [docs/components/pro/chatbot/README.md:80-354](file://docs/components/pro/chatbot/README.md#L80-L354) +- [docs/components/pro/chatbot/demos/message_config.py:1-65](file://docs/components/pro/chatbot/demos/message_config.py#L1-L65) +- [docs/components/pro/chatbot/demos/chatbot_config.py:1-123](file://docs/components/pro/chatbot/demos/chatbot_config.py#L1-L123) + +**章节来源** + +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/utils.ts:1-157](file://frontend/pro/chatbot/utils.ts#L1-L157) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [docs/components/pro/chatbot/README.md:80-354](file://docs/components/pro/chatbot/README.md#L80-L354) + +## 核心组件 + +本节对数据模型中的关键类型进行逐项解析，并给出字段语义、可选值、默认行为与使用要点。 + +- ChatbotMessage（单条消息） + - 字段要点 + - role：用户、助手、系统、分割线或内部欢迎标识 + - content：字符串、内容对象或内容对象数组；支持多段内容拼接 + - status：挂起/完成；挂起时不会渲染操作区（如动作按钮与底部信息） + - meta.feedback：点赞/踩反馈状态 + - divider_props、key、头/尾/头像符号键：用于渲染与标识 + - 使用方法 + - 在后端通过 ChatbotDataMessage 构造消息列表，传入前端 Chatbot 组件 + - 前端 message.tsx 将 content 归一化为内容对象数组并分发到对应子组件 + +- ChatbotMessages（消息数组） + - 类型别名：ChatbotMessage[] + - 用途：作为组件的 value 属性承载完整对话历史 + +- ChatbotMessageContentObject（消息内容对象） + - 字段要点 + - type：text、tool、file、suggestion 四种 + - content：对应类型的实际值 + - options：各类型的专属配置 + - copyable、editable：是否允许复制/编辑（仅 text/tool 生效） + +- 文本内容（text） + - 值类型：字符串 + - 配置：继承 Markdown 渲染能力（是否渲染、标签白名单、换行、RTL 等） + - 行为：支持复制、编辑（当 editable 为真且处于可编辑上下文） + +- 工具内容（tool） + - 值类型：字符串 + - 配置：标题、状态（pending/done）、Markdown 渲染 + - 行为：根据状态决定折叠/展开；支持复制、编辑 + +- 文件内容（file） + - 值类型：字符串或附件对象数组 + - 配置：Flex 布局参数（垂直/换行/对齐/间距等），以及图片/视频/音频卡片属性 + - 行为：将字符串或附件解析为可预览文件卡片，支持打开链接 + +- 建议内容（suggestion） + - 值类型：提示项数组（Ant Design X Prompts） + - 配置：标题、垂直布局、换行、样式与类名 + - 行为：渲染为可点击的提示列表；非最后一条消息时会禁用交互 + +- 用户/机器人配置（ChatbotUserConfig、ChatbotBotConfig） + - 动作：copy、edit、delete（用户）；copy、like、dislike、retry、edit、delete（机器人） + - 头部/底部/头像：支持自定义 + - 样式：elem_style、elem_classes、styles、class_names + +**章节来源** + +- [frontend/pro/chatbot/type.ts:121-160](file://frontend/pro/chatbot/type.ts#L121-L160) +- [frontend/pro/chatbot/type.ts:137-158](file://frontend/pro/chatbot/type.ts#L137-L158) +- [docs/components/pro/chatbot/README.md:297-352](file://docs/components/pro/chatbot/README.md#L297-L352) + +## 架构总览 + +下图展示从“消息内容”到“具体渲染”的端到端流程，涵盖前端类型定义、内容归一化、子组件渲染与后端模型映射。 + +```mermaid +sequenceDiagram +participant Backend as "后端
ChatbotDataMessage" +participant Frontend as "前端
Chatbot" +participant Utils as "工具
normalizeMessageContent" +participant Message as "消息渲染
message.tsx" +participant Text as "文本组件
text.tsx" +participant Tool as "工具组件
tool.tsx" +participant File as "文件组件
file.tsx" +participant Suggest as "建议组件
suggestion.tsx" +Backend->>Frontend : 传递 ChatbotDataMessages +Frontend->>Utils : 归一化 content +Utils-->>Frontend : 返回内容对象数组 +Frontend->>Message : 渲染每条消息 +Message->>Text : type="text" +Message->>Tool : type="tool" +Message->>File : type="file" +Message->>Suggest : type="suggestion" +Text-->>Message : 文本渲染结果 +Tool-->>Message : 折叠/展开工具内容 +File-->>Message : 文件卡片渲染 +Suggest-->>Message : 提示列表渲染 +Message-->>Frontend : 完整消息渲染 +``` + +**图表来源** + +- [docs/components/pro/chatbot/README.md:321-352](file://docs/components/pro/chatbot/README.md#L321-L352) +- [frontend/pro/chatbot/utils.ts:46-72](file://frontend/pro/chatbot/utils.ts#L46-L72) +- [frontend/pro/chatbot/message.tsx:52-175](file://frontend/pro/chatbot/message.tsx#L52-L175) +- [frontend/pro/chatbot/messages/text.tsx:11-18](file://frontend/pro/chatbot/messages/text.tsx#L11-L18) +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) +- [frontend/pro/chatbot/messages/file.tsx:44-118](file://frontend/pro/chatbot/messages/file.tsx#L44-L118) +- [frontend/pro/chatbot/messages/suggestion.tsx:16-36](file://frontend/pro/chatbot/messages/suggestion.tsx#L16-L36) + +## 详细组件分析 + +### 类型体系与关系 + +```mermaid +classDiagram +class ChatbotMessage { ++role ++content ++status ++meta ++divider_props ++key +} +class ChatbotMessageContentObject { ++type ++content ++options ++copyable ++editable +} +class ChatbotTextContentConfig +class ChatbotToolContentConfig { ++status ++title +} +class ChatbotFileContentConfig { ++vertical ++wrap ++justify ++align ++gap ++imageProps ++videoProps ++audioProps +} +class ChatbotSuggestionContentConfig +ChatbotMessage --> ChatbotMessageContentObject : "包含" +ChatbotMessageContentObject --> ChatbotTextContentConfig : "options" +ChatbotMessageContentObject --> ChatbotToolContentConfig : "options" +ChatbotMessageContentObject --> ChatbotFileContentConfig : "options" +ChatbotMessageContentObject --> ChatbotSuggestionContentConfig : "options" +``` + +**图表来源** + +- [frontend/pro/chatbot/type.ts:121-160](file://frontend/pro/chatbot/type.ts#L121-L160) +- [frontend/pro/chatbot/type.ts:54-68](file://frontend/pro/chatbot/type.ts#L54-L68) + +**章节来源** + +- [frontend/pro/chatbot/type.ts:121-160](file://frontend/pro/chatbot/type.ts#L121-L160) + +### 内容归一化与复制 + +- 归一化规则 + - 字符串：转为单元素内容对象（type=text） + - 数组：逐项检查，字符串转为 text 对象，否则保持原对象 + - 其他对象：包装为单元素数组 +- 复制规则 + - 若 content 不可复制（copyable=false），返回空字符串 + - 字符串：直接返回 + - 文件：序列化为可访问的 URL 列表 + - 其他：序列化为 JSON 字符串 +- 编辑更新 + - 支持按索引批量更新内容对象或字符串 + +```mermaid +flowchart TD +Start(["开始"]) --> CheckType["判断 content 类型"] +CheckType --> |字符串| ToSingle["封装为 type=text 的对象"] +CheckType --> |数组| MapItems["逐项转换：字符串->text 对象"] +CheckType --> |对象| WrapOne["包装为单元素数组"] +CheckType --> |其他| Empty["返回空数组"] +ToSingle --> End(["结束"]) +MapItems --> End +WrapOne --> End +Empty --> End +``` + +**图表来源** + +- [frontend/pro/chatbot/utils.ts:46-72](file://frontend/pro/chatbot/utils.ts#L46-L72) + +**章节来源** + +- [frontend/pro/chatbot/utils.ts:46-103](file://frontend/pro/chatbot/utils.ts#L46-L103) + +### 文本内容渲染 + +- 配置项：是否渲染 Markdown、LaTeX 分隔符、HTML 清洗、换行、RTL、允许标签 +- 行为：根据配置决定直接显示或交给 Markdown 组件渲染 + +**章节来源** + +- [frontend/pro/chatbot/messages/text.tsx:11-18](file://frontend/pro/chatbot/messages/text.tsx#L11-L18) +- [docs/components/pro/chatbot/README.md:120-174](file://docs/components/pro/chatbot/README.md#L120-L174) + +### 工具内容渲染 + +- 配置项：标题、状态（pending/done 控制折叠）、Markdown 渲染 +- 行为：根据状态初始化折叠状态；支持点击切换 + +**章节来源** + +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) +- [docs/components/pro/chatbot/README.md:254-261](file://docs/components/pro/chatbot/README.md#L254-L261) + +### 文件内容渲染 + +- 值解析：字符串或附件对象统一解析为文件卡片所需字段（uid/name/url/type/size） +- 配置项：Flex 布局与图片/视频/音频卡片属性 +- 行为：渲染文件卡片并提供预览链接 + +**章节来源** + +- [frontend/pro/chatbot/messages/file.tsx:18-42](file://frontend/pro/chatbot/messages/file.tsx#L18-L42) +- [frontend/pro/chatbot/messages/file.tsx:44-118](file://frontend/pro/chatbot/messages/file.tsx#L44-L118) +- [docs/components/pro/chatbot/README.md:264-281](file://docs/components/pro/chatbot/README.md#L264-L281) + +### 建议内容渲染 + +- 值类型：提示项数组（支持嵌套 children） +- 配置项：标题、垂直/换行、样式与类名 +- 行为：渲染为可点击的提示列表；非最后一条消息时禁用交互 + +**章节来源** + +- [frontend/pro/chatbot/messages/suggestion.tsx:16-36](file://frontend/pro/chatbot/messages/suggestion.tsx#L16-L36) +- [docs/components/pro/chatbot/README.md:284-291](file://docs/components/pro/chatbot/README.md#L284-L291) + +### 序列化与反序列化示例 + +- 后端到前端 + - 后端使用 ChatbotDataMessage/ChatbotDataMessages 构造消息列表 + - 前端 message.tsx 接收并调用 normalizeMessageContent 归一化 + - 子组件按 type 分发渲染 +- 前端到后端 + - 复制：getCopyText 将内容序列化为字符串或 JSON + - 编辑：updateContent 按索引更新内容对象或字符串 +- 示例参考 + - 基础消息配置与动作按钮：[docs/components/pro/chatbot/demos/message_config.py:10-61](file://docs/components/pro/chatbot/demos/message_config.py#L10-L61) + - 欢迎提示与重试：[docs/components/pro/chatbot/demos/chatbot_config.py:43-119](file://docs/components/pro/chatbot/demos/chatbot_config.py#L43-L119) + +**章节来源** + +- [docs/components/pro/chatbot/demos/message_config.py:10-61](file://docs/components/pro/chatbot/demos/message_config.py#L10-L61) +- [docs/components/pro/chatbot/demos/chatbot_config.py:43-119](file://docs/components/pro/chatbot/demos/chatbot_config.py#L43-L119) +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) +- [frontend/pro/chatbot/utils.ts:74-103](file://frontend/pro/chatbot/utils.ts#L74-L103) + +### 数据验证与错误处理 + +- 角色枚举校验：role 必须为受支持的枚举值之一 +- 内容类型校验：type 必须为 text/tool/file/suggestion +- 可编辑性：仅当 editable 为真且类型为 text/tool 时才进入编辑态 +- 状态影响渲染：status=pending 时不渲染动作区 +- 建议禁用：非最后一条消息时自动禁用建议项交互 +- 复制保护：copyable=false 时复制返回空字符串 + +**章节来源** + +- [frontend/pro/chatbot/type.ts:137-158](file://frontend/pro/chatbot/type.ts#L137-L158) +- [frontend/pro/chatbot/type.ts:121-135](file://frontend/pro/chatbot/type.ts#L121-L135) +- [frontend/pro/chatbot/message.tsx:52-175](file://frontend/pro/chatbot/message.tsx#L52-L175) +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) + +## 依赖分析 + +- 类型依赖 + - ChatbotMessage 依赖 ChatbotMessageContentObject 与配置类型（用户/机器人） + - 内容对象依赖各自配置类型（文本/工具/文件/建议） +- 渲染依赖 + - message.tsx 依赖各子组件（text/tool/file/suggestion） + - utils.ts 为 message.tsx 提供内容归一化、复制与遍历能力 +- 后端映射 + - 文档 README.md 中的 ChatbotDataMessage/ChatbotDataMessages 与前端类型一一对应 + +```mermaid +graph LR +A["ChatbotMessage"] --> B["ChatbotMessageContentObject"] +B --> C["ChatbotTextContentConfig"] +B --> D["ChatbotToolContentConfig"] +B --> E["ChatbotFileContentConfig"] +B --> F["ChatbotSuggestionContentConfig"] +G["message.tsx"] --> B +G --> C +G --> D +G --> E +G --> F +H["utils.ts"] --> G +I["README.md
ChatbotDataMessage"] --> A +``` + +**图表来源** + +- [frontend/pro/chatbot/type.ts:121-160](file://frontend/pro/chatbot/type.ts#L121-L160) +- [frontend/pro/chatbot/message.tsx:52-175](file://frontend/pro/chatbot/message.tsx#L52-L175) +- [frontend/pro/chatbot/utils.ts:46-72](file://frontend/pro/chatbot/utils.ts#L46-L72) +- [docs/components/pro/chatbot/README.md:321-352](file://docs/components/pro/chatbot/README.md#L321-L352) + +**章节来源** + +- [frontend/pro/chatbot/type.ts:121-160](file://frontend/pro/chatbot/type.ts#L121-L160) +- [frontend/pro/chatbot/message.tsx:52-175](file://frontend/pro/chatbot/message.tsx#L52-L175) +- [frontend/pro/chatbot/utils.ts:46-72](file://frontend/pro/chatbot/utils.ts#L46-L72) +- [docs/components/pro/chatbot/README.md:321-352](file://docs/components/pro/chatbot/README.md#L321-L352) + +## 性能考虑 + +- 内容归一化：避免重复判断与转换，尽量在上游（后端）构造标准化结构 +- 渲染优化：建议对长列表启用虚拟滚动；对文件卡片使用懒加载与尺寸限制 +- 复制与编辑：批量更新时避免不必要的重渲染，优先使用不可变更新策略 +- Markdown 渲染：合理设置允许标签与清洗策略，减少 DOM 注入风险 + +## 故障排查指南 + +- 现象：消息不显示动作按钮 + - 可能原因：status=pending + - 解决：将 status 设为 done 或移除 pending +- 现象：建议项无法点击 + - 可能原因：非最后一条消息 + - 解决：确保该消息为最后一条，或在渲染前禁用建议项 +- 现象：复制为空 + - 可能原因：copyable=false 或内容不可复制 + - 解决：开启 copyable 或调整内容类型 +- 现象：工具内容未折叠 + - 可能原因：status 未设为 done + - 解决：将 status 设为 done 以初始折叠 + +**章节来源** + +- [frontend/pro/chatbot/type.ts:137-158](file://frontend/pro/chatbot/type.ts#L137-L158) +- [frontend/pro/chatbot/messages/tool.tsx:13-18](file://frontend/pro/chatbot/messages/tool.tsx#L13-L18) +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) + +## 结论 + +本文档系统梳理了 Chatbot 聊天机器人组件的数据模型，明确了消息与内容对象的字段、渲染行为与配置方式，并给出了前后端映射、序列化/反序列化路径与常见问题的排查方法。遵循本文档的结构与约束，可在保证一致性的同时扩展更多内容类型与交互能力。 + +## 附录 + +- 示例参考 + - 基础消息与动作按钮：[docs/components/pro/chatbot/demos/message_config.py:10-61](file://docs/components/pro/chatbot/demos/message_config.py#L10-L61) + - 欢迎提示与重试：[docs/components/pro/chatbot/demos/chatbot_config.py:43-119](file://docs/components/pro/chatbot/demos/chatbot_config.py#L43-L119) +- 类型定义参考 + - ChatbotDataMessage/ChatbotDataMessages 等 Python 类型：[docs/components/pro/chatbot/README.md:297-352](file://docs/components/pro/chatbot/README.md#L297-L352) + - 前端类型定义：[frontend/pro/chatbot/type.ts:121-160](file://frontend/pro/chatbot/type.ts#L121-L160) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\346\266\210\346\201\257\345\244\204\347\220\206.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\346\266\210\346\201\257\345\244\204\347\220\206.md" new file mode 100644 index 00000000..fbac8a95 --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\346\266\210\346\201\257\345\244\204\347\220\206.md" @@ -0,0 +1,397 @@ +# 消息处理 + + +**本文引用的文件** +- [frontend/pro/chatbot/chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) +- [frontend/pro/chatbot/message.tsx](file://frontend/pro/chatbot/message.tsx) +- [frontend/pro/chatbot/utils.ts](file://frontend/pro/chatbot/utils.ts) +- [frontend/pro/chatbot/type.ts](file://frontend/pro/chatbot/type.ts) +- [frontend/pro/chatbot/chatbot-footer.tsx](file://frontend/pro/chatbot/chatbot-footer.tsx) +- [frontend/pro/chatbot/chatbot-header.tsx](file://frontend/pro/chatbot/chatbot-header.tsx) +- [frontend/pro/chatbot/messages/text.tsx](file://frontend/pro/chatbot/messages/text.tsx) +- [frontend/pro/chatbot/messages/tool.tsx](file://frontend/pro/chatbot/messages/tool.tsx) +- [frontend/pro/chatbot/messages/file.tsx](file://frontend/pro/chatbot/messages/file.tsx) +- [frontend/pro/chatbot/messages/suggestion.tsx](file://frontend/pro/chatbot/messages/suggestion.tsx) +- [frontend/pro/chatbot/messages/welcome.tsx](file://frontend/pro/chatbot/messages/welcome.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) + +## 简介 + +本章节面向 Chatbot 聊天机器人组件的消息处理能力，系统性阐述消息的预处理与后处理机制、消息内容的转换与格式化、消息事件的绑定与处理（复制、编辑、删除、点赞/踩、重试等）、消息状态管理（pending、done）与实时更新策略，并提供可扩展的自定义方式与回调使用建议。文档以循序渐进的方式组织，既适合快速上手，也便于深入理解实现细节。 + +## 项目结构 + +消息处理相关代码集中在前端 pro/chatbot 目录，采用“容器组件 + 子消息组件 + 工具函数 + 类型定义”的分层设计： + +- 容器组件：负责消息列表渲染、事件桥接、状态管理与滚动控制 +- 子消息组件：按类型渲染文本、工具输出、文件附件、建议提示等 +- 工具函数：消息内容归一化、复制文本提取、编辑内容更新、头像属性解析等 +- 类型定义：统一消息结构、动作数据、配置项与回调参数 + +```mermaid +graph TB +Chatbot["Chatbot 容器组件
chatbot.tsx"] --> Header["ChatbotHeader
chatbot-header.tsx"] +Chatbot --> Footer["ChatbotFooter
chatbot-footer.tsx"] +Chatbot --> Message["Message 渲染器
message.tsx"] +Message --> TextMsg["文本消息
messages/text.tsx"] +Message --> ToolMsg["工具消息
messages/tool.tsx"] +Message --> FileMsg["文件消息
messages/file.tsx"] +Message --> SuggestionMsg["建议提示
messages/suggestion.tsx"] +Chatbot --> Utils["工具函数
utils.ts"] +Chatbot --> Types["类型定义
type.ts"] +Chatbot --> Welcome["欢迎消息
messages/welcome.tsx"] +``` + +图表来源 + +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [frontend/pro/chatbot/utils.ts:1-157](file://frontend/pro/chatbot/utils.ts#L1-L157) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/chatbot-footer.tsx:1-363](file://frontend/pro/chatbot/chatbot-footer.tsx#L1-L363) +- [frontend/pro/chatbot/chatbot-header.tsx:1-23](file://frontend/pro/chatbot/chatbot-header.tsx#L1-L23) +- [frontend/pro/chatbot/messages/text.tsx:1-19](file://frontend/pro/chatbot/messages/text.tsx#L1-L19) +- [frontend/pro/chatbot/messages/tool.tsx:1-46](file://frontend/pro/chatbot/messages/tool.tsx#L1-L46) +- [frontend/pro/chatbot/messages/file.tsx:1-119](file://frontend/pro/chatbot/messages/file.tsx#L1-L119) +- [frontend/pro/chatbot/messages/suggestion.tsx:1-37](file://frontend/pro/chatbot/messages/suggestion.tsx#L1-L37) +- [frontend/pro/chatbot/messages/welcome.tsx:1-55](file://frontend/pro/chatbot/messages/welcome.tsx#L1-L55) + +章节来源 + +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [frontend/pro/chatbot/utils.ts:1-157](file://frontend/pro/chatbot/utils.ts#L1-L157) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) + +## 核心组件 + +- Chatbot 容器组件：负责消息列表的渲染、滚动控制、事件桥接（复制、编辑、删除、点赞/踩、重试、建议选择、欢迎词提示选择），以及消息状态的变更（如反馈标记） +- Message 渲染器：根据消息内容类型（文本、工具、文件、建议）进行差异化渲染；支持在编辑态下对可编辑内容进行内联编辑 +- 子消息组件：分别处理文本 Markdown 渲染、工具输出折叠面板、文件附件卡片、建议提示列表 +- 工具函数：消息内容归一化、复制文本提取、编辑内容更新、头像属性解析、建议内容遍历 +- 类型定义：统一消息结构、动作数据、配置项与回调参数，确保编译期约束与 IDE 提示 + +章节来源 + +- [frontend/pro/chatbot/chatbot.tsx:51-472](file://frontend/pro/chatbot/chatbot.tsx#L51-L472) +- [frontend/pro/chatbot/message.tsx:25-183](file://frontend/pro/chatbot/message.tsx#L25-L183) +- [frontend/pro/chatbot/utils.ts:46-157](file://frontend/pro/chatbot/utils.ts#L46-L157) +- [frontend/pro/chatbot/type.ts:121-197](file://frontend/pro/chatbot/type.ts#L121-L197) + +## 架构总览 + +消息处理的总体流程如下： + +- 输入消息数组经容器组件解析为 Bubble 列表项，附加索引、头/尾部信息、头像属性与“是否最后一条”标记 +- 每条消息在默认后处理阶段由 Message 渲染器根据类型选择对应子组件 +- 用户通过底部操作区触发复制、编辑、删除、点赞/踩、重试等事件，容器组件通过回调将事件与索引传递给上层应用 +- 编辑流程采用“编辑态 -> 确认/取消”的两段式交互，确认后通过不可变更新替换对应消息内容 +- 状态管理通过消息对象的 meta 字段记录反馈状态，支持 pending/done 状态在工具消息中驱动折叠面板 + +```mermaid +sequenceDiagram +participant U as "用户" +participant CB as "Chatbot 容器
chatbot.tsx" +participant MSG as "Message 渲染器
message.tsx" +participant FOOT as "底部操作区
chatbot-footer.tsx" +participant UTIL as "工具函数
utils.ts" +U->>CB : "传入消息数组 value" +CB->>CB : "解析并注入元信息
索引/头像/最后一条" +CB->>MSG : "渲染每条消息内容" +U->>FOOT : "点击复制/编辑/删除/点赞/重试" +FOOT->>CB : "回调 onCopy/onEdit/onDelete/onLike/onRetry" +CB->>UTIL : "复制时提取纯文本/链接" +CB->>CB : "编辑时进入编辑态
收集输入值" +U->>FOOT : "确认编辑" +FOOT->>CB : "onEditConfirm({index, value, previous_value})" +CB->>CB : "不可变更新替换消息内容" +CB-->>U : "UI 实时刷新" +``` + +图表来源 + +- [frontend/pro/chatbot/chatbot.tsx:137-245](file://frontend/pro/chatbot/chatbot.tsx#L137-L245) +- [frontend/pro/chatbot/message.tsx:52-175](file://frontend/pro/chatbot/message.tsx#L52-L175) +- [frontend/pro/chatbot/chatbot-footer.tsx:255-362](file://frontend/pro/chatbot/chatbot-footer.tsx#L255-L362) +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) + +## 详细组件分析 + +### 消息预处理与后处理机制 + +- 预处理 + - 解析输入消息数组，为每条消息注入索引、头/尾部信息、头像属性、是否最后一条标记，并生成唯一 key + - 合并用户/机器人配置，统一样式、类名、元素类等 + - 将 markdown 配置标准化，注入根路径与主题模式 +- 后处理 + - 默认后处理阶段：根据角色渲染头/体/尾部，注入头像、标题、内容渲染器 + - 内容渲染器：根据消息类型选择文本、工具、文件或建议组件 + - 编辑态：当某条消息处于编辑态时，可编辑类型（文本、工具）会显示文本域，输入值暂存于 editValues 中 + +```mermaid +flowchart TD +Start(["开始"]) --> Pre1["解析输入 value
注入索引/头像/最后一条"] +Pre1 --> Pre2["合并用户/机器人配置"] +Pre2 --> Pre3["标准化 markdown 配置"] +Pre3 --> Post1["默认后处理：角色映射
头/体/尾部注入"] +Post1 --> Render["内容渲染器：按类型选择子组件"] +Render --> EditCheck{"是否编辑态？"} +EditCheck --> |是| Edit["显示文本域
收集输入值"] +EditCheck --> |否| Done(["完成"]) +Edit --> Done +``` + +图表来源 + +- [frontend/pro/chatbot/chatbot.tsx:137-165](file://frontend/pro/chatbot/chatbot.tsx#L137-L165) +- [frontend/pro/chatbot/chatbot.tsx:246-422](file://frontend/pro/chatbot/chatbot.tsx#L246-L422) +- [frontend/pro/chatbot/message.tsx:52-81](file://frontend/pro/chatbot/message.tsx#L52-L81) + +章节来源 + +- [frontend/pro/chatbot/chatbot.tsx:137-165](file://frontend/pro/chatbot/chatbot.tsx#L137-L165) +- [frontend/pro/chatbot/chatbot.tsx:246-422](file://frontend/pro/chatbot/chatbot.tsx#L246-L422) +- [frontend/pro/chatbot/message.tsx:52-81](file://frontend/pro/chatbot/message.tsx#L52-L81) + +### 消息内容转换、验证与格式化 + +- 归一化：将字符串、数组或对象形式的内容统一封装为对象数组，保证后续渲染一致性 +- 复制文本提取：根据内容类型与 copyable 标记提取可复制文本，文件类型返回可访问链接的 JSON 表达 +- 编辑内容更新：根据当前内容形态（字符串/数组/对象）与编辑映射，生成新的内容结构 +- 建议内容遍历：对嵌套建议进行递归遍历，统一设置禁用状态等属性 + +```mermaid +flowchart TD +In(["输入 content"]) --> N1{"字符串？"} +N1 --> |是| N2["封装为单元素数组
type=text"] +N1 --> |否| N3{"数组？"} +N3 --> |是| N4["逐项检查：字符串->封装
对象->原样"] +N3 --> |否| N5{"对象？"} +N5 --> |是| N6["封装为单元素数组"] +N5 --> |否| N7["返回空数组"] +N2 --> Out(["输出对象数组"]) +N4 --> Out +N6 --> Out +N7 --> Out +``` + +图表来源 + +- [frontend/pro/chatbot/utils.ts:46-72](file://frontend/pro/chatbot/utils.ts#L46-L72) + +章节来源 + +- [frontend/pro/chatbot/utils.ts:46-157](file://frontend/pro/chatbot/utils.ts#L46-L157) + +### 消息事件绑定与处理（copy/edit/delete/like/retry） + +- 复制（copy） + - 底部操作区通过复制按钮触发，内部调用复制文本提取函数，最终触发 onCopy 回调 +- 编辑（edit） + - 进入编辑态后，输入值暂存在 editValues 中；确认时通过不可变更新替换对应消息内容，并触发 onEdit 回调 +- 删除（delete） + - 触发时通过不可变更新删除对应索引的消息项，并触发 onDelete 回调 +- 点赞/踩（like/dislike） + - 更新消息 meta.feedback 字段，支持切换；同时触发 onLike 回调 +- 重试（retry） + - 触发时调用 onRetry 回调，交由上层决定如何处理 + +```mermaid +sequenceDiagram +participant U as "用户" +participant FOOT as "底部操作区
chatbot-footer.tsx" +participant CB as "Chatbot 容器
chatbot.tsx" +participant UTIL as "工具函数
utils.ts" +U->>FOOT : "点击复制/编辑/删除/点赞/重试" +alt 复制 +FOOT->>UTIL : "getCopyText(content, root, apiPrefix)" +UTIL-->>FOOT : "返回可复制文本" +FOOT->>CB : "onCopy({index, value : 文本})" +else 编辑 +FOOT->>CB : "onEdit(index)" +CB->>CB : "setEditIndex(index)" +U->>CB : "输入框变更" +CB->>CB : "setEditValues(收集输入)" +U->>FOOT : "点击确认" +FOOT->>CB : "onEditConfirm({index, value, previous_value})" +CB->>CB : "不可变更新替换内容" +else 删除 +FOOT->>CB : "onDelete({index, value})" +CB->>CB : "不可变删除该消息" +else 点赞/踩 +FOOT->>CB : "onLike({index, value, liked})" +CB->>CB : "更新 meta.feedback 并触发回调" +else 重试 +FOOT->>CB : "onRetry({index, value})" +end +``` + +图表来源 + +- [frontend/pro/chatbot/chatbot-footer.tsx:53-100](file://frontend/pro/chatbot/chatbot-footer.tsx#L53-L100) +- [frontend/pro/chatbot/chatbot-footer.tsx:255-362](file://frontend/pro/chatbot/chatbot-footer.tsx#L255-L362) +- [frontend/pro/chatbot/chatbot.tsx:195-245](file://frontend/pro/chatbot/chatbot.tsx#L195-L245) +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) + +章节来源 + +- [frontend/pro/chatbot/chatbot-footer.tsx:53-100](file://frontend/pro/chatbot/chatbot-footer.tsx#L53-L100) +- [frontend/pro/chatbot/chatbot-footer.tsx:255-362](file://frontend/pro/chatbot/chatbot-footer.tsx#L255-L362) +- [frontend/pro/chatbot/chatbot.tsx:195-245](file://frontend/pro/chatbot/chatbot.tsx#L195-L245) +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) + +### 消息状态管理（pending、done）与实时更新 + +- 状态字段：消息对象支持 status 字段，用于标识“待处理/pending”或“已完成/done” +- 工具消息状态联动：工具消息组件根据 status 控制折叠面板初始展开状态 +- 反馈状态：消息对象 meta.feedback 记录用户反馈（like/dislike/null），用于 UI 着色与状态切换 +- 不可变更新：编辑确认、删除、点赞/踩均通过不可变更新策略修改消息数组，确保 React 有效 diff 与重渲染 + +```mermaid +stateDiagram-v2 +[*] --> Pending : "status='pending'" +Pending --> Done : "status='done'" +Done --> Pending : "status='pending'" +Done --> FeedbackLike : "用户点赞" +Done --> FeedbackDislike : "用户点踩" +FeedbackLike --> Done : "再次点赞/取消" +FeedbackDislike --> Done : "再次点踩/取消" +``` + +图表来源 + +- [frontend/pro/chatbot/type.ts:154-157](file://frontend/pro/chatbot/type.ts#L154-L157) +- [frontend/pro/chatbot/messages/tool.tsx:14-18](file://frontend/pro/chatbot/messages/tool.tsx#L14-L18) +- [frontend/pro/chatbot/chatbot.tsx:222-237](file://frontend/pro/chatbot/chatbot.tsx#L222-L237) + +章节来源 + +- [frontend/pro/chatbot/type.ts:154-157](file://frontend/pro/chatbot/type.ts#L154-L157) +- [frontend/pro/chatbot/messages/tool.tsx:14-18](file://frontend/pro/chatbot/messages/tool.tsx#L14-L18) +- [frontend/pro/chatbot/chatbot.tsx:222-237](file://frontend/pro/chatbot/chatbot.tsx#L222-L237) + +### 自定义扩展与回调使用 + +- 自定义渲染 + - 通过 Chatbot 的 userConfig/botConfig 注入样式、类名、元素类、头/尾部内容与头像 + - 通过 markdownConfig 控制 Markdown 渲染行为与主题模式 +- 自定义动作 + - actions/disabled_actions 支持增删改查、点赞/踩、重试等动作的启用/禁用与二次确认 + - 动作可附带 Tooltip 与 Popconfirm 提示 +- 回调扩展 + - onCopy/onEdit/onDelete/onLike/onRetry/onSuggestionSelect/onWelcomePromptSelect 等回调用于业务集成 + - onValueChange 用于接收消息数组变更后的最新值，便于持久化或进一步处理 + +章节来源 + +- [frontend/pro/chatbot/chatbot.tsx:66-107](file://frontend/pro/chatbot/chatbot.tsx#L66-L107) +- [frontend/pro/chatbot/chatbot.tsx:379-400](file://frontend/pro/chatbot/chatbot.tsx#L379-L400) +- [frontend/pro/chatbot/type.ts:79-119](file://frontend/pro/chatbot/type.ts#L79-L119) + +### 子消息组件与渲染逻辑 + +- 文本消息：支持 Markdown 渲染或直接文本展示 +- 工具消息：支持标题与内容的 Markdown 渲染，状态驱动折叠面板 +- 文件消息：支持图片/视频/音频卡片，自动解析可访问链接 +- 建议提示：支持多级嵌套，统一禁用状态与点击回调 +- 欢迎消息：整合欢迎语与提示词列表，支持图标 URL 解析 + +章节来源 + +- [frontend/pro/chatbot/messages/text.tsx:11-18](file://frontend/pro/chatbot/messages/text.tsx#L11-L18) +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) +- [frontend/pro/chatbot/messages/file.tsx:44-118](file://frontend/pro/chatbot/messages/file.tsx#L44-L118) +- [frontend/pro/chatbot/messages/suggestion.tsx:16-36](file://frontend/pro/chatbot/messages/suggestion.tsx#L16-L36) +- [frontend/pro/chatbot/messages/welcome.tsx:18-54](file://frontend/pro/chatbot/messages/welcome.tsx#L18-L54) + +## 依赖关系分析 + +- 组件耦合 + - Chatbot 对 Message、ChatbotHeader、ChatbotFooter、工具函数与类型定义存在强依赖 + - Message 对各子消息组件存在条件渲染依赖 + - ChatbotFooter 对工具函数中的复制文本提取与内容更新函数有直接调用 +- 外部依赖 + - 使用 Ant Design 组件库与 @ant-design/x 的 Bubble/List/Prompts/Welcome 等组件 + - 使用 immer 进行不可变更新 + - 使用 lodash-es 的 isEqual/omit 等工具函数 + +```mermaid +graph LR +Chatbot["chatbot.tsx"] --> Message["message.tsx"] +Chatbot --> Footer["chatbot-footer.tsx"] +Chatbot --> Header["chatbot-header.tsx"] +Chatbot --> Utils["utils.ts"] +Chatbot --> Types["type.ts"] +Message --> Text["messages/text.tsx"] +Message --> Tool["messages/tool.tsx"] +Message --> File["messages/file.tsx"] +Message --> Suggestion["messages/suggestion.tsx"] +Footer --> Utils +``` + +图表来源 + +- [frontend/pro/chatbot/chatbot.tsx:20-47](file://frontend/pro/chatbot/chatbot.tsx#L20-L47) +- [frontend/pro/chatbot/message.tsx:6-23](file://frontend/pro/chatbot/message.tsx#L6-L23) +- [frontend/pro/chatbot/chatbot-footer.tsx:32-31](file://frontend/pro/chatbot/chatbot-footer.tsx#L32-L31) + +章节来源 + +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [frontend/pro/chatbot/chatbot-footer.tsx:1-363](file://frontend/pro/chatbot/chatbot-footer.tsx#L1-L363) +- [frontend/pro/chatbot/utils.ts:1-157](file://frontend/pro/chatbot/utils.ts#L1-L157) +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) + +## 性能考虑 + +- 不可变更新：通过不可变更新策略减少不必要的重渲染，提升列表更新效率 +- 事件记忆化：使用 useMemoizedFn 包裹回调，降低因引用变化导致的子组件重渲染 +- 条件渲染：仅在需要时渲染底部操作区与编辑态 UI，避免无谓的 DOM 结构 +- 状态最小化：编辑态仅保存必要的 editValues 映射，避免冗余状态 +- 滚动控制：通过 useScroll 钩子控制滚动按钮显示与滚动行为，避免频繁滚动计算 + +章节来源 + +- [frontend/pro/chatbot/chatbot.tsx:172-183](file://frontend/pro/chatbot/chatbot.tsx#L172-L183) +- [frontend/pro/chatbot/chatbot.tsx:433-438](file://frontend/pro/chatbot/chatbot.tsx#L433-L438) +- [frontend/pro/chatbot/chatbot-footer.tsx:273-301](file://frontend/pro/chatbot/chatbot-footer.tsx#L273-L301) + +## 故障排查指南 + +- 复制结果为空 + - 检查内容是否被标记为不可复制（copyable=false），或内容形态不支持提取 + - 确认 rootUrl 与 apiPrefix 是否正确，文件链接解析是否可用 +- 编辑确认无效 + - 确认当前消息是否处于编辑态（isEditing），以及 editIndex 与当前索引一致 + - 检查 editValues 是否包含对应索引的输入值 +- 点赞/踩状态异常 + - 检查 meta.feedback 是否被正确更新，UI 着色是否依赖该字段 +- 工具消息未按预期折叠 + - 确认 status 是否为 'pending' 或 'done'，折叠面板初始状态由该状态决定 +- 欢迎提示点击无响应 + - 检查 onWelcomePromptSelect 回调是否正确传入，Prompts 的 items 是否正确解析 + +章节来源 + +- [frontend/pro/chatbot/utils.ts:105-140](file://frontend/pro/chatbot/utils.ts#L105-L140) +- [frontend/pro/chatbot/chatbot-footer.tsx:291-298](file://frontend/pro/chatbot/chatbot-footer.tsx#L291-L298) +- [frontend/pro/chatbot/chatbot.tsx:222-237](file://frontend/pro/chatbot/chatbot.tsx#L222-L237) +- [frontend/pro/chatbot/messages/tool.tsx:14-18](file://frontend/pro/chatbot/messages/tool.tsx#L14-L18) +- [frontend/pro/chatbot/messages/welcome.tsx:46-51](file://frontend/pro/chatbot/messages/welcome.tsx#L46-L51) + +## 结论 + +本组件通过清晰的预处理/后处理管线、完善的事件桥接与不可变更新策略，实现了对多类型消息的高效渲染与交互。借助丰富的配置与回调扩展点，开发者可在不破坏整体结构的前提下灵活定制 UI 与业务逻辑。配合性能优化与故障排查建议，可进一步提升用户体验与开发效率。 diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\351\205\215\347\275\256\351\200\211\351\241\271.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\351\205\215\347\275\256\351\200\211\351\241\271.md" new file mode 100644 index 00000000..48197678 --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\351\205\215\347\275\256\351\200\211\351\241\271.md" @@ -0,0 +1,364 @@ +# 配置选项 + + +**本文引用的文件** +- [frontend/pro/chatbot/type.ts](file://frontend/pro/chatbot/type.ts) +- [frontend/pro/chatbot/chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) +- [frontend/pro/chatbot/message.tsx](file://frontend/pro/chatbot/message.tsx) +- [frontend/pro/chatbot/messages/text.tsx](file://frontend/pro/chatbot/messages/text.tsx) +- [frontend/pro/chatbot/messages/tool.tsx](file://frontend/pro/chatbot/messages/tool.tsx) +- [frontend/pro/chatbot/messages/welcome.tsx](file://frontend/pro/chatbot/messages/welcome.tsx) +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) +- [docs/layout_templates/chatbot/demos/basic.py](file://docs/layout_templates/chatbot/demos/basic.py) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py](file://docs/layout_templates/chatbot/demos/fine_grained_control.py) +- [docs/layout_templates/chatbot/README-zh_CN.md](file://docs/layout_templates/chatbot/README-zh_CN.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本章节面向使用 Chatbot 聊天机器人组件的开发者与产品人员，系统性梳理前端与后端配置选项，覆盖欢迎配置（welcome_config）、Markdown 配置（markdown_config）、用户配置（user_config）、机器人配置（bot_config），并解释各配置项的作用、可选值与默认行为，提供配置示例与典型应用场景，说明配置之间的相互关系与优先级，最后给出高级技巧与性能优化建议。 + +## 项目结构 + +Chatbot 组件由前端 Svelte/React 实现与后端 Gradio 数据类定义共同组成： + +- 前端：类型定义、渲染逻辑、消息子组件、欢迎消息组件等 +- 后端：数据模型、事件绑定、静态资源处理、预处理/后处理逻辑 + +```mermaid +graph TB +subgraph "前端" +T["type.ts
类型与配置接口"] +C["chatbot.tsx
主组件与解析逻辑"] +M["message.tsx
消息渲染分发"] +MT["messages/text.tsx
文本消息"] +MU["messages/tool.tsx
工具消息"] +MW["messages/welcome.tsx
欢迎消息"] +end +subgraph "后端" +PY["__init__.py
数据类与组件实现"] +end +T --> C +C --> M +M --> MT +M --> MU +C --> MW +PY --> C +``` + +图表来源 + +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [frontend/pro/chatbot/message.tsx:1-184](file://frontend/pro/chatbot/message.tsx#L1-L184) +- [frontend/pro/chatbot/messages/text.tsx:1-19](file://frontend/pro/chatbot/messages/text.tsx#L1-L19) +- [frontend/pro/chatbot/messages/tool.tsx:1-46](file://frontend/pro/chatbot/messages/tool.tsx#L1-L46) +- [frontend/pro/chatbot/messages/welcome.tsx:1-55](file://frontend/pro/chatbot/messages/welcome.tsx#L1-L55) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:1-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L1-L495) + +章节来源 + +- [frontend/pro/chatbot/type.ts:1-197](file://frontend/pro/chatbot/type.ts#L1-L197) +- [frontend/pro/chatbot/chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:1-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L1-L495) + +## 核心组件 + +- 类型与配置接口：定义 welcome_config、markdown_config、user_config、bot_config 及消息内容对象的结构与可选字段 +- 主组件：负责合并默认值、解析配置、注入主题与根路径、渲染消息列表与欢迎区 +- 消息渲染：根据内容类型分发到文本、工具、文件、建议等子组件 +- 欢迎消息：渲染欢迎语与提示词卡片 + +章节来源 + +- [frontend/pro/chatbot/type.ts:27-158](file://frontend/pro/chatbot/type.ts#L27-L158) +- [frontend/pro/chatbot/chatbot.tsx:51-472](file://frontend/pro/chatbot/chatbot.tsx#L51-L472) +- [frontend/pro/chatbot/message.tsx:25-184](file://frontend/pro/chatbot/message.tsx#L25-L184) +- [frontend/pro/chatbot/messages/welcome.tsx:11-54](file://frontend/pro/chatbot/messages/welcome.tsx#L11-L54) + +## 架构总览 + +下图展示了 Chatbot 的配置解析与渲染流程，从 props 到最终渲染的关键节点与依赖关系。 + +```mermaid +sequenceDiagram +participant U as "调用方" +participant C as "Chatbot 主组件" +participant R as "角色解析器" +participant W as "欢迎消息" +participant MSG as "消息渲染" +participant MD as "Markdown 渲染" +U->>C : 传入 welcome_config / markdown_config / user_config / bot_config +C->>C : 解析并合并默认值 +C->>R : 注入角色映射与后处理 +R-->>C : 返回角色化后的 Bubble.List +C->>W : 渲染欢迎区含提示词 +C->>MSG : 渲染消息列表 +MSG->>MD : 文本/工具消息按需渲染 Markdown +MSG-->>C : 子组件输出 +W-->>C : 欢迎区输出 +C-->>U : 完整 UI 输出 +``` + +图表来源 + +- [frontend/pro/chatbot/chatbot.tsx:76-472](file://frontend/pro/chatbot/chatbot.tsx#L76-L472) +- [frontend/pro/chatbot/messages/welcome.tsx:18-54](file://frontend/pro/chatbot/messages/welcome.tsx#L18-L54) +- [frontend/pro/chatbot/message.tsx:39-184](file://frontend/pro/chatbot/message.tsx#L39-L184) +- [frontend/pro/chatbot/messages/text.tsx:11-18](file://frontend/pro/chatbot/messages/text.tsx#L11-L18) +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) + +## 详细组件分析 + +### 欢迎配置（welcome_config） + +- 作用：控制欢迎区的外观、文案与提示词卡片 +- 关键字段 + - variant：外观变体，支持 borderless、filled + - icon：图标，可为字符串、路径或文件数据 + - title：标题 + - description：描述 + - extra：附加内容 + - elem_style / elem_classes / styles / class_names：样式与类名 + - prompts：提示词卡片集合（见下方“提示词配置”） +- 默认行为 + - 若未提供，主组件会以 borderless 作为默认变体 +- 与提示词的关系 + - prompts 字段可嵌套提示词卡片配置，用于引导用户快速开始 + +章节来源 + +- [frontend/pro/chatbot/type.ts:34-41](file://frontend/pro/chatbot/type.ts#L34-L41) +- [frontend/pro/chatbot/chatbot.tsx:108-115](file://frontend/pro/chatbot/chatbot.tsx#L108-L115) +- [frontend/pro/chatbot/messages/welcome.tsx:24-51](file://frontend/pro/chatbot/messages/welcome.tsx#L24-L51) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:38-50](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L38-L50) + +### 提示词配置（prompts 在 welcome_config 中） + +- 作用：在欢迎区展示一组提示词卡片，辅助用户快速发起对话 +- 关键字段 + - title：提示词区域标题 + - vertical / wrap：布局方向与换行 + - styles / class_names / elem_style / elem_classes：样式与类名 + - items：提示词条目数组（每个条目包含 label、description、children 等） + +章节来源 + +- [frontend/pro/chatbot/type.ts:27-32](file://frontend/pro/chatbot/type.ts#L27-L32) +- [frontend/pro/chatbot/messages/welcome.tsx:41-51](file://frontend/pro/chatbot/messages/welcome.tsx#L41-L51) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:26-36](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L26-L36) + +### Markdown 配置（markdown_config） + +- 作用：统一控制文本与工具消息中的 Markdown 渲染行为 +- 关键字段 + - renderMarkdown：是否启用 Markdown 渲染（前端） + - render_markdown：是否启用 Markdown 渲染（后端） + - latex_delimiters：LaTeX 分隔符配置 + - sanitize_html：是否清理 HTML + - line_breaks：是否保留换行 + - rtl：是否从右到左 + - allow_tags：允许的标签或布尔开关 +- 默认行为 + - 前端默认开启 renderMarkdown 并设置换行策略 + - 后端默认启用渲染、清理 HTML、换行与多组 LaTeX 分隔符 + +章节来源 + +- [frontend/pro/chatbot/type.ts:54-56](file://frontend/pro/chatbot/type.ts#L54-L56) +- [frontend/pro/chatbot/message.tsx:87-95](file://frontend/pro/chatbot/message.tsx#L87-L95) +- [frontend/pro/chatbot/messages/tool.tsx:14-18](file://frontend/pro/chatbot/messages/tool.tsx#L14-L18) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:52-106](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L52-L106) + +### 用户配置（user_config） + +- 作用：控制用户消息气泡的外观、头像、动作按钮与样式 +- 关键字段 + - actions：动作按钮列表，支持 copy、edit、delete；或带 tooltip/popconfirm 的对象 + - disabled_actions：禁用的动作集合 + - header / footer：头部与尾部文案 + - avatar：头像，可为字符串、文件数据或头像属性对象 + - variant / shape / placement：外观、形状与位置 + - loading / typing：加载与打字效果 + - elem_style / elem_classes / styles / class_names：样式与类名 +- 默认行为 + - 默认仅启用 copy 动作（后端默认值） + +章节来源 + +- [frontend/pro/chatbot/type.ts:86-97](file://frontend/pro/chatbot/type.ts#L86-L97) +- [frontend/pro/chatbot/chatbot.tsx:246-432](file://frontend/pro/chatbot/chatbot.tsx#L246-L432) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:117-151](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L117-L151) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:123-131](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L123-L131) + +### 机器人配置（bot_config） + +- 作用：控制机器人消息气泡的外观、头像、动作按钮与样式 +- 关键字段 + - actions：动作按钮列表，支持 copy、like、dislike、retry、edit、delete；或带 tooltip/popconfirm 的对象 + - disabled_actions：禁用的动作集合 + - header / footer：头部与尾部文案 + - avatar：头像 + - variant / shape / placement：外观、形状与位置 + - loading / typing：加载与打字效果 + - elem_style / elem_classes / styles / class_names：样式与类名 +- 默认行为 + - 默认启用 copy 动作（后端默认值） + +章节来源 + +- [frontend/pro/chatbot/type.ts:108-119](file://frontend/pro/chatbot/type.ts#L108-L119) +- [frontend/pro/chatbot/chatbot.tsx:246-432](file://frontend/pro/chatbot/chatbot.tsx#L246-L432) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:153-180](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L153-L180) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:162-170](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L162-L170) + +### 消息内容与渲染（消息类型与选项） + +- 内容类型 + - text：纯文本或 Markdown 文本 + - tool：工具消息，可折叠显示标题与内容 + - file：文件列表，支持图片/视频/音频属性 + - suggestion：建议列表，支持禁用与点击回调 +- 内容选项 + - 文本/工具：继承 Markdown 配置，工具消息支持 title 与 status（pending/done） + - 文件：继承 Flex 布局配置，支持 imageProps/videoProps/audioProps + - 建议：继承提示词配置 +- 编辑与可复制 + - 可通过 content.options.editable 控制是否允许编辑 + - 可通过 content.options.copyable 控制是否允许复制 + +章节来源 + +- [frontend/pro/chatbot/type.ts:43-68](file://frontend/pro/chatbot/type.ts#L43-L68) +- [frontend/pro/chatbot/type.ts:121-135](file://frontend/pro/chatbot/type.ts#L121-L135) +- [frontend/pro/chatbot/message.tsx:52-174](file://frontend/pro/chatbot/message.tsx#L52-L174) +- [frontend/pro/chatbot/messages/text.tsx:11-18](file://frontend/pro/chatbot/messages/text.tsx#L11-L18) +- [frontend/pro/chatbot/messages/tool.tsx:13-45](file://frontend/pro/chatbot/messages/tool.tsx#L13-L45) + +### 配置优先级与合并规则 + +- 主组件解析顺序 + - welcome_config：以 borderless 为默认变体，其余字段按传入覆盖 + - markdown_config：前端默认开启换行与渲染，后端默认启用渲染与清理 + - user_config / bot_config：按传入覆盖，未传则为空对象 + - 消息级配置：message.options 与全局 markdown_config 合并，message.options 优先 +- 头像与静态资源 + - 后端会对 avatar 与 welcome.icon 进行静态资源包装，确保可访问 +- 角色与样式 + - 主组件根据角色（user/assistant/chatbot-internal-welcome）应用不同样式与类名 + +章节来源 + +- [frontend/pro/chatbot/chatbot.tsx:108-136](file://frontend/pro/chatbot/chatbot.tsx#L108-L136) +- [frontend/pro/chatbot/chatbot.tsx:246-432](file://frontend/pro/chatbot/chatbot.tsx#L246-L432) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:363-380](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L363-L380) + +### 配置示例与应用场景 + +- 基础示例 + - 使用 welcome_config 设置标题、描述与提示词卡片 + - 使用 user_config/bot_config 配置动作按钮与头像 + - 参考：[basic.py:516-564](file://docs/layout_templates/chatbot/demos/basic.py#L516-L564) +- 细粒度控制示例 + - 自定义角色渲染、消息状态与反馈按钮 + - 参考：[fine_grained_control.py:575-800](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L575-L800) +- 应用场景 + - 即时助手：启用 copy、like/dislike、retry、delete 等动作 + - 多轮对话：结合会话列表与消息状态管理 + - 多媒体输入：配合文件上传与文件消息渲染 + +章节来源 + +- [docs/layout_templates/chatbot/demos/basic.py:516-564](file://docs/layout_templates/chatbot/demos/basic.py#L516-L564) +- [docs/layout_templates/chatbot/demos/fine_grained_control.py:575-800](file://docs/layout_templates/chatbot/demos/fine_grained_control.py#L575-L800) +- [docs/layout_templates/chatbot/README-zh_CN.md:1-20](file://docs/layout_templates/chatbot/README-zh_CN.md#L1-L20) + +## 依赖分析 + +- 组件耦合 + - 主组件依赖类型定义与消息子组件，消息子组件再依赖 Markdown 渲染 + - 欢迎消息依赖提示词组件与文件 URL 处理 +- 外部依赖 + - Ant Design X（Welcome、Prompts、Bubble.List） + - Ant Design（Avatar、Button、Collapse、Flex 等） + - 全局 Markdown 组件与文件上传工具 + +```mermaid +graph LR +Chatbot["chatbot.tsx"] --> Types["type.ts"] +Chatbot --> Msg["message.tsx"] +Msg --> Text["messages/text.tsx"] +Msg --> Tool["messages/tool.tsx"] +Chatbot --> Welcome["messages/welcome.tsx"] +Chatbot --> ADX["Ant Design X 组件"] +Chatbot --> AD["Ant Design 组件"] +Chatbot --> GlobalMD["全局 Markdown 组件"] +``` + +图表来源 + +- [frontend/pro/chatbot/chatbot.tsx:26-47](file://frontend/pro/chatbot/chatbot.tsx#L26-L47) +- [frontend/pro/chatbot/message.tsx:10-23](file://frontend/pro/chatbot/message.tsx#L10-L23) +- [frontend/pro/chatbot/messages/text.tsx:2-4](file://frontend/pro/chatbot/messages/text.tsx#L2-L4) +- [frontend/pro/chatbot/messages/tool.tsx:3-4](file://frontend/pro/chatbot/messages/tool.tsx#L3-L4) +- [frontend/pro/chatbot/messages/welcome.tsx:3-6](file://frontend/pro/chatbot/messages/welcome.tsx#L3-L6) + +## 性能考虑 + +- 渲染优化 + - 合理使用 elem_style / styles 与 class_names，避免过度重排 + - 工具消息使用折叠（collapse）减少初始渲染开销 +- 资源处理 + - 头像与欢迎图标通过静态资源服务提供，避免重复传输 +- 交互节流 + - 对频繁触发的事件（如滚动、编辑）进行防抖/节流处理（在上层应用中实现） +- 内存与状态 + - 长对话建议限制消息数量或采用分页/懒加载策略 + +## 故障排查指南 + +- 欢迎图标不显示 + - 检查 welcome_config.icon 是否为有效路径或文件数据，确认静态资源服务已启用 +- Markdown 渲染异常 + - 前端检查 renderMarkdown 开关；后端检查 render_markdown 与 sanitize_html +- 动作按钮无效 + - 确认 actions 与 disabled_actions 配置正确，必要时使用 tooltip/popconfirm 对话框 +- 文件消息无法预览 + - 检查文件路径与 MIME 类型，确认后端已转换为 FileData + +章节来源 + +- [frontend/pro/chatbot/messages/welcome.tsx:32-38](file://frontend/pro/chatbot/messages/welcome.tsx#L32-L38) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:363-380](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L363-L380) +- [frontend/pro/chatbot/messages/tool.tsx:14-18](file://frontend/pro/chatbot/messages/tool.tsx#L14-L18) + +## 结论 + +通过系统化的配置选项与清晰的优先级规则，Chatbot 组件能够灵活适配多种业务场景。建议在实际项目中： + +- 明确各配置项职责边界，避免重复覆盖 +- 将 Markdown 与样式配置集中在全局，局部微调 +- 对多媒体与长文本采用折叠/懒加载策略 +- 在复杂交互场景下，结合细粒度控制示例进行二次封装 + +## 附录 + +- 快速对照表 + - welcome_config：variant/icon/title/description/extra/prompt + - markdown_config：renderMarkdown/render_markdown/latex_delimiters/sanitize_html/line_breaks/rtl/allow_tags + - user_config：actions/disabled_actions/header/footer/avatar/variant/shape/placement/loading/typing/elem_style/elem_classes/styles/class_names + - bot_config：actions/disabled_actions/header/footer/avatar/variant/shape/placement/loading/typing/elem_style/elem_classes/styles/class_names + - 消息内容：text/tool/file/suggestion，各自支持 options 与 copyable/editable diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\351\233\206\346\210\220\347\244\272\344\276\213.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\351\233\206\346\210\220\347\244\272\344\276\213.md" new file mode 100644 index 00000000..e5ab406d --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/Chatbot \350\201\212\345\244\251\346\234\272\345\231\250\344\272\272/\351\233\206\346\210\220\347\244\272\344\276\213.md" @@ -0,0 +1,349 @@ +# 集成示例 + + +**本文引用的文件** +- [backend/modelscope_studio/components/pro/chatbot/__init__.py](file://backend/modelscope_studio/components/pro/chatbot/__init__.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [frontend/pro/chatbot/Index.svelte](file://frontend/pro/chatbot/Index.svelte) +- [frontend/pro/chatbot/package.json](file://frontend/pro/chatbot/package.json) +- [docs/layout_templates/chatbot/README.md](file://docs/layout_templates/chatbot/README.md) +- [docs/layout_templates/chatbot/app.py](file://docs/layout_templates/chatbot/app.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向需要在实际项目中集成 Chatbot 聊天机器人组件的开发者，提供从后端 Python 组件到前端 Svelte 包装层的完整集成示例与最佳实践。内容覆盖与 Gradio 应用的集成方式、消息数据模型与事件绑定、与外部 AI 服务的连接思路、与数据库的交互策略、以及多种典型使用场景（客服机器人、问答系统、内容创作助手）的落地方法。同时给出部署指引、常见问题解决方案与性能优化建议。 + +## 项目结构 + +Chatbot 组件由后端 Python 组件与前端 Svelte 包装两部分组成： + +- 后端：基于 Gradio 的自定义组件，负责消息数据模型、预处理/后处理、静态资源托管与事件绑定。 +- 前端：Svelte 包装层，负责将 Gradio 属性映射到内部聊天组件，并通过异步加载实现按需渲染。 + +```mermaid +graph TB +subgraph "后端" +PY_INIT["Python 组件定义
backend/modelscope_studio/components/pro/chatbot/__init__.py"] +PY_PRO["导出入口
backend/modelscope_studio/components/pro/components.py"] +end +subgraph "前端" +FE_INDEX["Svelte 包装入口
frontend/pro/chatbot/Index.svelte"] +FE_PKG["包导出配置
frontend/pro/chatbot/package.json"] +end +PY_INIT --> PY_PRO +PY_PRO --> FE_INDEX +FE_INDEX --> FE_PKG +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) +- [frontend/pro/chatbot/package.json:1-15](file://frontend/pro/chatbot/package.json#L1-L15) + +章节来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [frontend/pro/chatbot/Index.svelte:1-90](file://frontend/pro/chatbot/Index.svelte#L1-L90) +- [frontend/pro/chatbot/package.json:1-15](file://frontend/pro/chatbot/package.json#L1-L15) + +## 核心组件 + +- 消息数据模型与配置类族 + - 文本、工具、文件、建议等多类型内容选项 + - 用户/机器人消息样式、头像、动作按钮、元信息等 +- 组件主体 + - 支持高度控制、自动滚动、欢迎页、Markdown 渲染、用户/机器人配置 + - 事件绑定：变更、复制、编辑、删除、点赞、重试、建议选择、欢迎提示选择 +- 预处理与后处理 + - 将前端传入的消息内容转换为后端可识别格式；将文件路径转换为 Gradio FileData 并注入 MIME 类型 + - 头像与静态资源路径处理 + +章节来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L284) +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) + +## 架构总览 + +下图展示了从 Gradio 应用到 Chatbot 组件的调用链路与数据流： + +```mermaid +sequenceDiagram +participant App as "Gradio 应用" +participant Py as "Python 组件
ModelScopeProChatbot" +participant FE as "Svelte 包装
Index.svelte" +participant UI as "聊天界面" +App->>Py : 初始化组件并传入 value/配置 +Py->>FE : 注入属性与事件回调 +FE->>UI : 异步加载并渲染 Chatbot +UI-->>FE : 用户交互事件复制/编辑/删除/点赞/重试/建议选择 +FE-->>Py : 触发对应事件回调 +Py-->>App : 返回处理后的消息列表 +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-314](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L314) +- [frontend/pro/chatbot/Index.svelte:67-89](file://frontend/pro/chatbot/Index.svelte#L67-L89) + +## 详细组件分析 + +### 数据模型与消息结构 + +- 内容类型 + - 文本、工具（含标题与状态）、文件（支持多文件，自动注入 FileData）、建议（Prompts） +- 消息对象 + - 角色（user/assistant/system/divider）、键值、状态（pending/done）、内容、动作、元信息 +- Markdown 与渲染 + - 可配置是否渲染 Markdown、LaTeX 分隔符、HTML 清洗、换行、RTL、允许标签 +- 文件展示布局 + - Flex 布局参数（垂直/换行/对齐/间距等），并可分别配置图片/视频/音频属性 +- 动作按钮 + - 用户与机器人的动作集合可独立配置，支持 Tooltip 与确认气泡 + +```mermaid +classDiagram +class ChatbotMarkdownConfig { ++bool render_markdown ++list latex_delimiters ++bool sanitize_html ++bool line_breaks ++bool rtl ++allow_tags +} +class ChatbotActionConfig { ++action ++tooltip ++popconfirm +} +class ChatbotUserConfig { ++actions ++disabled_actions ++avatar ++placement ++typing +} +class ChatbotBotConfig { ++actions ++disabled_actions ++placement +} +class ChatbotDataTextContentOptions +class ChatbotDataToolContentOptions { ++title ++status +} +class ChatbotDataFileContentOptions { ++vertical ++wrap ++justify ++align ++gap +} +class ChatbotDataSuggestionContentOptions +class ChatbotDataSuggestionContentItem +class ChatbotDataMeta { ++feedback +} +class ChatbotDataMessageContent { ++type ++copyable ++editable ++content ++options +} +class ChatbotDataMessage { ++role ++key ++status ++content ++meta +} +ChatbotDataMessage --> ChatbotDataMessageContent : "包含" +ChatbotDataMessageContent --> ChatbotDataTextContentOptions : "可选" +ChatbotDataMessageContent --> ChatbotDataToolContentOptions : "可选" +ChatbotDataMessageContent --> ChatbotDataFileContentOptions : "可选" +ChatbotDataMessageContent --> ChatbotDataSuggestionContentOptions : "可选" +ChatbotDataMessage --> ChatbotDataMeta : "可选" +ChatbotUserConfig <|-- ChatbotBotConfig : "继承" +ChatbotMarkdownConfig <|-- ChatbotDataTextContentOptions : "继承" +ChatbotPromptsConfig <|-- ChatbotDataSuggestionContentOptions : "继承" +ChatbotPromptConfig <|-- ChatbotDataSuggestionContentItem : "继承" +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L284) + +章节来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:14-284](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L14-L284) + +### 事件绑定与交互流程 + +- 事件列表 + - change、copy、edit、delete、like、retry、suggestion_select、welcome_prompt_select +- 绑定机制 + - 通过 Gradio 事件监听器在初始化时绑定相应回调，触发后更新内部状态并回传给应用 + +```mermaid +sequenceDiagram +participant UI as "聊天界面" +participant FE as "Svelte 包装" +participant Py as "Python 组件" +participant App as "Gradio 应用" +UI->>FE : 用户点击“复制/编辑/删除/点赞/重试” +FE->>Py : 触发对应事件如 copy/edit/delete/like/retry +Py-->>App : 回调返回处理后的消息列表 +App->>Py : 可能触发 suggestion_select 或 welcome_prompt_select +Py-->>App : 更新后的消息与状态 +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:289-314](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L289-L314) + +章节来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:289-314](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L289-L314) + +### 预处理与后处理逻辑 + +- 预处理 + - 将文件类内容中的 FileData 路径提取为字符串，便于跨层传输 +- 后处理 + - 将文件路径转换为 Gradio FileData，自动推断 MIME 类型与大小，支持 HTTP/本地路径 + - 头像与静态资源路径统一通过 serve_static_file 处理 + +```mermaid +flowchart TD +Start(["进入 preprocess/postprocess"]) --> CheckType{"输入类型？"} +CheckType --> |字符串/字典| Convert["转换为标准结构"] +CheckType --> |列表/元组| MapList["递归转换每个元素"] +Convert --> DonePre["返回标准化消息列表"] +MapList --> DonePre +DonePre --> PostProcess["后处理：文件转 FileData
头像路径处理"] +PostProcess --> End(["完成"]) +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:400-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L400-L495) + +章节来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:400-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L400-L495) + +### 与 Gradio 应用的集成 + +- 导出与导入 + - 在后端通过导出入口统一暴露组件，前端以 Svelte 包装形式被 Gradio 解析 +- 属性传递 + - Svelte 包装层将 Gradio 共享属性（root、api_prefix、theme）透传至组件 +- 示例模板 + - 提供应用模板与演示页面，展示多对话管理、历史操作、中断通知、输入建议、附件上传等功能 + +章节来源 + +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [frontend/pro/chatbot/Index.svelte:14-89](file://frontend/pro/chatbot/Index.svelte#L14-L89) +- [docs/layout_templates/chatbot/README.md:1-20](file://docs/layout_templates/chatbot/README.md#L1-L20) +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) + +## 依赖分析 + +- 组件耦合 + - 后端组件与前端包装通过 Gradio 协议解耦，前端仅负责属性映射与异步加载 +- 外部依赖 + - 使用 Gradio 的数据类与事件系统，文件处理依赖 Gradio Client 工具 +- 包导出 + - 前端包以 Gradio 兼容方式导出入口，确保在 Gradio 生态中可直接使用 + +```mermaid +graph LR +PY["Python 组件"] --> |事件/数据| GR["Gradio 协议"] +GR --> |属性/事件| FE["Svelte 包装"] +FE --> |渲染| UI["聊天界面"] +PY --> |文件处理| GC["Gradio Client 工具"] +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [frontend/pro/chatbot/package.json:4-13](file://frontend/pro/chatbot/package.json#L4-L13) + +章节来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:286-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L286-L495) +- [frontend/pro/chatbot/package.json:4-13](file://frontend/pro/chatbot/package.json#L4-L13) + +## 性能考虑 + +- 渲染优化 + - 使用异步加载组件，避免首屏阻塞 + - 控制消息数量与文件大小，必要时分页或懒加载 +- 事件处理 + - 对高频事件（如复制/编辑）进行节流或去抖 +- 文件处理 + - 优先使用 HTTP 链接减少本地读取开销；本地文件自动计算大小与 MIME 类型 +- 主题与样式 + - 通过 Gradio 共享主题属性统一渲染，减少重复计算 + +## 故障排查指南 + +- 无法显示文件内容 + - 检查文件路径是否正确，HTTP 链接是否可达；确认后处理阶段已转换为 FileData +- 头像不显示 + - 确认头像路径已通过静态资源处理函数转换 +- 事件未触发 + - 确认事件名称拼写一致且已在初始化时绑定 +- 消息状态异常 + - pending 状态不会渲染动作区，检查状态设置逻辑 + +章节来源 + +- [backend/modelscope_studio/components/pro/chatbot/**init**.py:390-495](file://backend/modelscope_studio/components/pro/chatbot/__init__.py#L390-L495) + +## 结论 + +Chatbot 组件通过清晰的数据模型、完善的事件体系与前后端解耦设计，能够高效支撑多种聊天场景。结合 Gradio 应用模板与 Svelte 包装层，开发者可以快速搭建具备多轮对话、历史管理、文件上传与反馈能力的智能聊天界面，并在此基础上扩展与优化。 + +## 附录 + +### 场景化集成要点 + +- 客服机器人 + - 使用欢迎页与提示词引导用户；启用“重试”与“编辑”动作提升纠错效率 +- 问答系统 + - 通过“建议选择”与“欢迎提示选择”快速生成问题；开启 LaTeX 渲染以支持公式 +- 内容创作助手 + - 支持多类型文件上传与展示；利用“点赞/反馈”收集用户偏好 + +### 部署与运行 + +- 运行示例应用模板 + - 使用文档模板提供的入口脚本启动队列与服务 +- 包导出与安装 + - 前端包以 Gradio 兼容方式导出，可在 Gradio 环境中直接引用 + +章节来源 + +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) +- [frontend/pro/chatbot/package.json:4-13](file://frontend/pro/chatbot/package.json#L4-L13) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250.md" new file mode 100644 index 00000000..8ac18468 --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250.md" @@ -0,0 +1,367 @@ +# MonacoEditor 代码编辑器 + + +**本文档引用的文件** +- [backend/modelscope_studio/components/pro/monaco_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [frontend/pro/monaco-editor/monaco-editor.tsx](file://frontend/pro/monaco-editor/monaco-editor.tsx) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx) +- [frontend/pro/monaco-editor/loader.ts](file://frontend/pro/monaco-editor/loader.ts) +- [frontend/pro/monaco-editor/useValueChange.ts](file://frontend/pro/monaco-editor/useValueChange.ts) +- [frontend/pro/monaco-editor/monaco-editor.less](file://frontend/pro/monaco-editor/monaco-editor.less) +- [docs/components/pro/monaco_editor/README.md](file://docs/components/pro/monaco_editor/README.md) +- [docs/components/pro/monaco_editor/README-zh_CN.md](file://docs/components/pro/monaco_editor/README-zh_CN.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向需要在应用中集成专业代码编辑器的开发者，系统性介绍基于 Monaco Editor 的代码编辑能力：语法高亮、智能提示、代码补全、Diff 编辑器等。文档覆盖组件的配置项（编辑器选项、JavaScript 自定义、差异编辑器等）、使用示例（不同编程语言支持与自定义配置）、编辑器加载机制与性能优化策略、主题配置、快捷键绑定以及插件扩展思路。内容兼顾技术深度与可读性，帮助快速落地高质量的代码编辑体验。 + +## 项目结构 + +该组件位于前后端分层清晰的工程中，采用“Python 后端 + React 前端 + Svelte 预处理”的混合架构： + +- 后端通过 Gradio 组件封装，提供统一的 Python API 与事件绑定 +- 前端使用 @monaco-editor/react 作为渲染层，配合本地/CDN 加载器初始化 Monaco 环境 +- 提供标准编辑器与 Diff 编辑器两种形态，支持主题切换、只读模式、行定位、加载态定制等 + +```mermaid +graph TB +subgraph "后端" +PY_API["Python 接口
Gradio 组件封装"] +end +subgraph "前端" +IDX["Svelte 入口
Index.svelte"] +EDIT["标准编辑器
monaco-editor.tsx"] +DIFF["差异编辑器
diff-editor/monaco-editor.diff-editor.tsx"] +LDR["加载器
loader.ts"] +VAL["值同步钩子
useValueChange.ts"] +CSS["样式
monaco-editor.less"] +end +PY_API --> IDX +IDX --> EDIT +IDX --> DIFF +EDIT --> LDR +DIFF --> LDR +EDIT --> VAL +DIFF --> VAL +EDIT --> CSS +DIFF --> CSS +``` + +图表来源 + +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-160](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L160) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) + +章节来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:1-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L1-L107) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:68-105](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L68-L105) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## 核心组件 + +- 标准编辑器组件：提供基础代码编辑能力，支持主题模式、只读、高度、加载态、事件绑定、JavaScript 自定义钩子等 +- 差异编辑器组件（MonacoEditorDiffEditor）：用于对比两段文本的差异，支持独立设置左右两侧语言、行定位、验证回调等 + - **后端导出入口**：`MonacoEditorDiffEditor` 通过 [backend/modelscope_studio/components/pro/**init**.py](file://backend/modelscope_studio/components/pro/__init__.py) 导出，导入方式为 `from modelscope_studio.components.pro import MonacoEditorDiffEditor` + - **与标准编辑器的关系**：MonacoEditorDiffEditor 是 MonacoEditor 的子组件，两者均属于 `pro` 模块。标准编辑器用于单文件编辑，差异编辑器专用于展示两个版本代码的 diff 对比。 +- 加载器：支持本地打包与 CDN 两种加载模式，自动注入 Monaco 环境与多语言 Worker +- 值同步钩子：在高频输入场景下进行去抖处理，避免频繁触发上层逻辑 + +章节来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:68-105](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L68-L105) +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-160](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L160) +- [frontend/pro/monaco-editor/loader.ts:27-95](file://frontend/pro/monaco-editor/loader.ts#L27-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:4-44](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L44) + +## 架构总览 + +整体调用链路如下： + +- 后端组件实例化时设置加载器模式、语言、只读、高度等参数 +- 前端入口根据加载器配置初始化 Monaco 环境（本地或 CDN） +- React 层通过 @monaco-editor/react 渲染编辑器，桥接生命周期钩子与事件 +- 值变更通过 useValueChange 进行节流，确保性能与一致性 + +```mermaid +sequenceDiagram +participant Py as "后端组件" +participant FE as "前端入口" +participant L as "加载器" +participant R as "React 编辑器" +participant M as "Monaco 环境" +Py->>FE : 传递加载器配置与属性 +FE->>L : 初始化本地/CDN 加载器 +L->>M : 注入 monaco 实例与 Worker +FE->>R : 渲染编辑器并传入选项 +R->>M : onMount 生命周期回调 +R-->>Py : 变更事件与值回传 +``` + +图表来源 + +- [frontend/pro/monaco-editor/loader.ts:3-95](file://frontend/pro/monaco-editor/loader.ts#L3-L95) +- [frontend/pro/monaco-editor/monaco-editor.tsx:38-92](file://frontend/pro/monaco-editor/monaco-editor.tsx#L38-L92) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:67-158](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L67-L158) + +## 详细组件分析 + +### 标准编辑器组件 + +- 职责：封装 Monaco Editor 的 React 组件，提供统一的属性接口与事件绑定 +- 关键特性 + - 主题模式：根据 themeMode 切换 vs-dark 或 light + - 只读模式：通过 readOnly 控制编辑态 + - 高度控制：height 支持数值（px）与 CSS 字符串 + - 加载态：支持自定义 loading 插槽或默认 Spin + - 事件绑定：支持 mount/change/validate 等事件 + - JavaScript 自定义：before_mount/after_mount 可传入 JS 字符串函数，分别在加载前/后执行 + - 值同步：内部使用 useValueChange 去抖处理，避免高频输入导致的性能问题 + +```mermaid +classDiagram +class 标准编辑器Props { ++string|undefined value ++string|undefined language ++boolean|undefined readOnly ++string|number|undefined height ++object|undefined options ++string|undefined themeMode ++function|undefined beforeMount ++function|undefined afterMount ++function|undefined onValueChange +} +class useValueChange { ++返回 : [value, setValue] ++作用 : 去抖更新值 +} +标准编辑器Props --> useValueChange : "使用" +``` + +图表来源 + +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:4-44](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L44) + +章节来源 + +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) + +### 差异编辑器组件 + +- 职责：对比两段文本的差异，支持独立设置左右语言、行定位、只读、验证回调等 +- 关键特性 + - 左右两侧值：original（左侧原值）、value/modified（右侧修改值） + - 语言分离：original_language 与 modified_language 可独立设置 + - 行定位：line 指定初始可视行，支持运行时更新 + - 验证回调：onValidate 获取校验结果，便于集成错误标记 + - 事件绑定：onChange 在右侧编辑器内容变化时触发 + - 加载态：支持自定义 loading 插槽或默认 Spin + +```mermaid +sequenceDiagram +participant FE as "前端差异编辑器" +participant E as "DiffEditor" +participant V as "useValueChange" +participant CB as "回调" +FE->>E : 渲染并传入 options/readOnly +E-->>FE : onMount 返回编辑器实例 +FE->>CB : afterMount 回调可访问 editor 与 monaco +E->>V : 内容变化 setValue +V-->>FE : 去抖后回传新值 +FE-->>CB : onChange/onValidate 回调 +``` + +图表来源 + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:35-159](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L35-L159) + +章节来源 + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-160](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L160) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:68-105](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L68-L105) + +### 加载器与环境初始化 + +- 本地加载（推荐离线/内网部署） + - 动态导入 monaco-editor 与各类语言 Worker + - 设置 MonacoEnvironment.getWorker，按标签选择对应 Worker + - 通过 monacoLoader.config 注入 monaco 实例 +- CDN 加载 + - 通过 monacoLoader.config 指定 vs 路径 + - 适用于外网可访问的场景 +- 并发初始化 + - 使用全局 Promise 避免重复初始化 + - 支持多次调用的安全完成回调 + +```mermaid +flowchart TD +Start(["开始"]) --> Mode{"加载模式"} +Mode --> |本地| Local["动态导入 monaco 与 Worker"] +Mode --> |CDN| CDN["设置 vs 路径"] +Local --> Env["配置 MonacoEnvironment.getWorker"] +Env --> Config["monacoLoader.config 注入"] +CDN --> Config +Config --> Done(["完成"]) +``` + +图表来源 + +- [frontend/pro/monaco-editor/loader.ts:27-95](file://frontend/pro/monaco-editor/loader.ts#L27-L95) + +章节来源 + +- [frontend/pro/monaco-editor/loader.ts:3-95](file://frontend/pro/monaco-editor/loader.ts#L3-L95) + +### 值同步与去抖策略 + +- 场景：编辑器高频 onChange 触发，上层逻辑可能昂贵 +- 策略：useValueChange 在短时间内合并更新，仅在去抖结束后回传最新值 +- 行为：typing 状态与定时器管理，确保输入过程中的流畅体验 + +```mermaid +flowchart TD +Enter(["输入事件"]) --> SetTyping["标记正在输入"] +SetTyping --> Debounce["启动去抖计时器(约100ms)"] +Debounce --> Update["计时结束，更新显示值"] +Update --> Callback["触发上层 onValueChange"] +Callback --> Clear["清理计时器"] +``` + +图表来源 + +- [frontend/pro/monaco-editor/useValueChange.ts:14-32](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L32) + +章节来源 + +- [frontend/pro/monaco-editor/useValueChange.ts:4-44](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L44) + +## 依赖关系分析 + +- 组件导出 + - 后端统一导出标准编辑器与差异编辑器类 +- 前端依赖 + - @monaco-editor/react：编辑器渲染与事件桥接 + - @svelte-preprocess-react：Svelte 与 React 的互操作 + - Ant Design Spin：默认加载态组件 + - useValueChange：自定义 Hook，负责值同步与去抖 +- 外部接口 + - Monaco Editor 官方类型与 API + - Gradio 事件监听与属性透传 + +```mermaid +graph LR +BE["后端组件"] --> FEI["前端入口"] +FEI --> REACT["@monaco-editor/react"] +FEI --> PRE["@svelte-preprocess-react"] +FEI --> ANT["Ant Design Spin"] +REACT --> MONACO["Monaco Editor"] +PRE --> HOOKS["useValueChange"] +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-10](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L10) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-17](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L17) + +章节来源 + +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## 性能考虑 + +- 去抖更新：useValueChange 将高频变更合并，减少上层处理压力 +- 按需加载：CDN 模式下仅加载必要资源；本地模式按标签选择 Worker，避免无关语言解析开销 +- 渲染隔离：编辑器容器独立样式，避免全局样式污染 +- 事件最小化：仅在必要时触发 onChange/validate，避免不必要的重渲染 +- 行定位：Diff 编辑器支持 line 参数，避免全量滚动查找 + +## 故障排除指南 + +- 编辑器未加载 + - 检查加载器初始化是否完成（本地/CDN） + - 确认 monacoLoader.config 是否正确设置 +- Worker 加载失败 + - 核对 Worker 导入路径与标签匹配（json/css/html/typescript/javascript） + - 若使用 CDN，请确认 vs 路径可达 +- 输入卡顿 + - 检查是否频繁订阅 onChange，建议使用去抖策略 + - 降低复杂度：禁用不必要的语法高亮/自动补全选项 +- Diff 编辑器不显示差异 + - 确认 original 与 modified 值已正确传入 + - 检查语言设置是否一致或独立配置 +- 主题不生效 + - 确认 themeMode 与 Monaco 主题映射（dark->vs-dark，light->light） + +章节来源 + +- [frontend/pro/monaco-editor/loader.ts:53-78](file://frontend/pro/monaco-editor/loader.ts#L53-L78) +- [frontend/pro/monaco-editor/monaco-editor.tsx:83-88](file://frontend/pro/monaco-editor/monaco-editor.tsx#L83-L88) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:127-153](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L127-L153) + +## 结论 + +该组件以 Gradio 为后端接口，结合 @monaco-editor/react 与自研加载器，提供了稳定、可扩展的代码编辑能力。通过本地/CDN 双模式加载、去抖值同步、主题与只读控制、Diff 对比等特性，能够满足大多数应用场景的需求。建议在生产环境中优先使用本地加载以提升稳定性，并根据业务场景合理配置语言、Worker 与编辑器选项，以获得最佳性能与用户体验。 + +## 附录 + +### 配置项速查（标准编辑器） + +- value：编辑器初始值 +- language：编辑器语言（支持所有 Monaco 基础语言） +- read_only：是否只读 +- height：高度（数值为 px，字符串为 CSS 单位） +- options：编辑器构造选项（参考 Monaco 官方类型） +- theme_mode：主题模式（dark/light） +- before_mount/after_mount：JS 字符串函数，分别在加载前/后执行 +- loading：加载文案或自定义加载插槽 +- on_value_change：值变更回调 + +章节来源 + +- [docs/components/pro/monaco_editor/README.md:48-64](file://docs/components/pro/monaco_editor/README.md#L48-L64) +- [docs/components/pro/monaco_editor/README-zh_CN.md:48-64](file://docs/components/pro/monaco_editor/README-zh_CN.md#L48-L64) + +### 配置项速查（差异编辑器） + +- value：右侧修改值（与 modified 二选一） +- original：左侧原始值 +- language：统一语言（若未单独设置） +- original_language：左侧语言 +- modified_language：右侧语言 +- line：初始可视行 +- read_only：是否只读 +- options：编辑器构造选项 +- before_mount/after_mount：JS 字符串函数 +- loading：加载文案或自定义加载插槽 +- on_change：右侧内容变更回调 +- on_validate：校验回调 + +章节来源 + +- [docs/components/pro/monaco_editor/README.md:48-64](file://docs/components/pro/monaco_editor/README.md#L48-L64) +- [docs/components/pro/monaco_editor/README-zh_CN.md:48-64](file://docs/components/pro/monaco_editor/README-zh_CN.md#L48-L64) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\345\237\272\347\241\200\344\275\277\347\224\250.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\345\237\272\347\241\200\344\275\277\347\224\250.md" new file mode 100644 index 00000000..0b53997d --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\345\237\272\347\241\200\344\275\277\347\224\250.md" @@ -0,0 +1,331 @@ +# 基础使用 + + +**本文引用的文件** +- [frontend/pro/monaco-editor/Index.svelte](file://frontend/pro/monaco-editor/Index.svelte) +- [frontend/pro/monaco-editor/monaco-editor.tsx](file://frontend/pro/monaco-editor/monaco-editor.tsx) +- [frontend/pro/monaco-editor/loader.ts](file://frontend/pro/monaco-editor/loader.ts) +- [frontend/pro/monaco-editor/useValueChange.ts](file://frontend/pro/monaco-editor/useValueChange.ts) +- [backend/modelscope_studio/components/pro/monaco_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py) +- [docs/components/pro/monaco_editor/README.md](file://docs/components/pro/monaco_editor/README.md) +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py) +- [frontend/package.json](file://frontend/package.json) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本章节面向初学者，介绍如何在 ModelScope Studio 的 Pro 组件体系中快速上手使用 MonacoEditor。内容涵盖： + +- 最简单的使用示例：基础文本编辑、语言设置、高度配置 +- 常用参数说明：language、height、options 的使用方法 +- 编辑器初始化流程与基本配置项 +- 提供可直接参考的示例路径与运行效果说明 + +## 项目结构 + +MonacoEditor 在前端采用 Svelte + React 包装的方式集成，后端以 Gradio 组件形式暴露给 Python 使用。关键目录与文件如下： + +- 前端组件入口：frontend/pro/monaco-editor/Index.svelte +- React 包装层：frontend/pro/monaco-editor/monaco-editor.tsx +- 加载器：frontend/pro/monaco-editor/loader.ts +- 值变更处理：frontend/pro/monaco-editor/useValueChange.ts +- 后端组件定义：backend/modelscope_studio/components/pro/monaco_editor/**init**.py +- 文档与示例：docs/components/pro/monaco_editor/README.md、demos/monaco_editor_options.py +- 依赖声明：frontend/package.json + +```mermaid +graph TB +subgraph "后端" +PyComp["Python 组件
ModelScopeProMonacoEditor"] +end +subgraph "前端" +SvelteEntry["Svelte 入口
Index.svelte"] +ReactWrapper["React 包装层
monaco-editor.tsx"] +Loader["加载器
loader.ts"] +ValueHook["值变更钩子
useValueChange.ts"] +end +PyComp --> SvelteEntry +SvelteEntry --> Loader +SvelteEntry --> ReactWrapper +ReactWrapper --> ValueHook +``` + +图表来源 + +- [frontend/pro/monaco-editor/Index.svelte:1-100](file://frontend/pro/monaco-editor/Index.svelte#L1-L100) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-94](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L94) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) + +章节来源 + +- [frontend/pro/monaco-editor/Index.svelte:1-100](file://frontend/pro/monaco-editor/Index.svelte#L1-L100) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-94](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L94) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:1-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L1-L107) +- [docs/components/pro/monaco_editor/README.md:1-89](file://docs/components/pro/monaco_editor/README.md#L1-L89) +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:1-34](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L1-L34) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## 核心组件 + +- 后端组件：ModelScopeProMonacoEditor（支持语言、高度、选项、只读、挂载前后回调等） +- 前端包装：MonacoEditor（基于 @monaco-editor/react，负责渲染与事件桥接） +- 加载器：支持本地打包或 CDN 模式加载 Monaco 依赖 +- 值变更钩子：useValueChange（防抖合并输入，避免频繁触发） + +章节来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:46-85](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L46-L85) +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-19](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L19) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/useValueChange.ts:4-43](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L43) + +## 架构总览 + +MonacoEditor 的调用链路从 Python 组件到 Svelte 入口，再到 React 包装层，最终由 @monaco-editor/react 渲染。加载器负责在本地或 CDN 模式下初始化 Monaco 环境。 + +```mermaid +sequenceDiagram +participant Py as "Python 组件" +participant Svelte as "Svelte 入口(Index.svelte)" +participant Loader as "加载器(loader.ts)" +participant React as "React 包装(monaco-editor.tsx)" +participant Monaco as "@monaco-editor/react" +Py->>Svelte : 传递属性与值 +Svelte->>Loader : 初始化本地/CDN 加载器 +Loader-->>Svelte : 返回 monacoLoader 配置完成 +Svelte->>React : 透传属性并渲染 +React->>Monaco : 创建编辑器实例 +Monaco-->>React : 挂载完成回调 +React-->>Svelte : 触发 mount/change/validate 事件 +``` + +图表来源 + +- [frontend/pro/monaco-editor/Index.svelte:64-99](file://frontend/pro/monaco-editor/Index.svelte#L64-L99) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/monaco-editor.tsx:21-92](file://frontend/pro/monaco-editor/monaco-editor.tsx#L21-L92) + +## 详细组件分析 + +### 后端组件：ModelScopeProMonacoEditor + +- 支持的关键参数 + - value：编辑器初始值 + - language：语言模式（如 python/javascript 等） + - height：编辑器高度（数字表示 px，字符串可为 CSS 单位） + - options：Monaco 编辑器构造选项字典 + - read_only：是否只读 + - before_mount/after_mount：挂载前/后的 JS 回调字符串 + - line：滚动到指定行 + - loading：加载提示文案 + - override_services：覆盖服务配置 + - \_loader：加载器配置（mode/cdn_url） +- 事件 + - mount：编辑器挂载时触发 + - change：编辑器值变化时触发 + - validate：验证标记就绪时触发（部分语言支持） +- 插槽 + - loading：自定义加载态内容 + +章节来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:46-85](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L46-L85) +- [docs/components/pro/monaco_editor/README.md:29-89](file://docs/components/pro/monaco_editor/README.md#L29-L89) + +### 前端包装：MonacoEditor（React） + +- 属性映射 + - 接收来自后端的所有属性，并透传给 @monaco-editor/react 的 Editor + - 内部处理 themeMode（暗色/亮色）、height、options（含 readOnly）等 + - 提供 onValueChange 与 onChange 的桥接 +- 加载态 + - 默认使用 Spin 组件作为加载指示；可通过插槽替换 +- 事件桥接 + - onMount/afterMount：统一触发挂载事件 + - onChange：结合 useValueChange 防抖更新 + +章节来源 + +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-19](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L19) +- [frontend/pro/monaco-editor/monaco-editor.tsx:21-92](file://frontend/pro/monaco-editor/monaco-editor.tsx#L21-L92) + +### 加载器：本地/CDN 模式 + +- 本地模式 + - 动态导入 monaco-editor 及各类 worker + - 设置 MonacoEnvironment.getWorker，按语言类型分发对应 worker + - 通过 monacoLoader.config 注入 monaco 实例 +- CDN 模式 + - 通过 monacoLoader.config 指定 vs 路径（默认指向公共 CDN） + - 支持自定义 cdn_url + +章节来源 + +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +### 值变更处理：useValueChange + +- 设计目标 + - 在用户输入过程中避免频繁触发外部回调 + - 通过定时器将“正在输入”状态与最终值解耦 +- 行为 + - 输入开始：进入 typing 状态 + - 输入结束（定时器）：同步显示值并触发 onValueChange + - 组件卸载：清理定时器 + +章节来源 + +- [frontend/pro/monaco-editor/useValueChange.ts:4-43](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L43) + +### Svelte 入口：Index.svelte + +- 负责 + - 解析后端传入的属性与附加属性 + - 根据 \_loader 配置选择本地或 CDN 加载器 + - 将主题、样式、id、类名、值等透传给 React 包装层 + - 处理可见性与插槽渲染 + +章节来源 + +- [frontend/pro/monaco-editor/Index.svelte:14-99](file://frontend/pro/monaco-editor/Index.svelte#L14-L99) + +### 示例：最简单使用 + +- Python 端示例（路径） + - [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:6-30](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L6-L30) +- 运行效果 + - 展示一个默认高度、带语法高亮的语言编辑器 + - 可通过 language 切换语言，通过 height 调整高度 + - 通过 options 关闭 minimap 与行号等 + +章节来源 + +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:6-30](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L6-L30) + +### 参数详解与最佳实践 + +- language + - 作用：启用对应语言的语法高亮与智能感知 + - 建议：与实际内容一致，便于阅读与校验 +- height + - 作用：控制编辑器容器高度 + - 建议：数字单位 px，或使用字符串 CSS 单位（如 "50vh"） +- options + - 作用：透传 Monaco 构造选项，如 minimap、lineNumbers、scrollbar 等 + - 建议：仅开启必要功能，避免过度装饰影响性能 +- read_only + - 作用：禁用编辑能力 + - 建议：配合 diff 编辑器或只读展示场景 +- before_mount/after_mount + - 作用：在挂载前后注入 JS 逻辑（访问 monaco 或 editor 对象） + - 建议：谨慎使用，避免阻塞初始化 +- line + - 作用：首次渲染后滚动到指定行 + - 建议：与 value/modified 配合，确保编辑器已就绪后再滚动 + +章节来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:46-85](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L46-L85) +- [docs/components/pro/monaco_editor/README.md:29-89](file://docs/components/pro/monaco_editor/README.md#L29-L89) + +## 依赖分析 + +- 前端依赖 + - @monaco-editor/react：编辑器核心封装 + - monaco-editor：编辑器与 worker + - antd：Spin 加载态组件 + - svelte：组件框架 +- 后端依赖 + - Gradio 组件基类与事件系统 + +```mermaid +graph LR +Py["Python 组件"] --> FE["Svelte + React 包装"] +FE --> ReactMonaco["@monaco-editor/react"] +FE --> Antd["antd(Spin)"] +FE --> Monaco["monaco-editor"] +``` + +图表来源 + +- [frontend/package.json:17-31](file://frontend/package.json#L17-L31) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-10](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L10) + +章节来源 + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-10](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L10) + +## 性能考虑 + +- 选项裁剪：通过 options 关闭不必要的特性（如 minimap、滚动条、行号），减少 DOM 与渲染开销 +- 防抖输入：useValueChange 在输入阶段延迟触发回调，降低频繁更新带来的抖动 +- 本地/CDN 选择：本地模式体积较大但离线可用；CDN 模式首屏更快，需网络稳定 +- 只读场景：read_only 可显著减少交互与校验成本 + +## 故障排查指南 + +- 编辑器不显示或空白 + - 检查 \_loader 配置（mode/cdn_url）是否正确 + - 确认加载器初始化完成后再渲染编辑器 +- 语言高亮无效 + - 确认 language 设置正确且对应语言存在 + - 若使用自定义 worker，请检查 MonacoEnvironment.getWorker 分发逻辑 +- 加载态不消失 + - 确认加载器 done() 已被调用 + - 如使用自定义加载态插槽，确保插槽内容正确渲染 +- 输入卡顿 + - 检查 options 中是否启用了大量装饰（如 minimap、大字体、复杂主题） + - 调整 useValueChange 的节流策略或减少外部监听 + +章节来源 + +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/monaco-editor.tsx:71-82](file://frontend/pro/monaco-editor/monaco-editor.tsx#L71-L82) +- [frontend/pro/monaco-editor/useValueChange.ts:14-24](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L24) + +## 结论 + +通过上述组件与流程，ModelScope Studio 的 MonacoEditor 能够在 Python 环境中以简洁的参数完成基础编辑需求。建议从最小配置入手（language、height、options），逐步引入只读、挂载回调与行定位等高级能力，以获得更好的开发体验与性能表现。 + +## 附录 + +- 快速示例（Python） + - 示例路径：[docs/components/pro/monaco_editor/demos/monaco_editor_options.py:6-30](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L6-L30) +- API 参考 + - 属性与事件说明：[docs/components/pro/monaco_editor/README.md:29-89](file://docs/components/pro/monaco_editor/README.md#L29-L89) +- 初始化流程图 + +```mermaid +flowchart TD +Start(["开始"]) --> ParseProps["解析后端属性
value/language/height/options 等"] +ParseProps --> DecideLoader{"选择加载器模式"} +DecideLoader --> |本地| LocalInit["动态导入 monaco 与 workers
配置 MonacoEnvironment"] +DecideLoader --> |CDN| CDNInit["配置 vs 路径
指向 CDN"] +LocalInit --> Render["渲染 React 包装层"] +CDNInit --> Render +Render --> Mount["挂载编辑器
触发 mount/change/validate"] +Mount --> End(["完成"]) +``` + +图表来源 + +- [frontend/pro/monaco-editor/Index.svelte:64-99](file://frontend/pro/monaco-editor/Index.svelte#L64-L99) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/monaco-editor.tsx:21-92](file://frontend/pro/monaco-editor/monaco-editor.tsx#L21-L92) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\345\267\256\345\274\202\347\274\226\350\276\221\345\231\250.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\345\267\256\345\274\202\347\274\226\350\276\221\345\231\250.md" new file mode 100644 index 00000000..7b9a30ba --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\345\267\256\345\274\202\347\274\226\350\276\221\345\231\250.md" @@ -0,0 +1,383 @@ +# 差异编辑器 + + +**本文引用的文件** +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte](file://frontend/pro/monaco-editor/diff-editor/Index.svelte) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py) +- [docs/components/pro/monaco_editor/README.md](file://docs/components/pro/monaco_editor/README.md) +- [docs/components/pro/monaco_editor/README-zh_CN.md](file://docs/components/pro/monaco_editor/README-zh_CN.md) +- [docs/components/pro/monaco_editor/demos/diff_editor.py](file://docs/components/pro/monaco_editor/demos/diff_editor.py) +- [frontend/pro/monaco-editor/loader.ts](file://frontend/pro/monaco-editor/loader.ts) +- [frontend/pro/monaco-editor/useValueChange.ts](file://frontend/pro/monaco-editor/useValueChange.ts) +- [frontend/pro/monaco-editor/monaco-editor.less](file://frontend/pro/monaco-editor/monaco-editor.less) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本篇文档聚焦于 MonacoEditor 的差异编辑器（Diff Editor）能力，系统讲解如何在模型空间 Studio 的 Pro 组件体系中使用差异编辑器进行左右对比显示、差异高亮、同步滚动等核心功能，并覆盖配置项、事件绑定、加载模式（本地/CDN）、以及在版本控制与代码审查场景中的应用建议。同时，文档对内部实现机制（如值变更节流、验证标记监听、主题与加载态）进行技术剖析，帮助读者在复杂场景下进行定制与优化。 + +## 项目结构 + +差异编辑器由前端 Svelte 组件桥接、React 包装层、后端 Gradio 组件三部分协同构成： + +- 前端 Svelte 层负责属性透传、加载器初始化与插槽渲染； +- React 包装层负责与 @monaco-editor/react DiffEditor 的集成、事件绑定、值变更节流与验证标记监听； +- 后端 Python 组件负责 Gradio 生命周期、事件声明与前端资源目录映射。 + +```mermaid +graph TB +subgraph "后端" +PY["Python 组件
ModelScopeProMonacoEditorDiffEditor"] +end +subgraph "前端" +IDX["Svelte 入口
Index.svelte"] +WRAP["React 包装层
monaco-editor.diff-editor.tsx"] +LDR["加载器
loader.ts"] +VAL["值变更节流 Hook
useValueChange.ts"] +STY["样式
monaco-editor.less"] +end +PY --> IDX +IDX --> LDR +IDX --> WRAP +WRAP --> VAL +WRAP --> STY +``` + +**图表来源** + +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:1-103](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L1-L103) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-160](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L160) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) + +**章节来源** + +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:1-103](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L1-L103) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-160](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L160) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:1-106](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L1-L106) + +## 核心组件 + +- 前端差异编辑器包装组件：负责与 @monaco-editor/react DiffEditor 的对接，处理值变更、验证标记、主题切换、加载态与挂载回调。 +- Svelte 入口组件：负责加载器初始化（本地或 CDN）、属性透传、插槽渲染与可见性控制。 +- 后端 Gradio 组件：声明事件（mount/change/validate）、暴露属性与默认值、映射前端资源目录。 +- 加载器：统一初始化 Monaco 环境与 Web Worker，支持本地打包与 CDN 路径配置。 +- 值变更节流 Hook：在高频输入场景下降低回调频率，提升交互流畅度。 +- 样式：提供加载态容器尺寸占满与主题类名约定。 + +**章节来源** + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-33](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L33) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:1-103](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L1-L103) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:10-31](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L10-L31) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) + +## 架构总览 + +差异编辑器的调用链路如下： + +- 后端组件实例化并声明事件； +- 前端 Svelte 入口根据 \_loader 配置初始化加载器； +- React 包装层挂载 DiffEditor，注册内容变更与验证标记监听； +- 用户交互触发值变更，经节流后回传给上层； +- 主题随 Gradio shared theme 切换，加载态可自定义插槽。 + +```mermaid +sequenceDiagram +participant Py as "后端组件" +participant S as "Svelte 入口" +participant L as "加载器" +participant R as "React 包装层" +participant M as "@monaco-editor/react DiffEditor" +Py->>S : 初始化并传入属性/事件 +S->>L : 根据 _loader 模式选择本地或 CDN +L-->>S : 完成 Monaco 环境与 Worker 注入 +S->>R : 透传属性并渲染 +R->>M : onMount 注册内容变更与验证监听 +M-->>R : 触发 onChange/onValidate +R-->>S : onValueChange 回传值节流 +S-->>Py : 更新 value 并触发事件 +``` + +**图表来源** + +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:14-31](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L14-L31) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:66-91](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L66-L91) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:67-98](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L67-L98) + +## 详细组件分析 + +### React 包装层（差异编辑器） + +该组件是差异编辑器的核心实现，职责包括： + +- 接收并合并 options 与只读状态； +- 监听修改侧编辑器的内容变更，触发 onValueChange 与 onChange； +- 监听验证标记变化，触发 onValidate； +- 支持按行号定位与滚动； +- 主题随 Gradio theme 自动切换； +- 提供可插拔的 loading 插槽。 + +```mermaid +classDiagram +class MonacoDiffEditor { ++height ++className ++style ++themeMode ++slots ++beforeMount ++afterMount ++children ++onMount ++onChange ++onValueChange ++onValidate ++value ++modified ++options ++readOnly ++line ++handleEditorMount(editor, monaco) ++useEffect(清理 Disposable) ++useEffect(按行滚动) +} +``` + +**图表来源** + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-33](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L33) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:67-98](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L67-L98) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:109-113](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L109-L113) + +**章节来源** + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-160](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L160) + +### Svelte 入口（加载与属性透传） + +- 根据 \_loader.mode 决定使用本地加载还是 CDN； +- 将 Gradio shared theme 透传给 React 包装层以实现主题联动； +- 将 children 渲染为 React Slot，支持 loading 插槽； +- 通过 updateProps 将 onValueChange 的值回写到组件状态。 + +```mermaid +flowchart TD +Start(["进入 Svelte 入口"]) --> CheckMode{"检查 _loader.mode"} +CheckMode --> |local| InitLocal["initLocalLoader()"] +CheckMode --> |cdn| InitCDN["initCDNLoader(cdn_url)"] +CheckMode --> |未设置| Skip["跳过初始化"] +InitLocal --> Render["渲染 React 包装层"] +InitCDN --> Render +Skip --> Render +Render --> Theme["透传 themeMode"] +Theme --> Slots["透传 children/插槽"] +Slots --> Done(["完成"]) +``` + +**图表来源** + +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:66-91](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L66-L91) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +**章节来源** + +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:1-103](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L1-L103) + +### 后端组件（Gradio） + +- 声明事件：mount、change、validate； +- 支持 slots：loading； +- 暴露属性：original、language、original_language、modified_language、line、read_only、options、override_services、height、before_mount、after_mount 等； +- 映射前端资源目录为 pro/monaco-editor/diff-editor。 + +```mermaid +classDiagram +class ModelScopeProMonacoEditorDiffEditor { ++EVENTS ++SLOTS ++original ++line ++loading ++override_services ++options ++read_only ++before_mount ++after_mount ++language ++original_language ++modified_language ++height ++FRONTEND_DIR ++api_info() ++preprocess() ++postprocess() +} +``` + +**图表来源** + +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:14-31](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L14-L31) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:36-82](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L36-L82) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:84-86](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L84-L86) + +**章节来源** + +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:1-106](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L1-L106) + +### 加载器（本地/CDN） + +- 本地加载：动态导入 monaco-editor 及各类语言 Worker，并注入 MonacoEnvironment； +- CDN 加载：通过路径配置指向 CDN； +- 统一初始化入口，避免重复加载。 + +```mermaid +flowchart TD +A["调用 initLocalLoader()/initCDNLoader()"] --> B{"已初始化？"} +B --> |否| C["等待初始化完成"] +B --> |是| D["本地：注入 MonacoEnvironment 与 Worker"] +B --> |是| E["CDN：配置 vs 路径"] +D --> F["完成"] +E --> F +``` + +**图表来源** + +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +**章节来源** + +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) + +### 值变更节流 Hook + +- 在高频输入时延迟触发 onValueChange，减少上游更新频率； +- 通过定时器与 typing 状态控制显示值与回调时机。 + +```mermaid +flowchart TD +Start(["收到新值"]) --> SetTyping["设置 typing=true"] +SetTyping --> ClearTimer["清除旧定时器"] +ClearTimer --> StartTimer["启动 100ms 定时器"] +StartTimer --> Callback["触发 onValueChange"] +Callback --> ResetTyping["定时器结束，typing=false"] +ResetTyping --> UpdateDisplay["更新显示值非输入期间"] +``` + +**图表来源** + +- [frontend/pro/monaco-editor/useValueChange.ts:14-32](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L32) + +**章节来源** + +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) + +## 依赖关系分析 + +- React 包装层依赖 @monaco-editor/react DiffEditor 与 monaco-editor 类型； +- 通过 useValueChange 进行节流； +- Svelte 入口依赖加载器与 ReactSlot； +- 后端组件依赖 Gradio 事件系统与前端资源目录映射。 + +```mermaid +graph LR +PY["后端组件"] --> IDX["Svelte 入口"] +IDX --> LDR["加载器"] +IDX --> WRAP["React 包装层"] +WRAP --> VAL["useValueChange"] +WRAP --> MONACO["@monaco-editor/react DiffEditor"] +WRAP --> STY["monaco-editor.less"] +``` + +**图表来源** + +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:84-86](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L84-L86) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:12-14](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L12-L14) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-17](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L17) +- [frontend/pro/monaco-editor/useValueChange.ts:1-2](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L2) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) + +**章节来源** + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-17](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L17) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:12-14](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L12-L14) + +## 性能考量 + +- 输入节流：通过 useValueChange 在高频输入时降低回调频率，避免频繁上抛与重渲染。 +- Disposable 管理：在卸载时释放编辑器与标记监听的订阅，防止内存泄漏。 +- 主题切换：按需切换 vs-dark/light，避免不必要的重绘。 +- 加载策略：优先使用本地加载以减少网络抖动；CDN 模式下确保路径正确与缓存命中。 +- 大文档优化：建议在 options 中合理配置如 minimap、lineNumbers、scrollBeyondLastLine 等，减少渲染开销。 + +[本节为通用指导，不直接分析具体文件] + +## 故障排查指南 + +- 编辑器未显示或空白 + - 检查 \_loader 配置是否正确，确认本地加载或 CDN 路径可用； + - 确认 Gradio theme 是否正常透传至 themeMode。 +- 值不回传或事件不触发 + - 确认 onValueChange 是否被正确绑定； + - 检查 onChange/onValidate 是否被注册； + - 确认 before_mount/after_mount 字符串函数是否有效。 +- 验证标记不出现 + - 仅在支持丰富智能感知的语言（TypeScript、JavaScript、CSS、LESS、SCSS、JSON、HTML）下触发； + - 确认 monaco.editor.onDidChangeMarkers 订阅是否生效。 +- 行号定位无效 + - 确认传入 line 为数值类型； + - 确认编辑器已就绪后再调用 revealLine。 + +**章节来源** + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:67-98](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L67-L98) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:109-113](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L109-L113) +- [docs/components/pro/monaco_editor/README.md:66-74](file://docs/components/pro/monaco_editor/README.md#L66-L74) + +## 结论 + +差异编辑器在模型空间 Studio 中通过“后端事件 + 前端桥接 + React 包装 + 加载器”的分层设计，实现了稳定、可扩展的左右对比与差异高亮体验。配合值变更节流、验证标记监听与主题联动，能够在版本控制与代码审查等场景中高效工作。建议在生产环境中结合大文档优化与加载策略，持续关注事件与订阅的生命周期管理。 + +[本节为总结，不直接分析具体文件] + +## 附录 + +### 使用示例与场景 + +- 基础差异编辑器示例：展示 original 与 value 的对比、只读切换与 change 事件绑定。 +- 版本控制场景：左侧为基线版本，右侧为当前修改，结合 validate 事件提示错误位置。 +- 代码审查场景：开启只读模式，仅允许查看差异与评论，结合 before_mount/after_mount 扩展高级能力。 + +**章节来源** + +- [docs/components/pro/monaco_editor/demos/diff_editor.py:1-44](file://docs/components/pro/monaco_editor/demos/diff_editor.py#L1-L44) + +### 配置项与事件参考 + +- 属性（DiffEditor）：value、original、language、original_language、modified_language、line、read_only、loading、options、override_services、height、before_mount、after_mount。 +- 事件：mount、change、validate。 +- 插槽：loading。 + +**章节来源** + +- [docs/components/pro/monaco_editor/README.md:48-64](file://docs/components/pro/monaco_editor/README.md#L48-L64) +- [docs/components/pro/monaco_editor/README-zh_CN.md:48-64](file://docs/components/pro/monaco_editor/README-zh_CN.md#L48-L64) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:14-31](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L14-L31) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\347\273\204\344\273\266\346\246\202\350\247\210.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\347\273\204\344\273\266\346\246\202\350\247\210.md" new file mode 100644 index 00000000..c522421b --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\347\273\204\344\273\266\346\246\202\350\247\210.md" @@ -0,0 +1,379 @@ +# 组件概览 + + +**本文引用的文件** +- [backend/modelscope_studio/components/pro/monaco_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py) +- [frontend/pro/monaco-editor/Index.svelte](file://frontend/pro/monaco-editor/Index.svelte) +- [frontend/pro/monaco-editor/monaco-editor.tsx](file://frontend/pro/monaco-editor/monaco-editor.tsx) +- [frontend/pro/monaco-editor/loader.ts](file://frontend/pro/monaco-editor/loader.ts) +- [frontend/pro/monaco-editor/useValueChange.ts](file://frontend/pro/monaco-editor/useValueChange.ts) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte](file://frontend/pro/monaco-editor/diff-editor/Index.svelte) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx) +- [docs/components/pro/monaco_editor/README.md](file://docs/components/pro/monaco_editor/README.md) +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +MonacoEditor 是基于 Gradio 的专业代码编辑器组件，底层集成微软 Monaco 编辑器，提供语法高亮、智能提示、错误标记、主题适配等能力，并支持差异对比编辑（Diff Editor）。该组件在机器学习与 AI 应用中广泛用于： + +- 模型训练脚本与配置文件的编写与校验 +- Prompt 工程与提示词模板的编辑 +- 多模态输入场景下的代码/文本混合编辑 +- 在线代码评审与对比展示 + +组件特性包括： + +- 语法高亮与语言模式切换 +- 智能提示与自动补全 +- 错误标记与验证事件 +- 主题适配（明暗主题） +- 差异对比编辑（左右源对比） +- 可插拔加载策略（本地打包或 CDN） + +## 项目结构 + +MonacoEditor 组件由后端 Python 组件定义与前端 Svelte/React 实现共同构成，文档与示例位于 docs 目录。 + +```mermaid +graph TB +subgraph "后端" +PY["Python 后端组件
backend/modelscope_studio/components/pro/monaco_editor/__init__.py"] +end +subgraph "前端" +IDX["Svelte 入口
frontend/pro/monaco-editor/Index.svelte"] +CORE["React 包装组件
frontend/pro/monaco-editor/monaco-editor.tsx"] +DIFF_IDX["Svelte 入口Diff
frontend/pro/monaco-editor/diff-editor/Index.svelte"] +DIFF_CORE["React Diff 包装组件
frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx"] +LOADER["加载器
frontend/pro/monaco-editor/loader.ts"] +VALUEHOOK["值变更钩子
frontend/pro/monaco-editor/useValueChange.ts"] +end +subgraph "文档与示例" +DOC["组件文档
docs/components/pro/monaco_editor/README.md"] +DEMO["示例脚本
docs/components/pro/monaco_editor/demos/monaco_editor_options.py"] +end +PY --> IDX +PY --> DIFF_IDX +IDX --> CORE +DIFF_IDX --> DIFF_CORE +CORE --> LOADER +DIFF_CORE --> LOADER +CORE --> VALUEHOOK +DIFF_CORE --> VALUEHOOK +DOC --> DEMO +``` + +**图表来源** + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [frontend/pro/monaco-editor/Index.svelte:1-101](file://frontend/pro/monaco-editor/Index.svelte#L1-L101) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L95) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:1-103](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L1-L103) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L161) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [docs/components/pro/monaco_editor/README.md:1-89](file://docs/components/pro/monaco_editor/README.md#L1-L89) +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:1-34](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L1-L34) + +**章节来源** + +- [docs/components/pro/monaco_editor/README.md:1-89](file://docs/components/pro/monaco_editor/README.md#L1-L89) + +## 核心组件 + +- Python 后端组件：负责声明组件属性、事件绑定、默认加载策略与前端目录解析。 +- 前端包装组件： + - 普通编辑器：将 Monaco Editor React 组件桥接为 Svelte 组件，处理值变更、主题、加载态与事件转发。 + - 差异编辑器：在普通编辑器基础上增加左右源对比、行定位与验证事件。 +- 加载器：支持本地打包与 CDN 两种加载方式，按需初始化 Monaco 环境与 Web Worker。 +- 值变更钩子：优化输入体验，延迟触发变更回调，避免频繁重渲染。 + +**章节来源** + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L161) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/useValueChange.ts:4-43](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L43) + +## 架构总览 + +MonacoEditor 的运行时控制流如下： + +```mermaid +sequenceDiagram +participant User as "用户" +participant Svelte as "Svelte 入口
Index.svelte" +participant Loader as "加载器
loader.ts" +participant ReactComp as "React 包装组件
monaco-editor.tsx / diff-editor.tsx" +participant Monaco as "Monaco 编辑器" +User->>Svelte : 渲染组件传入 props +Svelte->>Loader : 初始化加载策略local/cdn +Loader-->>Svelte : 返回 Monaco 环境与资源 +Svelte->>ReactComp : 传递 propsvalue、options、事件等 +ReactComp->>Monaco : 创建编辑器实例onMount +User->>Monaco : 输入/修改内容 +Monaco-->>ReactComp : 触发 onChange/onValidate +ReactComp-->>Svelte : 调用 onValueChange 回传值 +Svelte-->>User : 更新组件状态 +``` + +**图表来源** + +- [frontend/pro/monaco-editor/Index.svelte:64-90](file://frontend/pro/monaco-editor/Index.svelte#L64-L90) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/monaco-editor.tsx:38-91](file://frontend/pro/monaco-editor/monaco-editor.tsx#L38-L91) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:67-107](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L67-L107) + +## 详细组件分析 + +### 普通编辑器组件（MonacoEditor） + +- 职责 + - 将 Gradio 属性映射到 Monaco React 组件 + - 处理只读、高度、主题、加载态与事件转发 + - 使用值变更钩子优化输入体验 +- 关键点 + - 通过 options 透传 Monaco 配置；readOnly 合并与 options 合并 + - 主题根据 Gradio 共享主题自动选择明/暗色 + - 支持自定义 loading 插槽或默认加载指示器 +- 适用场景 + - 代码/配置文件编辑 + - 文本内容输入与实时校验 + +```mermaid +classDiagram +class MonacoEditor { ++height ++value ++options ++readOnly ++themeMode ++onValueChange() ++beforeMount() ++afterMount() +} +class Loader { ++initLocalLoader() ++initCDNLoader(cdn) +} +class ValueHook { ++useValueChange() +} +MonacoEditor --> Loader : "初始化 Monaco 环境" +MonacoEditor --> ValueHook : "优化输入回调" +``` + +**图表来源** + +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/useValueChange.ts:4-43](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L43) + +**章节来源** + +- [frontend/pro/monaco-editor/monaco-editor.tsx:21-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L21-L95) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [frontend/pro/monaco-editor/useValueChange.ts:4-43](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L43) + +### 差异编辑器组件（MonacoEditor.DiffEditor） + +- 职责 + - 对比“原始”与“修改后”的内容 + - 提供行定位、验证事件与模型变更监听 +- 关键点 + - onMount 中订阅模型变更与标记变化事件 + - 支持单独设置 original_language 与 modified_language + - 支持 line 参数滚动到指定行 +- 适用场景 + - 代码评审、变更对比、配置差异展示 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 入口Diff" +participant ReactDiff as "React Diff 包装组件" +participant Monaco as "Monaco Diff 编辑器" +Svelte->>ReactDiff : 传入 propsoriginal/value/options 等 +ReactDiff->>Monaco : onMount 订阅模型变更与标记变化 +Monaco-->>ReactDiff : 模型变更事件onChange +Monaco-->>ReactDiff : 标记变化事件onValidate +ReactDiff-->>Svelte : 触发 onValueChange/onValidate +``` + +**图表来源** + +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:66-91](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L66-L91) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:35-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L35-L161) + +**章节来源** + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:35-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L35-L161) + +### 加载器与资源初始化 + +- 功能 + - 本地加载：动态导入 Monaco 与各类语言 Worker + - CDN 加载：通过路径配置指向 CDN 资源 + - 统一初始化：确保 Monaco 环境可用后再渲染编辑器 +- 注意事项 + - 本地加载会引入较大包体，建议生产环境优先 CDN + - CDN 可自定义路径，便于内网部署 + +```mermaid +flowchart TD +Start(["开始"]) --> Mode{"加载模式？"} +Mode --> |local| Local["initLocalLoader()
动态导入 Monaco 与 Worker"] +Mode --> |cdn| CDN["initCDNLoader(cdn)
配置 vs 路径"] +Local --> Ready["完成初始化"] +CDN --> Ready +Ready --> Render["渲染编辑器"] +``` + +**图表来源** + +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +**章节来源** + +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +### 值变更与输入优化 + +- 机制 + - useValueChange 在输入过程中延迟触发回调，减少频繁更新 + - typing 状态与定时器配合，保证最终值与回调时机一致 +- 效果 + - 提升大文档输入与实时预览的流畅度 + +**章节来源** + +- [frontend/pro/monaco-editor/useValueChange.ts:4-43](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L43) + +## 依赖关系分析 + +- 组件耦合 + - 后端组件仅负责声明与前端目录解析，逻辑解耦清晰 + - 前端通过 Svelte 桥接 React 组件，职责单一 +- 外部依赖 + - @monaco-editor/react：核心编辑器能力 + - antd Spin：加载态显示 + - lodash-es/isNumber：类型与判空辅助 +- 循环依赖 + - 未见直接循环依赖；加载器与组件通过函数调用解耦 + +```mermaid +graph LR +PY["后端组件"] --> IDX["Svelte 入口"] +IDX --> CORE["MonacoEditor 包装"] +IDX --> DIFF_IDX["Svelte 入口Diff"] +DIFF_IDX --> DIFF_CORE["MonacoDiffEditor 包装"] +CORE --> MONACO["@monaco-editor/react"] +DIFF_CORE --> MONACO +CORE --> ANT["antd Spin"] +DIFF_CORE --> ANT +CORE --> Lodash["lodash-es/isNumber"] +``` + +**图表来源** + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-10](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L10) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-13](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L13) + +**章节来源** + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-10](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L10) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-13](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L13) + +## 性能考量 + +- 加载策略 + - 生产环境建议使用 CDN，减少首屏体积 + - 本地加载适合开发调试或离线环境 +- 输入优化 + - useValueChange 延迟回调，降低高频输入对渲染的影响 +- 主题与样式 + - 明/暗主题切换由 Monaco 内部处理，注意避免重复样式覆盖 +- 差异编辑器 + - 大文档对比可能带来内存压力，建议分段编辑或限制行数 + +[本节为通用指导，无需特定文件来源] + +## 故障排查指南 + +- 编辑器不显示或空白 + - 检查加载器是否完成初始化（local/cdn） + - 确认 \_loader 配置与网络可达性 +- 语言高亮/智能提示无效 + - 确认 language 与 options 设置正确 + - 若使用自定义 before_mount/after_mount，检查是否影响 Monaco 实例 +- 验证事件未触发 + - 仅在具备丰富 IntelliSense 的语言下才会触发 validate 事件 +- 行定位无效 + - 确认 line 为数字且在有效范围内 +- 加载态不显示 + - 如自定义 loading 插槽，请确保插槽内容可渲染 + +**章节来源** + +- [docs/components/pro/monaco_editor/README.md:66-89](file://docs/components/pro/monaco_editor/README.md#L66-L89) +- [frontend/pro/monaco-editor/monaco-editor.tsx:71-82](file://frontend/pro/monaco-editor/monaco-editor.tsx#L71-L82) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:141-152](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L141-L152) + +## 结论 + +MonacoEditor 组件以 Gradio 为入口，结合 Svelte 与 React 的桥接方案，提供了稳定、可扩展的代码编辑体验。其核心优势在于： + +- 与 Monaco 强大的语言服务与生态无缝对接 +- 明确的前后端职责划分与可配置的加载策略 +- 面向 AI/ML 场景的差异化能力（Diff Editor、验证事件、主题适配） + +对于初学者，建议从基础用法入手，逐步掌握语言设置、选项配置与事件绑定，再探索高级定制与加载策略优化。 + +[本节为总结性内容，无需特定文件来源] + +## 附录 + +### 基本使用示例与配置要点 + +- 示例脚本展示了如何传入 value、language、height 以及 options（如禁用 minimap 与行号） +- 文档中提供了 API 表格与事件说明，便于查阅 + +**章节来源** + +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:6-30](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L6-L30) +- [docs/components/pro/monaco_editor/README.md:31-89](file://docs/components/pro/monaco_editor/README.md#L31-L89) + +### 组件 API 概览（关键字段） + +- 常用属性 + - value：编辑器初始值 + - language：语言模式 + - options：Monaco 构造选项 + - read_only：只读开关 + - height：组件高度 + - before_mount/after_mount：挂载前后执行的 JS 字符串 +- 事件 + - mount：编辑器挂载完成 + - change：内容变更 + - validate：触发校验与存在错误标记 +- 插槽 + - loading：自定义加载态 + +**章节来源** + +- [docs/components/pro/monaco_editor/README.md:31-89](file://docs/components/pro/monaco_editor/README.md#L31-L89) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\351\205\215\347\275\256\351\200\211\351\241\271.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\351\205\215\347\275\256\351\200\211\351\241\271.md" new file mode 100644 index 00000000..5fd595f4 --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\351\205\215\347\275\256\351\200\211\351\241\271.md" @@ -0,0 +1,406 @@ +# 配置选项 + + +**本文引用的文件** +- [frontend/pro/monaco-editor/monaco-editor.tsx](file://frontend/pro/monaco-editor/monaco-editor.tsx) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx) +- [frontend/pro/monaco-editor/loader.ts](file://frontend/pro/monaco-editor/loader.ts) +- [frontend/pro/monaco-editor/useValueChange.ts](file://frontend/pro/monaco-editor/useValueChange.ts) +- [frontend/pro/monaco-editor/Index.svelte](file://frontend/pro/monaco-editor/Index.svelte) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte](file://frontend/pro/monaco-editor/diff-editor/Index.svelte) +- [backend/modelscope_studio/components/pro/monaco_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py) +- [docs/components/pro/monaco_editor/README.md](file://docs/components/pro/monaco_editor/README.md) +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：配置清单与示例](#附录配置清单与示例) + +## 简介 + +本文件为 MonacoEditor 在当前仓库中的配置选项完整参考，覆盖编辑器外观、行为、功能、语言与主题、加载与性能等关键方面，并结合前端与 Python 后端的集成方式，给出可直接落地的配置建议、最佳实践与常见兼容性注意事项。 + +## 项目结构 + +围绕 MonacoEditor 的配置与使用，涉及以下层次： + +- 文档层：提供组件 API 说明与示例入口 +- 前端层：Svelte 包装、React 组件、加载器与事件桥接 +- 后端层：Gradio 组件封装，暴露属性、事件与插槽 + +```mermaid +graph TB +subgraph "文档层" +D1["docs/components/pro/monaco_editor/README.md"] +D2["docs/components/pro/monaco_editor/demos/monaco_editor_options.py"] +end +subgraph "前端层" +F1["frontend/pro/monaco-editor/Index.svelte"] +F2["frontend/pro/monaco-editor/diff-editor/Index.svelte"] +F3["frontend/pro/monaco-editor/monaco-editor.tsx"] +F4["frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx"] +F5["frontend/pro/monaco-editor/loader.ts"] +F6["frontend/pro/monaco-editor/useValueChange.ts"] +end +subgraph "后端层" +B1["backend/modelscope_studio/components/pro/monaco_editor/__init__.py"] +B2["backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py"] +end +D1 --> F1 +D1 --> F2 +D2 --> F1 +F1 --> F3 +F2 --> F4 +F3 --> F5 +F4 --> F5 +F3 --> F6 +F4 --> F6 +F1 --> B1 +F2 --> B2 +``` + +图表来源 + +- [frontend/pro/monaco-editor/Index.svelte:1-101](file://frontend/pro/monaco-editor/Index.svelte#L1-L101) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:1-103](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L1-L103) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L161) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:1-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L1-L107) +- [backend/modelscope_studio/components/pro/monaco_editor/diff_editor/**init**.py:1-106](file://backend/modelscope_studio/components/pro/monaco_editor/diff_editor/__init__.py#L1-L106) + +章节来源 + +- [docs/components/pro/monaco_editor/README.md:1-89](file://docs/components/pro/monaco_editor/README.md#L1-L89) +- [frontend/pro/monaco-editor/Index.svelte:1-101](file://frontend/pro/monaco-editor/Index.svelte#L1-L101) +- [frontend/pro/monaco-editor/diff-editor/Index.svelte:1-103](file://frontend/pro/monaco-editor/diff-editor/Index.svelte#L1-L103) + +## 核心组件 + +- MonacoEditor（单编辑器） + - 负责将 Gradio 的属性映射为 Monaco 的构造参数，处理加载态、只读、主题模式、值变更与挂载回调 + - 支持通过 options 透传 Monaco 构造选项；支持 before_mount/after_mount 注入 JS 字符串 +- MonacoDiffEditor（差异编辑器） + - 负责左右侧内容对比展示，支持原内容与修改内容的语言分离、行定位、校验标记监听 + - 支持 options 与只读配置，支持 line 参数在挂载后滚动到指定行 +- 加载器（本地/CDN） + - 初始化 Monaco 环境与 Web Worker，按需选择本地打包或 CDN 路径 +- 值变更节流 + - 使用定时器避免频繁触发上层回调，提升输入体验与性能 + +章节来源 + +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L161) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) + +## 架构总览 + +MonacoEditor 在当前工程中的调用链路如下： + +```mermaid +sequenceDiagram +participant Py as "Python 组件
ModelScopeProMonacoEditor" +participant FE as "Svelte 包装
Index.svelte" +participant R as "React 组件
monaco-editor.tsx" +participant M as "Monaco 实例" +participant L as "加载器
loader.ts" +Py->>FE : 传入属性value/language/options/height/... +FE->>L : 初始化本地/CDN 加载器 +FE->>R : 渲染 Editor 并注入 props +R->>M : 创建编辑器实例合并 options 与只读 +R-->>FE : 挂载回调beforeMount/afterMount +R-->>Py : 值变更回调change 事件 +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:46-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L46-L107) +- [frontend/pro/monaco-editor/Index.svelte:64-90](file://frontend/pro/monaco-editor/Index.svelte#L64-L90) +- [frontend/pro/monaco-editor/monaco-editor.tsx:56-88](file://frontend/pro/monaco-editor/monaco-editor.tsx#L56-L88) +- [frontend/pro/monaco-editor/loader.ts:27-78](file://frontend/pro/monaco-editor/loader.ts#L27-L78) + +## 详细组件分析 + +### 单编辑器（MonacoEditor）配置要点 + +- 属性映射与默认值 + - value、language、line、read_only、loading、options、overrideServices、height、before_mount、after_mount + - 主题模式由 themeMode 决定，暗色模式映射为 vs-dark，否则 light +- 行为特性 + - options 与 readOnly 合并传入底层构造函数 + - onChange 回调中同步更新显示值，避免频繁上抛 + - 加载态支持自定义插槽或默认旋转指示器 +- 事件与插槽 + - 事件：mount、change、validate（仅在具备丰富智能感知的语言中触发） + - 插槽：loading + +```mermaid +flowchart TD +Start(["进入 Editor 渲染"]) --> MergeOpts["合并 options 与 readOnly"] +MergeOpts --> ThemeMap["根据 themeMode 映射主题"] +ThemeMap --> Loading["渲染加载态插槽或默认"] +Loading --> MountHooks["执行 beforeMount/afterMount"] +MountHooks --> ListenChange["监听值变更并节流上报"] +ListenChange --> End(["完成"]) +``` + +图表来源 + +- [frontend/pro/monaco-editor/monaco-editor.tsx:64-88](file://frontend/pro/monaco-editor/monaco-editor.tsx#L64-L88) +- [frontend/pro/monaco-editor/useValueChange.ts:14-32](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L32) + +章节来源 + +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [docs/components/pro/monaco_editor/README.md:35-74](file://docs/components/pro/monaco_editor/README.md#L35-L74) + +### 差异编辑器（MonacoDiffEditor）配置要点 + +- 属性映射与默认值 + - value（右侧）、original（左侧）、language、original_language、modified_language、line、read_only、loading、options、overrideServices、height、before_mount、after_mount +- 行为特性 + - 只读与 options 合并传入底层构造函数 + - 挂载后根据 line 参数滚动到指定行 + - 监听模型标记变化，触发 validate 事件 + - onChange 回调中同步右侧编辑器值 +- 事件与插槽 + - 事件：mount、change、validate + - 插槽：loading + +```mermaid +sequenceDiagram +participant FE as "DiffEditor 包装" +participant R as "DiffEditor 组件" +participant E as "右侧编辑器" +participant M as "Monaco 标记系统" +FE->>R : 渲染 DiffEditor合并 options 与只读 +R->>E : 获取右侧编辑器实例 +R->>E : 若提供 line，滚动到该行 +R->>E : 监听内容变更，同步 value +R->>M : 监听标记变化，触发 validate +``` + +图表来源 + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:67-98](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L67-L98) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:127-153](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L127-L153) + +章节来源 + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L161) +- [docs/components/pro/monaco_editor/README.md:48-74](file://docs/components/pro/monaco_editor/README.md#L48-L74) + +### 加载器与主题 + +- 加载器 + - 本地加载：动态导入 monaco 与各类语言 worker，并设置 MonacoEnvironment.getWorker + - CDN 加载：通过 monaco-loader 配置 vs 路径 +- 主题 + - 通过 themeMode 将暗色映射为 vs-dark，否则 light，统一交由底层 Editor 处理 + +```mermaid +flowchart TD +Init(["初始化加载器"]) --> Mode{"模式？"} +Mode --> |local| Local["动态导入 monaco 与 worker
设置 MonacoEnvironment"] +Mode --> |cdn| CDN["配置 monaco-loader vs 路径"] +Local --> Done(["完成"]) +CDN --> Done +``` + +图表来源 + +- [frontend/pro/monaco-editor/loader.ts:27-78](file://frontend/pro/monaco-editor/loader.ts#L27-L78) +- [frontend/pro/monaco-editor/loader.ts:80-94](file://frontend/pro/monaco-editor/loader.ts#L80-L94) +- [frontend/pro/monaco-editor/monaco-editor.tsx:87-88](file://frontend/pro/monaco-editor/monaco-editor.tsx#L87-L88) + +章节来源 + +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) + +### 值变更节流机制 + +- 目标：减少高频输入导致的回调风暴 +- 机制：输入开始计时，100ms 内无新输入则提交一次变更 +- 影响：降低上层处理压力，改善交互流畅度 + +```mermaid +flowchart TD +In(["收到新值"]) --> SetTyping["标记正在输入"] +SetTyping --> Timer["启动 100ms 定时器"] +Timer --> NewInput{"期间有新输入？"} +NewInput --> |是| Reset["重置定时器"] --> Timer +NewInput --> |否| Commit["提交变更并清空状态"] +``` + +图表来源 + +- [frontend/pro/monaco-editor/useValueChange.ts:14-24](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L24) +- [frontend/pro/monaco-editor/useValueChange.ts:26-32](file://frontend/pro/monaco-editor/useValueChange.ts#L26-L32) + +章节来源 + +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) + +## 依赖关系分析 + +- 组件耦合 + - Svelte 包装负责属性透传与加载器初始化 + - React 组件负责具体编辑器实例化与事件绑定 + - 加载器与 Worker 解耦于编辑器逻辑 +- 外部依赖 + - @monaco-editor/react 提供 Editor/DiffEditor + - monaco-editor 与各语言 worker + - Gradio 组件桥接（Python 层） + +```mermaid +graph LR +Svelte["Svelte 包装"] --> ReactComp["React 组件"] +ReactComp --> Monaco["@monaco-editor/react"] +ReactComp --> Loader["加载器"] +Loader --> MonacoLib["monaco-editor"] +Loader --> Workers["语言 Worker"] +Svelte --> Gradio["Gradio 组件Python"] +``` + +图表来源 + +- [frontend/pro/monaco-editor/Index.svelte:10-12](file://frontend/pro/monaco-editor/Index.svelte#L10-L12) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-2](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L2) +- [frontend/pro/monaco-editor/loader.ts:33-51](file://frontend/pro/monaco-editor/loader.ts#L33-L51) + +章节来源 + +- [frontend/pro/monaco-editor/Index.svelte:1-101](file://frontend/pro/monaco-editor/Index.svelte#L1-L101) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L95) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) + +## 性能考量 + +- 加载策略 + - 优先使用本地加载以减少网络抖动对首开的影响；如需离线部署或内网环境，建议固定版本并预热 + - CDN 模式下确保路径稳定，避免重复下载 +- 语言与 Worker + - 仅加载所需语言的 worker，减少内存占用 + - 如需自定义语言，谨慎引入额外 worker +- 输入性能 + - 利用内置节流机制，避免高频变更导致的上层重绘 +- 视图与布局 + - 合理设置 height，避免过高的容器导致不必要的重排 + - 关闭不必要功能（如 minimap、lineNumbers）以降低渲染成本 + +章节来源 + +- [frontend/pro/monaco-editor/loader.ts:53-69](file://frontend/pro/monaco-editor/loader.ts#L53-L69) +- [frontend/pro/monaco-editor/useValueChange.ts:14-24](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L24) +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:24-29](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L24-L29) + +## 故障排查指南 + +- 编辑器未加载或空白 + - 检查 \_loader 配置（mode/local/cdn_url），确认加载器初始化成功 + - 确认 before_mount/after_mount 中未阻塞主线程 +- 语言高亮缺失 + - 确认 language 设置正确；若使用自定义语言，检查对应 worker 是否已加载 +- 只读无效 + - 确认 read_only 传入方式与 options 冲突（后者会覆盖前者），建议统一通过 read_only 控制 +- 行滚动不生效 + - DiffEditor 的 line 需在挂载后生效，确认 line 为数值且在挂载完成后设置 +- 事件未触发 + - validate 事件仅在具备丰富智能感知的语言中触发；确认语言与校验规则已启用 + +章节来源 + +- [frontend/pro/monaco-editor/loader.ts:27-78](file://frontend/pro/monaco-editor/loader.ts#L27-L78) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:110-113](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L110-L113) +- [docs/components/pro/monaco_editor/README.md:74-74](file://docs/components/pro/monaco_editor/README.md#L74-L74) + +## 结论 + +本仓库对 MonacoEditor 的封装提供了清晰的属性映射、事件桥接与加载器抽象，既保留了 Monaco 的强大能力，又降低了在 Gradio 生态中的使用门槛。通过合理配置 options、选择合适的加载模式与语言 worker、以及利用内置节流机制，可在保证体验的同时获得良好的性能表现。 + +## 附录：配置清单与示例 + +### 属性总览（单编辑器） + +- value：编辑器初始值 +- language：编辑器语言 +- line：垂直滚动到指定行 +- read_only：是否只读 +- loading：加载提示文本或插槽 +- options：Monaco 构造选项（透传 IStandaloneEditorConstructionOptions） +- overrideServices：服务覆盖（透传 IEditorOverrideServices） +- height：组件高度（数字为 px，字符串为 CSS 单位） +- before_mount：加载前执行的 JS 函数字符串（可访问 monaco） +- after_mount：加载后执行的 JS 函数字符串（可访问 editor 与 monaco） + +章节来源 + +- [docs/components/pro/monaco_editor/README.md:35-47](file://docs/components/pro/monaco_editor/README.md#L35-L47) +- [frontend/pro/monaco-editor/monaco-editor.tsx:35-70](file://frontend/pro/monaco-editor/monaco-editor.tsx#L35-L70) + +### 属性总览（差异编辑器） + +- value：修改后的源（右侧） +- original：原始源（左侧） +- language：编辑器语言 +- original_language：原始源单独语言 +- modified_language：修改后源单独语言 +- line：垂直滚动到指定行 +- read_only：是否只读 +- loading：加载提示文本或插槽 +- options：Monaco 构造选项（透传 IStandaloneEditorConstructionOptions） +- overrideServices：服务覆盖（透传 IEditorOverrideServices） +- height：组件高度（数字为 px，字符串为 CSS 单位） +- before_mount：加载前执行的 JS 函数字符串（可访问 monaco） +- after_mount：加载后执行的 JS 函数字符串（可访问 editor 与 monaco） + +章节来源 + +- [docs/components/pro/monaco_editor/README.md:48-65](file://docs/components/pro/monaco_editor/README.md#L48-L65) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:49-153](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L49-L153) + +### 事件与插槽 + +- 事件 + - mount：编辑器挂载完成 + - change：编辑器值变更 + - validate：存在校验标记时触发（仅部分语言） +- 插槽 + - loading：自定义加载态 + +章节来源 + +- [docs/components/pro/monaco_editor/README.md:66-89](file://docs/components/pro/monaco_editor/README.md#L66-L89) + +### 配置示例与最佳实践 + +- 基础示例（含 options） + - 参考：docs/components/pro/monaco_editor/demos/monaco_editor_options.py + - 建议：在 options 中关闭 minimap 与行号以提升性能 +- 语言与主题 + - 语言：通过 language 设置；如需差异编辑器两侧不同语言，分别设置 original_language 与 modified_language + - 主题：通过 themeMode 自动映射 vs-dark/light +- 加载模式 + - 本地：适合可控环境与离线场景 + - CDN：适合快速上线与多版本管理 + +章节来源 + +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:1-34](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L1-L34) +- [frontend/pro/monaco-editor/monaco-editor.tsx:87-88](file://frontend/pro/monaco-editor/monaco-editor.tsx#L87-L88) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:43-44](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L43-L44) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\351\253\230\347\272\247\345\212\237\350\203\275.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\351\253\230\347\272\247\345\212\237\350\203\275.md" new file mode 100644 index 00000000..7abac42d --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MonacoEditor \344\273\243\347\240\201\347\274\226\350\276\221\345\231\250/\351\253\230\347\272\247\345\212\237\350\203\275.md" @@ -0,0 +1,305 @@ +# 高级功能 + + +**本文引用的文件** +- [backend/modelscope_studio/components/pro/monaco_editor/__init__.py](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py) +- [frontend/pro/monaco-editor/monaco-editor.tsx](file://frontend/pro/monaco-editor/monaco-editor.tsx) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx) +- [frontend/pro/monaco-editor/loader.ts](file://frontend/pro/monaco-editor/loader.ts) +- [frontend/pro/monaco-editor/useValueChange.ts](file://frontend/pro/monaco-editor/useValueChange.ts) +- [frontend/pro/monaco-editor/monaco-editor.less](file://frontend/pro/monaco-editor/monaco-editor.less) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本篇“高级功能”文档聚焦于 MonacoEditor 在 ModelScope Studio 中的高级用法与扩展能力，涵盖以下主题： + +- JavaScript 自定义：如何在挂载前后注入自定义逻辑（如语言服务、主题切换、事件绑定） +- 服务覆盖：通过 override_services 参数对 Monaco 内部服务进行替换或增强 +- 加载器配置：本地加载与 CDN 加载两种模式的选择与配置 +- 编辑器扩展：自定义语言支持、插件开发、主题定制 +- 复杂场景集成：与 Gradio 生态系统（Blocks、ConfigProvider、Application）的深度集成示例 +- 底层实现机制与性能优化：事件绑定、值同步策略、工作线程与资源路径管理 + +## 项目结构 + +MonacoEditor 的实现采用“后端组件 + 前端 Svelte/React 包装”的分层设计： + +- 后端组件负责参数透传、事件绑定、加载器与服务覆盖配置 +- 前端组件基于 @monaco-editor/react 进行封装，提供统一的 React/Svelte 接口，并内置加载器初始化、值变更节流、主题适配等功能 + +```mermaid +graph TB +subgraph "后端" +PY["Python 后端组件
ModelScopeProMonacoEditor"] +end +subgraph "前端" +FE["Svelte/React 包装组件
MonacoEditor / MonacoDiffEditor"] +LDR["加载器初始化
loader.ts"] +VAL["值变更节流 Hook
useValueChange.ts"] +CSS["样式类名
monaco-editor.less"] +end +subgraph "外部依赖" +ME["@monaco-editor/react"] +MR["monaco-editor 工作线程"] +end +PY --> FE +FE --> ME +FE --> VAL +FE --> LDR +LDR --> MR +FE --> CSS +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L161) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) + +章节来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:1-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L1-L161) +- [frontend/pro/monaco-editor/loader.ts:1-95](file://frontend/pro/monaco-editor/loader.ts#L1-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:1-44](file://frontend/pro/monaco-editor/useValueChange.ts#L1-L44) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) + +## 核心组件 + +- 后端组件：ModelScopeProMonacoEditor + - 支持事件：mount、change、validate + - 支持插槽：loading + - 支持加载器配置：LOADER（默认 local 模式） + - 关键参数：language、options、read_only、height、before_mount、after_mount、override_services、line +- 前端组件：MonacoEditor（单编辑器）、MonacoDiffEditor（差异编辑器） + - 提供 themeMode、height、readOnly、onValueChange、loading 插槽等 + - 内置加载器初始化、值变更节流、主题映射（dark <-> vs-dark） + +章节来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) +- [frontend/pro/monaco-editor/monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:19-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L19-L161) + +## 架构总览 + +下图展示从 Python 后端到前端包装组件，再到 Monaco 编辑器与工作线程的整体调用链路。 + +```mermaid +sequenceDiagram +participant Py as "后端组件
ModelScopeProMonacoEditor" +participant FE as "前端组件
MonacoEditor/MonacoDiffEditor" +participant L as "加载器
loader.ts" +participant MR as "@monaco-editor/react" +participant M as "Monaco 编辑器实例" +participant W as "工作线程" +Py->>FE : 传递参数options、language、read_only、height、before_mount、after_mount、override_services、line +FE->>L : 初始化加载器本地/CDN +L-->>FE : 完成配置Monaco、Worker 映射、资源路径 +FE->>MR : 渲染 Editor/DiffEditor +MR->>M : 创建编辑器实例 +M->>W : 注册工作线程JSON/CSS/HTML/TS/通用 +FE->>FE : 绑定事件onChange/onMount/onValidate +FE-->>Py : 触发 mount/change/validate 事件回调 +``` + +图表来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:21-38](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L21-L38) +- [frontend/pro/monaco-editor/monaco-editor.tsx:38-91](file://frontend/pro/monaco-editor/monaco-editor.tsx#L38-L91) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:67-98](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L67-L98) +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) + +## 详细组件分析 + +### 后端组件：ModelScopeProMonacoEditor + +- 事件系统 + - mount：编辑器挂载时触发，用于执行 before_mount/after_mount 回调 + - change：编辑器内容变化时触发，可用于实时校验或保存 + - validate：标记（错误/警告）更新完成后触发 +- 插槽与加载器 + - loading 插槽：可自定义加载态 UI + - LOADER：支持本地（local）与 CDN 两种模式，默认 local +- 关键参数 + - language：语言标识，驱动语法高亮与语言服务 + - options：传递给 Monaco 的配置对象 + - read_only：只读模式 + - height：容器高度 + - before_mount/after_mount：挂载前后钩子 + - override_services：服务覆盖字典 + - line：定位到指定行（差异编辑器） + +章节来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:16-107](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L16-L107) + +### 前端组件：MonacoEditor（单编辑器） + +- 主题与尺寸 + - themeMode 映射：dark -> vs-dark；light -> light + - height 控制容器高度 +- 值变更与事件 + - 使用 useValueChange 实现输入节流（约 100ms），避免高频回调 + - onChange -> setValue -> onValueChange，确保与 Gradio 数据流一致 +- 加载态 + - 默认加载态为 Spin，可通过 loading 插槽替换 +- 工作线程与加载器 + - 由 loader.ts 初始化，按语言类型返回对应 Worker + +章节来源 + +- [frontend/pro/monaco-editor/monaco-editor.tsx:21-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L21-L95) +- [frontend/pro/monaco-editor/useValueChange.ts:4-44](file://frontend/pro/monaco-editor/useValueChange.ts#L4-L44) +- [frontend/pro/monaco-editor/monaco-editor.less:1-7](file://frontend/pro/monaco-editor/monaco-editor.less#L1-L7) + +### 前端组件：MonacoDiffEditor（差异编辑器） + +- 特性 + - 支持 modified/original 双视图对比 + - onValidate：监听标记变化并回传 markers + - line：自动滚动到指定行 +- 生命周期与事件 + - onMount：注册内容变更与标记变更监听，清理时释放 IDisposable + - onChange：将修改后的值同步到上层 +- 加载态与主题 + - 与单编辑器一致的加载态与主题映射 + +章节来源 + +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:35-161](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L35-L161) + +### 加载器与服务覆盖 + +- 加载器初始化 + - initLocalLoader：动态导入 monaco-editor 与各类 Worker，设置 MonacoEnvironment.getWorker + - initCDNLoader：通过 loader.config(paths.vs = cdn) 指定资源路径 +- 服务覆盖 + - 后端通过 override_services 将服务字典传递至前端包装组件 + - 前端可在 before_mount 中访问 monaco 实例，进行服务替换或扩展（例如替换语言服务、注册自定义贡献点） + +章节来源 + +- [frontend/pro/monaco-editor/loader.ts:27-94](file://frontend/pro/monaco-editor/loader.ts#L27-L94) +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:54-84](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L54-L84) + +### 值变更节流与数据流 + +```mermaid +flowchart TD +Start(["开始"]) --> Typing["检测输入中？"] +Typing --> |是| Debounce["启动定时器约 100ms"] +Debounce --> SetTyping["标记正在输入"] +SetTyping --> Wait["等待定时器结束"] +Wait --> ClearTyping["停止输入，清空定时器"] +ClearTyping --> Sync["同步显示值与上层回调"] +Typing --> |否| Sync +Sync --> End(["结束"]) +``` + +图表来源 + +- [frontend/pro/monaco-editor/useValueChange.ts:14-32](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L32) + +## 依赖关系分析 + +- 组件耦合 + - 后端组件与前端包装组件通过参数透传强耦合，事件回调通过 Gradio 事件系统解耦 + - 前端组件与 Monaco 的耦合通过 @monaco-editor/react 与 loader.ts 解耦 +- 外部依赖 + - @monaco-editor/react：编辑器渲染与生命周期管理 + - monaco-editor 工作线程：语言服务与语法解析 + - Ant Design Spin：加载态 UI +- 构建与打包 + - defineConfig.js 提供 Vite 插件与预处理配置，确保 Svelte/React 包装正常构建 + +```mermaid +graph LR +PY["后端组件"] --> FE["前端包装组件"] +FE --> REACT["@monaco-editor/react"] +FE --> WORKER["monaco-editor 工作线程"] +FE --> ANT["Ant Design Spin"] +FE --> CFG["defineConfig.js"] +``` + +图表来源 + +- [frontend/defineConfig.js:8-18](file://frontend/defineConfig.js#L8-L18) +- [frontend/pro/monaco-editor/monaco-editor.tsx:1-11](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L11) + +章节来源 + +- [frontend/defineConfig.js:8-18](file://frontend/defineConfig.js#L8-L18) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## 性能考量 + +- 输入节流 + - useValueChange 以约 100ms 的定时器降低 onChange 频率，减少上层回调与重渲染压力 +- Worker 分发 + - 按语言类型精确返回对应 Worker，避免不必要的多线程开销 +- 资源路径 + - CDN 模式下通过 loader.config(paths.vs = cdn) 减少本地体积与首屏时间 +- 主题切换 + - themeMode 切换仅影响主题映射，不重建编辑器实例，降低抖动 + +章节来源 + +- [frontend/pro/monaco-editor/useValueChange.ts:14-24](file://frontend/pro/monaco-editor/useValueChange.ts#L14-L24) +- [frontend/pro/monaco-editor/loader.ts:53-69](file://frontend/pro/monaco-editor/loader.ts#L53-L69) + +## 故障排查指南 + +- 加载失败或白屏 + - 检查 LOADER 配置是否正确（local/CDN），确认 CDN 路径可达 + - 若使用 CDN，确保跨域与缓存策略正确 +- 语言服务异常 + - 确认 language 设置与实际代码一致 + - 如需自定义语言服务，使用 before_mount 注入 monaco 服务替换逻辑 +- 事件未触发 + - 确认已启用相应事件绑定（bind_mount_event/bind_change_event/bind_validate_event） + - 检查 Gradio 事件系统是否正常（队列与 launch） +- 差异编辑器无法定位行 + - 确认 line 参数为有效数值，且 onMount 已完成后再设置 + +章节来源 + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:21-38](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L21-L38) +- [frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx:109-113](file://frontend/pro/monaco-editor/diff-editor/monaco-editor.diff-editor.tsx#L109-L113) + +## 结论 + +ModelScope Studio 的 MonacoEditor 高级功能围绕“参数透传 + 前端包装 + 加载器初始化 + 事件系统”展开，既保证了与 Gradio 生态的无缝集成，又提供了灵活的扩展点（语言服务、主题、加载策略）。通过节流与 Worker 精准分发，兼顾了交互流畅性与运行效率。 + +## 附录 + +### 与 Gradio 生态的集成示例 + +- Blocks 与 ConfigProvider：在 Blocks 上下文中使用组件，统一全局配置 +- Application：提供应用级上下文，便于事件与状态管理 +- 示例参考：演示了基础用法与 options 配置（如关闭 minimap、隐藏行号） + +章节来源 + +- [docs/components/pro/monaco_editor/demos/monaco_editor_options.py:6-34](file://docs/components/pro/monaco_editor/demos/monaco_editor_options.py#L6-L34) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206.md" new file mode 100644 index 00000000..6e53cb72 --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206.md" @@ -0,0 +1,401 @@ +# MultimodalInput 多模态输入框 + + +**本文档引用的文件** +- [backend 模块定义](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py) +- [前端组件实现](file://frontend/pro/multimodal-input/multimodal-input.tsx) +- [前端入口包装](file://frontend/pro/multimodal-input/Index.svelte) +- [录音钩子](file://frontend/pro/multimodal-input/recorder.ts) +- [音频处理工具](file://frontend/pro/multimodal-input/utils.ts) +- [组件文档说明](file://docs/components/pro/multimodal_input/README.md) +- [组件包导出配置](file://frontend/pro/multimodal-input/package.json) +- [组件打包配置](file://frontend/pro/multimodal-input/gradio.config.js) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +MultimodalInput 是一个基于 Ant Design X 的多模态输入组件，支持文本输入、文件上传、语音录制、粘贴上传、拖拽上传等多种交互方式。该组件在前端通过 React 实现，在后端通过 Gradio 组件桥接，提供完整的多模态数据处理能力。 + +组件主要特性包括： + +- 文本输入与自动高度调整 +- 文件上传（单个/多个、目录上传） +- 语音录制（基于 Web Audio API） +- 粘贴上传（剪贴板文件） +- 拖拽上传（支持全屏拖拽） +- 实时预览与下载 +- 可配置的附件面板 +- 结构化输入支持（技能/插槽模式） + +## 项目结构 + +MultimodalInput 组件采用前后端分离的架构设计： + +```mermaid +graph TB +subgraph "后端 (Python)" +Backend[ModelScopeProMultimodalInput] +UploadConfig[MultimodalInputUploadConfig] +ValueModel[MultimodalInputValue] +end +subgraph "前端 (React)" +Frontend[MultimodalInput 组件] +Recorder[录音钩子] +Utils[音频处理工具] +Wrapper[Index.svelte 包装器] +end +subgraph "外部依赖" +Antd[Ant Design X] +Gradio[Gradio 客户端] +Wavesurfer[Wavesurfer.js] +end +Backend --> Frontend +Frontend --> Antd +Frontend --> Gradio +Frontend --> Recorder +Recorder --> Wavesurfer +Frontend --> Utils +Wrapper --> Frontend +``` + +**图表来源** + +- [backend 模块定义:18-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L18-L259) +- [前端组件实现:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [前端入口包装:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) + +**章节来源** + +- [backend 模块定义:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) +- [前端组件实现:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [前端入口包装:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) + +## 核心组件 + +MultimodalInput 由三个核心部分组成： + +### 后端组件类 + +后端通过 ModelScopeProMultimodalInput 类实现，继承自 ModelScopeDataLayoutComponent，提供完整的 Gradio 组件生命周期管理。 + +### 前端组件实现 + +前端使用 React + TypeScript 实现，基于 @ant-design/x 的 Sender 和 Attachments 组件构建。 + +### 录音功能模块 + +集成 Wavesurfer.js 提供录音录制功能，支持实时波形显示和音频格式转换。 + +**章节来源** + +- [backend 模块定义:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) +- [前端组件实现:75-104](file://frontend/pro/multimodal-input/multimodal-input.tsx#L75-L104) +- [录音钩子:11-47](file://frontend/pro/multimodal-input/recorder.ts#L11-L47) + +## 架构总览 + +MultimodalInput 采用分层架构设计，确保前后端数据流的清晰分离： + +```mermaid +sequenceDiagram +participant User as 用户 +participant UI as 前端UI +participant Recorder as 录音模块 +participant Uploader as 上传模块 +participant Backend as 后端组件 +participant Gradio as Gradio客户端 +User->>UI : 输入文本/选择文件 +UI->>Uploader : 触发文件上传 +Uploader->>Gradio : 调用 upload 接口 +Gradio-->>Uploader : 返回 FileData 列表 +Uploader-->>UI : 更新文件列表 +User->>Recorder : 开始/停止录音 +Recorder->>Recorder : 录制音频数据 +Recorder->>Uploader : 上传录音文件 +Uploader->>Gradio : 调用 upload 接口 +Gradio-->>Uploader : 返回 FileData +Uploader-->>UI : 显示上传结果 +UI->>Backend : 触发 change 事件 +Backend->>Backend : 数据预处理 +Backend-->>User : 返回标准化数据 +``` + +**图表来源** + +- [前端组件实现:157-169](file://frontend/pro/multimodal-input/multimodal-input.tsx#L157-L169) +- [前端组件实现:220-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L220-L246) +- [前端入口包装:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) + +## 详细组件分析 + +### 数据模型与类型定义 + +```mermaid +classDiagram +class MultimodalInputValue { ++files : FileData[] ++text : string +} +class MultimodalInputUploadConfig { ++fullscreenDrop : boolean ++allowUpload : boolean ++allowPasteFile : boolean ++allowSpeech : boolean ++showCount : boolean ++uploadButtonTooltip : string ++accept : string ++maxCount : number ++directory : boolean ++multiple : boolean ++disabled : boolean ++overflow : string ++title : string ++imageProps : dict ++placeholder : dict +} +class ModelScopeProMultimodalInput { ++mode : string ++autoSize : boolean|dict ++uploadConfig : dict ++preprocess(payload) dict ++postprocess(value) MultimodalInputValue ++_processSingleFile(f) NamedString +} +MultimodalInputValue --> ModelScopeProMultimodalInput : 使用 +MultimodalInputUploadConfig --> ModelScopeProMultimodalInput : 配置 +``` + +**图表来源** + +- [backend 模块定义:18-80](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L18-L80) +- [backend 模块定义:82-205](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L205) + +### 上传配置详解 + +| 配置项 | 类型 | 默认值 | 描述 | +| ------------------- | ------- | ------------- | ------------------------------ | +| fullscreenDrop | boolean | false | 是否允许全屏拖拽文件到附件区域 | +| allowUpload | boolean | true | 是否允许文件上传 | +| allowPasteFile | boolean | true | 是否允许粘贴文件上传 | +| allowSpeech | boolean | false | 是否允许语音输入 | +| showCount | boolean | true | 附件面板关闭时是否显示文件数量 | +| uploadButtonTooltip | string | null | 上传按钮的提示信息 | +| accept | string | null | 接受的文件类型 | +| maxCount | number | null | 上传文件数量限制 | +| directory | boolean | false | 支持上传整个目录 | +| multiple | boolean | false | 支持多文件选择 | +| disabled | boolean | false | 禁用文件上传 | +| overflow | string | null | 文件列表溢出行为 | +| title | string | "Attachments" | 附件面板标题 | +| imageProps | dict | null | 图片配置 | +| placeholder | dict | 内置占位符 | 无文件时的占位信息 | + +### 事件处理机制 + +```mermaid +flowchart TD +Start([用户操作]) --> CheckType{"操作类型"} +CheckType --> |文本输入| TextChange["更新文本值
触发 onChange 事件"] +CheckType --> |文件添加| FileAdd["验证文件数量
添加到临时列表"] +CheckType --> |文件移除| FileRemove["从列表中移除
更新文件列表"] +CheckType --> |拖拽上传| DragUpload["处理拖拽文件
调用上传接口"] +CheckType --> |粘贴上传| PasteUpload["处理粘贴文件
调用上传接口"] +CheckType --> |录音上传| RecordUpload["录制音频
转换格式后上传"] +FileAdd --> UploadCall["调用 upload 接口"] +UploadCall --> UploadSuccess{"上传成功?"} +UploadSuccess --> |是| UpdateList["更新最终文件列表
触发回调"] +UploadSuccess --> |否| ErrorHandle["错误处理
恢复状态"] +TextChange --> End([完成]) +FileRemove --> End +DragUpload --> End +PasteUpload --> End +RecordUpload --> End +UpdateList --> End +ErrorHandle --> End +``` + +**图表来源** + +- [前端组件实现:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) +- [前端组件实现:352-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L352-L360) + +### 录音功能实现 + +录音功能通过 Wavesurfer.js 实现，支持以下特性： + +- 实时波形显示 +- 音频格式转换（WAV） +- 自动裁剪和重采样 +- 录制状态管理 + +```mermaid +sequenceDiagram +participant User as 用户 +participant Recorder as 录音钩子 +participant WaveSurfer as Wavesurfer实例 +participant AudioContext as 音频上下文 +participant Uploader as 上传模块 +User->>Recorder : 点击录音按钮 +Recorder->>WaveSurfer : 初始化录制器 +WaveSurfer->>AudioContext : 创建音频上下文 +AudioContext->>WaveSurfer : 配置录制参数 +User->>Recorder : 开始录制 +Recorder->>WaveSurfer : startRecording() +WaveSurfer->>AudioContext : 开始捕获音频 +User->>Recorder : 停止录制 +Recorder->>WaveSurfer : stopRecording() +WaveSurfer->>AudioContext : 获取音频缓冲区 +AudioContext->>Recorder : 转换为 WAV 格式 +Recorder->>Uploader : 上传音频文件 +Uploader->>Uploader : 调用 upload 接口 +Uploader-->>Recorder : 返回 FileData +Recorder-->>User : 显示上传结果 +``` + +**图表来源** + +- [录音钩子:24-41](file://frontend/pro/multimodal-input/recorder.ts#L24-L41) +- [音频处理工具:94-126](file://frontend/pro/multimodal-input/utils.ts#L94-L126) + +**章节来源** + +- [录音钩子:1-48](file://frontend/pro/multimodal-input/recorder.ts#L1-L48) +- [音频处理工具:1-127](file://frontend/pro/multimodal-input/utils.ts#L1-L127) + +## 依赖关系分析 + +```mermaid +graph TB +subgraph "核心依赖" +React[React 18+] +Antd[Ant Design 5.x] +ADX[Ant Design X] +Gradio[Gradio Client] +end +subgraph "录音相关" +Wavesurfer[Wavesurfer.js] +RecordPlugin[Record Plugin] +end +subgraph "工具库" +Lodash[LoDash] +Classnames[ClassNames] +Moment[Moment.js] +end +subgraph "组件内部" +MultimodalInput[MultimodalInput 组件] +Recorder[useRecorder 钩子] +Utils[音频处理工具] +Wrapper[Index.svelte 包装器] +end +MultimodalInput --> React +MultimodalInput --> Antd +MultimodalInput --> ADX +MultimodalInput --> Gradio +MultimodalInput --> Recorder +MultimodalInput --> Utils +Recorder --> Wavesurfer +Recorder --> RecordPlugin +Wrapper --> MultimodalInput +MultimodalInput --> Lodash +MultimodalInput --> Classnames +``` + +**图表来源** + +- [前端组件实现:1-26](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L26) +- [录音钩子:1-5](file://frontend/pro/multimodal-input/recorder.ts#L1-L5) +- [组件包导出配置:1-15](file://frontend/pro/multimodal-input/package.json#L1-L15) + +**章节来源** + +- [组件包导出配置:1-15](file://frontend/pro/multimodal-input/package.json#L1-L15) +- [组件打包配置:1-4](file://frontend/pro/multimodal-input/gradio.config.js#L1-L4) + +## 性能考虑 + +MultimodalInput 在设计时充分考虑了性能优化： + +### 文件上传优化 + +- 支持批量上传控制，通过 maxCount 限制同时上传的文件数量 +- 采用临时文件列表机制，避免重复渲染 +- 异步上传处理，不阻塞主线程 + +### 内存管理 + +- 录音结束后及时释放音频上下文资源 +- 文件上传完成后清理临时文件引用 +- 使用 useMemoizedFn 优化函数引用 + +### 渲染优化 + +- 条件渲染附件面板，减少不必要的 DOM 元素 +- 使用虚拟滚动处理大量文件列表 +- 按需加载录音插件 + +## 故障排除指南 + +### 常见问题及解决方案 + +**问题1：录音功能无法使用** + +- 检查浏览器权限设置 +- 确认 HTTPS 环境（录音需要安全上下文） +- 验证麦克风设备可用性 + +**问题2：文件上传失败** + +- 检查网络连接状态 +- 验证文件大小限制 +- 确认服务器上传接口正常 + +**问题3：拖拽上传无响应** + +- 确认 fullscreenDrop 配置正确 +- 检查 CSS 样式冲突 +- 验证浏览器兼容性 + +**问题4：音频格式不兼容** + +- 确认浏览器支持 WAV 格式 +- 检查音频采样率设置 +- 验证音频通道数配置 + +**章节来源** + +- [录音钩子:24-41](file://frontend/pro/multimodal-input/recorder.ts#L24-L41) +- [前端组件实现:178-179](file://frontend/pro/multimodal-input/multimodal-input.tsx#L178-L179) + +## 结论 + +MultimodalInput 是一个功能完整、架构清晰的多模态输入组件。它通过合理的分层设计和完善的错误处理机制，为开发者提供了强大的富媒体输入能力。组件支持多种输入方式，具有良好的扩展性和可配置性，适合构建各种复杂的富媒体应用界面。 + +## 附录 + +### 使用示例概览 + +由于代码片段内容较多，建议参考官方文档中的示例页面获取完整的使用示例。 + +### API 参考 + +组件支持的完整属性和事件接口，请参考组件文档中的 API 部分。 + +### 版本兼容性 + +- React 18+ +- Ant Design 5.x +- Ant Design X +- Gradio 3.x+ diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206/\344\275\277\347\224\250\347\244\272\344\276\213.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206/\344\275\277\347\224\250\347\244\272\344\276\213.md" new file mode 100644 index 00000000..70ad9a71 --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206/\344\275\277\347\224\250\347\244\272\344\276\213.md" @@ -0,0 +1,337 @@ +# 使用示例 + + +**本文引用的文件** +- [backend 模块：MultimodalInput 定义](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py) +- [前端索引：MultimodalInput 组件入口](file://frontend/pro/multimodal-input/Index.svelte) +- [前端实现：MultimodalInput React 组件](file://frontend/pro/multimodal-input/multimodal-input.tsx) +- [示例：基础用法](file://docs/components/pro/multimodal_input/demos/basic.py) +- [示例：Block 模式](file://docs/components/pro/multimodal_input/demos/block_mode.py) +- [示例：额外按钮与自定义操作](file://docs/components/pro/multimodal_input/demos/extra_button.py) +- [示例：上传配置](file://docs/components/pro/multimodal_input/demos/upload_config.py) +- [示例：与 Chatbot 组件集成](file://docs/components/pro/multimodal_input/demos/with_chatbot.py) +- [Chatbot 组件文档（中文）](file://docs/components/pro/chatbot/README-zh_CN.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向希望在 Gradio/ModelScope Studio 生态中使用 MultimodalInput 组件的开发者，提供从基础文本输入到与 Chatbot 集成的完整使用示例与说明。内容涵盖： + +- 基础用法：最简单的文本输入与提交流程 +- Block 模式：将输入区与发送按钮分离渲染，适合更复杂的布局 +- 自定义操作：通过插槽添加前缀/后缀按钮与工具栏 +- 上传配置：限制文件类型、数量、粘贴/语音等能力 +- 与 Chatbot 集成：在真实聊天应用中接收用户文本与文件，并处理取消与加载态 + +## 项目结构 + +MultimodalInput 由后端 Python 组件与前端 React/Svelte 实现组成，文档示例位于 docs/components/pro/multimodal_input/demos。 + +```mermaid +graph TB +subgraph "后端" +PY["Python 组件
MultimodalInput 定义"] +end +subgraph "前端" +IDX["Svelte 入口
Index.svelte"] +CMP["React 组件
multimodal-input.tsx"] +end +subgraph "示例" +DEMO_BASIC["基础用法"] +DEMO_BLOCK["Block 模式"] +DEMO_EXTRA["额外按钮与自定义操作"] +DEMO_UPLOAD["上传配置"] +DEMO_CHATBOT["与 Chatbot 集成"] +end +PY --> IDX --> CMP +DEMO_BASIC --> PY +DEMO_BLOCK --> PY +DEMO_EXTRA --> PY +DEMO_UPLOAD --> PY +DEMO_CHATBOT --> PY +``` + +**图表来源** + +- [前端索引：MultimodalInput 组件入口:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) +- [前端实现：MultimodalInput React 组件:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [示例：基础用法:1-17](file://docs/components/pro/multimodal_input/demos/basic.py#L1-L17) +- [示例：Block 模式:1-81](file://docs/components/pro/multimodal_input/demos/block_mode.py#L1-L81) +- [示例：额外按钮与自定义操作:1-78](file://docs/components/pro/multimodal_input/demos/extra_button.py#L1-L78) +- [示例：上传配置:1-38](file://docs/components/pro/multimodal_input/demos/upload_config.py#L1-L38) +- [示例：与 Chatbot 组件集成:1-57](file://docs/components/pro/multimodal_input/demos/with_chatbot.py#L1-L57) + +**章节来源** + +- [前端索引：MultimodalInput 组件入口:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) +- [前端实现：MultimodalInput React 组件:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [示例：基础用法:1-17](file://docs/components/pro/multimodal_input/demos/basic.py#L1-L17) +- [示例：Block 模式:1-81](file://docs/components/pro/multimodal_input/demos/block_mode.py#L1-L81) +- [示例：额外按钮与自定义操作:1-78](file://docs/components/pro/multimodal_input/demos/extra_button.py#L1-L78) +- [示例：上传配置:1-38](file://docs/components/pro/multimodal_input/demos/upload_config.py#L1-L38) +- [示例：与 Chatbot 组件集成:1-57](file://docs/components/pro/multimodal_input/demos/with_chatbot.py#L1-L57) + +## 核心组件 + +- 后端组件：ModelScopeProMultimodalInput 提供值模型、事件绑定、预处理/后处理逻辑与前端目录映射 +- 前端组件：MultimodalInput（React）封装 Sender 与 Attachments，支持文本输入、文件上传、语音录制、粘贴文件、插槽扩展等 +- 插槽：支持 header/prefix/footer/suffix 以及技能相关插槽（skill.\*） + +关键点 + +- 值模型：MultimodalInputValue 包含 text 与 files 字段 +- 事件：change/submit/cancel/key_down/key_press/focus/blur/upload/paste/paste_file/skill_closable_close/drop/download/preview/remove +- 模式：mode 支持 inline 与 block；block 模式下 footer 渲染为独立区域，包含发送/加载/语音等控件 + +**章节来源** + +- [backend 模块：MultimodalInput 定义:76-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L76-L259) +- [前端实现：MultimodalInput React 组件:32-104](file://frontend/pro/multimodal-input/multimodal-input.tsx#L32-L104) + +## 架构总览 + +MultimodalInput 在前端通过 Svelte 入口导入 React 组件，将 Gradio 侧的 props 与事件桥接至 React 组件内部，再将值变化回传给 Gradio。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant G as "Gradio 应用" +participant S as "Svelte 入口(Index.svelte)" +participant R as "React 组件(MultimodalInput)" +participant A as "附件面板(Attachments)" +participant E as "发送器(Sender)" +U->>G : 输入文本/选择文件/点击发送 +G->>S : 推送 value/事件 +S->>R : 透传 props 与事件 +R->>A : 上传文件/管理文件列表 +R->>E : 文本变更/提交/取消 +E-->>R : 触发 onChange/onSubmit/onCancel +R-->>S : onValueChange 回传 +S-->>G : 更新组件值 +``` + +**图表来源** + +- [前端索引：MultimodalInput 组件入口:68-98](file://frontend/pro/multimodal-input/Index.svelte#L68-L98) +- [前端实现：MultimodalInput React 组件:311-351](file://frontend/pro/multimodal-input/multimodal-input.tsx#L311-L351) + +## 详细组件分析 + +### 基础用法 + +- 目标：展示最基本的文本输入与提交 +- 关键点：创建 MultimodalInput 并绑定 submit 事件，函数接收输入值（包含 text 与 files） +- 适用场景：快速搭建聊天输入框，无需文件上传或额外按钮 + +```mermaid +flowchart TD +Start(["开始"]) --> Create["创建 MultimodalInput"] +Create --> Bind["绑定 submit 事件"] +Bind --> Submit["用户点击发送"] +Submit --> Fn["回调函数接收输入值"] +Fn --> End(["结束"]) +``` + +**图表来源** + +- [示例：基础用法:7-16](file://docs/components/pro/multimodal_input/demos/basic.py#L7-L16) + +**章节来源** + +- [示例：基础用法:1-17](file://docs/components/pro/multimodal_input/demos/basic.py#L1-L17) + +### Block 模式 + +- 目标：将输入区与发送按钮分离，footer 区域自定义布局 +- 关键点：mode="block"；footer 插槽内可放置“清历史”等按钮；auto_size 控制行数范围 +- 适用场景：需要更清晰的输入/操作分离布局，如垂直布局的聊天窗口 + +```mermaid +flowchart TD +Init(["初始化 MultimodalInput(mode='block')"]) --> Footer["自定义 footer 插槽"] +Footer --> AutoSize["配置 auto_size(minRows,maxRows)"] +AutoSize --> Submit["用户点击发送/取消"] +Submit --> Update["更新输入值与聊天记录"] +Update --> End(["完成一轮交互"]) +``` + +**图表来源** + +- [示例：Block 模式:57-77](file://docs/components/pro/multimodal_input/demos/block_mode.py#L57-L77) + +**章节来源** + +- [示例：Block 模式:1-81](file://docs/components/pro/multimodal_input/demos/block_mode.py#L1-L81) + +### 添加额外按钮与自定义操作 + +- 目标：通过插槽在前缀/后缀区域添加按钮与图标 +- 关键点：使用 ms.Slot("prefix")/("suffix") 注入按钮；结合 Tooltip/Button/Icon 实现“清历史”等操作 +- 适用场景：在输入框旁增加常用操作入口，提升交互效率 + +```mermaid +sequenceDiagram +participant U as "用户" +participant I as "MultimodalInput" +participant P as "prefix 插槽" +participant Btn as "清历史按钮" +U->>I : 点击输入框 +I->>P : 渲染前缀插槽 +P->>Btn : 渲染按钮 +U->>Btn : 点击清历史 +Btn-->>I : 触发 click 事件 +I-->>U : 更新聊天记录 +``` + +**图表来源** + +- [示例：额外按钮与自定义操作:59-74](file://docs/components/pro/multimodal_input/demos/extra_button.py#L59-L74) + +**章节来源** + +- [示例：额外按钮与自定义操作:1-78](file://docs/components/pro/multimodal_input/demos/extra_button.py#L1-L78) + +### 上传配置（文件类型、数量、粘贴/语音等） + +- 目标：灵活控制文件上传行为与外观 +- 关键点：MultimodalInputUploadConfig 支持 accept、max_count、fullscreen_drop、multiple、allow_speech、allow_paste_file、placeholder 等 +- 适用场景：限制上传类型（如图片）、限制数量、启用全屏拖拽、允许语音/粘贴文件 + +```mermaid +flowchart TD +Cfg["配置 upload_config"] --> Accept["设置 accept(如 image/*)"] +Cfg --> Max["设置 max_count 限制数量"] +Cfg --> Full["开启 fullscreen_drop"] +Cfg --> Other["开启 allow_speech/allow_paste_file"] +Accept --> Render["渲染上传按钮与占位符"] +Max --> Render +Full --> Render +Other --> Render +Render --> Upload["用户上传/粘贴/录音"] +Upload --> Done["完成上传并更新文件列表"] +``` + +**图表来源** + +- [示例：上传配置:12-34](file://docs/components/pro/multimodal_input/demos/upload_config.py#L12-L34) + +**章节来源** + +- [示例：上传配置:1-38](file://docs/components/pro/multimodal_input/demos/upload_config.py#L1-L38) + +### 与 Chatbot 组件集成 + +- 目标：在真实聊天应用中接收用户文本与文件，并处理取消与加载态 +- 关键点：MultimodalInput.submit 输出 {text, files}；Chatbot 支持多模态消息（text/file/tool/suggestion），可通过 value 列表管理消息流 +- 适用场景：构建带文件/语音输入的智能客服、问答助手等 + +```mermaid +sequenceDiagram +participant U as "用户" +participant MI as "MultimodalInput" +participant FN as "提交回调" +participant CB as "Chatbot" +U->>MI : 输入文本/选择文件/点击发送 +MI->>FN : 触发 submit，传入 {text, files} +FN->>CB : 追加用户消息(含 text/file) +FN->>CB : 追加机器人“正在生成”消息 +FN-->>MI : 清空输入并设置 loading +CB-->>U : 展示消息流 +U->>MI : 点击取消 +MI->>FN : 触发 cancel +FN->>CB : 结束加载并标记完成 +``` + +**图表来源** + +- [示例：与 Chatbot 组件集成:10-53](file://docs/components/pro/multimodal_input/demos/with_chatbot.py#L10-L53) +- [Chatbot 组件文档（中文）:298-349](file://docs/components/pro/chatbot/README-zh_CN.md#L298-L349) + +**章节来源** + +- [示例：与 Chatbot 组件集成:1-57](file://docs/components/pro/multimodal_input/demos/with_chatbot.py#L1-L57) +- [Chatbot 组件文档（中文）:1-354](file://docs/components/pro/chatbot/README-zh_CN.md#L1-L354) + +## 依赖关系分析 + +- 后端依赖：Gradio 数据类、事件系统、文件处理工具 +- 前端依赖：@ant-design/x 的 Sender/Attachments、Ant Design 图标与组件、Gradio 客户端上传工具 +- 插槽与事件：通过 slots 与事件名映射（如 key_press/paste_file）桥接到 React 侧 + +```mermaid +graph LR +PY["后端组件"] --> FE_IDX["Svelte 入口"] +FE_IDX --> FE_CMP["React 组件"] +FE_CMP --> ADX["Ant Design X(Sender/Attachments)"] +FE_CMP --> ANT["Ant Design(按钮/提示等)"] +FE_CMP --> GRCL["Gradio 客户端上传"] +``` + +**图表来源** + +- [前端实现：MultimodalInput React 组件:1-26](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L26) +- [前端索引：MultimodalInput 组件入口:1-15](file://frontend/pro/multimodal-input/Index.svelte#L1-L15) + +**章节来源** + +- [前端实现：MultimodalInput React 组件:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [前端索引：MultimodalInput 组件入口:1-99](file://frontend/pro/multimodal-input/Index.svelte#L1-L99) + +## 性能考量 + +- 上传节流与并发：前端对上传状态进行 uploading 标记，避免重复上传 +- 文件去重与合并：根据 uid 合并临时文件与服务端返回数据，减少重复渲染 +- 行为限制：max_count 与 multiple 可降低一次性上传压力 +- 加载态与取消：loading 与 cancel 事件用于中断长任务，改善用户体验 + +[本节为通用建议，不直接分析具体文件] + +## 故障排查指南 + +- 无法上传文件 + - 检查 upload_config 的 allow_upload/disabled 与 max_count + - 确认文件类型与 accept 设置 +- 上传后未显示文件 + - 确认 onUpload 回调与 onChange 是否正确更新 value +- 发送按钮不可用 + - 检查 disabled/loading/read_only 状态 +- 取消无效 + - 确保 cancel 绑定的 cancels 正确指向 submit 事件 +- Block 模式 footer 不显示 + - 确认 mode="block" 且 footer 插槽正确注入 + +**章节来源** + +- [前端实现：MultimodalInput React 组件:174-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L174-L246) +- [示例：Block 模式:69-77](file://docs/components/pro/multimodal_input/demos/block_mode.py#L69-L77) + +## 结论 + +MultimodalInput 提供了从基础文本输入到复杂多模态交互的一体化能力：通过简洁的 API 与灵活的插槽系统，既能满足快速集成需求，也能支持更丰富的交互设计。结合 Chatbot 组件，可轻松构建具备文件/语音输入能力的智能聊天应用。 + +[本节为总结性内容，不直接分析具体文件] + +## 附录 + +- 值模型与事件参考 + - 值模型：MultimodalInputValue(text, files) + - 事件：change/submit/cancel/key_down/key_press/focus/blur/upload/paste/paste_file/skill_closable_close/drop/download/preview/remove +- 插槽清单：suffix/header/prefix/footer/skill.title/skill.toolTip.title/skill.closable.closeIcon + +**章节来源** + +- [backend 模块：MultimodalInput 定义:76-143](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L76-L143) +- [前端实现：MultimodalInput React 组件:95-104](file://frontend/pro/multimodal-input/multimodal-input.tsx#L95-L104) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206/\346\225\260\346\215\256\345\244\204\347\220\206\346\234\272\345\210\266.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206/\346\225\260\346\215\256\345\244\204\347\220\206\346\234\272\345\210\266.md" new file mode 100644 index 00000000..2d99fe90 --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206/\346\225\260\346\215\256\345\244\204\347\220\206\346\234\272\345\210\266.md" @@ -0,0 +1,478 @@ +# 数据处理机制 + + +**本文引用的文件** +- [multimodal-input.tsx](file://frontend/pro/multimodal-input/multimodal-input.tsx) +- [recorder.ts](file://frontend/pro/multimodal-input/recorder.ts) +- [utils.ts](file://frontend/pro/multimodal-input/utils.ts) +- [useValueChange.ts](file://frontend/utils/hooks/useValueChange.ts) +- [useMemoizedFn.ts](file://frontend/utils/hooks/useMemoizedFn.ts) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [convertToCamelCase.ts](file://frontend/utils/convertToCamelCase.ts) +- [createFunction.ts](file://frontend/utils/createFunction.ts) +- [omitUndefinedProps.ts](file://frontend/utils/omitUndefinedProps.ts) +- [multimodal-input.less](file://frontend/pro/multimodal-input/multimodal-input.less) +- [__init__.py](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py) +- [index.js](file://backend/modelscope_studio/components/pro/multimodal_input/templates/component/index.js) +- [basic.py](file://docs/components/pro/multimodal_input/demos/basic.py) +- [README.md](file://docs/components/pro/multimodal_input/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件聚焦 MultimodalInput 组件的数据处理机制，系统阐述以下内容： + +- 前端与后端的数据模型与转换流程（preprocess/postprocess） +- 文件上传、下载、缓存处理策略 +- 事件监听机制（change、submit、cancel、upload、paste 等）及其触发条件与回调处理 +- 数据格式转换与错误处理最佳实践 + +## 项目结构 + +MultimodalInput 的实现横跨前端与后端两部分： + +- 前端：基于 Ant Design X 的 Sender 与 Attachments，结合录音与上传逻辑，负责用户交互与数据格式化 +- 后端：基于 Gradio 的数据类与事件绑定，负责输入预处理与输出后处理 + +```mermaid +graph TB +subgraph "前端" +MI["MultimodalInput 组件
multimodal-input.tsx"] +REC["录音钩子
recorder.ts"] +UTIL["音频处理工具
utils.ts"] +HVC["值同步钩子
useValueChange.ts"] +HMF["函数记忆钩子
useMemoizedFn.ts"] +HF["函数创建钩子
useFunction.ts"] +CCC["键名驼峰化
convertToCamelCase.ts"] +CF["字符串转函数
createFunction.ts"] +OUP["属性过滤
omitUndefinedProps.ts"] +CSS["样式
multimodal-input.less"] +end +subgraph "后端" +PY["组件定义与事件
__init__.py"] +IDX["前端打包入口
index.js"] +end +MI --- REC +MI --- UTIL +MI --- HVC +MI --- HMF +MI --- HF +MI --- CCC +MI --- CF +MI --- OUP +MI --- CSS +PY --- IDX +``` + +图示来源 + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [recorder.ts:1-48](file://frontend/pro/multimodal-input/recorder.ts#L1-L48) +- [utils.ts:1-127](file://frontend/pro/multimodal-input/utils.ts#L1-L127) +- [useValueChange.ts:1-30](file://frontend/utils/hooks/useValueChange.ts#L1-L30) +- [useMemoizedFn.ts:1-11](file://frontend/utils/hooks/useMemoizedFn.ts#L1-L11) +- [useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [convertToCamelCase.ts:1-22](file://frontend/utils/convertToCamelCase.ts#L1-L22) +- [createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) +- [omitUndefinedProps.ts:1-17](file://frontend/utils/omitUndefinedProps.ts#L1-L17) +- [multimodal-input.less:1-13](file://frontend/pro/multimodal-input/multimodal-input.less#L1-L13) +- [**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) +- [index.js:1-6](file://backend/modelscope_studio/components/pro/multimodal_input/templates/component/index.js#L1-L6) + +章节来源 + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) + +## 核心组件 + +- 前端组件：MultimodalInput（基于 sveltify 包装的 React 组件），内部组合 Sender 与 Attachments，并集成录音能力 +- 后端组件：ModelScopeProMultimodalInput（Gradio 组件），定义数据模型与事件绑定 + +关键职责： + +- 前端：维护本地状态（文本与文件列表）、处理上传/粘贴/删除等交互、格式化变更值、触发事件回调 +- 后端：preprocess 将前端传入的文件路径转换为可缓存的本地文件；postprocess 将本地文件还原为可展示的 FileData 列表 + +章节来源 + +- [multimodal-input.tsx:32-104](file://frontend/pro/multimodal-input/multimodal-input.tsx#L32-L104) +- [**init**.py:76-137](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L76-L137) + +## 架构总览 + +MultimodalInput 的数据流从用户交互开始，贯穿前端状态管理、上传处理、后端预处理与后处理，最终回到前端渲染。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant MI as "MultimodalInput(前端)" +participant SEN as "Sender(前端)" +participant ATT as "Attachments(前端)" +participant UP as "上传函数(upload)" +participant BE as "MultimodalInput(后端)" +participant FS as "文件系统/缓存" +U->>MI : 输入文本/选择文件/粘贴/录音 +MI->>SEN : 文本变更回调 +SEN-->>MI : onChange(value) +MI->>MI : formatChangedValue() 生成变更值 +MI-->>U : onChange 回调 +U->>ATT : 选择/拖拽/删除文件 +ATT-->>MI : onChange(info) +MI->>UP : 上传选中文件 +UP-->>MI : 返回 FileData[] +MI->>MI : 合并文件列表/更新状态 +MI-->>U : onUpload/onValueChange/onChange +U->>SEN : 提交 +SEN-->>BE : 触发 submit 事件 +BE->>BE : preprocess() 转换文件路径为本地文件 +BE-->>U : 返回处理后的值 +BE->>FS : 缓存/读取文件 +BE-->>MI : postprocess() 还原为 FileData 列表 +MI-->>U : 渲染附件列表 +``` + +图示来源 + +- [multimodal-input.tsx:336-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L336-L360) +- [multimodal-input.tsx:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) +- [multimodal-input.tsx:220-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L220-L246) +- [**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) + +## 详细组件分析 + +### 数据模型与字段含义 + +- 前端数据模型 + - MultimodalInputValue：包含 text（文本）与 files（文件数组）两个字段 + - MultimodalInputChangedValue：用于 onChange 回调，files 为文件路径数组，text 为文本 +- 后端数据模型 + - MultimodalInputValue：与前端一致，但 files 为 Gradio 的 ListFiles 类型 + - MultimodalInputUploadConfig：控制上传行为（如是否允许上传、粘贴、语音、最大数量等） + +字段说明（摘自类型定义与注释）： + +- files：文件集合，支持多文件与单文件模式 +- text：用户输入的文本内容 +- upload_config：上传配置对象，含 fullscreen_drop、allow_upload、allow_paste_file、allow_speech、max_count、placeholder 等 + +章节来源 + +- [multimodal-input.tsx:32-57](file://frontend/pro/multimodal-input/multimodal-input.tsx#L32-L57) +- [**init**.py:18-74](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L18-L74) +- [README.md:54-118](file://docs/components/pro/multimodal_input/README.md#L54-L118) + +### preprocess 与 postprocess 工作原理 + +- preprocess（后端） + - 输入：MultimodalInputValue（包含 text 与 files） + - 处理：遍历 files，将每个文件路径写入临时文件，返回包含 text 与本地文件路径的字典 + - 作用：确保后端能稳定访问文件，避免外部链接失效 +- postprocess（后端） + - 输入：后端处理结果（可能包含文件路径） + - 处理：对文件路径进行下载或本地缓存处理，再封装为 FileData 列表返回给前端 + - 作用：将后端存储的文件路径还原为前端可展示的文件信息（含原始名称、大小等） + +```mermaid +flowchart TD +Start(["进入 preprocess"]) --> CheckPayload{"payload 是否为空?"} +CheckPayload --> |是| ReturnEmpty["返回空文件列表"] +CheckPayload --> |否| IterateFiles["遍历 files 列表"] +IterateFiles --> TempFile["写入临时文件/获取本地路径"] +TempFile --> BuildOut["构建输出字典 {text, files}"] +BuildOut --> End(["结束"]) +subgraph "postprocess" +PStart(["进入 postprocess"]) --> PCheck{"value 是否为空?"} +PCheck --> |是| PReturnEmpty["返回空值"] +PCheck --> |否| PIterate["遍历 files 列表"] +PIterate --> PDownload{"是否为 HTTP 链接?"} +PDownload --> |是| SaveUrl["保存到缓存"] +PDownload --> |否| KeepLocal["使用本地路径"] +SaveUrl --> Pack["封装为 FileData 列表"] +KeepLocal --> Pack +Pack --> PEnd(["结束"]) +end +``` + +图示来源 + +- [**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) + +章节来源 + +- [**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) + +### 文件上传、下载与缓存处理 + +- 上传流程 + - 用户在 Attachments 中选择/拖拽文件，触发 onChange + - 前端根据 maxCount 限制有效文件数，生成临时上传项，设置状态为 uploading + - 调用 upload 函数（由上层注入）执行实际上传，返回 FileData 数组 + - 合并文件列表，触发 onUpload、onValueChange、onChange +- 下载与缓存 + - 后端在 preprocess 中将远程文件保存到本地缓存目录 + - 在 postprocess 中将本地文件路径还原为 FileData，供前端展示 + +```mermaid +sequenceDiagram +participant ATT as "Attachments(前端)" +participant MI as "MultimodalInput(前端)" +participant UP as "upload 函数" +participant BE as "后端组件" +participant FS as "缓存/文件系统" +ATT->>MI : onChange(info) +MI->>MI : 校验 maxCount/生成临时项 +MI->>UP : 上传文件 +UP-->>MI : 返回 FileData[] +MI->>MI : 合并文件列表/更新状态 +MI-->>ATT : 更新显示 +MI->>BE : 触发事件/提交数据 +BE->>FS : 保存/读取文件 +BE-->>MI : 返回处理后的值 +``` + +图示来源 + +- [multimodal-input.tsx:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) +- [multimodal-input.tsx:220-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L220-L246) +- [**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) + +章节来源 + +- [multimodal-input.tsx:181-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L181-L246) +- [multimodal-input.tsx:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) +- [**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) + +### 事件监听机制 + +- 事件绑定（后端） + - 支持的事件：change、submit、cancel、key_down、key_press、focus、blur、upload、paste、paste_file、skill_closable_close、drop、download、preview、remove + - 通过 EventListener 注册，绑定到组件内部 update 流程 +- 前端事件触发 + - 文本变更：Sender.onChange → onChange（格式化为变更值） + - 提交：Sender.onSubmit → onSubmit（仅当建议面板未打开时） + - 取消：Sender.onCancel → onCancel + - 粘贴：Sender.onPasteFile → onPasteFile（若允许粘贴） + - 上传：Attachments.onChange → onUpload + onValueChange + onChange + - 删除：Attachments.onChange → onRemove + 状态更新 + - 录音：useRecorder 触发录音状态变化，停止时调用上传函数 + +```mermaid +sequenceDiagram +participant SEN as "Sender(前端)" +participant ATT as "Attachments(前端)" +participant MI as "MultimodalInput(前端)" +participant BE as "后端组件" +SEN->>MI : onChange(text) +MI-->>SEN : onChange({text, files}) +SEN->>MI : onSubmit() +MI-->>SEN : onSubmit({text, files}) +SEN->>MI : onCancel() +MI-->>SEN : onCancel() +SEN->>MI : onPasteFile(files) +MI-->>SEN : onPasteFile(paths) +ATT->>MI : onChange(info) +MI-->>ATT : onUpload + onValueChange + onChange +ATT->>MI : onRemove(file) +MI-->>ATT : 状态更新 +``` + +图示来源 + +- [multimodal-input.tsx:344-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L344-L360) +- [multimodal-input.tsx:336-343](file://frontend/pro/multimodal-input/multimodal-input.tsx#L336-L343) +- [multimodal-input.tsx:352-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L352-L360) +- [multimodal-input.tsx:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) +- [**init**.py:86-135](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L86-L135) + +章节来源 + +- [multimodal-input.tsx:344-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L344-L360) +- [multimodal-input.tsx:336-343](file://frontend/pro/multimodal-input/multimodal-input.tsx#L336-L343) +- [multimodal-input.tsx:352-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L352-L360) +- [multimodal-input.tsx:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) +- [**init**.py:86-135](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L86-L135) + +### 数据格式转换与最佳实践 + +- 前端格式化 + - formatChangedValue：将 MultimodalInputValue 转为 MultimodalInputChangedValue，便于回调传递 + - convertObjectKeyToCamelCase：将上传配置的 snake_case 键名转换为 camelCase，适配组件属性 + - omitUndefinedProps：过滤 undefined/null 属性，避免无效配置透传 + - createFunction/useFunction：将字符串形式的函数表达式解析为可执行函数，支持插槽与格式化 +- 后端转换 + - preprocess：将文件路径写入临时文件，保证后端可访问 + - postprocess：将本地文件还原为 FileData，包含原始名称与大小等元信息 + +```mermaid +flowchart TD +A["输入 payload"] --> B["preprocess: 路径->本地文件"] +B --> C["后端处理"] +C --> D["postprocess: 本地文件->FileData 列表"] +D --> E["返回前端渲染"] +F["前端 value"] --> G["formatChangedValue: {files[], text}"] +G --> H["onChange 回调"] +``` + +图示来源 + +- [multimodal-input.tsx:59-66](file://frontend/pro/multimodal-input/multimodal-input.tsx#L59-L66) +- [convertToCamelCase.ts:13-21](file://frontend/utils/convertToCamelCase.ts#L13-L21) +- [omitUndefinedProps.ts:1-17](file://frontend/utils/omitUndefinedProps.ts#L1-L17) +- [createFunction.ts:10-37](file://frontend/utils/createFunction.ts#L10-L37) +- [**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) + +章节来源 + +- [multimodal-input.tsx:59-66](file://frontend/pro/multimodal-input/multimodal-input.tsx#L59-L66) +- [convertToCamelCase.ts:13-21](file://frontend/utils/convertToCamelCase.ts#L13-L21) +- [omitUndefinedProps.ts:1-17](file://frontend/utils/omitUndefinedProps.ts#L1-L17) +- [createFunction.ts:10-37](file://frontend/utils/createFunction.ts#L10-L37) +- [**init**.py:213-248](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L213-L248) + +### 录音与音频处理 + +- 录音钩子 + - useRecorder：基于 wavesurfer.js 与 record 插件，提供录音状态与 start/stop 控制 + - 停止录音时，回调返回 Blob，前端将其转换为 WAVE 格式并触发上传 +- 音频处理工具 + - processAudio：将 Blob 解码为 AudioBuffer，按需裁剪后编码为 WAV 字节流 + +```mermaid +sequenceDiagram +participant UI as "用户界面" +participant REC as "useRecorder" +participant WA as "wavesurfer.js" +participant UT as "processAudio" +participant MI as "MultimodalInput" +UI->>REC : 开始录音 +REC->>WA : startRecording() +WA-->>REC : record-start +REC-->>UI : 设置 recording=true +UI->>REC : 结束录音 +REC->>WA : stopRecording() +WA-->>REC : record-end(Blob) +REC->>UT : 处理 Blob -> WAV +UT-->>REC : Uint8Array +REC->>MI : 上传音频文件 +``` + +图示来源 + +- [recorder.ts:11-47](file://frontend/pro/multimodal-input/recorder.ts#L11-L47) +- [utils.ts:94-126](file://frontend/pro/multimodal-input/utils.ts#L94-L126) +- [multimodal-input.tsx:157-169](file://frontend/pro/multimodal-input/multimodal-input.tsx#L157-L169) + +章节来源 + +- [recorder.ts:11-47](file://frontend/pro/multimodal-input/recorder.ts#L11-L47) +- [utils.ts:94-126](file://frontend/pro/multimodal-input/utils.ts#L94-L126) +- [multimodal-input.tsx:157-169](file://frontend/pro/multimodal-input/multimodal-input.tsx#L157-L169) + +### 前端状态与 UI 插槽 + +- 值同步：useValueChange 确保 valueProp 与内部状态双向一致，避免抖动 +- 函数记忆：useMemoizedFn 保持回调引用稳定，减少重渲染 +- 插槽与格式化：useFunction + createFunction 支持字符串函数表达式，配合 slotConfig 实现结构化输入 +- UI 结构：根据 mode（inline/block）切换头部/底部布局，支持技能提示与可关闭图标等扩展 + +章节来源 + +- [useValueChange.ts:9-29](file://frontend/utils/hooks/useValueChange.ts#L9-L29) +- [useMemoizedFn.ts:1-11](file://frontend/utils/hooks/useMemoizedFn.ts#L1-L11) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [multimodal-input.tsx:407-457](file://frontend/pro/multimodal-input/multimodal-input.tsx#L407-L457) + +## 依赖关系分析 + +- 组件耦合 + - MultimodalInput 依赖多个工具钩子与函数，形成高内聚低耦合的模块化设计 + - 上传配置通过 convertObjectKeyToCamelCase 与 omitUndefinedProps 保证健壮性 +- 外部依赖 + - Ant Design X（Sender/Attachments）、Ant Design（Button/Badge/Flex）、wavesurfer.js（录音） + - Gradio（后端数据类与事件系统） + +```mermaid +graph LR +MI["MultimodalInput.tsx"] --> SEN["Sender(ANTDX)"] +MI --> ATT["Attachments(ANTDX)"] +MI --> REC["useRecorder.ts"] +MI --> UTIL["utils.ts"] +MI --> HVC["useValueChange.ts"] +MI --> HMF["useMemoizedFn.ts"] +MI --> HF["useFunction.ts"] +MI --> CCC["convertToCamelCase.ts"] +MI --> CF["createFunction.ts"] +MI --> OUP["omitUndefinedProps.ts"] +MI --> CSS["multimodal-input.less"] +BE["__init__.py"] --> IDX["index.js"] +``` + +图示来源 + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) +- [index.js:1-6](file://backend/modelscope_studio/components/pro/multimodal_input/templates/component/index.js#L1-L6) + +章节来源 + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) +- [index.js:1-6](file://backend/modelscope_studio/components/pro/multimodal_input/templates/component/index.js#L1-L6) + +## 性能考量 + +- 上传并发与节流 + - 使用 uploading 状态避免重复上传 + - 通过 maxCount 限制一次性上传数量，降低内存与网络压力 +- 渲染优化 + - useMemoizedFn 保持回调引用稳定，减少子组件重渲染 + - useValueChange 仅在值变化时更新，避免不必要的副作用 +- 音频处理 + - 录音结束后立即解码与编码，缩短主线程阻塞时间 + - 对大文件采用分片或流式处理策略（视业务需求） + +## 故障排查指南 + +- 上传失败 + - 检查 upload 函数返回值是否为 FileData[]，确保 uid 与临时项对应 + - 关注异常捕获与 uploading 状态恢复 +- 文件计数不正确 + - 确认 maxCount 配置与合并逻辑（单文件模式会清空旧列表） +- 事件未触发 + - 确认后端 EVENTS 绑定是否启用，前端是否正确传递回调 +- 录音无输出 + - 检查录音容器是否可用、浏览器权限与音频上下文初始化 + +章节来源 + +- [multimodal-input.tsx:242-245](file://frontend/pro/multimodal-input/multimodal-input.tsx#L242-L245) +- [multimodal-input.tsx:598-601](file://frontend/pro/multimodal-input/multimodal-input.tsx#L598-L601) +- [**init**.py:86-135](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L86-L135) + +## 结论 + +MultimodalInput 通过前后端协同，实现了完整的多模态输入体验：文本输入、文件上传、粘贴与录音，配合严格的预处理与后处理流程，确保数据一致性与稳定性。其模块化的前端实现与清晰的事件体系，为扩展更多交互能力提供了良好基础。 + +## 附录 + +- 示例应用：基础用法与与聊天机器人集成 +- API 文档：属性、插槽与类型定义参考 + +章节来源 + +- [basic.py:7-16](file://docs/components/pro/multimodal_input/demos/basic.py#L7-L16) +- [README.md:27-118](file://docs/components/pro/multimodal_input/README.md#L27-L118) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206/\347\273\204\344\273\266\346\246\202\350\247\210.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206/\347\273\204\344\273\266\346\246\202\350\247\210.md" new file mode 100644 index 00000000..410acbfe --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/MultimodalInput \345\244\232\346\250\241\346\200\201\350\276\223\345\205\245\346\241\206/\347\273\204\344\273\266\346\246\202\350\247\210.md" @@ -0,0 +1,324 @@ +# 组件概览 + + +**本文引用的文件列表** +- [multimodal-input.tsx](file://frontend/pro/multimodal-input/multimodal-input.tsx) +- [recorder.ts](file://frontend/pro/multimodal-input/recorder.ts) +- [utils.ts](file://frontend/pro/multimodal-input/utils.ts) +- [multimodal-input.less](file://frontend/pro/multimodal-input/multimodal-input.less) +- [__init__.py](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py) +- [README.md](file://docs/components/pro/multimodal_input/README.md) +- [upload_config.py](file://docs/components/pro/multimodal_input/demos/upload_config.py) +- [basic.py](file://docs/components/pro/multimodal_input/demos/basic.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +MultimodalInput 是一个基于 Ant Design X 的多模态输入组件，支持文本输入、图片上传、音频录制、文件拖拽等多种输入方式。它在机器学习与对话式应用中具有重要价值：既能承载自然语言指令，也能接收图像、音频等多媒体数据，便于构建更丰富的交互体验与多模态模型训练/推理管线。 + +组件设计理念： + +- 以“文本 + 文件”为核心数据模型，统一对外暴露 value 与变更事件。 +- 基于 Ant Design X 的 Sender 与 Attachments 组合，提供一致的输入与附件管理体验。 +- 支持 inline/block 两种渲染模式，适配不同布局需求。 +- 提供灵活的上传配置（类型限制、数量上限、粘贴上传、全屏拖拽等）与可插拔的录音能力。 + +## 项目结构 + +MultimodalInput 在前端采用 React + Svelte Preprocess 的桥接方案，在后端通过 Gradio 数据类与事件绑定对接 Python 环境。核心文件分布如下： + +- 前端实现：multimodal-input.tsx（主组件）、recorder.ts（录音钩子）、utils.ts（音频处理）、multimodal-input.less（样式） +- 后端实现：**init**.py（数据模型、事件、预处理/后处理） +- 文档与示例：README.md（API 说明）、demos 下的示例脚本 + +```mermaid +graph TB +subgraph "前端" +A["multimodal-input.tsx
主组件"] +B["recorder.ts
录音钩子"] +C["utils.ts
音频处理"] +D["multimodal-input.less
样式"] +end +subgraph "后端" +E["__init__.py
数据模型/事件/预处理/后处理"] +end +A --> B +A --> C +A --> D +A --> E +``` + +图表来源 + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [recorder.ts:1-48](file://frontend/pro/multimodal-input/recorder.ts#L1-L48) +- [utils.ts:1-127](file://frontend/pro/multimodal-input/utils.ts#L1-L127) +- [multimodal-input.less:1-13](file://frontend/pro/multimodal-input/multimodal-input.less#L1-L13) +- [**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) + +章节来源 + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [**init**.py:1-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L1-L259) + +## 核心组件 + +- 主组件：MultimodalInput（React 包装的 Svelte 组件），负责文本输入、附件面板、录音按钮、提交/取消等交互。 +- 录音钩子：useRecorder，封装录音开始/停止与状态管理，并在录音结束时回调生成的音频 Blob。 +- 音频处理：processAudio/process_audio，将录音转换为 WAV 格式并返回二进制数据。 +- 数据模型：MultimodalInputValue（files/text），MultimodalInputUploadConfig（上传配置）。 +- 后端组件：ModelScopeProMultimodalInput，定义事件、slots、预处理/后处理逻辑，以及默认上传配置。 + +章节来源 + +- [multimodal-input.tsx:32-104](file://frontend/pro/multimodal-input/multimodal-input.tsx#L32-L104) +- [recorder.ts:6-47](file://frontend/pro/multimodal-input/recorder.ts#L6-L47) +- [utils.ts:60-126](file://frontend/pro/multimodal-input/utils.ts#L60-L126) +- [**init**.py:18-79](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L18-L79) +- [**init**.py:82-259](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L82-L259) + +## 架构总览 + +MultimodalInput 将“文本输入 + 附件上传 + 录音采集”整合为统一的数据流： + +- 输入层：Sender 负责文本输入；附件面板由 Attachments 提供。 +- 采集层：录音通过 wavesurfer.js + record 插件实现，结束后转为 WAV 并触发上传。 +- 上传层：调用外部 upload 回调，将文件写入后端并返回 FileData 列表，更新内部文件列表。 +- 事件层：onChange/onSubmit/onUpload/onRemove/onPasteFile 等事件贯穿整个流程，便于上层业务订阅。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant S as "Sender(文本)" +participant A as "Attachments(附件)" +participant R as "录音钩子(useRecorder)" +participant P as "音频处理(utils)" +participant F as "上传(upload回调)" +participant M as "MultimodalInput(主组件)" +U->>S : 输入文本 +S->>M : onChange(text) +U->>A : 拖拽/选择文件 +A->>M : onChange(文件列表) +U->>R : 开始录音 +R->>P : 录音结束回调Blob +P-->>R : WAV二进制 +R->>F : 上传WAV +F-->>M : 返回FileData[] +M->>M : 更新files列表 +M-->>U : 触发onUpload/onValueChange +U->>S : 提交 +S->>M : onSubmit +M-->>U : 触发onSubmit +``` + +图表来源 + +- [multimodal-input.tsx:157-169](file://frontend/pro/multimodal-input/multimodal-input.tsx#L157-L169) +- [utils.ts:94-126](file://frontend/pro/multimodal-input/utils.ts#L94-L126) +- [multimodal-input.tsx:181-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L181-L246) +- [multimodal-input.tsx:336-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L336-L360) + +## 详细组件分析 + +### 组件接口与数据模型 + +- MultimodalInputValue：包含 files（文件数组）与 text（文本）两个字段，作为组件的值对象。 +- MultimodalInputChangedValue：对外暴露的变更值，files 为字符串路径数组，text 为字符串。 +- MultimodalInputUploadConfig：上传相关配置项，如 accept、max_count、allow_speech、allow_paste_file、fullscreen_drop、multiple、directory、overflow、title、image_props、placeholder 等。 + +章节来源 + +- [multimodal-input.tsx:32-66](file://frontend/pro/multimodal-input/multimodal-input.tsx#L32-L66) +- [multimodal-input.tsx:42-57](file://frontend/pro/multimodal-input/multimodal-input.tsx#L42-L57) +- [**init**.py:18-79](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L18-L79) + +### 渲染模式与插槽 + +- mode：inline（内联）与 block（块级）两种模式，block 模式下输入区与发送/加载按钮分离，footer 中提供额外操作区与动作区。 +- slots：支持 suffix/header/prefix/footer 以及 skill.\* 系列插槽，用于扩展 UI 与技能提示/关闭图标等。 + +章节来源 + +- [multimodal-input.tsx:86-104](file://frontend/pro/multimodal-input/multimodal-input.tsx#L86-L104) +- [multimodal-input.tsx:426-457](file://frontend/pro/multimodal-input/multimodal-input.tsx#L426-L457) +- [**init**.py:139-143](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L139-L143) + +### 上传与文件管理 + +- 上传入口：通过 upload 回调将文件写入后端，返回 FileData 列表，合并到当前文件列表。 +- 限制策略：支持 max_count 单文件替换或批量追加；支持 multiple/directory/fullscreen_drop 等。 +- 事件回调：onUpload/onRemove/onPreview/onDownload/onDrop 等，便于上层处理下载/预览/移除等行为。 + +章节来源 + +- [multimodal-input.tsx:181-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L181-L246) +- [multimodal-input.tsx:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) +- [**init**.py:111-135](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L111-L135) + +### 录音与音频处理 + +- 录音钩子：useRecorder 提供 recording 状态与 start/stop 方法，录音结束时回调 Blob。 +- 音频处理：processAudio 将 Blob 解码为 AudioBuffer，按需裁剪后转为 WAV 字节流，再封装为 File 对象触发上传。 + +章节来源 + +- [recorder.ts:6-47](file://frontend/pro/multimodal-input/recorder.ts#L6-L47) +- [utils.ts:94-126](file://frontend/pro/multimodal-input/utils.ts#L94-L126) +- [multimodal-input.tsx:157-169](file://frontend/pro/multimodal-input/multimodal-input.tsx#L157-L169) + +### 事件与生命周期 + +- 事件：change/submit/cancel/key_down/key_press/focus/blur/upload/paste/paste_file/skill_closable_close/drop/download/preview/remove。 +- 生命周期：组件内部维护 value 与 fileList，onChange/onSubmit/onUpload/onRemove 等回调串联前后端交互。 + +章节来源 + +- [**init**.py:86-135](file://backend/modelscope_studio/components/pro/multimodal_input/__init__.py#L86-L135) +- [multimodal-input.tsx:336-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L336-L360) +- [multimodal-input.tsx:511-602](file://frontend/pro/multimodal-input/multimodal-input.tsx#L511-L602) + +### 类图（代码级） + +```mermaid +classDiagram +class MultimodalInputValue { ++files : FileData[] ++text : string +} +class MultimodalInputChangedValue { ++files : string[] ++text : string +} +class MultimodalInputUploadConfig { ++fullscreen_drop : bool ++allow_upload : bool ++allow_paste_file : bool ++allow_speech : bool ++show_count : bool ++upload_button_tooltip : string ++accept : string ++max_count : int ++directory : bool ++multiple : bool ++disabled : bool ++overflow : wrap|scrollX|scrollY ++title : string ++image_props : dict ++placeholder : dict +} +class ModelScopeProMultimodalInput { ++EVENTS ++SLOTS ++preprocess(payload) ++postprocess(value) +} +class useRecorder { ++recording : bool ++start() ++stop() +} +class Utils { ++processAudio(blob, start?, end?) : Promise
组件包装与逻辑"] +B["multimodal-input.less
样式"] +C["recorder.ts
录音能力"] +D["utils.ts
工具函数"] +end +subgraph "后端" +E["components.py
导出 ProMultimodalInput"] +F["multimodal_input/__init__.py
类型定义与组件类"] +end +subgraph "文档" +G["README.md
API 与类型说明"] +end +A --> E +E --> F +A --> B +A --> C +A --> D +G --> A +G --> F +``` + +图表来源 + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [README.md:1-119](file://docs/components/pro/multimodal_input/README.md#L1-L119) + +章节来源 + +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [README.md:1-119](file://docs/components/pro/multimodal_input/README.md#L1-L119) + +## 核心组件 + +- MultimodalInputUploadConfig：用于配置文件上传区域的行为与外观，包含接受类型、数量限制、目录上传、多选、禁用、溢出行为、占位信息、标题、图片属性等。 +- MultimodalInput：基于 Ant Design X 的 Sender 与 Attachments 组合，支持文本输入、文件上传、语音录制、粘贴文件等能力；通过 uploadConfig 控制上传区域行为。 + +章节来源 + +- [multimodal-input.tsx:42-57](file://frontend/pro/multimodal-input/multimodal-input.tsx#L42-L57) +- [README.md:56-118](file://docs/components/pro/multimodal_input/README.md#L56-L118) + +## 架构总览 + +MultimodalInput 将外部传入的 uploadConfig 转换为内部可用的配置对象，并将其透传给 Attachments 组件，同时根据 allowUpload/allowSpeech/allowPasteFile 等开关控制功能启用状态。上传流程中会根据 maxCount 与目录/多选策略进行文件集合合并与去重处理。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant MI as "MultimodalInput" +participant CFG as "uploadConfig" +participant ATT as "Attachments" +participant SEN as "Sender" +Dev->>MI : 传入 uploadConfig 与 props +MI->>CFG : 转换为驼峰键名并合并默认值 +MI->>ATT : 透传除特殊字段外的配置 +MI->>SEN : 配置允许的输入方式语音/粘贴 +SEN-->>MI : 用户提交或取消 +ATT-->>MI : 文件增删/拖拽/选择事件 +MI->>MI : 根据 maxCount/目录/多选策略处理文件列表 +MI-->>Dev : 触发 onValueChange/onUpload/onPasteFile 等回调 +``` + +图表来源 + +- [multimodal-input.tsx:174-177](file://frontend/pro/multimodal-input/multimodal-input.tsx#L174-L177) +- [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) +- [multimodal-input.tsx:282-284](file://frontend/pro/multimodal-input/multimodal-input.tsx#L282-L284) + +章节来源 + +- [multimodal-input.tsx:174-177](file://frontend/pro/multimodal-input/multimodal-input.tsx#L174-L177) +- [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) +- [multimodal-input.tsx:282-284](file://frontend/pro/multimodal-input/multimodal-input.tsx#L282-L284) + +## 详细组件分析 + +### MultimodalInputUploadConfig 参数详解 + +以下参数均来自后端类型定义与前端实现映射，作用与默认值以文档与源码为准。 + +- fullscreen_drop + - 作用：是否允许将文件拖拽到整个页面窗口以触发附件面板。 + - 默认值：False + - 使用场景：需要在任意位置释放文件时打开附件面板。 + - 实现要点：当开启时，getDropContainer 返回 document.body，使拖拽范围扩大至全局。 + - 参考路径 + - [multimodal-input.tsx:480-486](file://frontend/pro/multimodal-input/multimodal-input.tsx#L480-L486) + +- allow_upload + - 作用：是否启用上传区域与文件选择/拖拽功能。 + - 默认值：True + - 使用场景：仅需文本输入，不希望用户上传文件。 + - 实现要点：影响 allowSpeech/allowPasteFile 的可用性（二者在 allowUpload 为真时才生效）。 + - 参考路径 + - [multimodal-input.tsx:282-284](file://frontend/pro/multimodal-input/multimodal-input.tsx#L282-L284) + +- allow_paste_file + - 作用：是否允许通过剪贴板粘贴文件。 + - 默认值：True + - 使用场景：提升便捷性，允许用户直接粘贴文件内容。 + - 实现要点：受 allow_upload 控制，若关闭则忽略粘贴事件。 + - 参考路径 + - [multimodal-input.tsx:352-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L352-L360) + +- allow_speech + - 作用：是否启用语音输入（麦克风录音）。 + - 默认值：False + - 使用场景：需要语音转文字或上传音频文件。 + - 实现要点：仅在 allowUpload 为真时生效；录音结束后自动触发上传。 + - 参考路径 + - [multimodal-input.tsx:317-333](file://frontend/pro/multimodal-input/multimodal-input.tsx#L317-L333) + - [multimodal-input.tsx:157-169](file://frontend/pro/multimodal-input/multimodal-input.tsx#L157-L169) + +- show_count + - 作用：当附件面板关闭时，是否显示文件数量徽标。 + - 默认值：True + - 使用场景：在不展开面板的情况下提示已添加的文件数量。 + - 参考路径 + - [multimodal-input.tsx:288-294](file://frontend/pro/multimodal-input/multimodal-input.tsx#L288-L294) + +- upload_button_tooltip + - 作用：上传按钮的悬浮提示文案。 + - 默认值：无（空字符串） + - 使用场景：为上传入口提供额外说明。 + - 参考路径 + - [multimodal-input.tsx:287-305](file://frontend/pro/multimodal-input/multimodal-input.tsx#L287-L305) + +- accept + - 作用：限制可选择的文件类型（HTML input accept 属性语义）。 + - 默认值：None + - 使用场景：只允许图片、文档或特定格式文件。 + - 参考路径 + - [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) + +- max_count + - 作用：限制可上传的文件总数；当为 1 时替换当前文件。 + - 默认值：None + - 使用场景：单文件覆盖型上传（如头像）、批量上传上限控制。 + - 实现要点：在新增/粘贴/拖拽时按剩余配额截断有效文件列表。 + - 参考路径 + - [multimodal-input.tsx:187-204](file://frontend/pro/multimodal-input/multimodal-input.tsx#L187-L204) + - [multimodal-input.tsx:543-552](file://frontend/pro/multimodal-input/multimodal-input.tsx#L543-L552) + +- directory + - 作用：是否支持上传整个目录（文件夹内所有文件）。 + - 默认值：False + - 使用场景：需要批量上传目录结构。 + - 参考路径 + - [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) + +- multiple + - 作用：是否允许多文件选择（配合 Ctrl/Cmd 多选）。 + - 默认值：False + - 使用场景：需要一次选择多个文件。 + - 参考路径 + - [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) + +- disabled + - 作用：整体禁用上传区域与按钮。 + - 默认值：False + - 使用场景：只读模式或等待条件满足后再启用。 + - 实现要点：uploadDisabled 综合 disabled/loading/readOnly/uploading 计算得出。 + - 参考路径 + - [multimodal-input.tsx:178-179](file://frontend/pro/multimodal-input/multimodal-input.tsx#L178-L179) + +- overflow + - 作用：文件列表溢出时的行为（wrap/scrollX/scrollY）。 + - 默认值：None + - 使用场景：在有限空间内展示大量文件。 + - 参考路径 + - [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) + +- image_props + - 作用：传递给内部图片预览组件的配置（与 Ant Design Image 相同）。 + - 默认值：None + - 使用场景：自定义图片缩放、加载失败回退等。 + - 参考路径 + - [multimodal-input.tsx:476-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L476-L478) + +- placeholder + - 作用：无文件时的占位信息，支持 inline 与 drop 两种形态。 + - 默认值：包含 inline/title/description/icon 与 drop/title 的默认值。 + - 使用场景：引导用户点击/拖拽上传。 + - 参考路径 + - [multimodal-input.tsx:488-507](file://frontend/pro/multimodal-input/multimodal-input.tsx#L488-L507) + - [README.md:103-112](file://docs/components/pro/multimodal_input/README.md#L103-L112) + +- title + - 作用：附件面板标题。 + - 默认值："Attachments" + - 使用场景：本地化或业务定制标题。 + - 参考路径 + - [multimodal-input.tsx:461-461](file://frontend/pro/multimodal-input/multimodal-input.tsx#L461-L461) + - [README.md:101-101](file://docs/components/pro/multimodal_input/README.md#L101-L101) + +章节来源 + +- [multimodal-input.tsx:42-57](file://frontend/pro/multimodal-input/multimodal-input.tsx#L42-L57) +- [multimodal-input.tsx:174-177](file://frontend/pro/multimodal-input/multimodal-input.tsx#L174-L177) +- [multimodal-input.tsx:178-179](file://frontend/pro/multimodal-input/multimodal-input.tsx#L178-L179) +- [multimodal-input.tsx:187-204](file://frontend/pro/multimodal-input/multimodal-input.tsx#L187-L204) +- [multimodal-input.tsx:282-284](file://frontend/pro/multimodal-input/multimodal-input.tsx#L282-L284) +- [multimodal-input.tsx:287-305](file://frontend/pro/multimodal-input/multimodal-input.tsx#L287-L305) +- [multimodal-input.tsx:317-333](file://frontend/pro/multimodal-input/multimodal-input.tsx#L317-L333) +- [multimodal-input.tsx:352-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L352-L360) +- [multimodal-input.tsx:461-461](file://frontend/pro/multimodal-input/multimodal-input.tsx#L461-L461) +- [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) +- [multimodal-input.tsx:480-486](file://frontend/pro/multimodal-input/multimodal-input.tsx#L480-L486) +- [multimodal-input.tsx:488-507](file://frontend/pro/multimodal-input/multimodal-input.tsx#L488-L507) +- [multimodal-input.tsx:543-552](file://frontend/pro/multimodal-input/multimodal-input.tsx#L543-L552) +- [README.md:56-118](file://docs/components/pro/multimodal_input/README.md#L56-L118) + +### 配置组合示例（路径指引） + +以下示例均来自文档与示例应用，你可以通过对应路径查看完整实现与效果： + +- 基础示例（含上传配置） + - 示例路径 + - [README.md:23-25](file://docs/components/pro/multimodal_input/README.md#L23-L25) + +- 上传配置示例（演示多种配置项） + - 示例路径 + - [README.md:23-25](file://docs/components/pro/multimodal_input/README.md#L23-L25) + +- 与 Chatbot 集成示例 + - 示例路径 + - [README.md:11-13](file://docs/components/pro/multimodal_input/README.md#L11-L13) + +- 块模式（Block Mode） + - 示例路径 + - [README.md:19-21](file://docs/components/pro/multimodal_input/README.md#L19-L21) + +- 附加按钮配置示例 + - 示例路径 + - [README.md:15-17](file://docs/components/pro/multimodal_input/README.md#L15-L17) + +- 基础示例 + - 示例路径 + - [README.md:7-9](file://docs/components/pro/multimodal_input/README.md#L7-L9) + +章节来源 + +- [README.md:7-25](file://docs/components/pro/multimodal_input/README.md#L7-L25) +- [README.md:11-21](file://docs/components/pro/multimodal_input/README.md#L11-L21) +- [README.md:15-17](file://docs/components/pro/multimodal_input/README.md#L15-L17) + +## 依赖关系分析 + +- 前端依赖 + - @ant-design/x：Sender 与 Attachments 组件提供输入与附件管理能力。 + - antd：Button、Badge、Flex、Tooltip 等 UI 组件用于界面与交互。 + - lodash-es：工具函数（如 omit）辅助处理配置与事件。 +- 后端依赖 + - GradioModel：MultimodalInputUploadConfig 与 MultimodalInputValue 的数据模型基类。 + - components.py：导出 ProMultimodalInput，供上层应用使用。 + +```mermaid +graph LR +MI["MultimodalInput.tsx"] --> X["@ant-design/x
Sender/Attachments"] +MI --> ANT["antd
UI 组件库"] +MI --> LODASH["lodash-es
工具函数"] +CFG["MultimodalInputUploadConfig"] --> GR["GradioModel
数据模型"] +PRO["components.py"] --> MI +``` + +图表来源 + +- [multimodal-input.tsx:1-26](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L26) +- [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [README.md:56-118](file://docs/components/pro/multimodal_input/README.md#L56-L118) + +章节来源 + +- [multimodal-input.tsx:1-26](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L26) +- [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [README.md:56-118](file://docs/components/pro/multimodal_input/README.md#L56-L118) + +## 性能考量 + +- 文件数量与大小 + - 使用 max_count 控制并发与存储压力；对大文件建议分片或服务端校验。 +- 渲染与更新 + - 通过 useMemo 与 useValueChange 优化渲染与状态同步，避免不必要的重渲染。 +- 上传策略 + - 在 allowUpload=false 或 disabled/loading/readOnly 时短路上传流程，减少无效请求。 +- 拖拽范围 + - fullscreen_drop 会将拖拽容器设置为 document.body，注意在复杂页面中可能带来额外事件开销。 + +章节来源 + +- [multimodal-input.tsx:174-177](file://frontend/pro/multimodal-input/multimodal-input.tsx#L174-L177) +- [multimodal-input.tsx:178-179](file://frontend/pro/multimodal-input/multimodal-input.tsx#L178-L179) +- [multimodal-input.tsx:480-486](file://frontend/pro/multimodal-input/multimodal-input.tsx#L480-L486) + +## 故障排查指南 + +- 无法上传文件 + - 检查 allow_upload 是否为真；确认 disabled/loading/readOnly/uploading 状态。 + - 确认 accept 与 multiple 设置是否符合预期。 + - 参考路径 + - [multimodal-input.tsx:282-284](file://frontend/pro/multimodal-input/multimodal-input.tsx#L282-L284) + - [multimodal-input.tsx:178-179](file://frontend/pro/multimodal-input/multimodal-input.tsx#L178-L179) + - [multimodal-input.tsx:466-478](file://frontend/pro/multimodal-input/multimodal-input.tsx#L466-L478) +- 粘贴文件无效 + - 检查 allow_paste_file 是否为真；确保浏览器权限与剪贴板内容可识别。 + - 参考路径 + - [multimodal-input.tsx:352-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L352-L360) +- 语音输入不可用 + - 检查 allow_speech 与 allow_upload；确认浏览器麦克风权限。 + - 参考路径 + - [multimodal-input.tsx:317-333](file://frontend/pro/multimodal-input/multimodal-input.tsx#L317-L333) + - [multimodal-input.tsx:282-284](file://frontend/pro/multimodal-input/multimodal-input.tsx#L282-L284) +- 文件数量超过限制 + - 检查 max_count；当为 1 时会替换当前文件；大于 1 时按剩余配额截断。 + - 参考路径 + - [multimodal-input.tsx:187-204](file://frontend/pro/multimodal-input/multimodal-input.tsx#L187-L204) + - [multimodal-input.tsx:543-552](file://frontend/pro/multimodal-input/multimodal-input.tsx#L543-L552) +- 拖拽范围异常 + - fullscreen_drop 为真时，拖拽范围扩展至 document.body；请确认页面结构与事件冲突。 + - 参考路径 + - [multimodal-input.tsx:480-486](file://frontend/pro/multimodal-input/multimodal-input.tsx#L480-L486) + +章节来源 + +- [multimodal-input.tsx:178-179](file://frontend/pro/multimodal-input/multimodal-input.tsx#L178-L179) +- [multimodal-input.tsx:187-204](file://frontend/pro/multimodal-input/multimodal-input.tsx#L187-L204) +- [multimodal-input.tsx:282-284](file://frontend/pro/multimodal-input/multimodal-input.tsx#L282-L284) +- [multimodal-input.tsx:317-333](file://frontend/pro/multimodal-input/multimodal-input.tsx#L317-L333) +- [multimodal-input.tsx:352-360](file://frontend/pro/multimodal-input/multimodal-input.tsx#L352-L360) +- [multimodal-input.tsx:480-486](file://frontend/pro/multimodal-input/multimodal-input.tsx#L480-L486) +- [multimodal-input.tsx:543-552](file://frontend/pro/multimodal-input/multimodal-input.tsx#L543-L552) + +## 结论 + +MultimodalInputUploadConfig 提供了从文件类型、数量、目录、多选到上传区域行为与占位信息的全面配置能力。通过合理组合 allow_upload、allow_speech、allow_paste_file、max_count、fullscreen_drop、accept、multiple、directory、disabled、overflow、image_props、placeholder、title、upload_button_tooltip 等参数，可以快速适配从简单文本输入到复杂多模态交互的各种场景。建议优先明确业务目标（单/多文件、是否允许目录、是否需要语音/粘贴），再据此选择合适的默认值与覆盖项。 + +## 附录 + +- 相关类型定义与默认值参考 + - [README.md:56-118](file://docs/components/pro/multimodal_input/README.md#L56-L118) +- 组件导出与集成 + - [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222.md" new file mode 100644 index 00000000..6e173e60 --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222.md" @@ -0,0 +1,365 @@ +# WebSandbox 网页沙盒 + + +**本文引用的文件** +- [web-sandbox.tsx](file://frontend/pro/web-sandbox/web-sandbox.tsx) +- [parser.ts](file://frontend/pro/web-sandbox/parser.ts) +- [utils.ts](file://frontend/pro/web-sandbox/utils.ts) +- [react-iframe-template.html](file://frontend/pro/web-sandbox/react-iframe-template.html) +- [html-iframe-event-listener.js](file://frontend/pro/web-sandbox/html-iframe-event-listener.js) +- [web-sandbox.less](file://frontend/pro/web-sandbox/web-sandbox.less) +- [Index.svelte](file://frontend/pro/web-sandbox/Index.svelte) +- [web-sandbox-CY4X1bGf.js](file://backend/modelscope_studio/components/pro/web_sandbox/templates/component/web-sandbox-CY4X1bGf.js) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：使用示例与最佳实践](#附录使用示例与最佳实践) + +## 简介 + +WebSandbox 是一个用于在受控环境中安全渲染第三方或用户输入内容的组件，支持两种模式： + +- React 模式：以 React 应用入口文件为起点进行编译、打包与运行，适合复杂交互与组件化场景。 +- HTML 模式：对 HTML 文档进行解析与注入，内联脚本与样式，适合快速渲染静态或半静态页面。 + +该组件通过 iframe 隔离执行环境，利用 postMessage 进行父子窗口事件通信，并提供完善的错误处理与主题适配能力，确保在不破坏宿主应用的前提下完成安全渲染。 + +## 项目结构 + +前端核心位于 frontend/pro/web-sandbox，后端模板由 Python 后端生成并注入到运行时中，Svelte 层负责桥接与属性透传。 + +```mermaid +graph TB +subgraph "前端" +A["web-sandbox.tsx
组件主体与生命周期"] +B["parser.ts
文件解析与依赖图构建"] +C["utils.ts
路径/入口/模板工具"] +D["react-iframe-template.html
React 模板"] +E["html-iframe-event-listener.js
iframe 内事件监听"] +F["web-sandbox.less
样式"] +G["Index.svelte
Svelte 包装层"] +end +subgraph "后端" +H["web-sandbox-CY4X1bGf.js
后端模板与运行时"] +end +A --> B +A --> C +A --> D +A --> E +A --> F +G --> A +H --> D +H --> E +``` + +**图表来源** + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [web-sandbox.less:1-24](file://frontend/pro/web-sandbox/web-sandbox.less#L1-L24) +- [Index.svelte:1-76](file://frontend/pro/web-sandbox/Index.svelte#L1-L76) +- [web-sandbox-CY4X1bGf.js:163-205](file://backend/modelscope_studio/components/pro/web_sandbox/templates/component/web-sandbox-CY4X1bGf.js#L163-L205) + +**章节来源** + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [Index.svelte:1-76](file://frontend/pro/web-sandbox/Index.svelte#L1-L76) +- [web-sandbox-CY4X1bGf.js:163-205](file://backend/modelscope_studio/components/pro/web_sandbox/templates/component/web-sandbox-CY4X1bGf.js#L163-L205) + +## 核心组件 + +- WebSandbox 主体：负责接收输入文件、构建 import map、解析/转换文件、生成 iframe 内容、处理消息与错误、注入主题与事件监听脚本。 +- 解析器 WebSandboxParser：基于 Babel Standalone 分析依赖、拓扑排序、替换相对导入为 Blob URL、提取样式表、产出可运行的资源清单。 +- 工具集：路径标准化、入口文件推断、HTML 模板渲染、文件内容提取。 +- 模板与事件监听：React 模板与 HTML 事件监听脚本，统一通过 postMessage 通知父窗口“就绪”与“错误”。 + +关键职责与行为： + +- 安全隔离：iframe 与父窗口通过 postMessage 通信；样式与脚本通过 Blob URL 注入，避免跨域风险。 +- 错误处理：编译期错误与运行期错误分别上报；可选择是否展示通知与回退渲染。 +- 主题适配：向 iframe 注入主题模式，支持动态更新。 +- 事件通信：iframe 加载完成后发送“就绪”，运行时错误通过“错误”事件上报。 + +**章节来源** + +- [web-sandbox.tsx:21-55](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L55) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:20-83](file://frontend/pro/web-sandbox/utils.ts#L20-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## 架构总览 + +WebSandbox 的整体流程分为“编译与注入”和“iframe 渲染与通信”两个阶段。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant WS as "WebSandbox(前端)" +participant Parser as "WebSandboxParser" +participant Iframe as "iframe(子窗口)" +participant Parent as "父窗口" +Dev->>WS : 提供 files/imports/template/value +WS->>Parser : 解析文件/构建依赖图/转换代码 +Parser-->>WS : 返回 entryUrl/styleSheetUrls/normalizedFiles +WS->>WS : 生成 iframe HTML(Blob URL) +WS->>Iframe : 设置 src(Blob URL) +Iframe->>Parent : postMessage("sandbox-ready") +Parent-->>WS : 监听消息(type="sandbox-ready") +WS->>WS : 触发 onCompileSuccess/关闭 loading +Iframe->>Parent : postMessage("sandbox-error", message) +Parent-->>WS : 监听消息(type="sandbox-error") +WS->>WS : 触发 onRenderError/可选通知 +``` + +**图表来源** + +- [web-sandbox.tsx:94-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L94-L218) +- [web-sandbox.tsx:220-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L220-L297) +- [react-iframe-template.html:16-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L16-L40) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## 详细组件分析 + +### WebSandbox 主组件（React） + +- 输入参数与默认值：value、imports、template、showRenderError、showCompileError、height、className、style、onCompileError、onRenderError、onCompileSuccess、onCustom、compileErrorRender 等。 +- 导入映射：根据 template 选择内置 React/ReactDOM 映射，再合并用户自定义 imports。 +- 编译流程： + - React 模式：解析入口文件，构建依赖图，Babel 转换，替换相对导入为 Blob URL，收集样式表，生成入口 URL。 + - HTML 模式：解析 DOM，抽取内联脚本并重写，注入 importmap 与样式链接，注入事件监听脚本，生成完整 HTML Blob URL。 +- iframe 生命周期：创建 Blob URL -> 注入主题与自定义分发函数 -> 监听 sandbox-ready 与 sandbox-error -> 清理 URL。 +- 错误处理：编译期错误通过 onCompileError 与可选的 compileErrorRender 或插槽呈现；运行期错误通过 onRenderError 与通知提示。 + +```mermaid +flowchart TD +Start(["开始"]) --> CheckValue{"是否有 value?"} +CheckValue -- 否 --> End(["结束"]) +CheckValue -- 是 --> Mode{"template=react?"} +Mode -- 是 --> ParseReact["解析入口/构建依赖图
Babel 转换/生成 Blob URL"] +Mode -- 否 --> ParseHTML["解析 DOM/抽取内联脚本
注入 importmap/样式/事件监听"] +ParseReact --> BuildIframe["生成 iframe HTML(Blob URL)"] +ParseHTML --> BuildIframe +BuildIframe --> LoadIframe["设置 iframe.src 并注入主题"] +LoadIframe --> Ready{"收到 sandbox-ready?"} +Ready -- 是 --> OnSuccess["触发 onCompileSuccess/停止 loading"] +Ready -- 否 --> ErrorEvt{"收到 sandbox-error?"} +ErrorEvt -- 是 --> OnError["触发 onRenderError/可选通知"] +OnSuccess --> End +OnError --> End +``` + +**图表来源** + +- [web-sandbox.tsx:94-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L94-L218) +- [web-sandbox.tsx:220-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L220-L297) + +**章节来源** + +- [web-sandbox.tsx:21-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L365) + +### WebSandboxParser 解析器 + +- 文件归一化：规范化路径、识别 JS/TS/JSX/TSX/CSS 扩展名。 +- 依赖图构建：基于 AST 分析 import 声明，处理相对路径与目录索引，生成邻接表。 +- 拓扑排序：检测循环依赖并抛出错误。 +- 代码转换：Babel 转换 React/TSX，替换相对导入为 Blob URL，移除或保留 CSS 导入，生成样式表 Blob URL。 +- 输出：entryUrl、styleSheetUrls、normalizedFiles、cleanup（回收 Blob URL）。 + +```mermaid +flowchart TD +A["输入 files/importMap/entryFilePath"] --> B["归一化文件路径/扩展名"] +B --> C["构建依赖图(含相对/目录索引)"] +C --> D{"是否存在循环依赖?"} +D -- 是 --> E["抛出错误"] +D -- 否 --> F["拓扑排序输出顺序"] +F --> G["Babel 转换/替换导入/处理 CSS"] +G --> H["生成 Blob URL 映射/样式表 URL"] +H --> I["返回 entryUrl/styleSheetUrls/cleanup"] +``` + +**图表来源** + +- [parser.ts:28-314](file://frontend/pro/web-sandbox/parser.ts#L28-L314) + +**章节来源** + +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) + +### 工具模块 + +- 路径与入口：normalizePath、getEntryFile、getFileCode、renderHtmlTemplate。 +- 默认入口文件集合：React 模式与 HTML 模式的默认入口列表。 + +**章节来源** + +- [utils.ts:20-83](file://frontend/pro/web-sandbox/utils.ts#L20-L83) + +### 模板与事件监听 + +- React 模板：包含 importmap、样式注入、事件监听脚本与入口模块加载。 +- HTML 事件监听：在 iframe 内捕获 error 与 DOMContentLoaded，通过 postMessage 通知父窗口。 + +**章节来源** + +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +### Svelte 包装层与后端模板 + +- Svelte 层：负责属性透传、可见性控制、插槽与主题传递。 +- 后端模板：生成与前端一致的 iframe HTML 模板与事件监听脚本，保证前后端一致性。 + +**章节来源** + +- [Index.svelte:1-76](file://frontend/pro/web-sandbox/Index.svelte#L1-L76) +- [web-sandbox-CY4X1bGf.js:163-205](file://backend/modelscope_studio/components/pro/web_sandbox/templates/component/web-sandbox-CY4X1bGf.js#L163-L205) + +## 依赖关系分析 + +- 组件耦合： + - WebSandbox 对 parser.ts、utils.ts、模板与事件监听脚本存在直接依赖。 + - Svelte 层仅作为桥接，不直接参与业务逻辑。 +- 外部依赖： + - Babel Standalone 用于代码转换与 AST 分析。 + - Ant Design 的 notification/Alert 用于错误提示。 + - React/ReactDOM 在 React 模式下通过 importmap 引入。 +- 潜在循环依赖： + - 解析器内部通过拓扑排序避免循环依赖；若用户文件存在循环导入，将在编译阶段报错。 + +```mermaid +graph LR +WS["web-sandbox.tsx"] --> P["parser.ts"] +WS --> U["utils.ts"] +WS --> T["react-iframe-template.html"] +WS --> L["html-iframe-event-listener.js"] +S["Index.svelte"] --> WS +B["web-sandbox-CY4X1bGf.js"] --> T +B --> L +``` + +**图表来源** + +- [web-sandbox.tsx:1-20](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L20) +- [parser.ts:1-12](file://frontend/pro/web-sandbox/parser.ts#L1-L12) +- [utils.ts:1-1](file://frontend/pro/web-sandbox/utils.ts#L1-L1) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [Index.svelte:1-12](file://frontend/pro/web-sandbox/Index.svelte#L1-L12) +- [web-sandbox-CY4X1bGf.js:163-205](file://backend/modelscope_studio/components/pro/web_sandbox/templates/component/web-sandbox-CY4X1bGf.js#L163-L205) + +**章节来源** + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [Index.svelte:1-76](file://frontend/pro/web-sandbox/Index.svelte#L1-L76) +- [web-sandbox-CY4X1bGf.js:163-205](file://backend/modelscope_studio/components/pro/web_sandbox/templates/component/web-sandbox-CY4X1bGf.js#L163-L205) + +## 性能考量 + +- Blob URL 管理：解析器与组件均维护 Blob URL 映射并在清理阶段回收，避免内存泄漏。 +- 懒加载与异步：Svelte 包装层采用异步组件加载，减少首屏压力。 +- 依赖图优化：通过拓扑排序与按序转换，减少重复工作量。 +- 样式注入：CSS 通过 Blob URL 或外链注入，避免阻塞主线程渲染。 +- 事件监听：仅在 iframe 就绪后才开始监听，降低无效通信成本。 + +[本节为通用性能建议，无需特定文件引用] + +## 故障排查指南 + +- 编译期错误 + - 现象：组件显示编译错误，onCompileError 回调被触发。 + - 排查：检查 imports 是否正确、template 与入口文件是否匹配、是否存在循环依赖。 + - 参考：[web-sandbox.tsx:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218)、[parser.ts:128-174](file://frontend/pro/web-sandbox/parser.ts#L128-L174) +- 运行期错误 + - 现象：iframe 报错，父窗口收到 sandbox-error。 + - 排查：查看 onRenderError 回调与通知；确认第三方库是否通过 importmap 正确引入。 + - 参考：[web-sandbox.tsx:262-282](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L282)、[html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- 未触发“就绪” + - 现象：onCompileSuccess 不触发，loading 持续。 + - 排查：确认模板是否正确注入事件监听脚本；检查 Blob URL 是否有效。 + - 参考：[react-iframe-template.html:16-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L16-L40) +- 样式缺失 + - 现象：页面无样式或样式异常。 + - 排查：确认 styleSheetUrls 是否生成；检查 CSS 导入路径与 importmap。 + - 参考：[parser.ts:258-276](file://frontend/pro/web-sandbox/parser.ts#L258-L276) +- 主题不生效 + - 现象：iframe 内主题与宿主不一致。 + - 排查：确认 themeMode 传入与消息派发；检查 iframe 内是否正确接收主题。 + - 参考：[web-sandbox.tsx:244-261](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L261) + +**章节来源** + +- [web-sandbox.tsx:203-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L297) +- [parser.ts:128-276](file://frontend/pro/web-sandbox/parser.ts#L128-L276) +- [react-iframe-template.html:16-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L16-L40) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## 结论 + +WebSandbox 通过严格的文件解析与转换、安全的 iframe 隔离以及统一的事件通信机制，实现了对第三方或用户输入内容的安全渲染。其双模（React/HTML）设计兼顾了灵活性与易用性，配合完善的错误处理与主题适配，能够满足大多数需要安全渲染的场景需求。 + +[本节为总结性内容，无需特定文件引用] + +## 附录：使用示例与最佳实践 + +### 配置项概览 + +- value：文件对象字典，支持字符串或带 is_entry 标记的对象。 +- imports：自定义 importmap，覆盖默认 React/ReactDOM 映射。 +- template：'react' 或 'html'。 +- showRenderError/showCompileError：是否展示运行/编译错误通知。 +- onCompileError/onRenderError/onCompileSuccess/onCustom：事件回调。 +- compileErrorRender：自定义编译错误渲染。 +- height/className/style：容器样式控制。 + +参考路径： + +- [web-sandbox.tsx:21-55](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L55) + +### 安全策略与事件处理 + +- 自定义事件处理：通过 onCustom 将 iframe 内部事件分发至父窗口，实现松耦合通信。 +- 安全边界：iframe 与父窗口通过 postMessage 通信，避免直接 DOM 访问；Blob URL 隔离脚本与样式。 +- 错误捕获：iframe 内错误统一上报，父窗口可选择展示通知或静默处理。 + +参考路径： + +- [web-sandbox.tsx:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +### 使用示例（步骤说明） + +- React 模式 + - 准备入口文件（如 index.tsx），在 value 中标记 is_entry 或使用默认入口。 + - 如需引入第三方库，在 imports 中提供对应 URL。 + - 设置 template='react'，渲染组件并监听 onCompileSuccess 与 onRenderError。 + - 参考：[web-sandbox.tsx:94-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L94-L218)、[react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- HTML 模式 + - 准备 index.html，内联脚本会被抽取并转换。 + - 设置 template='html'，组件会自动注入 importmap、样式与事件监听脚本。 + - 参考：[web-sandbox.tsx:110-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L110-L218)、[html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +### 最佳实践 + +- 优先使用 React 模式以获得更好的类型与生态支持。 +- 将第三方库纳入 imports，避免直接使用 CDN 跨域脚本。 +- 在生产环境开启 showRenderError 以便及时发现运行期问题。 +- 使用 compileErrorRender 插槽或函数自定义错误界面，提升用户体验。 +- 注意清理 Blob URL，防止内存泄漏。 + +[本节为通用指导，无需特定文件引用] diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\344\272\213\344\273\266\345\244\204\347\220\206.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\344\272\213\344\273\266\345\244\204\347\220\206.md" new file mode 100644 index 00000000..a91560d1 --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\344\272\213\344\273\266\345\244\204\347\220\206.md" @@ -0,0 +1,300 @@ +# 事件处理 + + +**本文引用的文件** +- [web-sandbox.tsx](file://frontend/pro/web-sandbox/web-sandbox.tsx) +- [html-iframe-event-listener.js](file://frontend/pro/web-sandbox/html-iframe-event-listener.js) +- [react-iframe-template.html](file://frontend/pro/web-sandbox/react-iframe-template.html) +- [parser.ts](file://frontend/pro/web-sandbox/parser.ts) +- [utils.ts](file://frontend/pro/web-sandbox/utils.ts) +- [README.md](file://docs/components/pro/web_sandbox/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) + +## 简介 + +本章节面向使用 WebSandbox 组件的开发者，系统性讲解组件支持的事件类型、触发时机、回调参数与使用方式，并结合源码分析事件与沙盒安全机制的关系。同时提供事件监听与处理的参考路径、调试与排障建议，帮助快速定位问题并稳定集成。 + +## 项目结构 + +WebSandbox 位于前端 pro 组件目录，核心由以下文件构成： + +- 组件实现：web-sandbox.tsx +- 沙盒 iframe 事件监听脚本：html-iframe-event-listener.js +- React 模板（iframe 内容）：react-iframe-template.html +- 文件解析与打包：parser.ts +- 工具函数：utils.ts +- 文档与示例：docs/components/pro/web_sandbox/README.md + +```mermaid +graph TB +A["WebSandbox 组件
web-sandbox.tsx"] --> B["事件监听脚本
html-iframe-event-listener.js"] +A --> C["React 模板
react-iframe-template.html"] +A --> D["解析器
parser.ts"] +A --> E["工具函数
utils.ts"] +B --> F["iframe 窗口
window.onerror / DOMContentLoaded"] +C --> F +D --> A +E --> A +``` + +图表来源 + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) + +章节来源 + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [README.md:1-70](file://docs/components/pro/web_sandbox/README.md#L1-L70) + +## 核心组件 + +WebSandbox 是一个在页面内通过 iframe 渲染“React 或 HTML”代码的沙盒组件。它负责： + +- 解析传入的文件集合，构建依赖图并进行转换 +- 生成样式与入口资源，注入到 iframe 中 +- 通过 postMessage 在宿主与 iframe 之间传递事件 +- 将编译与渲染阶段的事件回调暴露给上层 + +章节来源 + +- [web-sandbox.tsx:21-35](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L35) +- [web-sandbox.tsx:79-92](file://frontend/pro/web-sandbox/web-sandbox.tsx#L79-L92) +- [web-sandbox.tsx:284-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L284-L297) + +## 架构总览 + +WebSandbox 的事件流从 iframe 内部产生，经由 window 事件监听转发为 postMessage，再由宿主监听 window message 并分发到对应的回调。 + +```mermaid +sequenceDiagram +participant Host as "宿主应用
web-sandbox.tsx" +participant Iframe as "iframe 内容
react-iframe-template.html / html-iframe-event-listener.js" +participant Parser as "解析器
parser.ts" +Host->>Parser : "解析文件/构建依赖图/转换代码" +Parser-->>Host : "返回入口URL/样式URL/清理函数" +Host->>Iframe : "设置iframe内容(React模板或HTML)" +Iframe->>Iframe : "window.addEventListener('DOMContentLoaded')" +Iframe-->>Host : "postMessage({type : 'sandbox-ready'})" +Host->>Host : "onCompileSuccessMemoized()" +Host->>Host : "setLoading(false)" +Iframe->>Iframe : "window.addEventListener('error')" +Iframe-->>Host : "postMessage({type : 'sandbox-error', message})" +Note over Host,Iframe : "事件监听与回调在宿主侧统一处理" +``` + +图表来源 + +- [web-sandbox.tsx:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- [react-iframe-template.html:17-28](file://frontend/pro/web-sandbox/react-iframe-template.html#L17-L28) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## 详细组件分析 + +### 事件类型与触发时机 + +- compile_success（编译成功） + - 触发时机：iframe 内部 DOMContentLoaded 事件触发后，向父窗口发送 sandbox-ready 消息；宿主收到消息后调用 onCompileSuccess 回调。 + - 回调参数：无 + - 使用方式：在 WebSandbox 上注册 onCompileSuccess 回调，用于在沙盒准备就绪时执行后续逻辑（如隐藏加载态、启用交互等）。 + - 参考路径 + - [web-sandbox.tsx:277-279](file://frontend/pro/web-sandbox/web-sandbox.tsx#L277-L279) + - [react-iframe-template.html:24-28](file://frontend/pro/web-sandbox/react-iframe-template.html#L24-L28) + +- compile_error（编译错误） + - 触发时机：解析与转换过程中发生异常，组件捕获异常并调用 onCompileError 回调；同时将错误信息保存到本地状态，可配合 showCompileError 与 compileErrorRender 控制错误展示。 + - 回调参数：message（字符串） + - 使用方式：在 WebSandbox 上注册 onCompileError 回调，用于记录日志、上报或引导用户修复代码。 + - 参考路径 + - [web-sandbox.tsx:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218) + - [parser.ts:285-312](file://frontend/pro/web-sandbox/parser.ts#L285-L312) + +- render_error（渲染错误） + - 触发时机：iframe 内部发生运行时错误（window.onerror），向父窗口发送 sandbox-error 消息；宿主收到消息后调用 onRenderError 回调，并根据 showRenderError 决定是否弹出通知。 + - 回调参数：message（字符串） + - 使用方式：在 WebSandbox 上注册 onRenderError 回调，用于捕获渲染期异常并进行降级处理。 + - 参考路径 + - [web-sandbox.tsx:267-276](file://frontend/pro/web-sandbox/web-sandbox.tsx#L267-L276) + - [html-iframe-event-listener.js:1-6](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L6) + - [react-iframe-template.html:17-22](file://frontend/pro/web-sandbox/react-iframe-template.html#L17-L22) + +- custom（自定义事件） + - 触发时机：宿主将 dispatch 函数注入到 iframe 的 window 上，iframe 内可通过 window.dispatch(...args) 主动向宿主派发自定义事件；宿主收到消息后调用 onCustom 回调。 + - 回调参数：...args（任意参数序列） + - 使用方式：在 WebSandbox 上注册 onCustom 回调，用于接收 iframe 内自定义业务事件（如点击、状态变更等）。 + - 参考路径 + - [web-sandbox.tsx:249-256](file://frontend/pro/web-sandbox/web-sandbox.tsx#L249-L256) + - [web-sandbox.tsx:299-306](file://frontend/pro/web-sandbox/web-sandbox.tsx#L299-L306) + +章节来源 + +- [web-sandbox.tsx:262-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L297) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [react-iframe-template.html:17-28](file://frontend/pro/web-sandbox/react-iframe-template.html#L17-L28) +- [README.md:48-56](file://docs/components/pro/web_sandbox/README.md#L48-L56) + +### 事件监听与处理流程 + +```mermaid +flowchart TD +Start(["开始"]) --> Parse["解析文件/构建依赖图/转换代码"] +Parse --> BuildIframe["生成iframe内容(React模板或HTML)"] +BuildIframe --> Ready["iframe DOMContentLoaded"] +Ready --> PostReady["postMessage({type:'sandbox-ready'})"] +PostReady --> OnSuccess["调用 onCompileSuccess()"] +BuildIframe --> Error["iframe 发生运行时错误"] +Error --> PostErr["postMessage({type:'sandbox-error', message})"] +PostErr --> OnRenderError["调用 onRenderError(message)"] +BuildIframe --> Custom["iframe 调用 window.dispatch(...)"] +Custom --> OnCustom["调用 onCustom(...args)"] +OnSuccess --> End(["结束"]) +OnRenderError --> End +OnCustom --> End +``` + +图表来源 + +- [web-sandbox.tsx:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- [react-iframe-template.html:24-28](file://frontend/pro/web-sandbox/react-iframe-template.html#L24-L28) +- [html-iframe-event-listener.js:1-6](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L6) + +### 事件与沙盒安全机制的关系 + +- 同源策略与 postMessage：iframe 与宿主通过 postMessage 通信，避免直接跨域访问，降低 XSS 风险。 +- 仅暴露必要接口：宿主将 dispatch 注入 iframe 的 window，iframe 可主动上报事件，但无法直接访问宿主 DOM 或全局对象。 +- 错误隔离：iframe 内部错误通过 window.onerror 捕获并上报，不破坏宿主运行环境。 +- 主题注入：宿主通过 postMessage 注入主题模式，iframe 仅能读取该只读信息，无法篡改宿主上下文。 +- 参考路径 + - [web-sandbox.tsx:249-261](file://frontend/pro/web-sandbox/web-sandbox.tsx#L249-L261) + - [html-iframe-event-listener.js:1-6](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L6) + - [react-iframe-template.html:17-22](file://frontend/pro/web-sandbox/react-iframe-template.html#L17-L22) + +章节来源 + +- [web-sandbox.tsx:249-261](file://frontend/pro/web-sandbox/web-sandbox.tsx#L249-L261) +- [html-iframe-event-listener.js:1-6](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L6) +- [react-iframe-template.html:17-22](file://frontend/pro/web-sandbox/react-iframe-template.html#L17-L22) + +### 事件监听与处理的完整示例（参考路径） + +- React 模板示例（HTML/JSX/TSX 入口文件） + - [react-iframe-template.html:30-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L30-L40) +- 编译错误处理（onCompileError） + - [web-sandbox.tsx:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218) +- 渲染错误处理（onRenderError） + - [web-sandbox.tsx:267-276](file://frontend/pro/web-sandbox/web-sandbox.tsx#L267-L276) +- 编译成功处理（onCompileSuccess） + - [web-sandbox.tsx:277-279](file://frontend/pro/web-sandbox/web-sandbox.tsx#L277-L279) +- 自定义事件处理（onCustom） + - [web-sandbox.tsx:249-256](file://frontend/pro/web-sandbox/web-sandbox.tsx#L249-L256) + +章节来源 + +- [react-iframe-template.html:30-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L30-L40) +- [web-sandbox.tsx:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218) +- [web-sandbox.tsx:267-276](file://frontend/pro/web-sandbox/web-sandbox.tsx#L267-L276) +- [web-sandbox.tsx:277-279](file://frontend/pro/web-sandbox/web-sandbox.tsx#L277-L279) +- [web-sandbox.tsx:249-256](file://frontend/pro/web-sandbox/web-sandbox.tsx#L249-L256) + +## 依赖分析 + +- 组件与模板/脚本的耦合 + - WebSandbox 通过 react-iframe-template.html 注入 importmap、样式与入口模块；通过 html-iframe-event-listener.js 统一转发错误与就绪事件。 +- 解析器与工具函数 + - parser.ts 负责依赖分析、转换与资源生成；utils.ts 提供路径规范化、入口文件选择等辅助能力。 +- 事件来源与去向 + - 事件来源：iframe 内部 window.onerror、DOMContentLoaded；iframe 内部 dispatch 调用 + - 事件去向：宿主 window message 监听器分发到 onCompileSuccess/onCompileError/onRenderError/onCustom + +```mermaid +graph LR +WS["WebSandbox
web-sandbox.tsx"] --> RT["React 模板
react-iframe-template.html"] +WS --> EL["事件监听脚本
html-iframe-event-listener.js"] +WS --> PR["解析器
parser.ts"] +PR --> UT["工具函数
utils.ts"] +EL --> WS +RT --> WS +``` + +图表来源 + +- [web-sandbox.tsx:1-20](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L20) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) + +章节来源 + +- [web-sandbox.tsx:1-20](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L20) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) + +## 性能考虑 + +- 资源释放：解析器生成的 Blob URL 在清理函数中统一回收，避免内存泄漏。 + - 参考路径：[parser.ts:306-311](file://frontend/pro/web-sandbox/parser.ts#L306-L311) +- 加载态控制：编译成功后及时关闭加载态，提升用户体验。 + - 参考路径：[web-sandbox.tsx:277-279](file://frontend/pro/web-sandbox/web-sandbox.tsx#L277-L279) +- 事件监听去重：组件在 iframeUrl 更新时重新绑定 window message 监听，确保不会重复绑定导致性能问题。 + - 参考路径：[web-sandbox.tsx:284-288](file://frontend/pro/web-sandbox/web-sandbox.tsx#L284-L288) + +## 故障排除指南 + +- 编译错误（compile_error） + - 现象：组件显示错误区域或触发 onCompileError 回调 + - 排查要点： + - 检查入口文件是否正确（template 为 react 时默认入口为 index.\*，html 时为 index.html） + - 参考路径：[utils.ts:48-75](file://frontend/pro/web-sandbox/utils.ts#L48-L75) + - 检查第三方依赖映射（imports）是否正确 + - 参考路径：[web-sandbox.tsx:79-92](file://frontend/pro/web-sandbox/web-sandbox.tsx#L79-L92) + - 查看解析器抛出的错误堆栈（循环依赖、语法错误等） + - 参考路径：[parser.ts:166-170](file://frontend/pro/web-sandbox/parser.ts#L166-L170), [parser.ts:292-298](file://frontend/pro/web-sandbox/parser.ts#L292-L298) +- 渲染错误（render_error） + - 现象：iframe 内部运行时报错，触发 onRenderError 回调 + - 排查要点： + - 确认模板中入口模块导出是否为函数（React 组件） + - 参考路径：[react-iframe-template.html:35-39](file://frontend/pro/web-sandbox/react-iframe-template.html#L35-L39) + - 检查样式与 importmap 是否正确注入 + - 参考路径：[react-iframe-template.html:7-12](file://frontend/pro/web-sandbox/react-iframe-template.html#L7-L12) +- 自定义事件（custom） + - 现象：iframe 内通过 window.dispatch(...) 主动上报事件，宿主触发 onCustom 回调 + - 排查要点： + - 确认宿主已将 dispatch 注入 iframe 的 window + - 参考路径：[web-sandbox.tsx:249-256](file://frontend/pro/web-sandbox/web-sandbox.tsx#L249-L256) +- 事件未触发 + - 现象：编译成功或渲染错误事件未回调 + - 排查要点： + - 确认 iframe 内部是否正确注入事件监听脚本 + - 参考路径：[react-iframe-template.html:17-28](file://frontend/pro/web-sandbox/react-iframe-template.html#L17-L28), [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + - 确认宿主 window message 监听是否正常绑定与解绑 + - 参考路径：[web-sandbox.tsx:284-288](file://frontend/pro/web-sandbox/web-sandbox.tsx#L284-L288) + +章节来源 + +- [utils.ts:48-75](file://frontend/pro/web-sandbox/utils.ts#L48-L75) +- [parser.ts:166-170](file://frontend/pro/web-sandbox/parser.ts#L166-L170) +- [parser.ts:292-298](file://frontend/pro/web-sandbox/parser.ts#L292-L298) +- [react-iframe-template.html:35-39](file://frontend/pro/web-sandbox/react-iframe-template.html#L35-L39) +- [react-iframe-template.html:7-12](file://frontend/pro/web-sandbox/react-iframe-template.html#L7-L12) +- [web-sandbox.tsx:249-256](file://frontend/pro/web-sandbox/web-sandbox.tsx#L249-L256) +- [web-sandbox.tsx:284-288](file://frontend/pro/web-sandbox/web-sandbox.tsx#L284-L288) + +## 结论 + +WebSandbox 通过标准化的事件模型（compile_success、compile_error、render_error、custom）与 iframe 安全边界，为前端代码预览提供了可控、可观测且易扩展的能力。合理利用事件回调与错误处理机制，可在保证安全的前提下实现丰富的交互与调试体验。 diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\344\275\277\347\224\250\347\244\272\344\276\213.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\344\275\277\347\224\250\347\244\272\344\276\213.md" new file mode 100644 index 00000000..d70c932c --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\344\275\277\347\224\250\347\244\272\344\276\213.md" @@ -0,0 +1,309 @@ +# 使用示例 + + +**本文引用的文件** +- [web-sandbox.tsx](file://frontend/pro/web-sandbox/web-sandbox.tsx) +- [Index.svelte](file://frontend/pro/web-sandbox/Index.svelte) +- [parser.ts](file://frontend/pro/web-sandbox/parser.ts) +- [utils.ts](file://frontend/pro/web-sandbox/utils.ts) +- [react-iframe-template.html](file://frontend/pro/web-sandbox/react-iframe-template.html) +- [README-zh_CN.md](file://docs/components/pro/web_sandbox/README-zh_CN.md) +- [__init__.py](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向开发者，系统化地介绍 WebSandbox 组件的使用方式与最佳实践，涵盖： + +- HTML 渲染示例与注意事项 +- React 组件渲染示例与模板类型选择 +- 错误处理与事件通信 +- 动态内容渲染、事件通信、样式定制等复杂场景 +- 从简单到复杂的渐进式示例路径 +- 完整可运行的示例说明（以“代码片段路径”形式给出） + +目标是帮助你在不直接阅读源码的前提下，快速上手并正确使用该组件。 + +## 项目结构 + +WebSandbox 由三部分组成： + +- 前端 Svelte 包装层：负责属性透传、插槽渲染与主题注入 +- 核心 React 组件：负责文件解析、依赖图构建、编译与 iframe 渲染 +- 解析器与工具：负责文件规范化、依赖分析、转换与资源清理 + +```mermaid +graph TB +A["Index.svelte
属性透传/插槽/主题"] --> B["web-sandbox.tsx
核心逻辑/编译/消息监听"] +B --> C["parser.ts
依赖图/拓扑排序/转换"] +B --> D["utils.ts
入口定位/路径规范化/模板渲染"] +B --> E["react-iframe-template.html
iframe 模板"] +``` + +图表来源 + +- [Index.svelte:1-75](file://frontend/pro/web-sandbox/Index.svelte#L1-L75) +- [web-sandbox.tsx:37-363](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L363) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:28-83](file://frontend/pro/web-sandbox/utils.ts#L28-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) + +章节来源 + +- [Index.svelte:1-75](file://frontend/pro/web-sandbox/Index.svelte#L1-L75) +- [web-sandbox.tsx:37-363](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L363) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:28-83](file://frontend/pro/web-sandbox/utils.ts#L28-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) + +## 核心组件 + +- 组件名称：WebSandbox +- 支持模板类型：react、html +- 关键能力： + - 将一组前端文件（JS/TS/JSX/TSX/HTML/CSS）作为输入，生成可运行的 iframe 内容 + - 自动注入 importmap，支持第三方依赖与样式资源 + - 提供编译/渲染事件回调与错误展示 + - 支持自定义错误渲染插槽与函数 + - 主题模式透传与事件通信桥接 + +章节来源 + +- [web-sandbox.tsx:21-35](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L35) +- [README-zh_CN.md:34-70](file://docs/components/pro/web_sandbox/README-zh_CN.md#L34-L70) + +## 架构总览 + +WebSandbox 的工作流分为“文件解析与编译”和“iframe 渲染与事件通信”两大阶段。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Wrap as "Index.svelte" +participant Core as "web-sandbox.tsx" +participant Parser as "parser.ts" +participant Utils as "utils.ts" +participant Iframe as "react-iframe-template.html" +Dev->>Wrap : 传入 props/value/template/imports +Wrap->>Core : 透传属性/插槽/主题 +Core->>Utils : 获取入口文件/规范化路径 +Core->>Parser : 解析文件/构建依赖图/拓扑排序 +Parser-->>Core : 返回 entryUrl/styleSheetUrls/cleanup +Core->>Iframe : 渲染 iframe 模板(含 importmap/样式/入口) +Core-->>Dev : 触发 compile_success/compile_error +Iframe-->>Core : sandbox-ready/sandbox-error +Core-->>Dev : 触发 render_error/custom +``` + +图表来源 + +- [Index.svelte:12-75](file://frontend/pro/web-sandbox/Index.svelte#L12-L75) +- [web-sandbox.tsx:94-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L94-L218) +- [parser.ts:285-312](file://frontend/pro/web-sandbox/parser.ts#L285-L312) +- [utils.ts:48-75](file://frontend/pro/web-sandbox/utils.ts#L48-L75) +- [react-iframe-template.html:7-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L7-L40) + +## 详细组件分析 + +### HTML 渲染示例 + +- 适用场景：直接渲染 HTML 页面，支持内联脚本与样式表 +- 关键点： + - template 必须为 html + - 入口文件默认为 index.html；也可通过 is_entry 手动指定 + - 内联脚本会被抽取并参与编译，同时保留原结构 + - 自动注入 importmap 与样式链接 +- 示例路径 + - [HTML 示例占位符:22-24](file://docs/components/pro/web_sandbox/README-zh_CN.md#L22-L24) + +章节来源 + +- [web-sandbox.tsx:110-186](file://frontend/pro/web-sandbox/web-sandbox.tsx#L110-L186) +- [utils.ts:48-75](file://frontend/pro/web-sandbox/utils.ts#L48-L75) +- [README-zh_CN.md:22-24](file://docs/components/pro/web_sandbox/README-zh_CN.md#L22-L24) + +### React 组件渲染示例 + +- 适用场景：渲染单文件 React 组件（函数组件或类组件） +- 关键点： + - template 默认为 react；会自动注入 react 与 react-dom 的 importmap + - 入口文件默认为 index.(ts|tsx|js|jsx) + - 支持 TS/TSX 与 JSX；自动启用 React 自动运行时 + - CSS 导入会被提取为独立样式资源 +- 示例路径 + - [React 示例占位符:7-18](file://docs/components/pro/web_sandbox/README-zh_CN.md#L7-L18) + +章节来源 + +- [web-sandbox.tsx:187-202](file://frontend/pro/web-sandbox/web-sandbox.tsx#L187-L202) +- [parser.ts:176-283](file://frontend/pro/web-sandbox/parser.ts#L176-L283) +- [README-zh_CN.md:7-18](file://docs/components/pro/web_sandbox/README-zh_CN.md#L7-L18) + +### 错误处理示例 + +- 编译期错误：文件解析/转换异常、循环依赖、入口缺失 +- 运行期错误：iframe 中的 DOMContentLoaded 与全局 error 事件 +- 可选展示策略： + - 内置 Alert 错误提示 + - 自定义 compileErrorRender 插槽或函数 + - 通过事件回调 onCompileError/onRenderError/onCompileSuccess 获取状态 +- 示例路径 + - [错误处理示例占位符:30-32](file://docs/components/pro/web_sandbox/README-zh_CN.md#L30-L32) + +章节来源 + +- [web-sandbox.tsx:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218) +- [web-sandbox.tsx:317-342](file://frontend/pro/web-sandbox/web-sandbox.tsx#L317-L342) +- [README-zh_CN.md:30-32](file://docs/components/pro/web_sandbox/README-zh_CN.md#L30-L32) + +### 事件通信示例 + +- 组件向外部发送的消息： + - sandbox-ready：编译完成，iframe 已就绪 + - sandbox-error：运行期错误，携带 message +- 外部向组件内部派发的事件： + - 通过 window.dispatch 或自定义事件桥接（由业务方在 iframe 内触发） +- 示例路径 + - [事件通信示例占位符:26-28](file://docs/components/pro/web_sandbox/README-zh_CN.md#L26-L28) + +章节来源 + +- [web-sandbox.tsx:262-282](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L282) +- [react-iframe-template.html:17-28](file://frontend/pro/web-sandbox/react-iframe-template.html#L17-L28) +- [README-zh_CN.md:48-55](file://docs/components/pro/web_sandbox/README-zh_CN.md#L48-L55) + +### 样式定制与导入 + +- 第三方 CSS：通过 importmap 映射或 http(s) 地址直接引入 +- 本地 CSS：被提取为独立 Blob URL 并注入到 iframe +- 自定义样式：可在 HTML 模板中注入额外 link 或在 React 模板中通过样式资源列表注入 +- 示例路径 + - [样式定制示例占位符:45-46](file://docs/components/pro/web_sandbox/README-zh_CN.md#L45-L46) + +章节来源 + +- [parser.ts:258-276](file://frontend/pro/web-sandbox/parser.ts#L258-L276) +- [web-sandbox.tsx:221-242](file://frontend/pro/web-sandbox/web-sandbox.tsx#L221-L242) + +### 复杂场景：动态内容渲染与事件桥接 + +- 动态内容：通过 value 动态更新文件集合，组件会重新解析并重建 iframe +- 事件桥接：在 iframe 内通过 window.dispatch 发送自定义事件，父组件 onCustom 接收 +- 主题同步：组件会向 iframe 注入 themeMode，并通过 postMessage 同步主题 +- 示例路径 + - [动态内容与事件桥接示例占位符:26-28](file://docs/components/pro/web_sandbox/README-zh_CN.md#L26-L28) + +章节来源 + +- [web-sandbox.tsx:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- [Index.svelte:60-75](file://frontend/pro/web-sandbox/Index.svelte#L60-L75) + +### 最佳实践 + +- 明确入口文件：优先使用默认入口；若需自定义，使用 is_entry 标记 +- 控制依赖体积：合理拆分模块，避免重复引入大体积库 +- 错误可见性：生产环境建议开启 showCompileError/showRenderError 并自定义错误渲染 +- 主题一致性：统一 themeMode，确保与宿主应用一致 +- 性能优化：对大型 CSS/JS 进行按需加载与缓存 + +章节来源 + +- [utils.ts:48-75](file://frontend/pro/web-sandbox/utils.ts#L48-L75) +- [web-sandbox.tsx:317-342](file://frontend/pro/web-sandbox/web-sandbox.tsx#L317-L342) + +## 依赖关系分析 + +WebSandbox 的关键依赖链如下： + +```mermaid +graph LR +WS["web-sandbox.tsx"] --> P["parser.ts"] +WS --> U["utils.ts"] +WS --> T["react-iframe-template.html"] +IDX["Index.svelte"] --> WS +BACK["backend/__init__.py"] --> IDX +``` + +图表来源 + +- [web-sandbox.tsx:1-19](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L19) +- [parser.ts:1-12](file://frontend/pro/web-sandbox/parser.ts#L1-L12) +- [utils.ts:1-1](file://frontend/pro/web-sandbox/utils.ts#L1-L1) +- [react-iframe-template.html:1-10](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L10) +- [Index.svelte:1-12](file://frontend/pro/web-sandbox/Index.svelte#L1-L12) +- [**init**.py:69-85](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L69-L85) + +章节来源 + +- [web-sandbox.tsx:1-19](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L19) +- [parser.ts:1-12](file://frontend/pro/web-sandbox/parser.ts#L1-L12) +- [utils.ts:1-1](file://frontend/pro/web-sandbox/utils.ts#L1-L1) +- [react-iframe-template.html:1-10](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L10) +- [Index.svelte:1-12](file://frontend/pro/web-sandbox/Index.svelte#L1-L12) +- [**init**.py:69-85](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L69-L85) + +## 性能考量 + +- 文件解析与转换：采用拓扑排序保证依赖顺序，避免重复转换 +- Blob URL 管理：转换后的 JS/CSS 统一以 Blob URL 形式注入，便于清理 +- iframe 生命周期：组件卸载时主动 revokeObjectURL，防止内存泄漏 +- 样式注入：CSS 资源按需注入，减少无关样式加载 +- 主题同步：通过 postMessage 一次性注入，避免频繁重绘 + +章节来源 + +- [parser.ts:129-174](file://frontend/pro/web-sandbox/parser.ts#L129-L174) +- [parser.ts:306-312](file://frontend/pro/web-sandbox/parser.ts#L306-L312) +- [web-sandbox.tsx:299-306](file://frontend/pro/web-sandbox/web-sandbox.tsx#L299-L306) + +## 故障排查指南 + +- 编译失败 + - 症状：显示内置错误提示或触发 onCompileError + - 排查要点：检查入口文件是否存在、依赖是否在 importmap 中、是否存在循环依赖 + - 参考路径：[编译错误处理:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218) +- 运行失败 + - 症状：触发 onRenderError，iframe 中弹出通知 + - 排查要点：查看 iframe 控制台错误、确认入口导出是否为合法组件 + - 参考路径：[运行期错误监听:262-282](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L282) +- 事件未收到 + - 症状：onCustom 未触发 + - 排查要点：确认 iframe 内是否调用了 dispatch，且主题同步已生效 + - 参考路径：[主题注入与事件派发:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- 样式未生效 + - 症状：CSS 未加载或样式冲突 + - 排查要点：检查 importmap 映射、相对 CSS 是否被正确提取为 Blob URL + - 参考路径：[样式提取与注入:258-276](file://frontend/pro/web-sandbox/parser.ts#L258-L276) + +章节来源 + +- [web-sandbox.tsx:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218) +- [web-sandbox.tsx:262-282](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L282) +- [web-sandbox.tsx:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- [parser.ts:258-276](file://frontend/pro/web-sandbox/parser.ts#L258-L276) + +## 结论 + +WebSandbox 提供了在安全沙箱中渲染 React 与 HTML 的完整能力。通过清晰的文件输入、自动化的依赖解析与转换、以及完善的事件与错误处理机制，开发者可以快速搭建动态预览与交互演示场景。建议结合本文示例路径与最佳实践，逐步扩展到更复杂的动态渲染与事件通信需求。 + +## 附录 + +- 组件 API 与事件参考 + - [API 与事件说明:34-55](file://docs/components/pro/web_sandbox/README-zh_CN.md#L34-L55) +- 后端包装与前端目录映射 + - [后端组件包装:69-85](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L69-L85) +- Svelte 包装层与属性透传 + - [Svelte 包装层:12-75](file://frontend/pro/web-sandbox/Index.svelte#L12-L75) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\345\256\211\345\205\250\346\234\272\345\210\266.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\345\256\211\345\205\250\346\234\272\345\210\266.md" new file mode 100644 index 00000000..e34c10bc --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\345\256\211\345\205\250\346\234\272\345\210\266.md" @@ -0,0 +1,294 @@ +# 安全机制 + + +**本文引用的文件** +- [web-sandbox.tsx](file://frontend/pro/web-sandbox/web-sandbox.tsx) +- [parser.ts](file://frontend/pro/web-sandbox/parser.ts) +- [utils.ts](file://frontend/pro/web-sandbox/utils.ts) +- [html-iframe-event-listener.js](file://frontend/pro/web-sandbox/html-iframe-event-listener.js) +- [react-iframe-template.html](file://frontend/pro/web-sandbox/react-iframe-template.html) +- [walkHtmlNodes.ts](file://frontend/utils/walkHtmlNodes.ts) +- [web-sandbox.less](file://frontend/pro/web-sandbox/web-sandbox.less) +- [package.json](file://frontend/package.json) +- [README.md（WebSandbox 文档）](file://docs/components/pro/web_sandbox/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能与安全权衡](#性能与安全权衡) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：安全配置与最佳实践](#附录安全配置与最佳实践) + +## 简介 + +本文件聚焦于 WebSandbox 组件的安全机制，系统阐述其基于浏览器 iframe 的安全隔离原理、跨域与内容安全策略的落地方式、事件监听与消息传递的安全实现、以及针对恶意内容注入与 XSS 的防护要点。同时给出可操作的安全配置建议、审计清单与漏洞防护指南。 + +## 项目结构 + +WebSandbox 位于前端工程 pro 子目录中，核心由以下模块组成： + +- 组件入口与渲染控制：web-sandbox.tsx +- 沙箱解析与打包：parser.ts +- 工具与模板：utils.ts、react-iframe-template.html、web-sandbox.less +- iframe 内部事件监听：html-iframe-event-listener.js +- HTML 模板内脚本处理辅助：walkHtmlNodes.ts +- 依赖声明：package.json +- 组件文档：docs/components/pro/web_sandbox/README.md + +```mermaid +graph TB +A["web-sandbox.tsx
组件入口与渲染控制"] --> B["parser.ts
依赖图构建与转换"] +A --> C["utils.ts
路径/模板/入口解析"] +A --> D["react-iframe-template.html
iframe 模板"] +A --> E["html-iframe-event-listener.js
iframe 内错误与就绪事件"] +A --> F["web-sandbox.less
样式与 iframe 边距"] +A --> G["walkHtmlNodes.ts
HTML 节点遍历用于提取脚本"] +B --> H["@babel/standalone
代码转换与 importmap 处理"] +C --> I["path-browserify-esm
路径规范化"] +``` + +图表来源 + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [walkHtmlNodes.ts:1-19](file://frontend/utils/walkHtmlNodes.ts#L1-L19) +- [package.json:1-59](file://frontend/package.json#L1-L59) + +章节来源 + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [walkHtmlNodes.ts:1-19](file://frontend/utils/walkHtmlNodes.ts#L1-L19) +- [package.json:1-59](file://frontend/package.json#L1-L59) +- [README.md（WebSandbox 文档）:1-70](file://docs/components/pro/web_sandbox/README.md#L1-L70) + +## 核心组件 + +- WebSandbox 主组件：负责接收源代码文件集合、构建 importmap、选择模板类型、生成 iframe 内容、处理编译/渲染错误、通过 postMessage 与 iframe 通信。 +- WebSandboxParser：对输入文件进行依赖图构建、拓扑排序、Babel 转换、CSS 处理与 Blob URL 生成，输出入口 URL 与样式表列表，并提供清理函数回收内存。 +- 工具集：路径规范化、默认入口文件识别、模板渲染、HTML 节点遍历等。 +- iframe 模板与事件监听：模板内注入 importmap 与样式；iframe 内部监听错误与就绪事件并通过 postMessage 上报。 + +章节来源 + +- [web-sandbox.tsx:21-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L365) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:3-83](file://frontend/pro/web-sandbox/utils.ts#L3-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## 架构总览 + +WebSandbox 的安全隔离以浏览器 iframe 为基础，结合 importmap、Babel 转换、Blob URL 与 postMessage 事件通道实现“最小权限”的运行环境。 + +```mermaid +sequenceDiagram +participant U as "调用方" +participant WS as "WebSandbox 组件" +participant P as "WebSandboxParser" +participant IF as "iframe 内容" +participant PM as "postMessage 通道" +U->>WS : 传入 files 与 imports +WS->>P : 解析并构建依赖图/拓扑排序/转换 +P-->>WS : 返回入口 URL 与样式表列表 +WS->>WS : 生成 iframe HTMLimportmap/样式 +WS->>IF : 设置 src 为 Blob URL +IF->>PM : DOMContentLoaded -> sandbox-ready +WS->>PM : 监听 sandbox-ready +IF->>PM : error -> sandbox-error +WS->>U : 触发 compile_success/render_error 事件 +``` + +图表来源 + +- [web-sandbox.tsx:94-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L94-L218) +- [parser.ts:285-312](file://frontend/pro/web-sandbox/parser.ts#L285-L312) +- [react-iframe-template.html:16-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L16-L40) +- [html-iframe-event-listener.js:1-12](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L12) + +## 详细组件分析 + +### 安全隔离原理与实现 + +- 浏览器级隔离：iframe 默认与父页面处于不同源上下文，具备独立的执行环境与 DOM，天然阻断脚本直接访问父页面全局对象。 +- 权限最小化：仅注入必要的 importmap 与样式，不授予额外权限或能力。 +- 进程边界：iframe 中的 React/JS 代码在独立线程中执行，避免与宿主主线程共享状态。 + +章节来源 + +- [web-sandbox.tsx:350-356](file://frontend/pro/web-sandbox/web-sandbox.tsx#L350-L356) +- [react-iframe-template.html:7-12](file://frontend/pro/web-sandbox/react-iframe-template.html#L7-L12) + +### iframe 安全策略与跨域限制 + +- 同源策略：iframe 与父页面同源时可直接访问；非同源时需通过 postMessage 通信，WebSandbox 已严格限定消息来源与类型，仅接受来自 iframe 的特定消息。 +- CSP：组件未显式设置 CSP 头，但通过 Blob URL 与 importmap 降低外链风险；如需更强保障，可在服务端或网关层设置 CSP 头。 +- 跨站脚本：iframe 内脚本无法直接访问父页面 DOM，除非父页面显式将 iframe 的 contentWindow 暴露给子页面（WebSandbox 仅传递主题与自定义分发函数，且未暴露敏感接口）。 + +章节来源 + +- [web-sandbox.tsx:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- [html-iframe-event-listener.js:1-12](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L12) +- [react-iframe-template.html:16-29](file://frontend/pro/web-sandbox/react-iframe-template.html#L16-L29) + +### 内容安全策略（CSP）与资源加载 + +- importmap：在 iframe 内注入 importmap，限定第三方依赖来源，避免加载不受控脚本。 +- 样式与 CSS：相对 CSS 通过 Blob URL 注入，外部 CSS 仅允许 http(s) 或已映射到 importmap 的地址。 +- 恶意脚本过滤：HTML 模板模式下，组件会扫描并替换内联脚本为转换后的 Blob URL，避免直接执行不可信脚本。 + +章节来源 + +- [react-iframe-template.html:7-12](file://frontend/pro/web-sandbox/react-iframe-template.html#L7-L12) +- [parser.ts:258-276](file://frontend/pro/web-sandbox/parser.ts#L258-L276) +- [web-sandbox.tsx:110-179](file://frontend/pro/web-sandbox/web-sandbox.tsx#L110-L179) + +### 事件监听器与消息传递机制 + +- iframe 就绪与错误上报：iframe 内部监听 DOMContentLoaded 与 error 事件，通过 postMessage 发送 sandbox-ready 与 sandbox-error。 +- 父页面监听：父页面仅接受来自 iframe 的消息，根据 type 分发到对应回调（渲染错误/编译成功），并对主题与自定义分发函数进行安全传递。 +- 事件来源校验：消息来源严格限定为 iframe.contentWindow，避免伪造消息。 + +```mermaid +sequenceDiagram +participant Parent as "父页面" +participant Child as "iframe" +Parent->>Child : 设置 src 为 Blob URL +Child-->>Parent : postMessage(type="sandbox-ready") +Child-->>Parent : postMessage(type="sandbox-error", message) +Parent->>Parent : 校验 e.source === iframe.contentWindow +Parent->>Parent : switch(type){case "sandbox-ready" : ...} +``` + +图表来源 + +- [web-sandbox.tsx:262-282](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L282) +- [html-iframe-event-listener.js:1-12](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L12) +- [react-iframe-template.html:16-29](file://frontend/pro/web-sandbox/react-iframe-template.html#L16-L29) + +### 恶意内容注入与 XSS 防护 + +- 输入规范化：路径与入口文件均经过规范化处理，避免路径穿越与歧义。 +- 代码转换：使用 Babel 对 JS/TSX/JSX 进行转换，替换相对导入为 Blob URL，移除或转换 CSS 导入，减少直接执行不可信脚本的机会。 +- HTML 模板模式：扫描并替换内联脚本，将其转换为 Blob URL 并注入到 DOM，避免直接执行用户输入的脚本。 +- 错误隔离：iframe 内部错误通过 postMessage 上报，父页面仅展示描述性信息，不回显原始堆栈或源码。 + +章节来源 + +- [utils.ts:28-34](file://frontend/pro/web-sandbox/utils.ts#L28-L34) +- [parser.ts:176-283](file://frontend/pro/web-sandbox/parser.ts#L176-L283) +- [web-sandbox.tsx:110-179](file://frontend/pro/web-sandbox/web-sandbox.tsx#L110-L179) +- [html-iframe-event-listener.js:1-12](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L12) + +### 依赖与安全相关的第三方库 + +- @babel/standalone：用于在浏览器端进行代码转换与导入路径替换，是安全转换的关键。 +- path-browserify-esm：用于路径规范化，避免路径注入。 +- antd：提供通知与加载提示，用于错误展示与用户体验。 + +章节来源 + +- [package.json:8-39](file://frontend/package.json#L8-L39) +- [parser.ts:1-12](file://frontend/pro/web-sandbox/parser.ts#L1-L12) +- [utils.ts:1-8](file://frontend/pro/web-sandbox/utils.ts#L1-L8) + +## 依赖关系分析 + +WebSandbox 的安全实现依赖于多模块协作：组件层负责控制与消息桥接，解析层负责依赖与代码转换，工具层负责路径与模板处理，iframe 层负责事件上报与隔离。 + +```mermaid +graph LR +WS["web-sandbox.tsx"] --> PR["parser.ts"] +WS --> UT["utils.ts"] +WS --> RT["react-iframe-template.html"] +WS --> EL["html-iframe-event-listener.js"] +PR --> BL["@babel/standalone"] +UT --> PB["path-browserify-esm"] +WS --> AN["antd通知/加载"] +``` + +图表来源 + +- [web-sandbox.tsx:1-19](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L19) +- [parser.ts:1-12](file://frontend/pro/web-sandbox/parser.ts#L1-L12) +- [utils.ts:1-8](file://frontend/pro/web-sandbox/utils.ts#L1-L8) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [package.json:8-39](file://frontend/package.json#L8-L39) + +章节来源 + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [package.json:1-59](file://frontend/package.json#L1-L59) + +## 性能与安全权衡 + +- 转换成本：Babel 转换与 Blob URL 创建带来一定开销，建议在输入规模较大时启用缓存与增量更新策略。 +- 消息监听：仅监听来自 iframe 的消息，避免频繁事件导致的性能问题。 +- 样式与脚本：优先使用 Blob URL 注入相对 CSS，减少网络请求；对外部 CSS 严格白名单控制。 + +[本节为通用建议，无需列出章节来源] + +## 故障排查指南 + +- 编译失败：检查输入文件是否包含循环依赖、语法错误或缺失入口文件；组件会在解析阶段抛出错误并触发编译错误回调。 +- 渲染错误：iframe 内部错误通过 postMessage 上报，父页面会弹出错误通知或触发渲染错误回调；建议开启 showRenderError 查看具体信息。 +- 主题与自定义事件：确认父页面正确设置 themeMode 与 onCustom 回调；iframe 通过 postMessage 接收主题变更。 +- 样式异常：检查 importmap 与样式注入逻辑，确保样式 URL 正确且可访问。 + +章节来源 + +- [web-sandbox.tsx:203-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L218) +- [web-sandbox.tsx:267-281](file://frontend/pro/web-sandbox/web-sandbox.tsx#L267-L281) +- [parser.ts:128-174](file://frontend/pro/web-sandbox/parser.ts#L128-L174) + +## 结论 + +WebSandbox 通过浏览器 iframe 隔离、importmap 与 Babel 转换、Blob URL 注入、严格的 postMessage 事件通道，实现了对用户输入代码的最小权限运行与有效安全隔离。配合路径规范化与错误上报机制，能够在保证可用性的同时显著降低 XSS 与恶意脚本风险。 + +[本节为总结性内容，无需列出章节来源] + +## 附录：安全配置与最佳实践 + +### 安全配置建议 + +- 限制第三方依赖来源：通过 importmap 明确第三方库版本与域名，避免加载不受控脚本。 +- 强化 CSP：在服务端或网关层设置 Content-Security-Policy，限制脚本执行来源与内联脚本。 +- 最小权限原则：仅注入必要样式与脚本，避免向 iframe 暴露宿主敏感接口。 +- 资源白名单：对外部 CSS/JS 采用白名单策略，仅允许 https 或受信任域名。 + +### 最佳实践 + +- 输入校验：对用户输入的文件名与路径进行严格校验，避免路径穿越。 +- 错误信息脱敏：错误展示应避免泄露内部路径与源码细节。 +- 增量更新：对大型项目启用缓存与增量转换，提升性能与安全性。 +- 审计日志：记录编译与运行时关键事件，便于追踪与审计。 + +### 漏洞防护指南 + +- XSS 防护：避免 innerHTML 直接拼接用户输入；使用 Blob URL 替换内联脚本。 +- 循环依赖检测：解析阶段即发现并阻止循环依赖，防止异常行为。 +- 跨站消息：严格校验 postMessage 的来源与类型，拒绝未知来源的消息。 + +章节来源 + +- [README.md（WebSandbox 文档）:34-70](file://docs/components/pro/web_sandbox/README.md#L34-L70) +- [web-sandbox.tsx:110-179](file://frontend/pro/web-sandbox/web-sandbox.tsx#L110-L179) +- [parser.ts:128-174](file://frontend/pro/web-sandbox/parser.ts#L128-L174) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\347\273\204\344\273\266\346\246\202\350\247\210.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\347\273\204\344\273\266\346\246\202\350\247\210.md" new file mode 100644 index 00000000..7544f8f7 --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\347\273\204\344\273\266\346\246\202\350\247\210.md" @@ -0,0 +1,329 @@ +# 组件概览 + + +**本文引用的文件** +- [web-sandbox.tsx](file://frontend/pro/web-sandbox/web-sandbox.tsx) +- [parser.ts](file://frontend/pro/web-sandbox/parser.ts) +- [utils.ts](file://frontend/pro/web-sandbox/utils.ts) +- [react-iframe-template.html](file://frontend/pro/web-sandbox/react-iframe-template.html) +- [html-iframe-event-listener.js](file://frontend/pro/web-sandbox/html-iframe-event-listener.js) +- [README.md（WebSandbox 文档）](file://docs/components/pro/web_sandbox/README.md) +- [react.py（示例）](file://docs/components/pro/web_sandbox/demos/react.py) +- [html.py（示例）](file://docs/components/pro/web_sandbox/demos/html.py) +- [error_handling.py（示例）](file://docs/components/pro/web_sandbox/demos/error_handling.py) +- [custom_sandbox_event.py（示例）](file://docs/components/pro/web_sandbox/demos/custom_sandbox_event.py) +- [__init__.py（后端组件入口）](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py) +- [components.py（后端组件导出）](file://backend/modelscope_studio/components/pro/components.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录：快速开始与基本用法](#附录快速开始与基本用法) + +## 简介 + +WebSandbox 是一个用于在页面中编译与预览“React”或“HTML”代码的安全沙盒组件。它通过将用户提供的源文件进行解析、转换与打包，并在独立的 iframe 中运行，从而实现对第三方内容的安全渲染与隔离。该组件广泛适用于在线代码演示、教学示例展示、低信任度前端内容预览等场景。 + +## 项目结构 + +WebSandbox 组件由前后端两部分组成： + +- 前端（Svelte/React）负责解析与编译用户代码、生成 iframe 内容、处理错误与主题注入、以及与父页面通信。 +- 后端（Python）负责将组件暴露为 Gradio 的 Pro 组件，绑定事件与插槽，供 Python 端调用。 + +```mermaid +graph TB +subgraph "前端" +A["web-sandbox.tsx
组件主入口"] +B["parser.ts
文件解析与转换"] +C["utils.ts
工具函数"] +D["react-iframe-template.html
React 模板"] +E["html-iframe-event-listener.js
HTML 事件监听"] +end +subgraph "后端" +F["__init__.py
Pro 组件定义"] +G["components.py
组件导出"] +end +A --> B +A --> C +A --> D +A --> E +F --> G +F --> A +``` + +图表来源 + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [**init**.py（后端组件入口）:1-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L1-L86) +- [components.py（后端组件导出）:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +章节来源 + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) +- [**init**.py（后端组件入口）:1-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L1-L86) +- [components.py（后端组件导出）:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## 核心组件 + +- 组件名称：WebSandbox（Pro） +- 功能定位：在安全隔离的 iframe 中编译与渲染 React 或 HTML 代码，支持错误提示、主题注入、自定义事件透传。 +- 主要能力： + - 多模板支持：React 与 HTML 两种模板类型。 + - 自动依赖映射：基于 importmap 注入第三方依赖（如 React 生态）。 + - 编译与打包：对 JS/TS/JSX/TSX 进行转换与打包，内联相对 CSS，外链第三方 CSS。 + - 安全隔离：通过 Blob URL 与 iframe 实现资源与脚本隔离。 + - 错误处理：编译错误与渲染错误分别上报，可选择是否显示。 + - 主题与事件：向 iframe 注入主题信息；支持自定义事件从 iframe 透传到父页面。 + +章节来源 + +- [README.md（WebSandbox 文档）:1-70](file://docs/components/pro/web_sandbox/README.md#L1-L70) +- [web-sandbox.tsx:21-35](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L35) +- [parser.ts:176-283](file://frontend/pro/web-sandbox/parser.ts#L176-L283) +- [utils.ts:48-75](file://frontend/pro/web-sandbox/utils.ts#L48-L75) + +## 架构总览 + +WebSandbox 的整体流程包括：接收用户文件 → 解析与依赖分析 → 转换与打包 → 生成 iframe 内容 → 渲染与错误上报 → 主题注入与事件透传。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Front as "WebSandbox(前端)" +participant Parser as "WebSandboxParser" +participant Iframe as "iframe(子页面)" +participant Parent as "父页面" +Dev->>Front : 传入 value、template、imports 等参数 +Front->>Parser : 解析文件、构建依赖图、拓扑排序 +Parser-->>Front : 返回 entryUrl/styleSheetUrls/normalizedFiles +Front->>Front : 生成 iframe HTML(Blob URL) +Front->>Iframe : 加载 iframe +Iframe-->>Parent : postMessage("sandbox-ready") +Parent-->>Front : 触发 compile_success +Iframe-->>Parent : postMessage("sandbox-error", message) +Parent-->>Front : 触发 render_error +``` + +图表来源 + +- [web-sandbox.tsx:94-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L94-L218) +- [parser.ts:285-312](file://frontend/pro/web-sandbox/parser.ts#L285-L312) +- [react-iframe-template.html:24-28](file://frontend/pro/web-sandbox/react-iframe-template.html#L24-L28) +- [html-iframe-event-listener.js:8-12](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L8-L12) + +## 详细组件分析 + +### 组件类与接口（前端） + +WebSandbox 作为 Svelte 化的 React 组件，定义了属性、事件与插槽，并在内部维护加载状态、编译错误与解析结果。 + +```mermaid +classDiagram +class WebSandboxProps { ++value ++imports ++showRenderError ++showCompileError ++template ++onCompileError ++onCompileSuccess ++onRenderError ++onCustom ++height ++themeMode ++compileErrorRender ++children +} +class WebSandbox { ++iframeRef ++divRef ++loading ++compileError ++parsedValue ++resolvedImportMap ++useEffect(处理文件) ++useMemo(生成 iframeUrl) ++useEffect(消息监听) +} +WebSandbox --> WebSandboxProps : "使用" +``` + +图表来源 + +- [web-sandbox.tsx:21-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L365) + +章节来源 + +- [web-sandbox.tsx:21-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L365) + +### 解析器（Parser） + +WebSandboxParser 负责： + +- 归一化文件路径与内容 +- 构建依赖图（AST 分析 import） +- 拓扑排序检测循环依赖 +- 转换与打包（JS/TS/JSX/TSX），替换相对导入为 Blob URL，内联/外链 CSS +- 生成入口文件 URL 与样式表 URL 列表 + +```mermaid +flowchart TD +Start(["开始"]) --> Normalize["归一化文件路径与内容"] +Normalize --> BuildGraph["构建依赖图(AST)"] +BuildGraph --> Sort["拓扑排序"] +Sort --> Transform["逐文件转换与打包"] +Transform --> CSS["收集相对/外部CSS"] +CSS --> Output["输出: entryUrl/styleSheetUrls/cleanup"] +Output --> End(["结束"]) +``` + +图表来源 + +- [parser.ts:28-312](file://frontend/pro/web-sandbox/parser.ts#L28-L312) + +章节来源 + +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) + +### 工具函数（Utils） + +- 文件扩展名与默认入口文件集合 +- 路径标准化 +- 模板渲染 +- 入口文件选择逻辑 + +章节来源 + +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) + +### iframe 模板与事件监听 + +- React 模板：注入 importmap、样式表、入口模块，监听错误与 ready 事件并通过 postMessage 通知父页面。 +- HTML 事件监听：在 HTML 模式下注入事件监听脚本，行为与模板一致。 + +章节来源 + +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +### 后端组件（Python） + +- 将前端组件注册为 Pro 组件，支持事件绑定与插槽配置。 +- 提供类型化文件数据结构，便于 Python 端传参。 + +章节来源 + +- [**init**.py（后端组件入口）:1-86](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L1-L86) +- [components.py（后端组件导出）:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## 依赖关系分析 + +- 组件耦合点： + - WebSandbox 依赖 Parser 进行文件解析与打包。 + - WebSandbox 依赖 utils 提供的工具函数（路径、入口选择、模板渲染）。 + - iframe 模板与事件监听脚本通过 Blob URL 注入到 iframe。 +- 外部依赖： + - importmap 用于在线依赖映射（如 React 生态）。 + - Babel Standalone 用于代码转换与 AST 分析。 +- 可能的循环依赖： + - Parser 通过拓扑排序避免循环依赖；若存在循环依赖会抛出异常。 + +```mermaid +graph LR +WS["WebSandbox(前端)"] --> P["WebSandboxParser"] +WS --> U["utils"] +WS --> T["react-iframe-template.html"] +WS --> L["html-iframe-event-listener.js"] +P --> B["Babel Standalone"] +WS --> IM["importmap(第三方依赖)"] +``` + +图表来源 + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +章节来源 + +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [parser.ts:1-314](file://frontend/pro/web-sandbox/parser.ts#L1-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) + +## 性能考虑 + +- 转换与打包成本：对每个 JS/TS 文件执行转换与 AST 分析，建议控制文件数量与体积。 +- Blob URL 管理：打包完成后需及时释放 Blob URL，避免内存泄漏。 +- 样式表策略：相对 CSS 内联为 Blob URL，外部 CSS 直接外链，减少重复请求。 +- 主题注入与消息通信：仅在 iframeUrl 变化时注入主题，避免频繁操作。 + +## 故障排查指南 + +- 编译错误 + - 现象：组件显示编译错误或触发 compile_error 事件。 + - 排查：检查入口文件是否存在、模板类型是否匹配、第三方依赖是否正确映射。 +- 渲染错误 + - 现象：iframe 内发生运行时错误，触发 render_error 事件并弹窗提示（取决于 show_render_error）。 + - 排查：查看 iframe 控制台日志，确认依赖与入口模块正确性。 +- 循环依赖 + - 现象：解析阶段抛出循环依赖异常。 + - 排查：检查 import 关系，拆分模块或调整导入路径。 +- 主题不生效 + - 现象：iframe 内主题未更新。 + - 排查：确认 themeMode 参数传递与 postMessage 是否成功。 + +章节来源 + +- [web-sandbox.tsx:244-297](file://frontend/pro/web-sandbox/web-sandbox.tsx#L244-L297) +- [parser.ts:128-174](file://frontend/pro/web-sandbox/parser.ts#L128-L174) +- [README.md（WebSandbox 文档）:34-70](file://docs/components/pro/web_sandbox/README.md#L34-L70) + +## 结论 + +WebSandbox 通过“解析-转换-打包-iframe 隔离”的完整链路，实现了对第三方前端代码的安全渲染。其多模板支持、自动依赖映射、完善的错误处理与事件透传机制，使其非常适合在教学、演示与低信任度内容预览等场景中使用。 + +## 附录：快速开始与基本用法 + +- 使用场景 + - 在线 React 示例演示 + - HTML 页面即时预览 + - 自定义事件从 iframe 透传到 Python + - 编译/渲染错误的可视化提示 +- 快速开始步骤 + - 准备文件：以字典形式提供文件内容，指定入口文件（或使用默认入口）。 + - 选择模板：template 设置为 'react' 或 'html'。 + - 添加依赖：通过 imports 提供 importmap 映射（如 React 生态）。 + - 渲染组件：设置高度、主题模式与错误处理策略。 +- 基本示例参考 + - React 示例：[react.py:1-171](file://docs/components/pro/web_sandbox/demos/react.py#L1-L171) + - HTML 示例：[html.py:1-113](file://docs/components/pro/web_sandbox/demos/html.py#L1-L113) + - 错误处理示例：[error_handling.py:1-29](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L29) + - 自定义事件示例：[custom_sandbox_event.py:1-27](file://docs/components/pro/web_sandbox/demos/custom_sandbox_event.py#L1-L27) + +章节来源 + +- [README.md（WebSandbox 文档）:1-70](file://docs/components/pro/web_sandbox/README.md#L1-L70) +- [react.py（示例）:1-171](file://docs/components/pro/web_sandbox/demos/react.py#L1-L171) +- [html.py（示例）:1-113](file://docs/components/pro/web_sandbox/demos/html.py#L1-L113) +- [error_handling.py（示例）:1-29](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L29) +- [custom_sandbox_event.py（示例）:1-27](file://docs/components/pro/web_sandbox/demos/custom_sandbox_event.py#L1-L27) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\351\205\215\347\275\256\351\200\211\351\241\271.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\351\205\215\347\275\256\351\200\211\351\241\271.md" new file mode 100644 index 00000000..dd549d5c --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/WebSandbox \347\275\221\351\241\265\346\262\231\347\233\222/\351\205\215\347\275\256\351\200\211\351\241\271.md" @@ -0,0 +1,381 @@ +# 配置选项 + + +**本文引用的文件** +- [web_sandbox.tsx](file://frontend/pro/web-sandbox/web-sandbox.tsx) +- [parser.ts](file://frontend/pro/web-sandbox/parser.ts) +- [utils.ts](file://frontend/pro/web-sandbox/utils.ts) +- [react-iframe-template.html](file://frontend/pro/web-sandbox/react-iframe-template.html) +- [html-iframe-event-listener.js](file://frontend/pro/web-sandbox/html-iframe-event-listener.js) +- [__init__.py（后端组件）](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py) +- [README（英文）](file://docs/components/pro/web_sandbox/README.md) +- [README（中文）](file://docs/components/pro/web_sandbox/README-zh_CN.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向 WebSandbox 组件的使用者与维护者，系统化梳理其配置参数与行为，涵盖 template、show_render_error、show_compile_error、imports、height 等关键参数的作用、默认值、适用场景，并提供典型配置组合示例、最佳实践与常见问题的解决方案。目标是帮助读者快速理解并正确使用该组件。 + +## 项目结构 + +WebSandbox 由“后端组件定义 + 前端渲染实现 + 沙箱解析与打包工具”三部分组成： + +- 后端组件：负责接收 Python 层传入的参数，暴露事件与插槽，决定前端资源目录。 +- 前端组件：负责构建 importmap、解析文件、生成 Blob URL、注入到 iframe 并处理错误与事件。 +- 工具与模板：解析器负责依赖图构建、拓扑排序与代码转换；模板与事件监听脚本用于 iframe 生命周期与错误上报。 + +```mermaid +graph TB +Backend["后端组件
__init__.py后端组件"] --> Frontend["前端组件
web-sandbox.tsx"] +Frontend --> Parser["解析器
parser.ts"] +Frontend --> Utils["工具集
utils.ts"] +Frontend --> Template["React 模板
react-iframe-template.html"] +Frontend --> HtmlListener["HTML 事件监听脚本
html-iframe-event-listener.js"] +``` + +**图表来源** + +- [**init**.py（后端组件）:15-73](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L73) +- [web_sandbox.tsx:37-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L365) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +**章节来源** + +- [**init**.py（后端组件）:15-73](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L73) +- [web_sandbox.tsx:37-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L365) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) +- [react-iframe-template.html:1-43](file://frontend/pro/web-sandbox/react-iframe-template.html#L1-L43) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## 核心组件 + +- 后端组件类：定义了组件的构造参数、事件绑定与前端资源目录映射。 +- 前端组件：接收 props，构建 importmap，解析文件并生成 iframe 内容，处理编译与渲染错误，派发事件。 +- 解析器：对输入文件建立依赖图，拓扑排序后进行代码转换，生成 Blob URL 与样式表链接。 +- 工具集：提供默认入口文件列表、路径规范化、模板渲染、入口文件选择等辅助能力。 +- 模板与事件监听：为 React 模板注入 importmap 与样式，监听加载完成与错误事件并通过 postMessage 上报。 + +**章节来源** + +- [**init**.py（后端组件）:15-73](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L15-L73) +- [web_sandbox.tsx:37-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L365) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:20-83](file://frontend/pro/web-sandbox/utils.ts#L20-L83) +- [react-iframe-template.html:7-42](file://frontend/pro/web-sandbox/react-iframe-template.html#L7-L42) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## 架构总览 + +下图展示了从后端到前端再到 iframe 的整体流程：后端传参 → 前端构建 importmap 与解析文件 → 生成 iframe 内容 → 主窗口监听消息并处理错误与成功事件。 + +```mermaid +sequenceDiagram +participant Py as "Python 后端" +participant FE as "前端组件 web-sandbox.tsx" +participant PR as "解析器 parser.ts" +participant IF as "iframe" +participant TH as "主题/事件" +Py->>FE : 传入参数value/template/imports/... +FE->>PR : 解析文件并构建依赖图 +PR-->>FE : 返回入口 URL、样式表 URL、清理函数 +FE->>IF : 注入 importmap/样式/入口脚本 +IF->>TH : 加载完成后发送 sandbox-ready +FE-->>Py : 触发 compile_success 事件 +IF->>FE : 发送 sandbox-error渲染错误 +FE-->>Py : 触发 render_error 事件 +``` + +**图表来源** + +- [web_sandbox.tsx:79-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L79-L218) +- [parser.ts:285-312](file://frontend/pro/web-sandbox/parser.ts#L285-L312) +- [react-iframe-template.html:16-40](file://frontend/pro/web-sandbox/react-iframe-template.html#L16-L40) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +## 详细组件分析 + +### 参数总览与默认值 + +- template + - 类型：'react' | 'html' + - 默认值：'react' + - 作用：决定渲染模板类型，影响默认入口文件与自动注入的 React 依赖。 + - 使用场景：预览 React 或 HTML 代码。 +- show_render_error + - 类型：bool + - 默认值：True + - 作用：是否在渲染阶段出现错误时弹出通知并回调事件。 + - 使用场景：开发调试期希望显式看到运行时错误。 +- show_compile_error + - 类型：bool + - 默认值：True + - 作用：是否在编译失败时展示错误 UI（可替换为自定义插槽或函数）。 + - 使用场景：需要在 UI 中直接呈现编译错误信息。 +- compile_error_render + - 类型：str | None + - 默认值：None + - 作用：传入 JavaScript 函数字符串，用于自定义编译失败的渲染逻辑。 + - 使用场景：需要更精细的错误展示或与主题一致的样式。 +- imports + - 类型：Dict[str, str] | None + - 默认值：None + - 作用：对应 importmap 的 imports 字段，用于添加在线依赖。template='react' 时会自动注入 React 相关依赖。 + - 使用场景：引入第三方库、CDN 资源或覆盖默认 React 版本。 +- height + - 类型：str | float | int + - 默认值：400 + - 作用：组件高度；数字表示像素，字符串表示 CSS 单位。 + - 使用场景：适配不同布局与响应式需求。 + +**章节来源** + +- [README（英文）:38-46](file://docs/components/pro/web_sandbox/README.md#L38-L46) +- [README（中文）:38-46](file://docs/components/pro/web_sandbox/README-zh_CN.md#L38-L46) +- [web_sandbox.tsx:21-35](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L35) +- [**init**.py（后端组件）:37-67](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L37-L67) + +### 参数详解与行为 + +#### template + +- 影响点： + - 默认入口文件：template='react' 时默认入口为 index.tsx/index.jsx/index.ts/index.js；template='html' 时默认入口为 index.html。 + - 自动注入 React 依赖：当 template='react' 且 imports 未覆盖时，自动添加 react 与 react-dom 的 CDN 映射。 +- 典型用法： + - 预览 React 应用：template='react'，提供入口文件（如 index.tsx）。 + - 预览静态 HTML：template='html'，提供 index.html。 +- 注意事项： + - 若同时提供多个候选入口文件，可通过 is_entry 标记明确主入口。 + +**章节来源** + +- [utils.ts:20-26](file://frontend/pro/web-sandbox/utils.ts#L20-L26) +- [utils.ts:48-75](file://frontend/pro/web-sandbox/utils.ts#L48-L75) +- [web_sandbox.tsx:80-92](file://frontend/pro/web-sandbox/web-sandbox.tsx#L80-L92) + +#### show_render_error + +- 行为： + - 当 iframe 内发生渲染错误（捕获 window.error 或 HTML 事件监听），若开启则弹出通知并触发 render_error 事件。 +- 建议： + - 开发阶段建议保持 True，便于快速定位问题。 + - 生产环境可根据业务策略关闭，避免用户看到底层错误。 + +**章节来源** + +- [web_sandbox.tsx:262-281](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L281) +- [html-iframe-event-listener.js:1-13](file://frontend/pro/web-sandbox/html-iframe-event-listener.js#L1-L13) + +#### show_compile_error + +- 行为： + - 当编译失败（解析器抛错或入口缺失）时，若开启则展示错误 UI；否则不显示错误界面。 + - 可结合 compile_error_render 或插槽 compileErrorRender 自定义展示。 +- 建议： + - 前端错误较多时建议开启，以便用户直观感知问题。 + +**章节来源** + +- [web_sandbox.tsx:317-342](file://frontend/pro/web-sandbox/web-sandbox.tsx#L317-L342) +- [web_sandbox.tsx:203-217](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L217) + +#### compile_error_render + +- 行为： + - 传入 JavaScript 函数字符串，用于自定义编译失败的渲染。 + - 也可通过插槽 compileErrorRender 提供 React 节点。 +- 建议： + - 与主题一致的错误样式；或提供重试按钮、复制错误信息等交互。 + +**章节来源** + +- [web_sandbox.tsx:317-342](file://frontend/pro/web-sandbox/web-sandbox.tsx#L317-L342) +- [**init**.py（后端组件）:35-35](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L35-L35) + +#### imports + +- 行为： + - 作为 importmap.imports 使用，template='react' 时会先合并内置 React 映射，再叠加用户提供的 imports。 + - 支持覆盖默认 React 版本或添加其他依赖。 +- 建议： + - 优先使用稳定的 CDN；确保跨域可访问。 + - 如需本地依赖，可结合打包策略或 Blob URL 方案。 + +**章节来源** + +- [web_sandbox.tsx:80-92](file://frontend/pro/web-sandbox/web-sandbox.tsx#L80-L92) +- [README（英文）:45-45](file://docs/components/pro/web_sandbox/README.md#L45-L45) +- [README（中文）:45-45](file://docs/components/pro/web_sandbox/README-zh_CN.md#L45-L45) + +#### height + +- 行为： + - 数字：以像素为单位；字符串：按 CSS 单位解析。 +- 建议： + - 在容器布局中保持一致的单位风格；配合 CSS Grid/Flex 使用更灵活。 + +**章节来源** + +- [web_sandbox.tsx:312-315](file://frontend/pro/web-sandbox/web-sandbox.tsx#L312-L315) +- [README（英文）:46-46](file://docs/components/pro/web_sandbox/README.md#L46-L46) +- [README（中文）:46-46](file://docs/components/pro/web_sandbox/README-zh_CN.md#L46-L46) + +### 典型配置组合示例 + +- 预览 React 应用（默认） + - template='react'，imports 为空或仅覆盖 React 版本，value 提供入口文件。 +- 预览 HTML 页面 + - template='html'，value 提供 index.html，必要时在 HTML 中内联脚本。 +- 自定义错误展示 + - show_compile_error=True，compile_error_render 提供函数字符串或插槽 compileErrorRender。 +- 高度自适应 + - height='100%' 或具体数值 px，配合父容器布局。 + +**章节来源** + +- [README（英文）:7-18](file://docs/components/pro/web_sandbox/README.md#L7-L18) +- [README（中文）:7-18](file://docs/components/pro/web_sandbox/README-zh_CN.md#L7-L18) +- [web_sandbox.tsx:317-342](file://frontend/pro/web-sandbox/web-sandbox.tsx#L317-L342) + +## 依赖关系分析 + +- 前端组件依赖解析器与工具集，解析器内部使用 Babel Standalone 进行代码转换与依赖分析。 +- 模板与事件监听脚本注入到 iframe，负责生命周期与错误上报。 +- 后端组件定义事件与插槽，前端组件在运行时绑定并触发相应事件。 + +```mermaid +classDiagram +class WebSandboxProps { ++value ++imports ++showRenderError ++showCompileError ++template ++onCompileError ++onCompileSuccess ++onRenderError ++onCustom ++height ++themeMode ++compileErrorRender +} +class WebSandbox { ++useEffect() ++useMemo() ++useState() ++iframeRef ++divRef +} +class WebSandboxParser { ++_normalizeFiles() ++_buildDependencyGraph() ++_topologicalSort() ++_transform() ++parse() +} +class Utils { ++getEntryFile() ++getFileCode() ++renderHtmlTemplate() ++normalizePath() +} +WebSandbox --> WebSandboxParser : "调用" +WebSandbox --> Utils : "使用" +WebSandboxParser --> Utils : "使用" +``` + +**图表来源** + +- [web_sandbox.tsx:21-35](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L35) +- [web_sandbox.tsx:37-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L365) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) + +**章节来源** + +- [web_sandbox.tsx:37-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L365) +- [parser.ts:14-314](file://frontend/pro/web-sandbox/parser.ts#L14-L314) +- [utils.ts:1-83](file://frontend/pro/web-sandbox/utils.ts#L1-L83) + +## 性能考量 + +- 编译与转换 + - 解析器对每个 JS/CSS 文件执行转换与依赖分析，文件数量与体积直接影响编译时间。 + - 建议：减少不必要的依赖、拆分入口文件、避免循环依赖。 +- Blob URL 与内存 + - 转换后的代码与样式均生成 Blob URL，组件卸载时会统一回收；仍需关注大量文件时的内存占用。 +- iframe 渲染 + - React 模板注入 importmap 与入口模块，首次加载可能受网络与 CDN 影响。 +- 主题与事件 + - 主题切换通过 postMessage 传递，避免频繁重绘；错误弹窗仅在开启相关开关时出现。 + +[本节为通用性能建议，无需特定文件引用] + +## 故障排查指南 + +- 编译失败 + - 症状：UI 展示编译错误或触发 compile_error 事件。 + - 排查要点： + - 检查 value 中是否存在有效入口文件（template 对应的默认文件名或 is_entry 标记）。 + - 检查 imports 中的依赖是否可访问、是否与模板类型匹配。 + - 查看错误信息中是否包含具体文件与错误堆栈。 +- 渲染错误 + - 症状：iframe 内部抛错，主窗口弹出通知并触发 render_error 事件。 + - 排查要点： + - 关闭 show_render_error 后观察是否仍出现错误，确认是否为 UI 展示导致。 + - 检查模板中是否正确注入 importmap 与样式。 +- 循环依赖 + - 症状：解析器抛出循环依赖错误。 + - 排查要点： + - 检查文件间相互 import 的关系，拆分或抽象公共模块。 +- 高度异常 + - 症状：内容被裁剪或滚动条异常。 + - 排查要点： + - 确认 height 传入格式（数字 vs 字符串 CSS 单位）与父容器尺寸一致。 + +**章节来源** + +- [web_sandbox.tsx:203-217](file://frontend/pro/web-sandbox/web-sandbox.tsx#L203-L217) +- [web_sandbox.tsx:262-281](file://frontend/pro/web-sandbox/web-sandbox.tsx#L262-L281) +- [parser.ts:128-174](file://frontend/pro/web-sandbox/parser.ts#L128-L174) +- [react-iframe-template.html:7-12](file://frontend/pro/web-sandbox/react-iframe-template.html#L7-L12) + +## 结论 + +WebSandbox 通过清晰的参数体系与完善的错误处理机制，为 React 与 HTML 代码提供了安全可控的沙箱预览能力。合理配置 template、imports、show\_\* 开关与 height，可满足从开发调试到生产展示的不同场景。建议在复杂项目中优先规范依赖与入口文件命名，配合自定义错误展示提升可观测性与用户体验。 + +[本节为总结性内容，无需特定文件引用] + +## 附录 + +### API 一览（参数、事件、插槽） + +- 参数 + - value：文件集合；template：'react'|'html'；imports：importmap.imports；show_render_error/show_compile_error：布尔开关；compile_error_render：JS 函数字符串；height：高度。 +- 事件 + - compile_success、compile_error、render_error、custom。 +- 插槽 + - compileErrorRender。 + +**章节来源** + +- [README（英文）:38-61](file://docs/components/pro/web_sandbox/README.md#L38-L61) +- [README（中文）:38-70](file://docs/components/pro/web_sandbox/README-zh_CN.md#L38-L70) +- [**init**.py（后端组件）:19-35](file://backend/modelscope_studio/components/pro/web_sandbox/__init__.py#L19-L35) diff --git "a/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/\344\270\223\344\270\232\347\273\204\344\273\266.md" "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/\344\270\223\344\270\232\347\273\204\344\273\266.md" new file mode 100644 index 00000000..770838aa --- /dev/null +++ "b/.wiki/zh/\344\270\223\344\270\232\347\273\204\344\273\266/\344\270\223\344\270\232\347\273\204\344\273\266.md" @@ -0,0 +1,355 @@ +# 专业组件 + + +**本文引用的文件** +- [chatbot.tsx](file://frontend/pro/chatbot/chatbot.tsx) +- [type.ts](file://frontend/pro/chatbot/type.ts) +- [utils.ts](file://frontend/pro/chatbot/utils.ts) +- [multimodal-input.tsx](file://frontend/pro/multimodal-input/multimodal-input.tsx) +- [recorder.ts](file://frontend/pro/multimodal-input/recorder.ts) +- [utils.ts](file://frontend/pro/multimodal-input/utils.ts) +- [web-sandbox.tsx](file://frontend/pro/web-sandbox/web-sandbox.tsx) +- [monaco-editor.tsx](file://frontend/pro/monaco-editor/monaco-editor.tsx) +- [components.py](file://backend/modelscope_studio/components/pro/components.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向有经验的开发者，系统化梳理 ModelScope Studio 专业组件库中的高级组件：Chatbot（聊天机器人）、MultimodalInput（多模态输入框）、WebSandbox（网页沙盒）与 MonacoEditor（代码编辑器）。文档从架构设计、数据流、处理逻辑、集成方式、性能优化到故障排除进行深入说明，并提供可直接定位到源码的路径指引，帮助在复杂专业场景中高效落地。 + +## 项目结构 + +专业组件位于前端目录的 pro 子模块，后端通过 components.py 汇总导出，形成统一的组件入口。各组件以 React + Svelte 预处理的方式封装，复用 Ant Design X 与 Ant Design 的能力，结合 Gradio 生态实现高性能交互。 + +```mermaid +graph TB +subgraph "后端" +A["components.py
统一导出 Pro 组件"] +end +subgraph "前端 Pro 组件" +B["Chatbot
聊天机器人"] +C["MultimodalInput
多模态输入框"] +D["WebSandbox
网页沙盒"] +E["MonacoEditor
代码编辑器"] +end +A --> B +A --> C +A --> D +A --> E +``` + +图表来源 + +- [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +章节来源 + +- [components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## 核心组件 + +- Chatbot：基于气泡消息列表的对话组件，支持用户/助手角色、欢迎提示、复制/点赞/重试/编辑/删除等交互，内置滚动控制与 Markdown 渲染。 +- MultimodalInput：支持文本与文件上传的输入组件，内建语音录制、粘贴上传、附件管理、技能面板等扩展槽位。 +- WebSandbox：将多文件/HTML 源码编译为可在 iframe 中安全运行的沙盒环境，支持 React/HTML 模板与主题注入。 +- MonacoEditor：对 Monaco 编辑器的轻量封装，提供只读模式、主题切换、值变更回调与加载占位。 + +章节来源 + +- [chatbot.tsx:51-76](file://frontend/pro/chatbot/chatbot.tsx#L51-L76) +- [multimodal-input.tsx:75-94](file://frontend/pro/multimodal-input/multimodal-input.tsx#L75-L94) +- [web-sandbox.tsx:21-35](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L35) +- [monaco-editor.tsx:12-19](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L19) + +## 架构总览 + +四个专业组件均采用“属性驱动 + 上下文/工具函数”的模式组织，内部通过状态管理与事件回调实现数据闭环；对外提供统一的 onValueChange/onChange/onSubmit 等回调，便于与上层应用或服务端联动。 + +```mermaid +graph TB +subgraph "Chatbot" +CB_API["属性: value/onValueChange/markdownConfig 等"] +CB_CORE["渲染: 气泡消息/欢迎提示/操作栏"] +CB_EVT["事件: onCopy/onEdit/onLike/onRetry 等"] +end +subgraph "MultimodalInput" +MI_API["属性: value/upload/onSubmit/uploadConfig"] +MI_CORE["渲染: Sender + Attachments + 技能面板"] +MI_EVT["事件: onUpload/onPasteFile/onRemove 等"] +end +subgraph "WebSandbox" +WS_API["属性: value/imports/template/themeMode"] +WS_PARSER["解析: WebSandboxParser/模板渲染"] +WS_IFRAME["输出: iframe + 主题注入 + 错误上报"] +end +subgraph "MonacoEditor" +ME_API["属性: value/options/themeMode/readOnly"] +ME_EDITOR["渲染: @monaco-editor/react"] +end +CB_API --> CB_CORE --> CB_EVT +MI_API --> MI_CORE --> MI_EVT +WS_API --> WS_PARSER --> WS_IFRAME +ME_API --> ME_EDITOR +``` + +图表来源 + +- [chatbot.tsx:77-472](file://frontend/pro/chatbot/chatbot.tsx#L77-L472) +- [multimodal-input.tsx:105-616](file://frontend/pro/multimodal-input/multimodal-input.tsx#L105-L616) +- [web-sandbox.tsx:37-362](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L362) +- [monaco-editor.tsx:21-93](file://frontend/pro/monaco-editor/monaco-editor.tsx#L21-L93) + +## 详细组件分析 + +### Chatbot 聊天机器人 + +- 功能特性 + - 角色化消息渲染：用户/助手/系统/分隔符等角色映射，支持头/体/脚/头像自定义。 + - 欢迎提示：内置欢迎消息区域，支持提示词选择回调。 + - 交互能力：复制、点赞/踩、重试、编辑、删除、建议项选择。 + - 自动滚动与底部按钮：可配置自动滚动与“回到底部”按钮。 + - Markdown 渲染：统一的 Markdown 配置，支持换行与渲染开关。 +- 关键属性与回调 + - 基础：rootUrl、apiPrefix、themeMode、height/minHeight/maxHeight、autoScroll、showScrollToBottomButton、scrollToBottomButtonOffset。 + - 配置：userConfig、botConfig、markdownConfig、welcomeConfig。 + - 数据：value（消息数组）、onValueChange。 + - 回调：onCopy、onEdit、onDelete、onLike、onRetry、onSuggestionSelect、onWelcomePromptSelect。 +- 内部机制 + - 使用上下文提供者与角色预处理，将外部消息标准化为气泡项。 + - 使用 Immer 进行不可变更新，保证编辑/点赞/删除等操作的稳定性。 + - 使用滚动钩子控制滚动位置与按钮显示。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant C as "Chatbot" +participant L as "Bubble.List" +participant F as "ChatbotFooter" +participant M as "Message" +U->>C : 输入消息/点击操作 +C->>C : 解析配置/标准化消息 +C->>L : 渲染消息列表 +L->>M : 渲染消息内容(含 Markdown) +L->>F : 渲染操作栏(复制/点赞/重试/编辑/删除) +F-->>C : 触发回调(onLike/onRetry/onEdit/onDelete) +C->>C : 更新消息数组(Immer) +C-->>U : onValueChange(value) +``` + +图表来源 + +- [chatbot.tsx:107-472](file://frontend/pro/chatbot/chatbot.tsx#L107-L472) + +章节来源 + +- [chatbot.tsx:51-475](file://frontend/pro/chatbot/chatbot.tsx#L51-L475) +- [type.ts](file://frontend/pro/chatbot/type.ts) +- [utils.ts](file://frontend/pro/chatbot/utils.ts) + +### MultimodalInput 多模态输入框 + +- 功能特性 + - 文本输入与发送：基于 Sender 组件，支持语音录制、粘贴上传、提交回调。 + - 文件上传：基于 Attachments，支持拖拽、全屏拖拽、计数显示、最大数量限制。 + - 附件管理：支持下载、预览、移除、占位图与图标定制。 + - 技能面板：标题、提示、可关闭等扩展槽位，支持自定义渲染与函数式配置。 + - 状态与禁用：loading/disabled/readOnly 控制上传流程。 +- 关键属性与回调 + - 基础：value、mode（inline/block）、upload（文件上传函数）、onValueChange/onChange/onSubmit。 + - 上传配置：uploadConfig（allowUpload/allowSpeech/allowPasteFile/showCount/title/placeholder/fullscreenDrop/maxCount 等）。 + - 事件：onUpload/onPasteFile/onRemove/onDownload/onDrop/onPreview。 +- 内部机制 + - 使用 useValueChange 同步外部 value 与内部状态。 + - 录音器 hook 支持麦克风录音并转换为音频文件后上传。 + - 上传时维护临时文件列表，完成后合并为最终文件列表并触发回调。 + +```mermaid +flowchart TD +Start(["开始"]) --> CheckMode["检查模式(mode)"] +CheckMode --> |inline| RenderInline["渲染 Sender + 可选附件头部"] +CheckMode --> |block| RenderBlock["渲染 Sender + 底部操作区"] +RenderInline --> Interact["文本输入/语音/粘贴/拖拽"] +RenderBlock --> Interact +Interact --> Upload["调用 upload(files)"] +Upload --> OnUpload["触发 onUpload/onValueChange/onChange"] +OnUpload --> End(["结束"]) +``` + +图表来源 + +- [multimodal-input.tsx:105-616](file://frontend/pro/multimodal-input/multimodal-input.tsx#L105-L616) + +章节来源 + +- [multimodal-input.tsx:75-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L75-L619) +- [recorder.ts](file://frontend/pro/multimodal-input/recorder.ts) +- [utils.ts](file://frontend/pro/multimodal-input/utils.ts) + +### WebSandbox 网页沙盒 + +- 功能特性 + - 多文件/HTML 源码编译：解析入口文件，提取样式表与脚本，生成可运行的 HTML 或 React 入口。 + - 安全沙盒：通过 iframe 承载，避免与宿主页面冲突。 + - 主题注入：支持主题模式传递至 iframe 内容。 + - 错误处理：编译错误与渲染错误的可视化展示与回调通知。 +- 关键属性与回调 + - 基础：value（文件字典）、imports（第三方依赖映射）、template（react/html）、themeMode、height。 + - 行为：showRenderError/showCompileError、onCompileError/onCompileSuccess/onRenderError/onCustom。 + - 自定义：compileErrorRender 插槽与函数。 +- 内部机制 + - 根据模板选择解析策略：HTML 模式下提取并替换内联脚本，React 模式下生成入口 URL。 + - 使用 WebSandboxParser 进行文件解析与依赖映射，生成 import map 与样式表链接。 + - 通过 postMessage 与 iframe 通信，接收 sandbox-ready/sandbox-error 等事件。 + +```mermaid +sequenceDiagram +participant App as "应用" +participant WS as "WebSandbox" +participant Parser as "WebSandboxParser" +participant Ifr as "iframe" +App->>WS : 传入 value/imports/template/themeMode +WS->>Parser : 解析文件/生成入口/样式表 +Parser-->>WS : 返回 entryUrl/styleSheetUrls 或 html +WS->>Ifr : 设置 srcObject(URL.createObjectURL) +Ifr-->>WS : postMessage(sandbox-ready/error) +WS-->>App : onCompileSuccess/onRenderError/onCustom +``` + +图表来源 + +- [web-sandbox.tsx:37-362](file://frontend/pro/web-sandbox/web-sandbox.tsx#L37-L362) + +章节来源 + +- [web-sandbox.tsx:21-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L21-L365) + +### MonacoEditor 代码编辑器 + +- 功能特性 + - 主题适配：根据 themeMode 切换 vs-dark/light。 + - 只读模式：通过 readOnly 属性控制编辑行为。 + - 加载占位：支持自定义 loading 插槽或默认 Spin。 + - 值同步：统一的 useValueChange 实现双向绑定。 +- 关键属性与回调 + - 基础：value、options、themeMode、readOnly、height。 + - 回调：onMount/beforeMount/afterMount、onChange/onValueChange。 +- 内部机制 + - 将 props 透传给 @monaco-editor/react 的 Editor 组件。 + - 在 mount 生命周期中串联 onMount/afterMount，确保初始化顺序。 + +```mermaid +sequenceDiagram +participant App as "应用" +participant ME as "MonacoEditor" +participant E as "@monaco-editor/react" +App->>ME : 传入 value/options/themeMode/readOnly +ME->>E : 渲染 Editor(设置 value/options/loading) +E-->>ME : onChange/value 更新 +ME-->>App : onValueChange(value) +``` + +图表来源 + +- [monaco-editor.tsx:21-93](file://frontend/pro/monaco-editor/monaco-editor.tsx#L21-L93) + +章节来源 + +- [monaco-editor.tsx:12-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L12-L95) + +## 依赖分析 + +- 组件间耦合 + - 各组件保持低耦合，通过统一的 onValueChange/onChange/onSubmit 等回调与上层应用解耦。 + - Chatbot/MultimodalInput/WebSandbox/MonacoEditor 分别独立封装，职责清晰。 +- 外部依赖 + - Chatbot：@ant-design/x（Bubble.List）、Ant Design（Avatar/Button）、Immer、Lodash。 + - MultimodalInput：@ant-design/x（Sender/Attachments）、Ant Design（Badge/Button/Flex/Tooltip）、录音与文件处理工具。 + - WebSandbox：@ant-design/x（HTML 解析与事件监听）、DOM 解析与遍历工具、iframe 通信。 + - MonacoEditor：@monaco-editor/react、Antd Spin。 + +```mermaid +graph LR +Chatbot["@ant-design/x(Bubble)
Antd(Avatar/Button)
Immer/Lodash"] --> CB["Chatbot"] +MI["@ant-design/x(Sender/Attachments)
Antd(Badge/Button/Flex/Tooltip)"] --> MI["MultimodalInput"] +WS["DOM/遍历/iframe"] --> WS["WebSandbox"] +ME["@monaco-editor/react/Antd(Spin)"] --> ME["MonacoEditor"] +``` + +图表来源 + +- [chatbot.tsx:1-25](file://frontend/pro/chatbot/chatbot.tsx#L1-L25) +- [multimodal-input.tsx:1-26](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L26) +- [web-sandbox.tsx:1-17](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L17) +- [monaco-editor.tsx:1-10](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L10) + +章节来源 + +- [chatbot.tsx:1-475](file://frontend/pro/chatbot/chatbot.tsx#L1-L475) +- [multimodal-input.tsx:1-619](file://frontend/pro/multimodal-input/multimodal-input.tsx#L1-L619) +- [web-sandbox.tsx:1-365](file://frontend/pro/web-sandbox/web-sandbox.tsx#L1-L365) +- [monaco-editor.tsx:1-95](file://frontend/pro/monaco-editor/monaco-editor.tsx#L1-L95) + +## 性能考虑 + +- Chatbot + - 使用 useMemo 与 useMemoizedFn 降低渲染与回调开销；通过 Immer 进行局部不可变更新，避免深层拷贝。 + - 滚动控制仅在必要时触发，减少 DOM 操作。 +- MultimodalInput + - 上传前进行最大数量与禁用状态校验，减少无效请求；临时文件列表仅在上传阶段存在，及时清理。 + - 录音转码与上传异步执行，避免阻塞 UI。 +- WebSandbox + - 解析阶段生成 import map 与样式表链接，避免重复计算；iframe URL 使用 revokeObjectURL 及时释放内存。 + - 编译错误与渲染错误快速反馈，避免长时间等待。 +- MonacoEditor + - 通过 options 合并与只读控制减少不必要的重绘；加载占位避免空白闪烁。 + +## 故障排除指南 + +- Chatbot + - 症状：消息不显示或样式异常 + - 排查：确认 value 是否为空或未标准化；检查 userConfig/botConfig/class_names 是否正确传入。 + - 参考路径：[chatbot.tsx:108-165](file://frontend/pro/chatbot/chatbot.tsx#L108-L165) +- MultimodalInput + - 症状：上传无响应或文件未显示 + - 排查：检查 upload 函数返回值是否为 FileData 数组；确认 maxCount 与 disabled 状态；查看 onUpload/onValueChange 是否触发。 + - 参考路径：[multimodal-input.tsx:174-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L174-L246) +- WebSandbox + - 症状：编译失败或渲染报错 + - 排查：检查 value 中是否存在入口文件；确认 imports 映射是否完整；查看 onCompileError/onRenderError 回调与 compileErrorRender 插槽。 + - 参考路径：[web-sandbox.tsx:95-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L95-L218) +- MonacoEditor + - 症状：编辑器不显示或主题不生效 + - 排查：确认 themeMode 与 options；检查 beforeMount/afterMount 生命周期是否正确串联。 + - 参考路径：[monaco-editor.tsx:39-87](file://frontend/pro/monaco-editor/monaco-editor.tsx#L39-L87) + +章节来源 + +- [chatbot.tsx:108-165](file://frontend/pro/chatbot/chatbot.tsx#L108-L165) +- [multimodal-input.tsx:174-246](file://frontend/pro/multimodal-input/multimodal-input.tsx#L174-L246) +- [web-sandbox.tsx:95-218](file://frontend/pro/web-sandbox/web-sandbox.tsx#L95-L218) +- [monaco-editor.tsx:39-87](file://frontend/pro/monaco-editor/monaco-editor.tsx#L39-L87) + +## 结论 + +ModelScope Studio 专业组件库通过高内聚、低耦合的设计，为复杂专业场景提供了即插即用的能力：Chatbot 提供了可扩展的消息与交互模型；MultimodalInput 融合文本与文件能力，满足多模态输入需求；WebSandbox 将前端工程化与沙盒安全结合；MonacoEditor 则以简洁封装提供一致的编辑体验。配合统一的回调与配置体系，开发者可以快速构建高质量的专业应用。 + +## 附录 + +- 组件导出入口 + - 后端统一导出：[components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + - **MonacoEditorDiffEditor 导出入口**：`MonacoEditorDiffEditor` 在 [backend/modelscope_studio/components/pro/**init**.py](file://backend/modelscope_studio/components/pro/__init__.py) 中导出，导入方式为 `from modelscope_studio.components.pro import MonacoEditorDiffEditor`。该组件为 MonacoEditor 的子组件，专用于代码 diff 对比展示场景。 +- 类型与工具 + - Chatbot 类型与工具：[type.ts](file://frontend/pro/chatbot/type.ts)、[utils.ts](file://frontend/pro/chatbot/utils.ts) + - MultimodalInput 工具与录音：[recorder.ts](file://frontend/pro/multimodal-input/recorder.ts)、[utils.ts](file://frontend/pro/multimodal-input/utils.ts) diff --git "a/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/Application \347\273\204\344\273\266.md" "b/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/Application \347\273\204\344\273\266.md" new file mode 100644 index 00000000..9ec95300 --- /dev/null +++ "b/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/Application \347\273\204\344\273\266.md" @@ -0,0 +1,424 @@ +# Application 组件 + + +**本文引用的文件** +- [backend/modelscope_studio/components/base/application/__init__.py](file://backend/modelscope_studio/components/base/application/__init__.py) +- [frontend/base/application/Application.svelte](file://frontend/base/application/Application.svelte) +- [frontend/base/application/Index.svelte](file://frontend/base/application/Index.svelte) +- [backend/modelscope_studio/utils/dev/app_context.py](file://backend/modelscope_studio/utils/dev/app_context.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [docs/components/base/application/README-zh_CN.md](file://docs/components/base/application/README-zh_CN.md) +- [docs/components/base/application/README.md](file://docs/components/base/application/README.md) +- [docs/app.py](file://docs/app.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Application 组件是 modelscope-studio 的应用根容器，负责承载并统一管理所有从 modelscope_studio 导出的组件与依赖。它不仅为应用提供基础运行环境，还通过生命周期事件与浏览器环境信息收集能力，帮助开发者实现页面行为监听、主题与语言适配、以及自定义事件桥接等关键功能。 + +- 作为应用根容器：确保所有 modelscope_studio 组件被正确包裹，否则页面可能无法成功预览。 +- 生命周期与环境感知：提供页面挂载、窗口大小变化、页面卸载等事件；可获取语言、主题、UA、屏幕尺寸与滚动位置等信息。 +- 自定义事件桥接：通过 window.ms_globals.dispatch 在前端触发自定义事件，Python 端可通过 ms.Application.custom 事件接收。 + +章节来源 + +- [docs/components/base/application/README-zh_CN.md:1-11](file://docs/components/base/application/README-zh_CN.md#L1-L11) +- [docs/components/base/application/README.md:1-11](file://docs/components/base/application/README.md#L1-L11) + +## 项目结构 + +Application 组件由后端 Python 组件类与前端 Svelte 实现共同构成，并通过工具模块提供上下文与基类支持。文档与示例位于 docs 目录中，用于演示与说明。 + +```mermaid +graph TB +subgraph "后端" +PY_APP["ModelScopeApplication
Python 组件类"] +APP_CTX["AppContext
应用上下文"] +BASE_META["ModelScopeDataLayoutComponent
基类"] +end +subgraph "前端" +IDX["Index.svelte
异步导入入口"] +CMP["Application.svelte
核心实现"] +end +subgraph "文档与示例" +DOCS_ZH["README-zh_CN.md"] +DOCS_EN["README.md"] +DOCS_APP["docs/app.py"] +end +PY_APP --> BASE_META +PY_APP --> APP_CTX +IDX --> CMP +DOCS_APP --> DOCS_ZH +DOCS_APP --> DOCS_EN +``` + +图表来源 + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/application/Application.svelte:1-149](file://frontend/base/application/Application.svelte#L1-L149) +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) +- [backend/modelscope_studio/utils/dev/component.py:101-169](file://backend/modelscope_studio/utils/dev/component.py#L101-L169) +- [docs/components/base/application/README-zh_CN.md:1-56](file://docs/components/base/application/README-zh_CN.md#L1-L56) +- [docs/components/base/application/README.md:1-56](file://docs/components/base/application/README.md#L1-L56) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +章节来源 + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/application/Application.svelte:1-149](file://frontend/base/application/Application.svelte#L1-L149) +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) +- [backend/modelscope_studio/utils/dev/component.py:101-169](file://backend/modelscope_studio/utils/dev/component.py#L101-L169) +- [docs/components/base/application/README-zh_CN.md:1-56](file://docs/components/base/application/README-zh_CN.md#L1-L56) +- [docs/components/base/application/README.md:1-56](file://docs/components/base/application/README.md#L1-L56) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## 核心组件 + +- 后端组件类：ModelScopeApplication 继承自 ModelScopeDataLayoutComponent，提供事件注册、数据模型、示例数据与前端目录解析等能力。 +- 前端实现：Application.svelte 负责在挂载时初始化页面数据，绑定 resize/unload 事件，暴露 window.ms_globals.dispatch 以供自定义事件桥接。 +- 上下文与基类：AppContext 提供应用实例的设置与断言；ModelScopeDataLayoutComponent 提供布局上下文与内部状态管理。 + +章节来源 + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [frontend/base/application/Application.svelte:1-149](file://frontend/base/application/Application.svelte#L1-L149) +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) +- [backend/modelscope_studio/utils/dev/component.py:101-169](file://backend/modelscope_studio/utils/dev/component.py#L101-L169) + +## 架构总览 + +Application 组件的运行流程如下：后端组件类在初始化时记录应用实例，前端在挂载阶段采集环境数据并绑定事件，同时提供自定义事件桥接通道。 + +```mermaid +sequenceDiagram +participant Py as "后端
ModelScopeApplication" +participant Ctx as "上下文
AppContext" +participant FE as "前端
Application.svelte" +participant Win as "浏览器
window" +Py->>Ctx : 设置应用实例 +FE->>FE : onMount 初始化 +FE->>FE : 采集屏幕/语言/主题/UA +FE->>Win : 绑定 resize/unload 事件 +FE->>Py : 触发 mount/resize/unmount 事件 +Win-->>FE : 用户调用 window.ms_globals.dispatch(...) +FE->>Py : 触发 custom 事件 +``` + +图表来源 + +- [backend/modelscope_studio/components/base/application/**init**.py:72-82](file://backend/modelscope_studio/components/base/application/__init__.py#L72-L82) +- [frontend/base/application/Application.svelte:87-129](file://frontend/base/application/Application.svelte#L87-L129) + +章节来源 + +- [backend/modelscope_studio/components/base/application/**init**.py:72-82](file://backend/modelscope_studio/components/base/application/__init__.py#L72-L82) +- [frontend/base/application/Application.svelte:87-129](file://frontend/base/application/Application.svelte#L87-L129) + +## 详细组件分析 + +### 后端组件类：ModelScopeApplication + +- 设计理念 + - 作为应用根容器，统一注入应用上下文，确保后续组件均依赖于已存在的 Application 实例。 + - 通过 Gradio 事件系统注册 mount/resized/unmount/custom 等事件监听器，便于前后端联动。 + - 使用 ApplicationPageData 作为数据模型，承载屏幕、语言、主题、UA 等环境信息。 +- 关键特性 + - 事件注册：EVENTS 定义了四个事件监听器，分别对应页面生命周期与自定义事件。 + - 数据模型：data_model 指向 ApplicationPageData，示例数据 example_payload/example_value 提供默认值。 + - 前端目录：FRONTEND_DIR 通过 resolve_frontend_dir 解析到 base/application 前端实现。 +- 生命周期与上下文 + - **init** 中设置 AppContext，随后调用父类构造，保证组件树构建时上下文可用。 + - preprocess/postprocess 保持数据原样传递，便于前端直接消费。 + +```mermaid +classDiagram +class ModelScopeApplication { ++EVENTS ++SLOTS ++FRONTEND_DIR ++data_model ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class ModelScopeDataLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__() ++__init__(...) +} +class AppContext { ++set_app(app) ++has_app() ++assert_app() ++get_app() +} +ModelScopeApplication --|> ModelScopeDataLayoutComponent +ModelScopeApplication --> AppContext : "设置/断言" +``` + +图表来源 + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/utils/dev/component.py:101-169](file://backend/modelscope_studio/utils/dev/component.py#L101-L169) +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) + +章节来源 + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/utils/dev/component.py:101-169](file://backend/modelscope_studio/utils/dev/component.py#L101-L169) +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) + +### 前端实现：Application.svelte + +- 功能要点 + - onMount 初始化：更新 value 并派发 mount 事件；随后绑定 resize 与 beforeunload 事件。 + - resize 事件：使用防抖（默认 500ms）更新 value 并派发 resize 事件，避免高频重绘。 + - beforeunload：在页面卸载前更新 value 并派发 unmount 事件。 + - 自定义事件：window.ms_globals.dispatch(...) 将参数数组转发为 custom 事件。 + - 可见性与样式：根据 visible 控制渲染，elem_id/elem_classes/elem_style 支持外部样式注入。 +- 数据模型 + - ApplicationPageData 包含 language、userAgent、theme、screen（width/height/scrollX/scrollY）。 +- 事件模型 + - mount/resized/unmount/custom 四类事件，分别对应页面生命周期与自定义事件。 + +```mermaid +flowchart TD +Start(["挂载开始"]) --> Init["初始化 value
采集语言/主题/UA/屏幕"] +Init --> Bind["绑定 resize/unload 事件"] +Bind --> MountEvt{"是否绑定 mount 事件？"} +MountEvt --> |是| DispatchMount["派发 mount 事件"] +MountEvt --> |否| Wait["等待用户交互"] +Wait --> ResizeEvt{"窗口尺寸变化？"} +ResizeEvt --> |是| Debounce["防抖处理默认 500ms"] +Debounce --> UpdateResize["更新 value 并派发 resize"] +ResizeEvt --> |否| UnloadEvt{"页面即将卸载？"} +UnloadEvt --> |是| UpdateUnload["更新 value 并派发 unmount"] +UnloadEvt --> |否| CustomEvt{"window.ms_globals.dispatch 调用？"} +CustomEvt --> |是| DispatchCustom["派发 custom 事件"] +CustomEvt --> |否| End(["结束"]) +``` + +图表来源 + +- [frontend/base/application/Application.svelte:87-129](file://frontend/base/application/Application.svelte#L87-L129) + +章节来源 + +- [frontend/base/application/Application.svelte:1-149](file://frontend/base/application/Application.svelte#L1-L149) + +### 入口包装：Index.svelte + +- 作用：通过异步导入 Application.svelte，延迟加载组件，减少首屏负担。 +- 渲染：将 children 透传给 Application 组件，保证内容渲染。 + +章节来源 + +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) + +### 上下文与基类支撑 + +- AppContext + - set_app：在后端初始化时设置当前应用实例。 + - assert_app：若未设置则发出警告，提示忘记引入 Application。 + - get_app：获取当前应用实例。 +- ModelScopeDataLayoutComponent + - 提供布局上下文与内部状态（\_internal），确保组件树结构正确。 + - 继承 Gradio 组件元类，支持事件与数据流。 + +章节来源 + +- [backend/modelscope_studio/utils/dev/app_context.py:4-25](file://backend/modelscope_studio/utils/dev/app_context.py#L4-L25) +- [backend/modelscope_studio/utils/dev/component.py:101-169](file://backend/modelscope_studio/utils/dev/component.py#L101-L169) + +### 使用示例与场景 + +- 基本用法：将 modelscope_studio 所有组件包裹在 Application 内，确保预览与交互正常。 +- 语言适配：通过 value.language 获取用户语言，动态切换文案或格式化。 +- 主题适配：通过 value.theme 返回不同权重内容或样式。 +- 自定义事件：在任意 JS 逻辑中调用 window.ms_globals.dispatch(...)，在 Python 端通过 ms.Application.custom 接收。 + +**Python 代码示例** + +```python +import gradio as gr +import modelscope_studio.components.base as ms +import modelscope_studio.components.antd as antd + +# 示例 1：基本包裹用法 +with gr.Blocks() as demo: + with ms.Application(): + with antd.ConfigProvider(): + with ms.AutoLoading(): + antd.Button("Hello ModelScope Studio") + +demo.launch() +``` + +```python +import gradio as gr +import modelscope_studio.components.base as ms +import modelscope_studio.components.antd as antd + +# 示例 2：监听页面挂载事件与语言/主题适配 +with gr.Blocks() as demo: + with ms.Application() as app: + with antd.ConfigProvider(): + output = gr.Textbox(label="页面信息") + + @app.mount + def on_mount(data: ms.ApplicationData): + # 获取用户语言和主题 + lang = data.value.language + theme = data.value.theme + return gr.update(value=f"语言: {lang}, 主题: {theme}") + +demo.launch() +``` + +```python +import gradio as gr +import modelscope_studio.components.base as ms +import modelscope_studio.components.antd as antd + +# 示例 3：监听自定义事件（结合 window.ms_globals.dispatch） +with gr.Blocks() as demo: + with ms.Application() as app: + with antd.ConfigProvider(): + output = gr.Textbox(label="自定义事件") + # 前端可通过 window.ms_globals.dispatch({type: 'my_event', payload: {...}}) 触发 + + @app.custom + def on_custom(data: ms.ApplicationData): + event_type = data.value.type if data.value else None + return gr.update(value=f"收到自定义事件: {event_type}") + +demo.launch() +``` + +章节来源 + +- [docs/components/base/application/README-zh_CN.md:12-20](file://docs/components/base/application/README-zh_CN.md#L12-L20) +- [docs/components/base/application/README.md:12-20](file://docs/components/base/application/README.md#L12-L20) + +### API 与类型说明 + +- 属性 + - value：ApplicationPageData，页面数据。 +- 事件 + - mount：页面挂载时触发。 + - resize：窗口尺寸变化时触发。 + - unmount：页面卸载时触发。 + - custom：通过 window.ms_globals.dispatch(...) 触发。 +- 类型 + - ApplicationPageScreenData：width、height、scrollX、scrollY。 + - ApplicationPageData：screen、language、theme、userAgent。 + +章节来源 + +- [docs/components/base/application/README-zh_CN.md:24-55](file://docs/components/base/application/README-zh_CN.md#L24-L55) +- [docs/components/base/application/README.md:24-55](file://docs/components/base/application/README.md#L24-L55) +- [backend/modelscope_studio/components/base/application/**init**.py:12-115](file://backend/modelscope_studio/components/base/application/__init__.py#L12-L115) + +## 依赖关系分析 + +- 后端依赖 + - Gradio 数据类与事件系统：用于事件监听器注册与数据模型。 + - 工具模块：AppContext、ModelScopeDataLayoutComponent 提供上下文与基类能力。 +- 前端依赖 + - Svelte 生命周期钩子：onMount/onDestroy。 + - svelte-i18n：获取本地化语言。 + - 样式工具：styleObject2String、classnames。 +- 文档与示例 + - docs/app.py 构建站点菜单与文档索引，定位 Application 组件文档。 + +```mermaid +graph LR +PY["ModelScopeApplication"] --> GR["Gradio 事件/数据类"] +PY --> CTX["AppContext"] +PY --> META["ModelScopeDataLayoutComponent"] +FE["Application.svelte"] --> SV["Svelte 生命周期"] +FE --> I18N["svelte-i18n"] +FE --> STY["样式工具"] +DOC["docs/app.py"] --> DZ["README-zh_CN.md"] +DOC --> DE["README.md"] +``` + +图表来源 + +- [backend/modelscope_studio/components/base/application/**init**.py:5-9](file://backend/modelscope_studio/components/base/application/__init__.py#L5-L9) +- [frontend/base/application/Application.svelte:1-149](file://frontend/base/application/Application.svelte#L1-L149) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +章节来源 + +- [backend/modelscope_studio/components/base/application/**init**.py:5-9](file://backend/modelscope_studio/components/base/application/__init__.py#L5-L9) +- [frontend/base/application/Application.svelte:1-149](file://frontend/base/application/Application.svelte#L1-L149) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## 性能考量 + +- 防抖策略：resize 事件默认使用 500ms 防抖，降低频繁重排与事件风暴风险。 +- 延迟加载：Index.svelte 采用异步导入，减少首屏资源压力。 +- 事件绑定：仅在需要时派发事件（bind\_\*\_event 或 attached_events 包含对应事件名），避免无谓的事件分发。 +- 样式与可见性：通过 visible 控制渲染，elem_style 支持字符串与对象两种形式，便于按需注入。 + +章节来源 + +- [frontend/base/application/Application.svelte:96-103](file://frontend/base/application/Application.svelte#L96-L103) +- [frontend/base/application/Index.svelte:5-7](file://frontend/base/application/Index.svelte#L5-L7) + +## 故障排除指南 + +- 页面无法预览 + - 现象：未包裹 Application 导致组件无法正常渲染。 + - 处理：确保所有 modelscope_studio 组件均被 Application 包裹。 +- 未检测到 Application 实例 + - 现象：控制台出现警告，提示未找到 Application 组件。 + - 处理：检查是否从 modelscope_studio.components.base 正确导入并初始化 Application。 +- 事件未触发 + - 现象：resize/mount/unmount/custom 事件未按预期触发。 + - 处理：确认前端已绑定对应事件（bind\_\*\_event 或 attached_events 包含事件名）；自定义事件需通过 window.ms_globals.dispatch(...) 触发。 +- 语言/主题不生效 + - 现象：语言或主题未按用户环境变化。 + - 处理：确保前端正确读取 navigator 与共享主题；必要时在 Python 端根据 value.language/value.theme 做分支处理。 + +章节来源 + +- [docs/components/base/application/README-zh_CN.md:3-11](file://docs/components/base/application/README-zh_CN.md#L3-L11) +- [docs/components/base/application/README.md:3-11](file://docs/components/base/application/README.md#L3-L11) +- [backend/modelscope_studio/utils/dev/app_context.py:16-21](file://backend/modelscope_studio/utils/dev/app_context.py#L16-L21) +- [frontend/base/application/Application.svelte:91-115](file://frontend/base/application/Application.svelte#L91-L115) + +## 结论 + +Application 组件作为 modelscope-studio 的应用根容器，承担着上下文注入、生命周期事件与环境信息采集的关键职责。通过后端组件类与前端实现的协同，它为整个应用提供了稳定的基础运行环境，并支持灵活的主题/语言适配与自定义事件桥接。遵循本文的最佳实践与故障排除建议，可有效提升开发效率与运行稳定性。 + +## 附录 + +- 版本信息：v2.0.0 +- 相关文档：Application 组件的中文与英文说明文档，包含示例与 API 说明。 + +章节来源 + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [docs/components/base/application/README-zh_CN.md:1-56](file://docs/components/base/application/README-zh_CN.md#L1-L56) +- [docs/components/base/application/README.md:1-56](file://docs/components/base/application/README.md#L1-L56) diff --git "a/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/AutoLoading \347\273\204\344\273\266.md" "b/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/AutoLoading \347\273\204\344\273\266.md" new file mode 100644 index 00000000..6201431e --- /dev/null +++ "b/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/AutoLoading \347\273\204\344\273\266.md" @@ -0,0 +1,339 @@ +# AutoLoading 组件 + + +**本文引用的文件** +- [auto-loading.tsx](file://frontend/base/auto-loading/auto-loading.tsx) +- [Index.svelte](file://frontend/base/auto-loading/Index.svelte) +- [useLoadingStatus.ts](file://frontend/base/auto-loading/useLoadingStatus.ts) +- [auto-loading.less](file://frontend/base/auto-loading/auto-loading.less) +- [package.json](file://frontend/base/auto-loading/package.json) +- [gradio.config.js](file://frontend/base/auto-loading/gradio.config.js) +- [__init__.py](file://backend/modelscope_studio/components/base/auto_loading/__init__.py) +- [loading-status.svelte.ts](file://frontend/svelte-preprocess-react/svelte-contexts/loading-status.svelte.ts) +- [import.ts](file://frontend/svelte-preprocess-react/component/import.ts) +- [README.md](file://docs/components/base/auto_loading/README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +AutoLoading 组件用于在 Gradio 前端向后端发起请求时，自动为被包裹的内容添加加载反馈与错误提示。它会自动收集子组件的加载状态，并在合适的时机显示加载动画或错误信息，从而提升用户体验。该组件支持自定义渲染插槽、遮罩层、计时器显示以及多种配置项，适用于全局兜底与局部精细控制。 + +## 项目结构 + +AutoLoading 的前端实现位于 base 组件目录中，包含 Svelte 入口、React 包装组件、状态钩子与样式文件；后端 Python 组件负责声明前端资源路径与跳过 API 调用。文档中提供了组件说明与示例入口。 + +```mermaid +graph TB +subgraph "前端(base/auto-loading)" +A["Index.svelte
Svelte 入口"] --> B["auto-loading.tsx
React 包装组件"] +B --> C["useLoadingStatus.ts
加载状态钩子"] +B --> D["auto-loading.less
样式"] +A --> E["package.json
导出配置"] +A --> F["gradio.config.js
构建配置"] +end +subgraph "后端(modelscope_studio/components/base/auto_loading)" +G["__init__.py
声明前端目录/跳过API"] +end +subgraph "文档(docs/components/base/auto_loading)" +H["README.md
使用说明与示例"] +end +A -. 集成 .-> B +A -. 配置 .-> E +A -. 构建 .-> F +G -. 资源 .-> A +H -. 使用 .-> A +``` + +**图表来源** + +- [Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [auto-loading.tsx:1-179](file://frontend/base/auto-loading/auto-loading.tsx#L1-L179) +- [useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [auto-loading.less:1-28](file://frontend/base/auto-loading/auto-loading.less#L1-L28) +- [package.json:1-15](file://frontend/base/auto-loading/package.json#L1-L15) +- [gradio.config.js:1-4](file://frontend/base/auto-loading/gradio.config.js#L1-L4) +- [**init**.py:47-64](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L47-L64) +- [README.md:1-36](file://docs/components/base/auto_loading/README.md#L1-L36) + +**章节来源** + +- [Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [auto-loading.tsx:1-179](file://frontend/base/auto-loading/auto-loading.tsx#L1-L179) +- [useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [auto-loading.less:1-28](file://frontend/base/auto-loading/auto-loading.less#L1-L28) +- [package.json:1-15](file://frontend/base/auto-loading/package.json#L1-L15) +- [gradio.config.js:1-4](file://frontend/base/auto-loading/gradio.config.js#L1-L4) +- [**init**.py:47-64](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L47-L64) +- [README.md:1-36](file://docs/components/base/auto_loading/README.md#L1-L36) + +## 核心组件 + +- Svelte 入口（Index.svelte）：负责解析属性、获取配置类型与插槽、注入加载状态上下文，并按需渲染 React 包装组件。 +- React 包装组件（auto-loading.tsx）：根据加载状态决定是否显示加载动画、遮罩、计时器与队列信息；在错误状态下显示可关闭的错误提示。 +- 加载状态钩子（useLoadingStatus.ts）：维护计时器、ETA 与格式化时间，基于 ILoadingStatus 推导展示数据。 +- 样式（auto-loading.less）：控制加载层定位、遮罩层级与错误弹层居中样式。 +- 后端组件（**init**.py）：声明前端目录、跳过 API 调用，便于直接通过前端资源使用。 +- 文档（README.md）：说明组件作用、状态含义、默认行为与示例入口。 + +**章节来源** + +- [Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [auto-loading.tsx:25-176](file://frontend/base/auto-loading/auto-loading.tsx#L25-L176) +- [useLoadingStatus.ts:5-93](file://frontend/base/auto-loading/useLoadingStatus.ts#L5-L93) +- [auto-loading.less:1-28](file://frontend/base/auto-loading/auto-loading.less#L1-L28) +- [**init**.py:47-64](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L47-L64) +- [README.md:1-36](file://docs/components/base/auto_loading/README.md#L1-L36) + +## 架构总览 + +AutoLoading 的工作流围绕“状态收集—条件渲染—UI 展示”展开。Svelte 入口通过上下文收集各子组件的 ILoadingStatus，React 组件根据状态选择加载动画或错误提示，并通过 Ant Design 组件呈现。 + +```mermaid +sequenceDiagram +participant Child as "子组件" +participant Bridge as "加载状态桥接" +participant Auto as "AutoLoading(React)" +participant UI as "Ant Design 组件" +Child->>Bridge : "setLoadingStatus(ILoadingStatus)" +Bridge-->>Auto : "loadingStatus(聚合)" +Auto->>Auto : "useLoadingStatus() 计算 ETA/计时器" +Auto->>UI : "根据状态渲染加载/错误" +UI-->>Auto : "用户交互(如关闭错误)" +Auto-->>Child : "继续渲染子内容" +``` + +**图表来源** + +- [loading-status.svelte.ts:47-75](file://frontend/svelte-preprocess-react/svelte-contexts/loading-status.svelte.ts#L47-L75) +- [auto-loading.tsx:48-175](file://frontend/base/auto-loading/auto-loading.tsx#L48-L175) +- [useLoadingStatus.ts:17-81](file://frontend/base/auto-loading/useLoadingStatus.ts#L17-L81) + +## 详细组件分析 + +### Svelte 入口（Index.svelte） + +- 负责从预处理上下文中获取组件属性、配置类型与插槽。 +- 通过 getLoadingStatus 注入生成的 loadingStatus 上下文，供内部 React 组件消费。 +- 使用 importComponent 实现延迟加载，确保全局初始化完成后再加载组件。 +- 将可见性、样式、类名等属性透传给 React 包装组件。 + +关键点 + +- 按需渲染：仅当 visible 为真时才渲染。 +- 插槽与配置：slots、configType、loadingStatus 作为 props 传递。 +- 生成键值：通过 window.ms_globals.loadingKey 为每个加载状态分配唯一键。 + +**章节来源** + +- [Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [import.ts:1-20](file://frontend/svelte-preprocess-react/component/import.ts#L1-L20) +- [loading-status.svelte.ts:47-75](file://frontend/svelte-preprocess-react/svelte-contexts/loading-status.svelte.ts#L47-L75) + +### React 包装组件（auto-loading.tsx） + +职责 + +- 解析配置类型（当前支持 antd），决定加载动画与错误提示的 UI。 +- 根据状态渲染加载动画（含遮罩、计时器、进度/队列信息）。 +- 在错误状态下渲染可关闭的错误提示，并在关闭后清空实例以避免重复渲染。 +- 支持自定义插槽：render（自定义加载内容）、errorRender（自定义错误内容）、loadingText（自定义加载文案）。 + +加载状态判断 + +- pending/generating 视为加载中；completed/error 视为结束。 +- 当存在 progress 或 queue_position/queue_size 时，动态展示进度与队列信息。 +- 可选显示计时器与 ETA。 + +样式与层级 + +- 加载层绝对定位并覆盖父容器，错误提示固定居中显示。 +- 根据主题 token 设置 z-index，保证遮罩与错误提示层级合理。 + +**章节来源** + +- [auto-loading.tsx:25-176](file://frontend/base/auto-loading/auto-loading.tsx#L25-L176) +- [auto-loading.less:1-28](file://frontend/base/auto-loading/auto-loading.less#L1-L28) + +### 加载状态钩子（useLoadingStatus.ts） + +功能 + +- 维护计时器：在 pending 状态开始计时，在非 pending 状态停止。 +- 计算 ETA 与格式化时间：结合 performance.now 与 ETA 字段计算剩余时间与已耗时。 +- 追踪旧 ETA：当 ETA 更新时，记录旧值并格式化新 ETA。 +- 返回状态字段：status、message、progress、queuePosition、queueSize、formattedEta、formattedTimer。 + +性能注意 + +- 使用 requestAnimationFrame 循环更新计时，避免阻塞主线程。 +- 使用 useMemoizedFn 缓存回调，减少重渲染。 + +**章节来源** + +- [useLoadingStatus.ts:5-93](file://frontend/base/auto-loading/useLoadingStatus.ts#L5-L93) + +### 样式（auto-loading.less） + +要点 + +- 加载层绝对定位，覆盖父容器，确保遮罩效果。 +- 错误提示固定定位并居中，避免布局抖动。 +- 通过 Ant Design 类名与主题 token 控制层级与外观。 + +**章节来源** + +- [auto-loading.less:1-28](file://frontend/base/auto-loading/auto-loading.less#L1-L28) + +### 后端组件（**init**.py） + +要点 + +- 声明前端目录为 base/auto-loading。 +- 跳过 API 调用，组件仅用于前端渲染与状态收集。 + +**章节来源** + +- [**init**.py:47-64](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L47-L64) + +### 文档（README.md） + +要点 + +- 组件作用：自动为被包裹内容添加加载动画与错误提示。 +- 状态说明：pending/generating/completed/error 四种状态。 +- 默认行为：pending 开始加载；generating/.completed 结束；error 显示错误（可配置）。 +- API 参数：generating、show_error、show_mask、show_timer、loading_text 等。 + +**章节来源** + +- [README.md:1-36](file://docs/components/base/auto_loading/README.md#L1-L36) + +## 依赖关系分析 + +AutoLoading 的依赖主要体现在以下方面： + +- Svelte 入口依赖加载状态上下文与导入工具，实现延迟加载与状态聚合。 +- React 组件依赖 Ant Design 的 Spin 与 Alert，以及主题 token。 +- useLoadingStatus 依赖浏览器性能接口与 React hooks，实现计时与状态格式化。 +- 后端组件声明前端资源路径，使前端组件可通过包导出正确加载。 + +```mermaid +graph LR +Index["Index.svelte"] --> Import["import.ts
延迟加载"] +Index --> Ctx["loading-status.svelte.ts
加载状态上下文"] +Index --> Auto["auto-loading.tsx"] +Auto --> Hook["useLoadingStatus.ts"] +Auto --> Less["auto-loading.less"] +Backend["__init__.py"] --> Index +Doc["README.md"] --> Index +``` + +**图表来源** + +- [Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [import.ts:1-20](file://frontend/svelte-preprocess-react/component/import.ts#L1-L20) +- [loading-status.svelte.ts:1-75](file://frontend/svelte-preprocess-react/svelte-contexts/loading-status.svelte.ts#L1-L75) +- [auto-loading.tsx:1-179](file://frontend/base/auto-loading/auto-loading.tsx#L1-L179) +- [useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [auto-loading.less:1-28](file://frontend/base/auto-loading/auto-loading.less#L1-L28) +- [**init**.py:47-64](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L47-L64) +- [README.md:1-36](file://docs/components/base/auto_loading/README.md#L1-L36) + +**章节来源** + +- [Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [auto-loading.tsx:1-179](file://frontend/base/auto-loading/auto-loading.tsx#L1-L179) +- [useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [auto-loading.less:1-28](file://frontend/base/auto-loading/auto-loading.less#L1-L28) +- [**init**.py:47-64](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L47-L64) +- [README.md:1-36](file://docs/components/base/auto_loading/README.md#L1-L36) + +## 性能考量 + +- 延迟初始化：通过 importComponent 与全局初始化 Promise，避免在未就绪时加载组件，降低首屏压力。 +- 计时器优化：使用 requestAnimationFrame 循环更新计时，减少主线程占用；仅在 pending 状态启动计时。 +- 状态聚合：仅最内层 AutoLoading 收集子组件状态，避免重复渲染与状态冲突。 +- 样式层级：通过 z-index 与绝对定位，确保遮罩与错误提示不会引发布局回流。 +- 自定义渲染：通过 render 与 errorRender 插槽，允许业务方自行优化加载与错误 UI，减少不必要的组件开销。 + +[本节为通用性能建议，不直接分析具体文件，故无“章节来源”] + +## 故障排除指南 + +常见问题与解决思路 + +- 多层嵌套 AutoLoading：根据文档说明，仅最内层可收集子组件状态并显示加载动画。若外层不生效，请检查嵌套层级。 +- 错误提示不消失：错误提示为可关闭组件，关闭后会清空内部实例。若仍显示，请确认是否手动覆盖了关闭逻辑或样式导致视觉残留。 +- 加载动画不出现：确认 loadingStatus 是否进入 pending/generating 状态；检查 generating/show_error 配置是否符合预期。 +- 计时器不更新：pending 状态才会启动计时；若长时间无 pending 状态，计时器不会启动。 +- 遮罩层级异常：样式通过主题 token 控制层级，若自定义样式覆盖了 z-index，请检查样式优先级。 + +**章节来源** + +- [README.md:5-19](file://docs/components/base/auto_loading/README.md#L5-L19) +- [auto-loading.tsx:139-166](file://frontend/base/auto-loading/auto-loading.tsx#L139-L166) +- [useLoadingStatus.ts:44-50](file://frontend/base/auto-loading/useLoadingStatus.ts#L44-L50) + +## 结论 + +AutoLoading 通过“状态收集—条件渲染—UI 展示”的机制，为 Gradio 应用提供了统一且可定制的加载与错误反馈能力。其延迟初始化与计时器优化有助于提升性能与体验；插槽与配置项则满足多样化的业务需求。配合文档与示例，可在全局与局部场景中灵活使用。 + +[本节为总结性内容，不直接分析具体文件，故无“章节来源”] + +## 附录 + +### API 定义（参数与行为） + +- generating：是否纳入 generating 状态的处理。 +- show_error：是否显示错误信息。 +- show_mask：是否显示遮罩。 +- show_timer：是否显示计时器。 +- loading_text：自定义加载文案，为空时使用 Gradio 提供的默认文案（含耗时、队列位置等）。 + +默认行为 + +- pending：显示加载动画。 +- generating/completed：结束加载动画。 +- error：结束加载动画；可选显示错误信息。 + +**章节来源** + +- [README.md:27-36](file://docs/components/base/auto_loading/README.md#L27-L36) +- [auto-loading.tsx:65-138](file://frontend/base/auto-loading/auto-loading.tsx#L65-L138) + +### 使用示例（场景与建议） + +- 全局兜底：在应用根部放置一个 AutoLoading，确保任何请求都会得到加载反馈。 +- 局部精细控制：在需要更丰富加载信息的区域单独使用，结合 render 与 loadingText 插槽自定义展示。 +- 错误显隐：通过 show_error 控制错误信息是否展示；必要时使用 errorRender 自定义错误 UI。 +- 队列与进度：当后端使用 yield 流式返回时，可利用 progress 与队列信息增强用户感知。 + +**章节来源** + +- [README.md:21-25](file://docs/components/base/auto_loading/README.md#L21-L25) +- [auto-loading.tsx:72-138](file://frontend/base/auto-loading/auto-loading.tsx#L72-L138) + +### 与其他组件的协作模式 + +- 与表单/列表等组件协作：在这些组件内部使用 AutoLoading，可获得一致的加载与错误反馈。 +- 与主题系统协作：通过 Ant Design 主题 token 控制遮罩与错误提示的层级与外观。 +- 与状态上下文协作：通过加载状态上下文，多个子组件的状态会被聚合，由最近的 AutoLoading 决策展示。 + +**章节来源** + +- [Index.svelte:56-62](file://frontend/base/auto-loading/Index.svelte#L56-L62) +- [loading-status.svelte.ts:47-75](file://frontend/svelte-preprocess-react/svelte-contexts/loading-status.svelte.ts#L47-L75) +- [auto-loading.tsx:68-134](file://frontend/base/auto-loading/auto-loading.tsx#L68-L134) diff --git "a/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/Fragment \347\273\204\344\273\266.md" "b/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/Fragment \347\273\204\344\273\266.md" new file mode 100644 index 00000000..b55009c0 --- /dev/null +++ "b/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/Fragment \347\273\204\344\273\266.md" @@ -0,0 +1,328 @@ +# Fragment 组件 + + +**本文引用的文件** +- [frontend/base/fragment/fragment.tsx](file://frontend/base/fragment/fragment.tsx) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js) +- [backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js](file://backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js) +- [docs/components/base/fragment/README.md](file://docs/components/base/fragment/README.md) +- [docs/components/base/fragment/README-zh_CN.md](file://docs/components/base/fragment/README-zh_CN.md) +- [docs/components/base/fragment/demos/basic.py](file://docs/components/base/fragment/demos/basic.py) +- [frontend/svelte-preprocess-react/react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/renderItems.tsx](file://frontend/utils/renderItems.tsx) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/style.ts](file://frontend/utils/style.ts) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +Fragment 是一个“片段”容器组件，其设计目标是在不引入额外 DOM 节点的前提下，将多个子元素组合为一个整体，以便作为某些只接受模型内部组件的插槽（slot）的可插入内容。它常用于将来自外部生态（如 Gradio 按钮）的组件，包裹成符合模型内部组件规范的形式，从而顺利进入组件树。 + +- 设计目的：避免在布局上引入多余容器节点，同时保持子节点的逻辑分组与传递。 +- 使用场景：当组件插槽仅支持特定生态导出的组件时，将非受支持组件用 Fragment 包裹后传入。 +- 优势：减少不必要的 DOM 层级，降低布局开销；保持子节点的直接性与可维护性。 + +## 项目结构 + +Fragment 在前端与后端分别有对应的实现与模板，配合 React Slot 机制完成跨框架桥接与渲染。 + +```mermaid +graph TB +subgraph "前端" +FE_Fragment["frontend/base/fragment/fragment.tsx"] +FE_ReactSlot["frontend/svelte-preprocess-react/react-slot.tsx"] +FE_RenderSlot["frontend/utils/renderSlot.tsx"] +FE_RenderItems["frontend/utils/renderItems.tsx"] +FE_Style["frontend/utils/style.ts"] +end +subgraph "后端模板" +BE_Fragment["backend/.../fragment-sXw8Jnlf.js"] +BE_EachFragment["backend/.../fragment-BaGnla3s.js"] +end +subgraph "文档与示例" +DOC_Readme["docs/components/base/fragment/README.md"] +DOC_ReadmeCN["docs/components/base/fragment/README-zh_CN.md"] +DEMO_Basic["docs/components/base/fragment/demos/basic.py"] +end +FE_Fragment --> BE_Fragment +FE_Fragment --> BE_EachFragment +FE_ReactSlot --> FE_RenderSlot +FE_RenderItems --> FE_ReactSlot +FE_RenderSlot --> FE_ReactSlot +FE_Style --> FE_ReactSlot +DOC_Readme --> DEMO_Basic +DOC_ReadmeCN --> DEMO_Basic +``` + +图表来源 + +- [frontend/base/fragment/fragment.tsx:1-11](file://frontend/base/fragment/fragment.tsx#L1-L11) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:437-445](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L437-L445) +- [backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js:1-11](file://backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js#L1-L11) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) +- [docs/components/base/fragment/README.md:1-10](file://docs/components/base/fragment/README.md#L1-L10) +- [docs/components/base/fragment/README-zh_CN.md:1-10](file://docs/components/base/fragment/README-zh_CN.md#L1-L10) +- [docs/components/base/fragment/demos/basic.py:1-22](file://docs/components/base/fragment/demos/basic.py#L1-L22) + +章节来源 + +- [frontend/base/fragment/fragment.tsx:1-11](file://frontend/base/fragment/fragment.tsx#L1-L11) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:437-445](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L437-L445) +- [docs/components/base/fragment/README.md:1-10](file://docs/components/base/fragment/README.md#L1-L10) + +## 核心组件 + +- 前端 Fragment（React 包装） + - 通过 sveltify 将 Svelte 组件能力桥接到 React 生态，内部以 React Fragment 形式透传 children，不引入额外 DOM。 + - 典型路径：[frontend/base/fragment/fragment.tsx:4-8](file://frontend/base/fragment/fragment.tsx#L4-L8) + +- 后端 Fragment（运行时模板） + - 生成 React Fragment 的运行时包装，供桥接层渲染，确保 children 以片段形式挂载。 + - 典型路径：[backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:437-441](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L437-L441) + +- 后端 Each Fragment（Svelte 模板） + - 面向 Svelte 的 Fragment 实现，便于在 Svelte 场景下复用片段语义。 + - 典型路径：[backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js:2-6](file://backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js#L2-L6) + +章节来源 + +- [frontend/base/fragment/fragment.tsx:1-11](file://frontend/base/fragment/fragment.tsx#L1-L11) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:437-445](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L437-L445) +- [backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js:1-11](file://backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js#L1-L11) + +## 架构总览 + +Fragment 的工作流围绕“片段容器 + React Slot + 上下文桥接”展开：前端 Fragment 将 children 以 React Fragment 透传；React Slot 负责将 Svelte/HTML 结构克隆并以“内容显示”方式挂载到 React 子树，避免引入额外容器节点；渲染工具链负责参数、事件与样式在桥接过程中的合并与应用。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant MS as "模型组件树" +participant Frag as "Fragment(React)" +participant RS as "ReactSlot" +participant Bridge as "桥接层(后端模板)" +participant DOM as "浏览器DOM" +Dev->>MS : "在插槽中放置 Fragment" +MS->>Frag : "接收 children" +Frag->>Frag : "以 React Fragment 透传 children" +Frag->>RS : "通过桥接层创建 Slot 渲染" +RS->>Bridge : "请求克隆/挂载 Svelte/HTML 结构" +Bridge-->>RS : "返回片段化 children" +RS->>DOM : "以 display : contents 挂载，不引入额外容器" +RS-->>Dev : "渲染完成" +``` + +图表来源 + +- [frontend/base/fragment/fragment.tsx:4-8](file://frontend/base/fragment/fragment.tsx#L4-L8) +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:437-441](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L437-L441) + +## 详细组件分析 + +### 组件类图（代码级） + +```mermaid +classDiagram +class Fragment_Frontend { ++children? : ReactNode ++渲染 : React.Fragment(children) +} +class ReactSlot { ++slot : HTMLElement ++clone? : boolean ++className? : string ++style? : CSSProperties ++render() : ReactElement[] +} +class BridgeRuntime { ++reactComponent : React.FC ++props : any ++children : ReactNode[] ++createPortal(node, target) +} +Fragment_Frontend --> ReactSlot : "通过桥接层渲染" +ReactSlot --> BridgeRuntime : "克隆/挂载片段" +BridgeRuntime --> ReactSlot : "返回片段 children" +``` + +图表来源 + +- [frontend/base/fragment/fragment.tsx:4-8](file://frontend/base/fragment/fragment.tsx#L4-L8) +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:305-328](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L305-L328) + +章节来源 + +- [frontend/base/fragment/fragment.tsx:1-11](file://frontend/base/fragment/fragment.tsx#L1-L11) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:250-328](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L250-L328) + +### 渲染流程（片段化挂载） + +- React Slot 在挂载时将目标元素克隆为“内容显示”节点，避免引入额外容器层级。 +- 若开启克隆模式，会递归克隆子节点与事件监听器，并通过 Portal 将 React 子树挂载到克隆节点内。 +- 最终以 display: contents 的方式呈现，使子节点直接参与父容器的布局计算。 + +```mermaid +flowchart TD +Start(["开始"]) --> CheckClone{"是否启用克隆?"} +CheckClone --> |否| MountDirect["直接以 contents 显示"] +CheckClone --> |是| CloneTree["克隆节点树
复制事件监听器"] +CloneTree --> PortalAttach["通过 Portal 挂载 React 子树"] +PortalAttach --> MountDirect +MountDirect --> ApplyStyles["应用样式/类名"] +ApplyStyles --> End(["结束"]) +``` + +图表来源 + +- [frontend/svelte-preprocess-react/react-slot.tsx:158-202](file://frontend/svelte-preprocess-react/react-slot.tsx#L158-L202) +- [frontend/utils/style.ts:39-76](file://frontend/utils/style.ts#L39-L76) + +章节来源 + +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) + +### API/服务组件调用序列（片段桥接） + +```mermaid +sequenceDiagram +participant Caller as "调用方" +participant Bridge as "桥接运行时" +participant ReactComp as "React 组件" +participant Slot as "ReactSlot" +participant DOM as "DOM" +Caller->>Bridge : "传入 Fragment + children" +Bridge->>ReactComp : "以 Fragment 形式渲染" +ReactComp->>Slot : "创建 Slot 并请求克隆" +Slot->>DOM : "克隆节点并设置 display : contents" +Slot-->>ReactComp : "返回片段 children" +ReactComp-->>Caller : "渲染完成" +``` + +图表来源 + +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:305-328](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L305-L328) +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) + +章节来源 + +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:250-328](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L250-L328) + +### 复杂逻辑组件（片段与上下文合并） + +- 片段在桥接过程中会合并多处上下文（如样式、类名、事件等），并在忽略标志下跳过上下文影响。 +- 支持参数映射与强制克隆，确保在复杂布局中仍能稳定传递属性与事件。 + +```mermaid +flowchart TD +Params["收集参数/上下文"] --> MergeCtx["合并样式/类名/事件"] +MergeCtx --> IgnoreFlag{"是否忽略上下文?"} +IgnoreFlag --> |是| SkipCtx["跳过上下文影响"] +IgnoreFlag --> |否| ApplyCtx["应用上下文"] +ApplyCtx --> Render["渲染片段 children"] +SkipCtx --> Render +``` + +图表来源 + +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:286-304](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L286-L304) + +章节来源 + +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:228-328](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L228-L328) + +## 依赖关系分析 + +- Fragment 前端实现依赖 React 与 sveltify，后端模板依赖运行时渲染器与桥接工具。 +- React Slot 依赖样式工具与防抖钩子，保证克隆与挂载的稳定性。 +- 渲染工具链（renderSlot、renderItems、createItemsContext）提供参数、事件与上下文的统一处理入口。 + +```mermaid +graph LR +FragTS["fragment.tsx"] --> BE_JS["fragment-sXw8Jnlf.js"] +FragTS --> BE_Svelte["fragment-BaGnla3s.js"] +ReactSlot["react-slot.tsx"] --> StyleUtils["style.ts"] +RenderSlot["renderSlot.tsx"] --> ReactSlot +RenderItems["renderItems.tsx"] --> ReactSlot +CreateItems["createItemsContext.tsx"] --> RenderItems +``` + +图表来源 + +- [frontend/base/fragment/fragment.tsx:1-11](file://frontend/base/fragment/fragment.tsx#L1-L11) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:1-446](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L1-L446) +- [backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js:1-11](file://backend/modelscope_studio/components/base/each/templates/component/fragment-BaGnla3s.js#L1-L11) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) + +章节来源 + +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderItems.tsx:1-114](file://frontend/utils/renderItems.tsx#L1-L114) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +## 性能考量 + +- 减少 DOM 层级：Fragment 以 React Fragment 透传 children，避免额外容器节点，降低布局与重排成本。 +- 克隆策略：在需要时启用克隆，但应避免对大量节点频繁克隆；必要时结合参数映射与强制克隆，减少无效更新。 +- 变更观察：React Slot 使用 MutationObserver 观察变更，配合防抖与最小化重渲染，避免过度刷新。 +- 样式与类名：通过样式工具统一转换，避免重复计算与字符串拼接带来的开销。 +- 事件绑定：克隆时复制事件监听器，确保交互一致性，同时注意移除时机，防止内存泄漏。 + +## 故障排查指南 + +- 插槽不生效 + - 确认插槽仅支持特定生态组件，需用 Fragment 包裹后再传入。 + - 参考示例：[docs/components/base/fragment/demos/basic.py:14-19](file://docs/components/base/fragment/demos/basic.py#L14-L19) + +- 子元素未正确渲染或样式丢失 + - 检查是否启用了克隆模式；若未启用，可能无法正确应用样式与类名。 + - 参考实现：[frontend/svelte-preprocess-react/react-slot.tsx:158-202](file://frontend/svelte-preprocess-react/react-slot.tsx#L158-L202) + +- 事件未触发或重复绑定 + - 确认克隆过程中事件监听器已复制；检查卸载时是否清理。 + - 参考实现：[frontend/svelte-preprocess-react/react-slot.tsx:67-95](file://frontend/svelte-preprocess-react/react-slot.tsx#L67-L95) + +- 参数映射与上下文冲突 + - 使用参数映射与强制克隆，确保上下文合并顺序与覆盖规则符合预期。 + - 参考实现：[backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:286-304](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L286-L304) + +章节来源 + +- [docs/components/base/fragment/demos/basic.py:1-22](file://docs/components/base/fragment/demos/basic.py#L1-L22) +- [frontend/svelte-preprocess-react/react-slot.tsx:67-202](file://frontend/svelte-preprocess-react/react-slot.tsx#L67-L202) +- [backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js:286-304](file://backend/modelscope_studio/components/base/fragment/templates/component/fragment-sXw8Jnlf.js#L286-L304) + +## 结论 + +Fragment 组件通过“片段容器 + React Slot + 上下文桥接”的机制，在不引入额外 DOM 节点的前提下，实现了多子元素的组合与传递。它特别适用于需要将非受支持组件注入到严格插槽约束场景中的布局需求。配合参数映射、事件合并与样式工具，Fragment 在复杂布局中具备良好的稳定性与可维护性。 + +## 附录 + +- 使用示例（文档与演示） + - 基本用法与对比：[docs/components/base/fragment/demos/basic.py:14-19](file://docs/components/base/fragment/demos/basic.py#L14-L19) + - 中文文档说明：[docs/components/base/fragment/README-zh_CN.md:1-10](file://docs/components/base/fragment/README-zh_CN.md#L1-L10) + - 英文文档说明：[docs/components/base/fragment/README.md:1-10](file://docs/components/base/fragment/README.md#L1-L10) diff --git "a/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/Slot \347\273\204\344\273\266.md" "b/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/Slot \347\273\204\344\273\266.md" new file mode 100644 index 00000000..5e40bdc8 --- /dev/null +++ "b/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/Slot \347\273\204\344\273\266.md" @@ -0,0 +1,333 @@ +# Slot 组件 + + +**本文引用的文件** +- [frontend/base/slot/Index.svelte](file://frontend/base/slot/Index.svelte) +- [frontend/svelte-preprocess-react/react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/patchSlots.ts](file://frontend/utils/patchSlots.ts) +- [docs/components/base/slot/README.md](file://docs/components/base/slot/README.md) +- [docs/components/base/slot/README-zh_CN.md](file://docs/components/base/slot/README-zh_CN.md) +- [docs/components/base/slot/demos/basic.py](file://docs/components/base/slot/demos/basic.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件围绕 Slot 插槽组件进行系统化说明，涵盖设计理念、内容分发机制、动态插入与自定义渲染、插槽类型与作用域、参数传递与数据绑定、与父组件的通信方式、使用示例、最佳实践、性能优化建议、与模板系统的差异与优势，以及调试技巧与常见问题解决方案。本文以仓库中的 Slot 组件实现与文档为基础，结合前端渲染管线与上下文机制，帮助读者从原理到实践全面掌握插槽系统。 + +## 项目结构 + +Slot 组件在前端采用 Svelte 实现，负责收集子树并将其注册到父组件的插槽上下文中；在渲染阶段，ReactSlot 将 Svelte 渲染出的 DOM 结构克隆并挂载到 React 环境中，实现跨框架的内容分发与动态更新。 + +```mermaid +graph TB +subgraph "前端(Svelte)" +A["Index.svelte
Slot 组件"] +B["svelte 上下文
slot.svelte"] +end +subgraph "工具层" +C["patchSlots.ts
参数补丁"] +D["renderSlot.tsx
渲染入口"] +end +subgraph "React 端" +E["react-slot.tsx
ReactSlot 组件"] +end +A --> B +A --> C +D --> E +C --> D +B --> D +D --> E +``` + +图表来源 + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) + +章节来源 + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) + +## 核心组件 + +- Slot（Svelte）：负责接收父组件传入的插槽名与可选的参数映射函数，将自身作为“插槽容器”注册到上下文，并在可见性允许时渲染子节点。 +- ReactSlot（React）：在 React 环境中接收 Svelte 生成的 DOM 片段，支持克隆、事件复制、样式与类名注入、MutationObserver 观察变化并动态重渲染。 +- renderSlot：提供统一的渲染入口，支持强制克隆、参数透传与上下文包裹。 +- patchSlots：对插槽渲染函数进行包装，按顺序将额外参数前置或追加到插槽回调中，便于父组件向子插槽传递上下文参数。 + +章节来源 + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) + +## 架构总览 + +Slot 的工作流分为“注册阶段”和“渲染阶段”。父组件通过上下文 API 注册插槽键与参数映射；Slot 组件在 Svelte 中收集子树并绑定到 DOM；最终由 ReactSlot 在 React 环境中克隆并挂载，同时保持事件与样式一致性。 + +```mermaid +sequenceDiagram +participant Parent as "父组件" +participant SlotComp as "Slot(Index.svelte)" +participant Ctx as "Svelte 上下文(slot.svelte)" +participant Utils as "patchSlots/renderSlot" +participant RSlot as "ReactSlot(react-slot.tsx)" +Parent->>SlotComp : 传入 value/params_mapping +SlotComp->>Ctx : setSlotKey/setSlotParamsMapping +SlotComp->>Ctx : setSlot(prevKey, currentKey, slotDom) +SlotComp-->>Parent : 渲染子节点(隐藏的 svelte-slot) +Utils->>RSlot : renderSlot(el, options) +RSlot->>RSlot : 克隆元素/复制事件/注入样式/类名 +RSlot-->>Parent : 挂载到 React 环境 +``` + +图表来源 + +- [frontend/base/slot/Index.svelte:32-54](file://frontend/base/slot/Index.svelte#L32-L54) +- [frontend/utils/patchSlots.ts:15-31](file://frontend/utils/patchSlots.ts#L15-L31) +- [frontend/utils/renderSlot.tsx:13-28](file://frontend/utils/renderSlot.tsx#L13-L28) +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) + +## 详细组件分析 + +### Slot 组件（Svelte） + +- 职责 + - 接收插槽名与参数映射函数字符串。 + - 将当前插槽键与参数映射写入上下文，供父组件消费。 + - 在可见时渲染子节点，但隐藏实际的 svelte-slot 容器，避免影响布局。 +- 关键点 + - 使用上下文 API 设置插槽键与参数映射。 + - 通过 effect 监听插槽名变化，触发 setSlot 注册。 + - 子节点通过 svelte-slot bind:this 绑定到 DOM，以便 ReactSlot 后续克隆与挂载。 + +```mermaid +flowchart TD +Start(["进入组件"]) --> ReadProps["读取 value/params_mapping"] +ReadProps --> SetCtx["setSlotKey / setSlotParamsMapping"] +SetCtx --> Effect["$effect 监听 value 变化"] +Effect --> HasSlot{"slot 已存在且 value 有效？"} +HasSlot --> |是| Register["setSlot(prevKey, currentKey, slotDom)"] +HasSlot --> |否| Wait["等待/保持不变"] +Register --> Render["渲染子节点(隐藏 svelte-slot)"] +Wait --> Render +Render --> End(["完成"]) +``` + +图表来源 + +- [frontend/base/slot/Index.svelte:31-61](file://frontend/base/slot/Index.svelte#L31-L61) + +章节来源 + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) + +### ReactSlot（React） + +- 职责 + - 接收 Svelte 生成的 slot DOM，支持克隆与事件复制。 + - 注入样式与类名，处理 React Portal 以正确挂载子树。 + - 使用 MutationObserver 监视 slot 的变更，自动重新克隆与渲染。 +- 关键点 + - cloneElementWithEvents：递归克隆节点，复制事件监听器，处理嵌套 svelte-slot。 + - mountElementProps：在克隆后挂载类名与内联样式。 + - observeAttributes：可选观察属性变化，配合防抖提升稳定性。 + +```mermaid +flowchart TD +Enter(["ReactSlot 挂载"]) --> CheckClone{"是否克隆？"} +CheckClone --> |是| Observe["MutationObserver 观察 slot 变更"] +Observe --> Render["cloneElementWithEvents 克隆并生成 portals"] +Render --> Inject["注入类名/样式/挂载 props"] +Inject --> Append["追加到 ref.current"] +CheckClone --> |否| DirectMount["直接挂载 slot"] +DirectMount --> Append +Append --> Cleanup["卸载时清理样式/移除节点/断开观察者"] +``` + +图表来源 + +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) + +章节来源 + +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) + +### 参数补丁与渲染入口 + +- patchSlots + - 对插槽渲染函数进行包装，支持将外部参数以“前置/追加”的方式注入到插槽回调中。 + - 用于父组件向子插槽传递上下文参数，增强插槽的可配置性。 +- renderSlot + - 提供统一入口，支持强制克隆、参数透传与上下文包裹。 + - 当传入 params 或 forceClone 时，通过 ContextPropsProvider 包裹 ReactSlot，确保渲染一致性。 + +```mermaid +sequenceDiagram +participant Caller as "调用方" +participant Patch as "patchSlots" +participant Render as "renderSlot" +participant RSlot as "ReactSlot" +Caller->>Patch : 传入 params 与 transform +Patch-->>Caller : 返回包装后的渲染函数 +Caller->>Render : 传入 el 与 options(params/forceClone/clone) +Render->>Render : 判断是否需要 ContextPropsProvider 包裹 +Render-->>Caller : 返回 ReactSlot 组件 +Caller->>RSlot : 渲染 ReactSlot +RSlot-->>Caller : 克隆并挂载 slot +``` + +图表来源 + +- [frontend/utils/patchSlots.ts:15-31](file://frontend/utils/patchSlots.ts#L15-L31) +- [frontend/utils/renderSlot.tsx:13-28](file://frontend/utils/renderSlot.tsx#L13-L28) +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) + +章节来源 + +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) + +## 依赖关系分析 + +- 组件耦合 + - Slot 依赖 Svelte 上下文 API 进行插槽注册与参数映射设置。 + - ReactSlot 依赖 slot DOM 的结构特征（如内部 portal 与 svelte-slot 标签），以正确解析与克隆。 + - renderSlot 与 patchSlots 为渲染管线提供通用能力，解耦于具体组件。 +- 外部依赖 + - React、ReactDOM（Portal）、MutationObserver、lodash-es（防抖与对象判断）。 +- 潜在循环依赖 + - 通过工具层与上下文层分离，避免组件间直接循环引用。 + +```mermaid +graph LR +Slot["Slot(Index.svelte)"] --> Ctx["Svelte 上下文(slot.svelte)"] +Slot --> Patch["patchSlots.ts"] +Render["renderSlot.tsx"] --> RSlot["ReactSlot(react-slot.tsx)"] +Patch --> Render +Ctx --> Render +``` + +图表来源 + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) + +章节来源 + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/utils/patchSlots.ts:1-32](file://frontend/utils/patchSlots.ts#L1-L32) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) + +## 性能考量 + +- 克隆策略 + - 克隆会带来额外的 DOM 操作与事件复制成本。仅在必要时启用 clone，避免不必要的重渲染。 +- 观察器与防抖 + - MutationObserver 配合防抖可减少频繁变更导致的重复克隆，建议在复杂表格或高频率更新场景中开启 observeAttributes 并合理设置防抖间隔。 +- 样式与类名注入 + - 批量注入样式与类名优于逐项操作，避免多次回流。 +- 参数透传 + - 通过 patchSlots 将参数前置/追加，减少中间层的额外封装，降低函数调用栈深度。 + +## 故障排查指南 + +- 插槽未生效 + - 检查父组件是否已正确注册插槽键与参数映射。 + - 确认 Slot 组件的 value 是否为空或未变化（effect 仅在变化时注册）。 +- 样式丢失或类名不生效 + - 确认 ReactSlot 是否正确注入 className 与内联样式。 + - 检查是否存在样式隔离或覆盖。 +- 事件未响应 + - 确认 clone 是否启用，事件复制逻辑依赖克隆路径。 + - 检查事件监听器是否被覆盖或移除。 +- 更新不生效 + - 确认是否启用了 observeAttributes，以及 MutationObserver 是否被断开。 + - 检查是否有外部代码直接修改了 slot 内容而未触发观察。 + +章节来源 + +- [frontend/svelte-preprocess-react/react-slot.tsx:156-212](file://frontend/svelte-preprocess-react/react-slot.tsx#L156-L212) +- [frontend/base/slot/Index.svelte:31-61](file://frontend/base/slot/Index.svelte#L31-L61) + +## 结论 + +Slot 组件通过 Svelte 与 React 的桥接，实现了跨框架的内容分发与动态渲染。其设计强调： + +- 明确的插槽注册与参数映射机制； +- 基于克隆与事件复制的稳定渲染； +- 可选的观察器与防抖策略，兼顾灵活性与性能； +- 工具层抽象（patchSlots、renderSlot）提升复用性与可维护性。 + +## 附录 + +### 插槽类型与作用域 + +- 插槽类型 + - 命名插槽：通过 value 指定插槽名，父组件按名接收。 + - 嵌套插槽：子插槽可再次包含插槽，形成多级内容分发。 +- 作用域 + - params_mapping 支持将父组件上下文参数映射到插槽作用域，实现参数驱动的渲染。 + +章节来源 + +- [docs/components/base/slot/README.md:13-16](file://docs/components/base/slot/README.md#L13-L16) +- [docs/components/base/slot/README-zh_CN.md:13-16](file://docs/components/base/slot/README-zh_CN.md#L13-L16) + +### 数据绑定与父组件通信 + +- 父组件通过上下文 API 注册插槽键与参数映射。 +- Slot 组件在 Svelte 中收集子树并通过 setSlot 完成注册。 +- ReactSlot 在渲染阶段克隆并挂载，保持事件与样式一致。 + +章节来源 + +- [frontend/base/slot/Index.svelte:32-54](file://frontend/base/slot/Index.svelte#L32-L54) +- [frontend/svelte-preprocess-react/react-slot.tsx:109-223](file://frontend/svelte-preprocess-react/react-slot.tsx#L109-L223) + +### 使用示例 + +- 基础示例：在 Card 组件中插入标题与额外按钮及图标插槽。 +- 示例路径：[docs/components/base/slot/demos/basic.py:1-23](file://docs/components/base/slot/demos/basic.py#L1-L23) + +章节来源 + +- [docs/components/base/slot/demos/basic.py:1-23](file://docs/components/base/slot/demos/basic.py#L1-L23) + +### 最佳实践 + +- 仅在必要时启用 clone 与 observeAttributes，避免过度渲染。 +- 使用 patchSlots 将参数前置/追加，减少中间层封装。 +- 对复杂表格等高频更新场景，开启 observeAttributes 并配合防抖。 +- 保持插槽键的唯一性与稳定性，避免重复注册导致的冲突。 + +### 与模板系统的区别与优势 + +- 区别 + - 模板系统通常在编译期确定结构；插槽系统在运行时动态分发内容。 +- 优势 + - 更强的组合性与可扩展性，适合跨框架与多组件协作。 + - 参数映射与上下文注入使插槽具备更强的表现力与可控性。 diff --git "a/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/\345\237\272\347\241\200\347\273\204\344\273\266.md" "b/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/\345\237\272\347\241\200\347\273\204\344\273\266.md" new file mode 100644 index 00000000..996ced28 --- /dev/null +++ "b/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/\345\237\272\347\241\200\347\273\204\344\273\266.md" @@ -0,0 +1,505 @@ +# 基础组件 + + +**本文引用的文件** +- [backend/modelscope_studio/components/base/application/__init__.py](file://backend/modelscope_studio/components/base/application/__init__.py) +- [backend/modelscope_studio/components/base/auto_loading/__init__.py](file://backend/modelscope_studio/components/base/auto_loading/__init__.py) +- [backend/modelscope_studio/components/base/slot/__init__.py](file://backend/modelscope_studio/components/base/slot/__init__.py) +- [backend/modelscope_studio/components/base/fragment/__init__.py](file://backend/modelscope_studio/components/base/fragment/__init__.py) +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [frontend/base/application/Index.svelte](file://frontend/base/application/Index.svelte) +- [frontend/base/auto-loading/Index.svelte](file://frontend/base/auto-loading/Index.svelte) +- [frontend/base/slot/Index.svelte](file://frontend/base/slot/Index.svelte) +- [frontend/base/fragment/Index.svelte](file://frontend/base/fragment/Index.svelte) +- [frontend/base/each/Index.svelte](file://frontend/base/each/Index.svelte) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/renderParamsSlot.tsx](file://frontend/utils/renderParamsSlot.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本篇文档聚焦 ModelScope Studio 的“基础组件”体系，系统讲解 Application、AutoLoading、Slot、Fragment 等核心组件的设计理念、数据与控制流、在整体组件体系中的作用与协作方式，并提供使用示例、最佳实践、性能优化建议与常见问题解决方案。目标是帮助开发者快速理解并正确使用这些基础组件来构建复杂界面。 + +## 项目结构 + +基础组件位于后端 Python 模块与前端 Svelte 实现之间，通过统一的组件基类与上下文机制进行桥接。后端负责定义组件类、事件与插槽能力、数据模型与生命周期钩子；前端负责渲染、插槽解析、状态管理与异步加载。 + +```mermaid +graph TB +subgraph "后端" +PY_APP["Application 组件
application/__init__.py"] +PY_AUTO["AutoLoading 组件
auto_loading/__init__.py"] +PY_SLOT["Slot 组件
slot/__init__.py"] +PY_FRAG["Fragment 组件
fragment/__init__.py"] +PY_BASE_INIT["基础组件导出
base/__init__.py"] +PY_DEV_COMP["组件基类
utils/dev/component.py"] +end +subgraph "前端" +FE_APP["Application 前端入口
base/application/Index.svelte"] +FE_AUTO["AutoLoading 前端入口
base/auto-loading/Index.svelte"] +FE_SLOT["Slot 前端入口
base/slot/Index.svelte"] +FE_FRAG["Fragment 前端入口
base/fragment/Index.svelte"] +FE_EACH["Each 前端入口
base/each/Index.svelte"] +FE_RENDER_SLOT["renderSlot 工具
utils/renderSlot.tsx"] +FE_RENDER_PARAMS_SLOT["renderParamsSlot 工具
utils/renderParamsSlot.tsx"] +end +PY_APP --> FE_APP +PY_AUTO --> FE_AUTO +PY_SLOT --> FE_SLOT +PY_FRAG --> FE_FRAG +PY_BASE_INIT --> PY_APP +PY_BASE_INIT --> PY_AUTO +PY_BASE_INIT --> PY_SLOT +PY_BASE_INIT --> PY_FRAG +PY_DEV_COMP --> PY_APP +PY_DEV_COMP --> PY_AUTO +PY_DEV_COMP --> PY_SLOT +PY_DEV_COMP --> PY_FRAG +FE_SLOT --> FE_RENDER_SLOT +FE_SLOT --> FE_RENDER_PARAMS_SLOT +FE_AUTO --> FE_EACH +``` + +**图表来源** + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:8-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L8-L65) +- [backend/modelscope_studio/components/base/slot/**init**.py:8-50](file://backend/modelscope_studio/components/base/slot/__init__.py#L8-L50) +- [backend/modelscope_studio/components/base/fragment/**init**.py:8-49](file://backend/modelscope_studio/components/base/fragment/__init__.py#L8-L49) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +**章节来源** + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +## 核心组件 + +本节对 Application、AutoLoading、Slot、Fragment 和 Each 的职责、特性与使用方式进行概览式说明。 + +- Application（应用容器） + - 职责：作为顶层布局容器，承载页面级事件绑定（自定义事件、挂载、窗口大小变化、卸载），并提供页面环境数据（屏幕尺寸、语言、主题、UA）。 + - 关键点：支持事件监听器注册；作为应用上下文根节点，确保子组件均在有效应用上下文中创建。 + - 典型用法：在应用入口处放置，内部嵌套其他基础或业务组件；通过事件监听器处理浏览器生命周期与交互。 + +- AutoLoading（自动加载占位） + - 职责：根据生成状态、错误状态与遮罩/计时器等配置，自动切换加载态、错误态与内容渲染；支持命名插槽（render、errorRender、loadingText）以灵活定制。 + - 关键点：skip_api 标记为真，避免重复 API 调用；通过前端上下文读取加载状态并联动插槽渲染。 + - 典型用法：包裹需要懒加载或条件渲染的内容区域；结合业务逻辑动态设置 generating/showError。 + +- Slot（插槽） + - 职责：声明与注册命名插槽，支持参数映射函数，将 DOM 插槽与 React/JSX 内容进行桥接；可嵌套形成层级化插槽键。 + - 关键点：通过上下文设置插槽键与参数映射；在渲染时由工具函数将插槽内容克隆并注入到目标元素。 + - 典型用法：在父组件中声明插槽，在子组件中按需渲染；用于复杂布局与条件渲染。 + +- Fragment（片段） + - 职责：轻量容器，不引入额外 DOM 包装，仅承载子节点与插槽；常用于条件渲染、列表项包装等场景。 + - 关键点：skip_api 标记为真；不触发额外渲染开销；可配合 Each/Slot 使用。 + - 典型用法：在 Each 中作为列表项容器；在条件分支中包裹多个子节点而不增加额外层级。 + +- Each（列表渲染） + - 职责：为列表或数组数据提供批量渲染能力，将列表中的每个元素与对应的插槽/Fragment 进行参数映射和渲染。 + - 关键点：仅为前端纯渲染组件，无对应后端 Python 类；配合 Fragment 使用实现列表项渲染，配合 Slot 实现参数映射插槽。 + - 参数映射：通过 Slot 的 params_mapping 属性，将列表元素的当前条目和索引注入到子组件插槽中。 + - 典型用法：将 ms.Each 包裹在支持条目渲染的父组件内部，配合 ms.Fragment 和 ms.Slot（带 params_mapping）实现列表动态渲染。 + +**章节来源** + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:8-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L8-L65) +- [backend/modelscope_studio/components/base/slot/**init**.py:8-50](file://backend/modelscope_studio/components/base/slot/__init__.py#L8-L50) +- [backend/modelscope_studio/components/base/fragment/**init**.py:8-49](file://backend/modelscope_studio/components/base/fragment/__init__.py#L8-L49) +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +## 架构总览 + +下图展示了基础组件从后端到前端的整体调用链路与协作关系。 + +```mermaid +sequenceDiagram +participant PyApp as "后端 Application" +participant PyAuto as "后端 AutoLoading" +participant PySlot as "后端 Slot" +participant PyFrag as "后端 Fragment" +participant FeApp as "前端 Application" +participant FeAuto as "前端 AutoLoading" +participant FeSlot as "前端 Slot" +participant FeFrag as "前端 Fragment" +participant Utils as "渲染工具(renderSlot/renderParamsSlot)" +PyApp->>FeApp : 初始化并绑定事件 +PyAuto->>FeAuto : 配置生成/错误/遮罩/文本 +PySlot->>FeSlot : 注册插槽键与参数映射 +FeSlot->>Utils : 渲染插槽(可克隆/强制克隆/传参) +Utils-->>FeSlot : 返回 ReactSlot 渲染结果 +PyFrag->>FeFrag : 作为容器承载子节点 +FeAuto->>FeFrag : 在加载/错误/内容间切换 +``` + +**图表来源** + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:8-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L8-L65) +- [backend/modelscope_studio/components/base/slot/**init**.py:8-50](file://backend/modelscope_studio/components/base/slot/__init__.py#L8-L50) +- [backend/modelscope_studio/components/base/fragment/**init**.py:8-49](file://backend/modelscope_studio/components/base/fragment/__init__.py#L8-L49) +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +## 详细组件分析 + +### Application 组件 + +- 设计理念 + - 作为应用级根容器，集中处理浏览器生命周期事件与页面环境信息，为上层组件提供一致的运行时上下文。 + - 通过事件监听器扩展应用行为边界，如自定义事件分发、挂载/卸载回调、窗口尺寸变化响应。 +- 数据模型 + - 页面屏幕数据（宽高、滚动位置）、语言、主题、用户代理等，便于前端适配不同设备与主题。 +- 前端实现要点 + - 异步导入实际组件，延迟渲染以提升首屏性能。 + - 将 children 透传给子组件，保持树形结构的灵活性。 +- 使用示例路径 + - 在应用入口创建 Application，并在其内部组织页面布局与业务组件。 + - 示例参考：[frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) + +```mermaid +classDiagram +class ModelScopeApplication { ++EVENTS ++SLOTS ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class ModelScopeDataLayoutComponent { ++skip_api ++__exit__() ++__init__(...) +} +ModelScopeApplication --|> ModelScopeDataLayoutComponent : "继承" +``` + +**图表来源** + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [backend/modelscope_studio/utils/dev/component.py:101-169](file://backend/modelscope_studio/utils/dev/component.py#L101-L169) + +**章节来源** + +- [backend/modelscope_studio/components/base/application/**init**.py:26-115](file://backend/modelscope_studio/components/base/application/__init__.py#L26-L115) +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) + +### AutoLoading 组件 + +- 设计理念 + - 自动化处理“生成中/错误/加载文本”等状态，减少业务侧样板代码；通过插槽实现高度可定制。 +- 关键属性 + - generating：是否处于生成中 + - show_error：是否显示错误态 + - show_mask/show_timer：遮罩与计时器开关 + - loading_text：自定义加载文案 + - 支持插槽：render、errorRender、loadingText +- 前端实现要点 + - 通过上下文读取加载状态，决定渲染哪一类内容。 + - 通过 processProps 与 getSlots 将后端传递的属性与插槽映射到前端组件。 +- 使用示例路径 + - 在需要懒加载或条件渲染的区域包裹 AutoLoading，并根据业务状态切换 generating/showError。 + - 示例参考：[frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) + +```mermaid +flowchart TD +Start(["进入 AutoLoading"]) --> CheckVisible["检查可见性"] +CheckVisible --> |不可见| End(["结束"]) +CheckVisible --> |可见| ReadCtx["读取加载状态(generating/error)"] +ReadCtx --> Decide{"选择渲染内容"} +Decide --> |生成中| RenderLoading["渲染 loadingText 插槽"] +Decide --> |错误| RenderError["渲染 errorRender 插槽"] +Decide --> |正常| RenderContent["渲染 render 插槽/默认内容"] +RenderLoading --> End +RenderError --> End +RenderContent --> End +``` + +**图表来源** + +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) + +**章节来源** + +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:8-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L8-L65) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) + +### Slot 组件 + +- 设计理念 + - 提供命名插槽与参数映射能力，将 Svelte 插槽与 React/JSX 渲染桥接，支持嵌套插槽键与动态参数。 +- 关键属性 + - value：插槽键名（支持嵌套） + - params_mapping：参数映射函数字符串，运行时转换为函数 +- 前端实现要点 + - 通过上下文设置当前插槽键与参数映射函数。 + - 使用 renderSlot/renderParamsSlot 将插槽内容克隆并注入到目标元素，支持强制克隆与多目标渲染。 +- 使用示例路径 + - 在父组件中声明 Slot，在子组件中按需渲染；或在 Each 中配合参数映射实现动态渲染。 + - 示例参考：[frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68)，[frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29)，[frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +```mermaid +sequenceDiagram +participant Parent as "父组件(Slot)" +participant Ctx as "插槽上下文" +participant Utils as "renderSlot/renderParamsSlot" +participant Child as "子组件" +Parent->>Ctx : 设置插槽键与参数映射 +Parent->>Utils : 请求渲染插槽(可克隆/强制克隆/传参) +Utils-->>Parent : 返回 ReactSlot 渲染结果 +Parent->>Child : 透传渲染结果 +``` + +**图表来源** + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +**章节来源** + +- [backend/modelscope_studio/components/base/slot/**init**.py:8-50](file://backend/modelscope_studio/components/base/slot/__init__.py#L8-L50) +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +### Fragment 组件 + +- 设计理念 + - 作为轻量容器，不引入额外 DOM 包装，仅承载子节点与插槽；适合条件渲染与列表项包装。 +- 前端实现要点 + - 通过异步导入实际组件，延迟渲染；在可见性为真时才渲染。 + - 不重置插槽键，避免影响兄弟节点的插槽状态。 +- 使用示例路径 + - 在 Each 或条件渲染中作为列表项容器；在需要无包裹容器时优先选择 Fragment。 + - 示例参考：[frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + +```mermaid +flowchart TD +Enter(["进入 Fragment"]) --> Visible{"是否可见?"} +Visible --> |否| Exit(["退出"]) +Visible --> |是| AsyncLoad["异步加载 Fragment 组件"] +AsyncLoad --> Render["渲染子节点/插槽"] +Render --> Exit +``` + +**图表来源** + +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + +**章节来源** + +- [backend/modelscope_studio/components/base/fragment/**init**.py:8-49](file://backend/modelscope_studio/components/base/fragment/__init__.py#L8-L49) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + +### Each 组件 + +- 设计理念 + - Each 是专为列表渲染设计的前端轻量组件，无对应的后端 Python 类。它允许基于数组数据批量实例化子组件，配合 Fragment 与 Slot 可实现参数化动态渲染。 +- 与 Fragment 的配合使用 + - 在 Each 的每个条目中使用 Fragment 作为轻量容器，避免引入额外 DOM 包装层级。 + - Fragment 的 `visible` 控制是否渲染当前条目，适合条件式列表。 + - 典型用法：在展示列表元素时，将列表容器组件中的每个条目渲染到一个 Fragment 中。 +- 参数映射（params_mapping） + - 在 Slot 组件上设置 `params_mapping` 属性，可将当前条目值（item）和索引（index）注入到插槽内容中。 + - `params_mapping` 是一个 JavaScript 字符串函数，运行时转换为函数，接收 `(item, index)` 并返回插槽参数对象。 + - 示例：`params_mapping="lambda item, index: {'children': item['label']}"` 将每个条目的 label 字段作为 children 渲染。 +- 前端实现要点 + - Each 通过合并上下文值与子项值，将列表元素传递给子组件插槽。 + - 支持嵌套 Each，内层通过 subIndex 防止插槽键冲突。 + - 需要时可配置 `forceClone`，确保每个条目拥有独立的插槽实例。 + - 示例参考：[frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +```mermaid +sequenceDiagram +participant PY as "后端父组件(items 属性)" +participant Each as "Each(前端)" +participant Frag as "Fragment(前端)" +participant Slot as "Slot(params_mapping)" +participant Child as "子组件插槽" +PY->>Each : 传入 items 数组 +Each->>Frag : 对每个 item 创建 Fragment +Frag->>Slot : 进入命名插槽 +Slot->>Child : params_mapping 将 item/index 注入到子组件 +Child-->>Each : 渲染列表项 UI +``` + +**图表来源** + +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +**章节来源** + +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + +### 组件基类与上下文 + +- ModelScopeLayoutComponent / ModelScopeComponent / ModelScopeDataLayoutComponent + - 统一处理组件生命周期、样式与内部索引；在 BlockContext 下参与布局树管理。 + - skip_api 控制是否跳过 API 层面的重复渲染或处理。 +- AppContext + - 确保所有基础组件在有效的应用上下文中创建，避免运行时错误。 + +```mermaid +classDiagram +class ModelScopeComponent { ++EVENTS ++skip_api ++__init__(...) +} +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__() ++__init__(...) +} +class ModelScopeDataLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__() ++__init__(...) +} +ModelScopeLayoutComponent --|> ModelScopeComponent : "继承" +ModelScopeDataLayoutComponent --|> ModelScopeComponent : "继承" +ModelScopeDataLayoutComponent --|> BlockContext : "混入" +``` + +**图表来源** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +**章节来源** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +## 依赖分析 + +- 后端导出 + - 基础组件通过 base/**init**.py 导出，统一对外接口，便于上层模块按需引入。 +- 组件间耦合 + - Application 作为根容器，其余组件围绕其展开；AutoLoading 与 Fragment 常作为通用容器；Slot 为跨组件插槽桥接的核心。 +- 外部依赖 + - 前端通过 @svelte-preprocess-react 与上下文系统实现 Svelte 与 React 的桥接；渲染工具提供插槽克隆与参数注入能力。 + +```mermaid +graph LR +Export["base/__init__.py 导出"] --> App["Application"] +Export --> Auto["AutoLoading"] +Export --> Slot["Slot"] +Export --> Frag["Fragment"] +App --> FeApp["frontend/base/application/Index.svelte"] +Auto --> FeAuto["frontend/base/auto-loading/Index.svelte"] +Slot --> FeSlot["frontend/base/slot/Index.svelte"] +Frag --> FeFrag["frontend/base/fragment/Index.svelte"] +FeSlot --> RenderSlot["utils/renderSlot.tsx"] +FeSlot --> RenderParams["utils/renderParamsSlot.tsx"] +``` + +**图表来源** + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +**章节来源** + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +## 性能考虑 + +- 延迟加载与可见性控制 + - Application/AutoLoading/Fragment 均采用异步导入与可见性判断，减少首屏渲染压力。 +- 插槽渲染优化 + - 使用 renderSlot/renderParamsSlot 时，合理设置 clone/forceClone 与 params，避免不必要的重复渲染。 +- Each 列表渲染 + - Each 支持合并值与上下文，必要时强制克隆以保证独立状态；注意在深层 Each 中维护 slotKey 与 subIndex，避免插槽键冲突。 +- 事件绑定 + - Application 的事件监听器仅在需要时启用，避免无谓的事件处理开销。 + +[本节为通用指导，无需特定文件引用] + +## 故障排查指南 + +- 插槽未生效 + - 检查 Slot 的 value 是否正确设置，以及父组件是否已注册对应插槽键。 + - 确认 renderSlot/renderParamsSlot 的参数是否正确传入（clone/forceClone/params）。 + - 参考：[frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68)，[frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29)，[frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- AutoLoading 未按预期切换 + - 确认 generating/showError 状态是否正确传递至前端；检查插槽名称是否匹配（render/errorRender/loadingText）。 + - 参考：[frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- Fragment 未渲染 + - 检查 visible 属性与异步加载是否完成；确认未误用 shouldResetSlotKey 导致插槽键丢失。 + - 参考：[frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- Each 列表错位或插槽冲突 + - 确保 Each 的上下文值与子项值正确合并；在嵌套 Each 中维护 subIndex 与 slotKey。 + - 参考：[frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +**章节来源** + +- [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) +- [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) +- [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) +- [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + +## 结论 + +基础组件体系以 Application 为根、AutoLoading 为通用容器、Slot 为跨组件桥接、Fragment 为轻量容器，配合统一的组件基类与上下文机制，实现了前后端协同、事件与插槽解耦、渲染性能可控的架构设计。遵循本文的最佳实践与排障建议，开发者可以高效地使用这些组件构建复杂且高性能的界面。 + +[本节为总结性内容，无需特定文件引用] + +## 附录 + +- 快速上手清单 + - 在应用入口放置 Application，确保全局上下文可用。 + - 对需要懒加载的区域使用 AutoLoading，并根据业务状态切换生成/错误态。 + - 使用 Slot 声明命名插槽，配合 renderSlot/renderParamsSlot 进行渲染。 + - 在列表或条件渲染中使用 Fragment 作为无包裹容器。 +- 相关实现参考路径 + - [frontend/base/application/Index.svelte:1-17](file://frontend/base/application/Index.svelte#L1-L17) + - [frontend/base/auto-loading/Index.svelte:1-81](file://frontend/base/auto-loading/Index.svelte#L1-L81) + - [frontend/base/slot/Index.svelte:1-68](file://frontend/base/slot/Index.svelte#L1-L68) + - [frontend/base/fragment/Index.svelte:1-50](file://frontend/base/fragment/Index.svelte#L1-L50) + - [frontend/base/each/Index.svelte:1-111](file://frontend/base/each/Index.svelte#L1-L111) + - [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) + - [frontend/utils/renderParamsSlot.tsx:1-51](file://frontend/utils/renderParamsSlot.tsx#L1-L51) + +[本节为补充材料，无需特定文件引用] diff --git "a/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/\345\270\203\345\261\200\347\273\204\344\273\266.md" "b/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/\345\270\203\345\261\200\347\273\204\344\273\266.md" new file mode 100644 index 00000000..106df538 --- /dev/null +++ "b/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/\345\270\203\345\261\200\347\273\204\344\273\266.md" @@ -0,0 +1,386 @@ +# 布局组件 + + +**本文引用的文件** +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/components/base/div/__init__.py](file://backend/modelscope_studio/components/base/div/__init__.py) +- [backend/modelscope_studio/components/base/span/__init__.py](file://backend/modelscope_studio/components/base/span/__init__.py) +- [backend/modelscope_studio/components/base/text/__init__.py](file://backend/modelscope_studio/components/base/text/__init__.py) +- [backend/modelscope_studio/components/base/markdown/__init__.py](file://backend/modelscope_studio/components/base/markdown/__init__.py) +- [frontend/base/package.json](file://frontend/base/package.json) +- [frontend/base/div/Index.svelte](file://frontend/base/div/Index.svelte) +- [frontend/base/span/Index.svelte](file://frontend/base/span/Index.svelte) +- [frontend/base/text/Index.svelte](file://frontend/base/text/Index.svelte) +- [frontend/base/markdown/Index.svelte](file://frontend/base/markdown/Index.svelte) +- [frontend/base/div/div.tsx](file://frontend/base/div/div.tsx) +- [frontend/base/span/span.tsx](file://frontend/base/span/span.tsx) +- [frontend/base/text/text.tsx](file://frontend/base/text/text.tsx) +- [frontend/base/markdown/markdown.tsx](file://frontend/base/markdown/markdown.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件系统性梳理模型空间（ModelScope Studio）中“布局组件”系列，重点覆盖 Div、Span、Text、Markdown 四类基础布局与内容组件。文档从架构、数据流、处理逻辑、样式与主题适配、组合与嵌套最佳实践、性能特性与优化建议、以及常见问题与调试技巧等维度进行深入说明，帮助开发者在页面布局与内容展示中高效、稳定地使用这些组件。 + +## 项目结构 + +布局组件位于后端 Python 组件层与前端 Svelte/React 层之间，采用“Python 组件定义 + Svelte 包装 + React 实现”的分层设计： + +- 后端：通过 Python 类定义组件行为、事件绑定、预处理/后处理逻辑，并声明前端资源目录。 +- 前端 Svelte 层：负责属性透传、可见性控制、样式与类名拼接、插槽（slots）解析与渲染。 +- React 层：具体 HTML 元素包装（如 div/span），或基于全局组件（如 Markdown）进行渲染。 + +```mermaid +graph TB +subgraph "后端" +PY_DIV["Python: Div 组件"] +PY_SPAN["Python: Span 组件"] +PY_TEXT["Python: Text 组件"] +PY_MD["Python: Markdown 组件"] +end +subgraph "前端(Svelte)" +SV_DIV["Svelte: div/Index.svelte"] +SV_SPAN["Svelte: span/Index.svelte"] +SV_TEXT["Svelte: text/Index.svelte"] +SV_MD["Svelte: markdown/Index.svelte"] +end +subgraph "前端(React)" +RX_DIV["React: div.tsx"] +RX_SPAN["React: span.tsx"] +RX_TEXT["React: text.tsx"] +RX_MD["React: markdown.tsx"] +end +PY_DIV --> SV_DIV --> RX_DIV +PY_SPAN --> SV_SPAN --> RX_SPAN +PY_TEXT --> SV_TEXT --> RX_TEXT +PY_MD --> SV_MD --> RX_MD +``` + +图表来源 + +- [backend/modelscope_studio/components/base/div/**init**.py:10-86](file://backend/modelscope_studio/components/base/div/__init__.py#L10-L86) +- [backend/modelscope_studio/components/base/span/**init**.py:10-87](file://backend/modelscope_studio/components/base/span/__init__.py#L10-L87) +- [backend/modelscope_studio/components/base/text/**init**.py:8-57](file://backend/modelscope_studio/components/base/text/__init__.py#L8-L57) +- [backend/modelscope_studio/components/base/markdown/**init**.py:11-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L11-L174) +- [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) +- [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) +- [frontend/base/div/div.tsx:1-18](file://frontend/base/div/div.tsx#L1-L18) +- [frontend/base/span/span.tsx:1-20](file://frontend/base/span/span.tsx#L1-L20) +- [frontend/base/text/text.tsx:1-11](file://frontend/base/text/text.tsx#L1-L11) +- [frontend/base/markdown/markdown.tsx:1-35](file://frontend/base/markdown/markdown.tsx#L1-L35) + +章节来源 + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [frontend/base/package.json:1-6](file://frontend/base/package.json#L1-L6) + +## 核心组件 + +本节对四个基础布局组件进行功能与用法概览，强调其在页面布局与内容展示中的定位与职责。 + +- Div + - 定位：块级容器，用于承载子元素或文本值；支持鼠标/滚轮等通用交互事件绑定。 + - 关键点：可接收额外属性透传，支持可见性、元素 ID、类名、内联样式等通用属性。 + - 适用场景：卡片背景、区域划分、复杂嵌套布局的外层容器。 + +- Span + - 定位：行内容器，适合包裹短文本或内联元素；同样支持通用交互事件。 + - 关键点：当存在子节点时优先渲染子节点，否则回退到 value 或子节点。 + - 适用场景：内联高亮、标签、按钮组内的文本片段。 + +- Text + - 定位：纯文本输出组件，无额外容器包装，直接渲染字符串。 + - 关键点：无事件绑定，仅处理 value；适合最小成本的文本渲染。 + - 适用场景：标题、段落、提示文案等轻量文本。 + +- Markdown + - 定位：富文本渲染组件，支持复制按钮插槽、LaTeX 数学公式、HTML 安全策略、换行与标题链接等选项。 + - 关键点：支持 copyButtons 插槽；后处理会清理缩进；主题模式与根路径透传给底层组件。 + - 适用场景：帮助文档、说明文本、动态生成的富文本内容。 + +章节来源 + +- [backend/modelscope_studio/components/base/div/**init**.py:10-86](file://backend/modelscope_studio/components/base/div/__init__.py#L10-L86) +- [backend/modelscope_studio/components/base/span/**init**.py:10-87](file://backend/modelscope_studio/components/base/span/__init__.py#L10-L87) +- [backend/modelscope_studio/components/base/text/**init**.py:8-57](file://backend/modelscope_studio/components/base/text/__init__.py#L8-L57) +- [backend/modelscope_studio/components/base/markdown/**init**.py:11-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L11-L174) + +## 架构总览 + +下图展示了从后端组件到前端渲染的整体调用链路与数据流： + +```mermaid +sequenceDiagram +participant Py as "后端组件(Python)" +participant Svelte as "前端包装(Svelte)" +participant React as "React 实现" +participant DOM as "DOM" +Py->>Svelte : 初始化并传递属性(visible/elem_*/value等) +Svelte->>Svelte : 处理属性透传/可见性/样式/类名 +Svelte->>React : 渲染对应 React 组件 +React->>DOM : 输出最终 HTML 节点(div/span/text/markdown) +DOM-->>React : 事件回调(如 click/mouseover/scroll) +React-->>Svelte : 触发事件更新 +Svelte-->>Py : 事件回调触发(由后端事件监听器绑定) +``` + +图表来源 + +- [backend/modelscope_studio/components/base/div/**init**.py:14-39](file://backend/modelscope_studio/components/base/div/__init__.py#L14-L39) +- [backend/modelscope_studio/components/base/span/**init**.py:14-39](file://backend/modelscope_studio/components/base/span/__init__.py#L14-L39) +- [backend/modelscope_studio/components/base/markdown/**init**.py:15-46](file://backend/modelscope_studio/components/base/markdown/__init__.py#L15-L46) +- [frontend/base/div/Index.svelte:22-47](file://frontend/base/div/Index.svelte#L22-L47) +- [frontend/base/span/Index.svelte:21-46](file://frontend/base/span/Index.svelte#L21-L46) +- [frontend/base/text/Index.svelte:15-29](file://frontend/base/text/Index.svelte#L15-L29) +- [frontend/base/markdown/Index.svelte:19-44](file://frontend/base/markdown/Index.svelte#L19-L44) +- [frontend/base/div/div.tsx:12-15](file://frontend/base/div/div.tsx#L12-L15) +- [frontend/base/span/span.tsx:12-17](file://frontend/base/span/span.tsx#L12-L17) +- [frontend/base/text/text.tsx:4-8](file://frontend/base/text/text.tsx#L4-L8) +- [frontend/base/markdown/markdown.tsx:8-32](file://frontend/base/markdown/markdown.tsx#L8-L32) + +## 详细组件分析 + +### Div 组件 + +- 设计要点 + - 作为块级容器，内部优先渲染子节点，若无子节点则回退到 value 字符串。 + - 支持通用交互事件绑定（click、dblclick、mousedown、mouseup、mouseover、mouseout、mousemove、scroll）。 + - 可透传额外属性，配合 elem_id、elem_classes、elem_style 进行样式与定位控制。 +- 数据流与处理逻辑 + - 预处理/后处理均保持字符串不变；可见性由 Svelte 层统一控制。 +- 使用建议 + - 适合大范围布局分区与复杂嵌套；避免在需要行内语义的场景使用。 + - 与 Grid/Flex 等布局结合时，注意不要引入不必要的层级。 + +```mermaid +flowchart TD +Start(["进入 Div 渲染"]) --> CheckChildren["检测是否存在子节点"] +CheckChildren --> HasChildren{"有子节点？"} +HasChildren --> |是| RenderChildren["渲染子节点"] +HasChildren --> |否| UseValue["使用 value 作为文本内容"] +RenderChildren --> End(["完成"]) +UseValue --> End +``` + +图表来源 + +- [frontend/base/div/div.tsx:12-15](file://frontend/base/div/div.tsx#L12-L15) +- [frontend/base/div/Index.svelte:50-63](file://frontend/base/div/Index.svelte#L50-L63) + +章节来源 + +- [backend/modelscope_studio/components/base/div/**init**.py:10-86](file://backend/modelscope_studio/components/base/div/__init__.py#L10-L86) +- [frontend/base/div/Index.svelte:1-65](file://frontend/base/div/Index.svelte#L1-L65) +- [frontend/base/div/div.tsx:1-18](file://frontend/base/div/div.tsx#L1-L18) + +### Span 组件 + +- 设计要点 + - 行内容器，优先渲染子节点；若无子节点则使用 value 或回退到空 span。 + - 支持与 Div 相同的交互事件绑定集合。 +- 使用建议 + - 适合内联文本片段、标签、按钮内的文字等场景。 + - 不建议在需要块级换行的场景使用。 + +```mermaid +flowchart TD +Start(["进入 Span 渲染"]) --> CheckChildren["检测是否存在子节点"] +CheckChildren --> HasChildren{"有子节点？"} +HasChildren --> |是| RenderChildren["渲染子节点"] +HasChildren --> |否| UseValueOrEmpty["使用 value 或空 span"] +RenderChildren --> End(["完成"]) +UseValueOrEmpty --> End +``` + +图表来源 + +- [frontend/base/span/span.tsx:12-17](file://frontend/base/span/span.tsx#L12-L17) +- [frontend/base/span/Index.svelte:49-63](file://frontend/base/span/Index.svelte#L49-L63) + +章节来源 + +- [backend/modelscope_studio/components/base/span/**init**.py:10-87](file://backend/modelscope_studio/components/base/span/__init__.py#L10-L87) +- [frontend/base/span/Index.svelte:1-64](file://frontend/base/span/Index.svelte#L1-L64) +- [frontend/base/span/span.tsx:1-20](file://frontend/base/span/span.tsx#L1-L20) + +### Text 组件 + +- 设计要点 + - 最小化包装，直接渲染字符串；无事件绑定。 + - 适合纯文本输出，性能开销低。 +- 使用建议 + - 与富文本或需要交互的场景不混用；需要样式时通过 elem_classes/elem_style 控制。 + +```mermaid +flowchart TD +Start(["进入 Text 渲染"]) --> GetValue["读取 value"] +GetValue --> RenderText["渲染文本节点"] +RenderText --> End(["完成"]) +``` + +图表来源 + +- [frontend/base/text/text.tsx:4-8](file://frontend/base/text/text.tsx#L4-L8) +- [frontend/base/text/Index.svelte:32-41](file://frontend/base/text/Index.svelte#L32-L41) + +章节来源 + +- [backend/modelscope_studio/components/base/text/**init**.py:8-57](file://backend/modelscope_studio/components/base/text/__init__.py#L8-L57) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/base/text/text.tsx:1-11](file://frontend/base/text/text.tsx#L1-L11) + +### Markdown 组件 + +- 设计要点 + - 支持 copyButtons 插槽，允许自定义复制按钮；支持 LaTeX 数学公式定界符、HTML 安全策略、换行与标题链接等选项。 + - 后处理会清理输入的缩进，保证渲染一致性。 + - 主题模式与根路径通过 props 透传到底层 Markdown 组件。 +- 数据流与处理逻辑 + - Svelte 层解析 slots 并将 copyButtons 目标注入 React 层。 + - React 层隐藏 children，交由全局 Markdown 组件进行渲染与交互。 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte : markdown/Index.svelte" +participant React as "React : markdown.tsx" +participant GlobalMD as "全局 Markdown 组件" +participant User as "用户" +Svelte->>React : 透传 value/样式/类名/主题/根路径 +React->>React : 解析 copyButtons 插槽目标 +React->>GlobalMD : 渲染 Markdown 并注入 copyButtons +User->>GlobalMD : 触发复制/点击等事件 +GlobalMD-->>React : 事件回调 +React-->>Svelte : 更新状态 +Svelte-->>Svelte : 触发后端事件监听器 +``` + +图表来源 + +- [frontend/base/markdown/Index.svelte:19-44](file://frontend/base/markdown/Index.svelte#L19-L44) +- [frontend/base/markdown/markdown.tsx:8-32](file://frontend/base/markdown/markdown.tsx#L8-L32) +- [backend/modelscope_studio/components/base/markdown/**init**.py:15-46](file://backend/modelscope_studio/components/base/markdown/__init__.py#L15-L46) + +章节来源 + +- [backend/modelscope_studio/components/base/markdown/**init**.py:11-174](file://backend/modelscope_studio/components/base/markdown/__init__.py#L11-L174) +- [frontend/base/markdown/Index.svelte:1-64](file://frontend/base/markdown/Index.svelte#L1-L64) +- [frontend/base/markdown/markdown.tsx:1-35](file://frontend/base/markdown/markdown.tsx#L1-L35) + +## 依赖关系分析 + +- 组件间耦合 + - 四个组件均通过统一的后端基类（布局/数据布局/普通组件）派生，具备一致的生命周期与事件机制。 + - 前端 Svelte 层采用相同的属性透传与可见性控制模式，降低维护成本。 +- 外部依赖 + - React 包装层依赖 @svelte-preprocess-react 提供的 sveltify 与 slot 能力。 + - Markdown 组件依赖全局 Markdown 组件与 ReactSlot 进行插槽渲染。 +- 潜在循环依赖 + - 当前结构为单向依赖（后端 → Svelte → React），未见循环依赖迹象。 + +```mermaid +graph LR +PY_BASE["后端基础组件基类"] --> PY_DIV["Div"] +PY_BASE --> PY_SPAN["Span"] +PY_BASE --> PY_TEXT["Text"] +PY_DATA_LAYOUT["数据布局基类"] --> PY_MD["Markdown"] +SV_DIV["Svelte: div/Index.svelte"] --> RX_DIV["React: div.tsx"] +SV_SPAN["Svelte: span/Index.svelte"] --> RX_SPAN["React: span.tsx"] +SV_TEXT["Svelte: text/Index.svelte"] --> RX_TEXT["React: text.tsx"] +SV_MD["Svelte: markdown/Index.svelte"] --> RX_MD["React: markdown.tsx"] +RX_MD --> GLOBAL_MD["全局 Markdown 组件"] +``` + +图表来源 + +- [backend/modelscope_studio/components/base/div/**init**.py](file://backend/modelscope_studio/components/base/div/__init__.py#L7) +- [backend/modelscope_studio/components/base/span/**init**.py](file://backend/modelscope_studio/components/base/span/__init__.py#L7) +- [backend/modelscope_studio/components/base/text/**init**.py](file://backend/modelscope_studio/components/base/text/__init__.py#L5) +- [backend/modelscope_studio/components/base/markdown/**init**.py](file://backend/modelscope_studio/components/base/markdown/__init__.py#L8) +- [frontend/base/markdown/markdown.tsx:4-5](file://frontend/base/markdown/markdown.tsx#L4-L5) + +章节来源 + +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [frontend/base/package.json:1-6](file://frontend/base/package.json#L1-L6) + +## 性能考量 + +- 渲染路径 + - Text 为纯文本直出，开销最低；Div/Span 在存在子节点时走 React 子树渲染，需关注子树规模。 + - Markdown 通过隐藏 children 的方式复用全局渲染能力，减少重复解析。 +- 事件绑定 + - 所有布局组件均支持多种鼠标/滚轮事件绑定，建议按需启用，避免不必要的回调开销。 +- 样式与类名 + - 通过 elem_classes/elem_style 控制样式，尽量使用原子化类名以减少样式计算。 +- 主题与资源 + - Markdown 主题模式与根路径透传，确保静态资源加载路径正确，避免二次请求。 + +[本节为通用性能建议，无需特定文件引用] + +## 故障排查指南 + +- 文本未显示 + - 检查 value 是否为空或仅含空白；Text 组件在 value 缺失时会回退为空 span。 + - 对于 Div/Span，确认是否传入了子节点导致 value 被忽略。 +- 事件无效 + - 确认事件监听器已在后端注册；检查 visible 是否为 true，不可见时不会触发。 +- Markdown 复制按钮不生效 + - 确认 copyButtons 插槽已正确挂载；React 层会根据插槽目标决定是否替换默认按钮。 +- 样式不生效 + - 检查 elem_id/elem_classes/elem_style 的拼接顺序与优先级；必要时使用更具体的 CSS 选择器。 +- 主题错乱 + - 确认 themeMode 与 rootUrl 正确透传至 Markdown 组件。 + +章节来源 + +- [backend/modelscope_studio/components/base/text/**init**.py:45-50](file://backend/modelscope_studio/components/base/text/__init__.py#L45-L50) +- [backend/modelscope_studio/components/base/div/**init**.py:14-39](file://backend/modelscope_studio/components/base/div/__init__.py#L14-L39) +- [backend/modelscope_studio/components/base/span/**init**.py:14-39](file://backend/modelscope_studio/components/base/span/__init__.py#L14-L39) +- [backend/modelscope_studio/components/base/markdown/**init**.py:49-52](file://backend/modelscope_studio/components/base/markdown/__init__.py#L49-L52) +- [frontend/base/markdown/markdown.tsx:14-31](file://frontend/base/markdown/markdown.tsx#L14-L31) + +## 结论 + +Div、Span、Text、Markdown 四个组件构成了模型空间布局与内容展示的基础能力。它们在后端统一抽象、前端一致包装、React 层精准渲染的设计下，既保证了易用性，也兼顾了扩展性与性能。合理选择组件类型、按需启用事件与插槽、遵循样式与主题规范，是构建高质量界面的关键。 + +[本节为总结性内容，无需特定文件引用] + +## 附录 + +### 组件属性与行为速查 + +- Div + - 事件：click、dblclick、mousedown、mouseup、mouseover、mouseout、mousemove、scroll + - 属性：value、additional_props、elem_id、elem_classes、elem_style、visible、render +- Span + - 事件：click、dblclick、mousedown、mouseup、mouseover、mouseout、mousemove、scroll + - 属性：value、additional_props、elem_id、elem_classes、elem_style、visible、render +- Text + - 事件：无 + - 属性：value、elem_id、elem_classes、elem_style、visible、render +- Markdown + - 事件：change、copy、click、dblclick、mousedown、mouseup、mouseover、mouseout、mousemove、scroll + - 插槽：copyButtons + - 属性：value、rtl、latex_delimiters、sanitize_html、line_breaks、header_links、allow_tags、show_copy_button、copy_buttons、elem_id、elem_classes、elem_style、visible、render + +章节来源 + +- [backend/modelscope_studio/components/base/div/**init**.py:14-68](file://backend/modelscope_studio/components/base/div/__init__.py#L14-L68) +- [backend/modelscope_studio/components/base/span/**init**.py:14-69](file://backend/modelscope_studio/components/base/span/__init__.py#L14-L69) +- [backend/modelscope_studio/components/base/text/**init**.py:12-39](file://backend/modelscope_studio/components/base/text/__init__.py#L12-L39) +- [backend/modelscope_studio/components/base/markdown/**init**.py:15-143](file://backend/modelscope_studio/components/base/markdown/__init__.py#L15-L143) diff --git "a/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/\346\270\262\346\237\223\347\273\204\344\273\266.md" "b/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/\346\270\262\346\237\223\347\273\204\344\273\266.md" new file mode 100644 index 00000000..a4fe9d6d --- /dev/null +++ "b/.wiki/zh/\345\237\272\347\241\200\347\273\204\344\273\266/\346\270\262\346\237\223\347\273\204\344\273\266.md" @@ -0,0 +1,371 @@ +# 渲染组件 + + +**本文引用的文件** +- [each.tsx](file://frontend/base/each/each.tsx) +- [Index.svelte（Each）](file://frontend/base/each/Index.svelte) +- [EachItem.svelte](file://frontend/base/each/EachItem.svelte) +- [each.placeholder.tsx](file://frontend/base/each/each.placeholder.tsx) +- [useTargets.ts](file://frontend/utils/hooks/useTargets.ts) +- [useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [filter.tsx](file://frontend/base/filter/filter.tsx) +- [Index.svelte（Filter）](file://frontend/base/filter/Index.svelte) +- [each/__init__.py](file://backend/modelscope_studio/components/base/each/__init__.py) +- [filter/__init__.py](file://backend/modelscope_studio/components/base/filter/__init__.py) +- [base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [filter/README-zh_CN.md](file://docs/components/base/filter/README-zh_CN.md) +- [filter/demos/basic.py](file://docs/components/base/filter/demos/basic.py) + + +## 目录 + +1. [引言](#引言) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [组件详解](#组件详解) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 引言 + +本篇文档聚焦于渲染组件系列中的 Each 与 Filter，系统阐述它们在数据渲染与条件显示中的关键作用。Each 负责将列表数据逐项渲染，并为每一项注入上下文；Filter 则负责对上下文进行筛选或提取，支持以键名提取子对象或通过函数自定义过滤。文档将从架构、数据流、处理逻辑、集成与状态管理、性能优化到调试技巧进行全面说明，并提供多场景使用示例与最佳实践。 + +## 项目结构 + +渲染组件位于前端 base 包下，分别由 Svelte 入口组件与 React 实现组成，并在后端 Python 层提供对应的组件类以对接 Gradio 数据流。核心文件组织如下： + +- 前端 Each：入口 Svelte 组件负责属性处理与占位符协调，React 实现负责循环渲染与上下文注入。 +- 前端 Filter：入口 Svelte 组件负责属性处理，React 实现负责上下文筛选与透传。 +- 后端 Each/Filter：Python 组件类，定义属性、可见性、前后处理与前端目录映射。 + +```mermaid +graph TB +subgraph "前端base" +EIdx["Each 入口Index.svelte"] +EImpl["Each 实现each.tsx"] +EItem["Each 子项EachItem.svelte"] +EPh["Each 占位each.placeholder.tsx"] +FIdx["Filter 入口Index.svelte"] +FImpl["Filter 实现filter.tsx"] +UT["工具：useTargets.ts"] +UF["工具：useFunction.ts"] +end +subgraph "后端Python" +PYE["ModelScopeEacheach/__init__.py"] +PYF["ModelScopeFilterfilter/__init__.py"] +PYPkg["base/__init__.py 导出"] +end +EIdx --> EImpl +EIdx --> EPh +EIdx --> EItem +EImpl --> UT +FIdx --> FImpl +FImpl --> UF +PYE --> EIdx +PYF --> FIdx +PYPkg --> PYE +PYPkg --> PYF +``` + +图表来源 + +- [Index.svelte（Each）:1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [each.tsx:1-61](file://frontend/base/each/each.tsx#L1-L61) +- [EachItem.svelte:1-37](file://frontend/base/each/EachItem.svelte#L1-L37) +- [each.placeholder.tsx:1-31](file://frontend/base/each/each.placeholder.tsx#L1-L31) +- [Index.svelte（Filter）:1-52](file://frontend/base/filter/Index.svelte#L1-L52) +- [filter.tsx:1-41](file://frontend/base/filter/filter.tsx#L1-L41) +- [useTargets.ts:1-52](file://frontend/utils/hooks/useTargets.ts#L1-L52) +- [useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [each/**init**.py:1-73](file://backend/modelscope_studio/components/base/each/__init__.py#L1-L73) +- [filter/**init**.py:1-45](file://backend/modelscope_studio/components/base/filter/__init__.py#L1-L45) +- [base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +章节来源 + +- [Index.svelte（Each）:1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [filter.tsx:1-41](file://frontend/base/filter/filter.tsx#L1-L41) +- [each.tsx:1-61](file://frontend/base/each/each.tsx#L1-L61) +- [each/**init**.py:1-73](file://backend/modelscope_studio/components/base/each/__init__.py#L1-L73) +- [filter/**init**.py:1-45](file://backend/modelscope_studio/components/base/filter/__init__.py#L1-L45) +- [base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +## 核心组件 + +- Each：接收列表数据与上下文，逐项渲染子节点，并将每项的值合并到上下文中，供子组件消费。 +- Filter：对当前上下文进行筛选或提取，支持两种模式： + - as_item：按键名提取上下文中的子对象作为新上下文继续向下传递。 + - params_mapping：传入 JS 函数字符串，对上下文执行自定义过滤，返回新的上下文。 + - 两者均不提供时，阻断上下文传递，使后续属性覆盖失效。 + +章节来源 + +- [each.tsx:8-13](file://frontend/base/each/each.tsx#L8-L13) +- [filter.tsx:9-13](file://frontend/base/filter/filter.tsx#L9-L13) +- [filter/README-zh_CN.md:1-22](file://docs/components/base/filter/README-zh_CN.md#L1-L22) + +## 架构总览 + +Each 与 Filter 的运行流程可概括为：前端入口组件解析属性并准备 React 实现；React 实现根据数据与上下文生成子树；Filter 在渲染前对上下文进行筛选，确保下游组件仅接收到所需数据。 + +```mermaid +sequenceDiagram +participant Py as "后端组件Each/Filter" +participant S as "入口组件Each/Filter" +participant R as "React 实现Each/Filter" +participant U as "工具钩子useTargets/useFunction" +Py->>S : 初始化并设置属性 +S->>R : 传递处理后的属性与插槽 +R->>U : 解析插槽目标Each/解析函数Filter +U-->>R : 返回目标/函数 +R->>R : Each 循环 value 并注入上下文 +R->>R : Filter 根据 as_item 或 params_mapping 过滤上下文 +R-->>S : 渲染结果 +S-->>Py : 可见性与渲染控制 +``` + +图表来源 + +- [Index.svelte（Each）:1-111](file://frontend/base/each/Index.svelte#L1-L111) +- [each.tsx:35-58](file://frontend/base/each/each.tsx#L35-L58) +- [Index.svelte（Filter）:1-52](file://frontend/base/filter/Index.svelte#L1-L52) +- [filter.tsx:15-38](file://frontend/base/filter/filter.tsx#L15-L38) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) + +## 组件详解 + +### Each 组件 + +Each 的职责是将列表数据逐项渲染，并为每个子项注入上下文。其关键点包括： + +- 输入属性：value（数组）、contextValue（初始上下文）、children（子树）、内部插槽键。 +- 渲染策略：先渲染一个“隔离”的隐藏容器，确保外部上下文不污染内部插槽；随后对 value 执行 map，为每一项创建 Item。 +- 上下文注入：Item 将传入的 value 合并到 contextValue，形成最终上下文，再通过 ContextPropsProvider 注入给子树。 +- 插槽解析：通过 useTargets 提取 children 中带有匹配 slotKey 的节点，保证渲染顺序与目标挂载正确。 + +```mermaid +flowchart TD +Start(["进入 Each 渲染"]) --> Parse["解析 children 插槽
useTargets 提取目标"] +Parse --> Isolate["渲染隔离容器隐藏"] +Isolate --> Loop{"遍历 value"} +Loop --> |是| Item["为每一项创建 Item
合并上下文"] +Item --> Render["克隆并渲染目标插槽"] +Render --> Next["下一个元素"] +Next --> Loop +Loop --> |否| End(["完成渲染"]) +``` + +图表来源 + +- [each.tsx:35-58](file://frontend/base/each/each.tsx#L35-L58) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) + +章节来源 + +- [each.tsx:8-13](file://frontend/base/each/each.tsx#L8-L13) +- [each.tsx:35-58](file://frontend/base/each/each.tsx#L35-L58) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [Index.svelte（Each）:66-104](file://frontend/base/each/Index.svelte#L66-L104) +- [each.placeholder.tsx:15-28](file://frontend/base/each/each.placeholder.tsx#L15-L28) +- [EachItem.svelte:23-27](file://frontend/base/each/EachItem.svelte#L23-L27) + +### Filter 组件 + +Filter 的职责是对当前上下文进行筛选或提取，支持两种模式： + +- as_item：从上下文中按键名提取子对象作为新上下文继续向下传递。 +- params_mapping：传入 JS 函数字符串，通过 useFunction 解析为函数，对上下文执行自定义过滤。 +- 未提供参数时：阻断上下文传递，使后续属性覆盖失效。 + +```mermaid +flowchart TD +Enter(["进入 Filter"]) --> ReadCtx["读取当前上下文"] +ReadCtx --> CheckAs{"是否提供 as_item？"} +CheckAs --> |是| Extract["提取 ctx[as_item] 作为新上下文"] +CheckAs --> |否| CheckMap{"是否提供 params_mapping？"} +CheckMap --> |是| Exec["执行 params_mapping(ctx) 作为新上下文"] +CheckMap --> |否| Block["不更新上下文阻断传递"] +Extract --> Provide["通过 ContextPropsProvider 透传"] +Exec --> Provide +Block --> Provide +Provide --> Exit(["完成"]) +``` + +图表来源 + +- [filter.tsx:15-38](file://frontend/base/filter/filter.tsx#L15-L38) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) + +章节来源 + +- [filter.tsx:9-13](file://frontend/base/filter/filter.tsx#L9-L13) +- [filter.tsx:15-38](file://frontend/base/filter/filter.tsx#L15-L38) +- [Index.svelte（Filter）:33-45](file://frontend/base/filter/Index.svelte#L33-L45) +- [filter/README-zh_CN.md:1-22](file://docs/components/base/filter/README-zh_CN.md#L1-L22) + +### 属性与事件 + +- Each（前端入口 Index.svelte） + - 关键属性：value、context_value、visible、elem_id、elem_classes、elem_style、\_internal.index 等。 + - 内部行为：通过占位组件收集变更（如 forceClone、合并后的 value/context_value），决定是否采用 React 实现或直接使用 EachItem 渲染。 +- Each（React 实现 each.tsx） + - 关键属性：value、contextValue、children、\_\_internal_slot_key。 + - 内部行为：隔离外部上下文，解析插槽目标，逐项渲染并注入上下文。 +- Filter（前端入口 Index.svelte） + - 关键属性：params_mapping、as_item、visible。 + - 内部行为：将 params_mapping 与 as_item 传递至 React 实现。 +- Filter（React 实现 filter.tsx） + - 关键属性：paramsMapping、asItem。 + - 内部行为：根据参数选择提取或函数过滤，更新上下文并透传。 + +章节来源 + +- [Index.svelte（Each）:17-57](file://frontend/base/each/Index.svelte#L17-L57) +- [Index.svelte（Each）:66-104](file://frontend/base/each/Index.svelte#L66-L104) +- [each.tsx:8-13](file://frontend/base/each/each.tsx#L8-L13) +- [Index.svelte（Filter）:16-31](file://frontend/base/filter/Index.svelte#L16-L31) +- [filter.tsx:9-13](file://frontend/base/filter/filter.tsx#L9-L13) + +### 与状态管理的集成 + +- Each 通过 contextValue 与子项 value 合并，形成逐项上下文，供下游组件读取。 +- Filter 通过 useContextPropsContext 获取当前上下文，结合 as_item 或 params_mapping 生成新的上下文，实现“条件显示/数据筛选”。 +- 可结合后端组件的 visible 控制渲染可见性，前端入口组件在不可见时不会加载 React 实现，减少开销。 + +章节来源 + +- [each.tsx:15-33](file://frontend/base/each/each.tsx#L15-L33) +- [filter.tsx:19-27](file://frontend/base/filter/filter.tsx#L19-L27) +- [Index.svelte（Each）:66-104](file://frontend/base/each/Index.svelte#L66-L104) +- [Index.svelte（Filter）:33-45](file://frontend/base/filter/Index.svelte#L33-L45) + +### 使用示例与场景 + +- 基础用法（无 Filter） + - 场景：对列表数据进行循环渲染，按钮等子组件直接消费 Each 注入的上下文。 + - 参考示例路径：[filter/demos/basic.py:1-20](file://docs/components/base/filter/demos/basic.py#L1-L20) +- 使用 as_item + - 场景：Each 输出的上下文包含多个字段，仅需将某字段作为新上下文继续传递给子组件。 + - 参考说明路径：[filter/README-zh_CN.md:1-22](file://docs/components/base/filter/README-zh_CN.md#L1-L22) +- 使用 params_mapping + - 场景：通过 JS 函数对上下文进行复杂筛选或转换，例如过滤、拼装派生字段等。 + - 参考说明路径：[filter/README-zh_CN.md:1-22](file://docs/components/base/filter/README-zh_CN.md#L1-L22) + +章节来源 + +- [filter/demos/basic.py:1-20](file://docs/components/base/filter/demos/basic.py#L1-L20) +- [filter/README-zh_CN.md:1-22](file://docs/components/base/filter/README-zh_CN.md#L1-L22) + +## 依赖关系分析 + +- Each 依赖 + - 工具钩子：useTargets 用于解析插槽目标，确保渲染顺序与挂载正确。 + - 上下文：ContextPropsProvider 用于隔离与合并上下文。 +- Filter 依赖 + - 工具钩子：useFunction 将字符串函数解析为可执行函数。 + - 上下文：ContextPropsProvider 用于透传筛选后的上下文。 +- 后端组件 + - Each/Filter 分别继承自布局组件基类，定义属性、可见性、前后处理与前端目录映射。 + +```mermaid +graph LR +UT["useTargets.ts"] --> EImpl["each.tsx"] +UF["useFunction.ts"] --> FImpl["filter.tsx"] +EIdx["Each Index.svelte"] --> EImpl +FIdx["Filter Index.svelte"] --> FImpl +PYE["ModelScopeEachPython"] --> EIdx +PYF["ModelScopeFilterPython"] --> FIdx +``` + +图表来源 + +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [each.tsx:1-7](file://frontend/base/each/each.tsx#L1-L7) +- [filter.tsx:1-7](file://frontend/base/filter/filter.tsx#L1-L7) +- [Index.svelte（Each）:1-16](file://frontend/base/each/Index.svelte#L1-L16) +- [Index.svelte（Filter）:1-8](file://frontend/base/filter/Index.svelte#L1-L8) +- [each/**init**.py:1-73](file://backend/modelscope_studio/components/base/each/__init__.py#L1-L73) +- [filter/**init**.py:1-45](file://backend/modelscope_studio/components/base/filter/__init__.py#L1-L45) + +章节来源 + +- [each.tsx:1-7](file://frontend/base/each/each.tsx#L1-L7) +- [filter.tsx:1-7](file://frontend/base/filter/filter.tsx#L1-L7) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [each/**init**.py:1-73](file://backend/modelscope_studio/components/base/each/__init__.py#L1-L73) +- [filter/**init**.py:1-45](file://backend/modelscope_studio/components/base/filter/__init__.py#L1-L45) + +## 性能考量 + +- 列表渲染 + - Each 对 value 执行 map 渲染，应避免在 children 中进行重型计算，尽量将计算前置或缓存。 + - 使用稳定 key（索引）有助于 React/Svelte 的 diff 优化，但若列表存在插入/删除，建议使用唯一 id 作为 key。 +- 上下文合并 + - Each/EachItem 合并上下文时，尽量保持 value 结构简洁，避免深层嵌套导致的重复渲染。 +- 条件筛选 + - Filter 的 params_mapping 应避免在每次渲染中创建新函数，推荐在上层定义并传入字符串形式的函数。 +- 可见性控制 + - 通过 visible 控制组件渲染，不可见时不加载 React 实现，减少不必要的初始化与渲染。 +- 大数据量处理 + - 优先考虑分页、虚拟滚动或懒加载策略，避免一次性渲染超大列表。 + - 合理拆分 Each 嵌套层级，减少上下文深度与渲染树复杂度。 + +## 故障排查指南 + +- 子组件无法读取上下文 + - 检查 Each 是否正确传入 contextValue 与 value，确认 EachItem 合并逻辑生效。 + - 若使用 Filter，请确认 as_item 键名正确或 params_mapping 返回了期望对象。 +- 插槽渲染顺序异常 + - 确认插槽键（slotKey）一致，且 useTargets 能正确识别目标节点。 +- Filter 不生效 + - 确认 params_mapping 字符串可被解析为函数，或 as_item 键名存在于当前上下文中。 + - 若未提供参数，Filter 会阻断上下文传递，这是预期行为。 +- 渲染卡顿 + - 检查 Each 的 value 是否过大，必要时进行分页或虚拟化。 + - 避免在 children 中进行昂贵操作，将计算移至上游或使用 memo 化。 + +章节来源 + +- [each.tsx:15-33](file://frontend/base/each/each.tsx#L15-L33) +- [filter.tsx:15-38](file://frontend/base/filter/filter.tsx#L15-L38) +- [useTargets.ts:5-51](file://frontend/utils/hooks/useTargets.ts#L5-L51) +- [Index.svelte（Each）:66-104](file://frontend/base/each/Index.svelte#L66-L104) +- [Index.svelte（Filter）:33-45](file://frontend/base/filter/Index.svelte#L33-L45) + +## 结论 + +Each 与 Filter 构成了渲染组件系列中“循环渲染”与“条件筛选”的核心能力。Each 通过上下文合并与插槽解析，为列表中的每一项提供一致的数据环境；Filter 则在渲染前对上下文进行提取或自定义过滤，满足多样化的条件显示与数据筛选需求。结合后端组件的可见性控制与前端工具钩子，可在保证性能的同时实现灵活的渲染策略。 + +## 附录 + +- API 概览（简要） + - Each（前端入口） + - 属性：value、context_value、visible、elem_id、elem_classes、elem_style、\_internal.index 等。 + - 行为：占位组件收集变更，决定是否采用 React 实现或 EachItem 渲染。 + - Each（React 实现） + - 属性：value、contextValue、children、\_\_internal_slot_key。 + - 行为：隔离外部上下文，解析插槽目标，逐项渲染并注入上下文。 + - Filter（前端入口） + - 属性：params_mapping、as_item、visible。 + - 行为：将参数传递至 React 实现。 + - Filter（React 实现） + - 属性：paramsMapping、asItem。 + - 行为：根据 as_item 或 params_mapping 更新上下文并透传。 +- 后端组件 + - Each/Filter 均继承自布局组件基类，定义属性、可见性、前后处理与前端目录映射。 + +章节来源 + +- [Index.svelte（Each）:17-57](file://frontend/base/each/Index.svelte#L17-L57) +- [each.tsx:8-13](file://frontend/base/each/each.tsx#L8-L13) +- [Index.svelte（Filter）:16-31](file://frontend/base/filter/Index.svelte#L16-L31) +- [filter.tsx:9-13](file://frontend/base/filter/filter.tsx#L9-L13) +- [each/**init**.py:23-51](file://backend/modelscope_studio/components/base/each/__init__.py#L23-L51) +- [filter/**init**.py:13-25](file://backend/modelscope_studio/components/base/filter/__init__.py#L13-L25) diff --git "a/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\345\274\200\345\217\221\346\214\207\345\215\227.md" "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\345\274\200\345\217\221\346\214\207\345\215\227.md" new file mode 100644 index 00000000..3b1affca --- /dev/null +++ "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\345\274\200\345\217\221\346\214\207\345\215\227.md" @@ -0,0 +1,325 @@ +# 开发指南 + + +**本文引用的文件** +- [README.md](file://README.md) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [frontend/package.json](file://frontend/package.json) +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [docs/app.py](file://docs/app.py) +- [docs/README.md](file://docs/README.md) +- [docs/helper/Docs.py](file://docs/helper/Docs.py) +- [docs/helper/Site.py](file://docs/helper/Site.py) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本指南面向希望参与 ModelScope Studio（基于 Gradio 的第三方组件库）开发与扩展的工程师，涵盖开发环境搭建、依赖安装、开发服务器启动、构建配置、整体架构与开发流程、组件开发标准流程与最佳实践、文档系统使用与示例规范、测试与质量保障、调试技巧与常见问题、贡献指南与代码规范等内容。 + +## 项目结构 + +仓库采用多包工作区组织方式，主要由以下部分组成： + +- 后端 Python 包：提供组件类与打包配置，负责组件在 Python 端的导出与分发。 +- 前端 Svelte/React 生态：通过 Vite 构建，提供组件的前端实现与打包。 +- 文档站点：基于 Gradio 的文档系统，动态加载各组件的文档与示例。 +- 工具与脚本：变更集版本管理、发布脚本、编码检查等。 + +```mermaid +graph TB +subgraph "后端" +PY["Python 包
backend/modelscope_studio"] +PY_INIT["__init__.py"] +PY_VER["version.py"] +PY_CFG["pyproject.toml"] +end +subgraph "前端" +FE_PKG["frontend/package.json"] +FE_CFG["frontend/defineConfig.js"] +FE_PLG["frontend/plugin.js"] +FE_BTN["frontend/antd/button/Index.svelte"] +end +subgraph "文档" +DOCS_APP["docs/app.py"] +DOCS_README["docs/README.md"] +DOCS_HELPER["docs/helper/Docs.py"] +DOCS_SITE["docs/helper/Site.py"] +end +PY --> DOCS_APP +FE_PKG --> DOCS_APP +FE_CFG --> FE_PLG +FE_BTN --> DOCS_APP +DOCS_APP --> DOCS_HELPER +DOCS_APP --> DOCS_SITE +DOCS_APP --> DOCS_README +``` + +**图表来源** + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [docs/README.md:1-75](file://docs/README.md#L1-L75) +- [docs/helper/Docs.py:1-178](file://docs/helper/Docs.py#L1-L178) +- [docs/helper/Site.py:1-255](file://docs/helper/Site.py#L1-L255) + +**章节来源** + +- [README.md:80-101](file://README.md#L80-L101) +- [package.json:8-25](file://package.json#L8-L25) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## 核心组件 + +- 后端组件导出：后端通过统一的导出入口将各子模块组件暴露给用户，便于按需导入与使用。 +- 前端组件桥接：前端以 Svelte 组件形式包装 Ant Design/React 组件，并通过插件进行全局变量映射与外部化处理。 +- 文档系统：文档站点通过动态加载各组件目录下的 app.py 生成文档与示例，支持中英文切换与主题样式注入。 + +**章节来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [docs/app.py:19-91](file://docs/app.py#L19-L91) + +## 架构总览 + +下图展示了从开发到运行的关键路径：开发者在本地执行命令启动文档站点，文档站点读取组件文档与示例，前端组件通过 Vite 插件进行构建与外部化，最终在浏览器中渲染。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant CLI as "脚本命令" +participant Docs as "文档站点 docs/app.py" +participant Helper as "Docs/Site 助手" +participant FE as "前端组件构建" +participant Browser as "浏览器" +Dev->>CLI : 执行开发命令 +CLI-->>Docs : 启动 docs/app.py +Docs->>Helper : 初始化 Docs/Site +Helper-->>Docs : 注入菜单/文档/示例 +Docs->>FE : 渲染组件页面 +FE->>FE : Vite 插件处理与打包 +FE-->>Browser : 输出静态资源 +Browser-->>Dev : 展示可交互文档与示例 +``` + +**图表来源** + +- [package.json:15](file://package.json#L15) +- [docs/app.py:577-595](file://docs/app.py#L577-L595) +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) +- [docs/helper/Site.py:9-255](file://docs/helper/Site.py#L9-L255) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:41-168](file://frontend/plugin.js#L41-L168) + +## 详细组件分析 + +### 文档系统与站点渲染 + +- 动态加载：站点根据组件类型扫描目录，动态加载每个组件的 app.py 并提取 docs 字典。 +- 菜单与标签页：通过 Site 类组织顶部标签页与侧边菜单，支持横向菜单与内嵌菜单联动。 +- CSS 注入：为避免多 Blocks 场景下的样式丢失，将各示例的 CSS 合并注入到根 Blocks 中。 + +```mermaid +flowchart TD +Start(["启动 docs/app.py"]) --> LoadDocs["扫描组件目录并加载 app.py"] +LoadDocs --> BuildSite["初始化 Site 并构建菜单/标签页"] +BuildSite --> Render["渲染 Blocks 页面"] +Render --> InjectCSS["合并注入示例 CSS"] +InjectCSS --> End(["完成渲染"]) +``` + +**图表来源** + +- [docs/app.py:19-91](file://docs/app.py#L19-L91) +- [docs/helper/Site.py:41-255](file://docs/helper/Site.py#L41-L255) +- [docs/helper/Docs.py:163-178](file://docs/helper/Docs.py#L163-L178) + +**章节来源** + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [docs/helper/Site.py:1-255](file://docs/helper/Site.py#L1-L255) +- [docs/helper/Docs.py:1-178](file://docs/helper/Docs.py#L1-L178) + +### 前端构建与组件桥接 + +- Vite 插件：对特定模块进行外部化映射，将 import 映射到 window 上的全局对象，减少打包体积并提升加载性能。 +- Svelte 组件：通过 importComponent 包装 React/AntD 组件，统一处理属性、插槽与可见性控制。 + +```mermaid +flowchart TD +Entry(["Index.svelte"]) --> GetProps["解析组件属性与附加属性"] +GetProps --> ProcessProps["过滤内部字段并生成最终 props"] +ProcessProps --> Slots["获取插槽内容"] +Slots --> Render["异步渲染目标组件"] +Render --> End(["输出到页面"]) +``` + +**图表来源** + +- [frontend/antd/button/Index.svelte:10-74](file://frontend/antd/button/Index.svelte#L10-L74) +- [frontend/plugin.js:41-168](file://frontend/plugin.js#L41-L168) + +**章节来源** + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +### 后端组件导出与版本 + +- 统一导出：后端组件通过 **init**.py 将各子模块组件集中导出，便于用户直接按需导入。 +- 版本管理：版本号集中维护于 version.py，确保前后端版本一致。 + +**章节来源** + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) + +## 依赖关系分析 + +- Python 依赖：后端通过 hatchling 构建，声明对 Gradio 的版本范围约束；前端依赖 Ant Design、React、Svelte 等生态库。 +- 文档与脚本：package.json 定义了开发、构建、格式化、校验与发布相关脚本；pyproject.toml 配置了打包产物与元信息。 + +```mermaid +graph LR +PJS["package.json 脚本"] --> DOCS["docs/app.py"] +PJS --> FEPLG["frontend/plugin.js"] +PYTOML["pyproject.toml"] --> BACK["backend/modelscope_studio"] +FEPKG["frontend/package.json"] --> FEPLG +DOCS --> FEPLG +DOCS --> BACK +``` + +**图表来源** + +- [package.json:8-25](file://package.json#L8-L25) +- [pyproject.toml:25-43](file://pyproject.toml#L25-L43) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +**章节来源** + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## 性能考虑 + +- 外部化与别名：Vite 插件对常用库进行外部化映射，减少重复打包，提升首屏加载速度。 +- 按需渲染：组件桥接层仅在 visible 为真时渲染，避免无用节点。 +- CSS 合并：文档站点将示例 CSS 合并注入，避免多 Blocks 场景下的样式缺失导致的重绘与闪烁。 + +[本节为通用建议，不涉及具体文件分析] + +## 故障排查指南 + +- 文档站点无法显示或样式异常 + - 确认是否在 Hugging Face Space 中设置了 ssr_mode=False。 + - 检查文档站点是否正确合并注入 CSS。 +- 组件未生效或报错 + - 检查组件是否已正确导出并在 **init**.py 中聚合。 + - 确认前端组件的属性与插槽是否按约定传递。 +- 构建失败或外部化异常 + - 检查 Vite 插件的 external excludes 配置是否覆盖了需要外部化的模块。 +- 开发服务器启动失败 + - 使用文档提供的命令启动开发模式，确认端口与热更新配置。 + +**章节来源** + +- [README.md:32-33](file://README.md#L32-L33) +- [docs/helper/Site.py:60-73](file://docs/helper/Site.py#L60-L73) +- [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) + +## 结论 + +本指南提供了从环境搭建到组件开发、文档系统使用、构建与部署、调试与故障排查的完整路径。建议在开发过程中遵循统一的组件开发流程与命名规范，充分利用文档系统与脚本工具，确保前后端一致性与可维护性。 + +[本节为总结性内容，不涉及具体文件分析] + +## 附录 + +### 开发环境搭建与命令 + +- 克隆仓库并安装后端依赖与前端依赖 +- 使用文档提供的开发命令启动本地文档站点 + +**章节来源** + +- [README.md:82-101](file://README.md#L82-L101) +- [package.json:15](file://package.json#L15) + +### 组件开发标准流程与最佳实践 + +- 在对应组件目录下创建或完善 app.py 与示例文件，确保文档系统可加载。 +- 前端组件保持最小必要属性透传，避免冗余逻辑。 +- 使用统一的插槽与样式注入机制，保证一致的外观与行为。 + +**章节来源** + +- [docs/app.py:19-91](file://docs/app.py#L19-L91) +- [frontend/antd/button/Index.svelte:10-74](file://frontend/antd/button/Index.svelte#L10-L74) + +### 文档系统使用与示例编写规范 + +- 使用 Docs 助手解析 Markdown 并渲染示例，支持折叠、标题与位置控制。 +- 示例代码与渲染结果并排展示，便于对比与调试。 + +**章节来源** + +- [docs/helper/Docs.py:82-178](file://docs/helper/Docs.py#L82-L178) + +### 测试策略与质量保证 + +- 使用脚本进行格式化、风格检查与类型检查，确保代码一致性。 +- 通过文档站点验证组件在不同环境下的表现。 + +**章节来源** + +- [package.json:18-22](file://package.json#L18-L22) + +### 调试技巧 + +- 利用 Gradio 的事件与更新机制，观察菜单切换与标签页联动。 +- 在浏览器控制台查看组件渲染与属性传递情况。 + +**章节来源** + +- [docs/helper/Site.py:203-255](file://docs/helper/Site.py#L203-L255) + +### 贡献指南与代码规范 + +- 遵循项目既定的脚本与工具链，提交前确保通过格式化与校验。 +- 变更版本与发布流程通过 Changesets 与脚本自动化。 + +**章节来源** + +- [package.json:10-25](file://package.json#L10-L25) diff --git "a/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\345\274\200\345\217\221\346\265\201\347\250\213.md" "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\345\274\200\345\217\221\346\265\201\347\250\213.md" new file mode 100644 index 00000000..6748a1c3 --- /dev/null +++ "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\345\274\200\345\217\221\346\265\201\347\250\213.md" @@ -0,0 +1,302 @@ +# 开发流程 + + +**本文引用的文件** +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [pyproject.toml](file://pyproject.toml) +- [README.md](file://README.md) +- [docs/app.py](file://docs/app.py) +- [frontend/package.json](file://frontend/package.json) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) +- [scripts/create-tag-n-release.mts](file://scripts/create-tag-n-release.mts) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本指南面向 ModelScope Studio 的开发者与维护者，系统阐述项目的整体架构、开发模式与发布流程。项目采用 Monorepo 结构，前端基于 Svelte 与 Gradio 组件生态，后端提供 Python 包封装与模板生成，文档站点通过 Python 动态加载各组件示例与文档。文档覆盖从需求分析到组件发布的全流程，包括 Git 工作流、分支管理、代码审查、本地开发与热重载、CI/CD 与自动化发布。 + +## 项目结构 + +- 顶层使用 pnpm workspace 管理多包，包含根工程、前端包、基础与专业组件包、以及共享的 lint 配置包。 +- 后端以 Python 包形式提供组件模板与打包规则，构建产物用于 PyPI 发布。 +- 文档站点位于 docs 目录，通过 Python 动态扫描组件目录并渲染示例页面，支持本地开发与热更新。 +- 前端组件以 Svelte + TypeScript 构建，配合 Gradio 生态进行演示与集成。 + +```mermaid +graph TB +Root["根工作区
package.json / pnpm-workspace.yaml"] --> Frontend["前端包
frontend/package.json"] +Root --> Backend["后端包
pyproject.toml"] +Root --> Lint["共享 Lint 配置
config/lint-config/package.json"] +Docs["文档站点
docs/app.py"] --> Backend +Docs --> Frontend +Frontend --> Gradio["@gradio/* 生态"] +Backend --> PyPI["PyPI 发布"] +``` + +图表来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +章节来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## 核心组件 + +- 文档站点与路由：docs/app.py 负责动态加载各组件的 app.py 示例与文档，组织多标签页与菜单项，并在本地开发时启用热更新。 +- 前端组件生态：frontend 目录下按 antd、antdx、base、pro 等分类组织组件，每个组件包含 Svelte 实现与 Gradio 配置。 +- 后端 Python 包：pyproject.toml 定义构建目标与产物清单，将大量模板文件打包进 wheel，供 PyPI 使用。 +- 共享 Lint 配置：config/lint-config 提供统一的 ESLint、Stylelint 规则与解析器，保证跨包一致性。 +- CI/CD 脚本：scripts 目录包含 PyPI 发布与 GitHub Release 创建脚本，配合 GitHub Actions 实现自动化发布。 + +章节来源 + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [config/lint-config/package.json:1-48](file://config/lint-config/package.json#L1-L48) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +## 架构总览 + +ModelScope Studio 的开发与发布围绕“文档驱动的组件开发”展开：前端组件以 Svelte 实现，后端 Python 包负责模板与打包，文档站点作为统一入口聚合所有组件示例；CI/CD 在主分支触发构建与发布，确保版本一致性与可追溯性。 + +```mermaid +graph TB +Dev["开发者"] --> LocalDev["本地开发
gradio cc dev docs/app.py"] +LocalDev --> Docs["文档站点
docs/app.py"] +Docs --> Antd["Antd 组件
frontend/antd/*"] +Docs --> Antdx["Antdx 组件
frontend/antdx/*"] +Docs --> Base["基础组件
frontend/base/*"] +Docs --> Pro["专业组件
frontend/pro/*"] +Antd --> Backend["后端模板打包
pyproject.toml"] +Antdx --> Backend +Base --> Backend +Pro --> Backend +Backend --> PyPI["PyPI 发布"] +PyPI --> Users["用户安装与使用"] +``` + +图表来源 + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [package.json:8-25](file://package.json#L8-L25) + +章节来源 + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [package.json:8-25](file://package.json#L8-L25) + +## 详细组件分析 + +### 文档站点与组件发现机制 + +文档站点通过扫描 docs/components 与 docs/layout_templates 下的子目录，动态导入每个组件的 app.py 并提取其 docs 字段，形成统一的站点结构。该机制支持新增组件无需修改站点路由，只需在对应目录提供 app.py 与示例即可。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Docs as "docs/app.py" +participant FS as "文件系统" +participant Comp as "组件 app.py" +Dev->>Docs : 启动 gradio cc dev +Docs->>FS : 扫描 components/* 与 layout_templates/* +FS-->>Docs : 返回组件目录列表 +Docs->>Comp : importlib.spec_from_file_location() +Comp-->>Docs : 导出 docs 字典 +Docs-->>Dev : 渲染站点与示例 +``` + +图表来源 + +- [docs/app.py:19-61](file://docs/app.py#L19-L61) + +章节来源 + +- [docs/app.py:19-61](file://docs/app.py#L19-L61) + +### 前端组件开发与构建 + +- 组件以 Svelte + TypeScript 编写，每个组件拥有独立 package.json 与 Gradio 配置，便于独立开发与演示。 +- 顶层 package.json 提供统一的构建与开发脚本，调用 Gradio CLI 构建与启动文档站点。 +- 前端包依赖 @gradio/\* 生态与 antd、svelte 等核心库，确保与 Gradio 组件生态兼容。 + +章节来源 + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [package.json:8-25](file://package.json#L8-L25) + +### 后端模板打包与发布 + +- pyproject.toml 定义了大量模板文件的打包规则，构建产物包含后端组件模板，确保安装后可在 Python 端直接使用。 +- 发布流程通过脚本检查版本是否已存在，若未存在则执行构建并使用 twine 上传至 PyPI。 + +```mermaid +flowchart TD +Start(["开始"]) --> Check["检查 PyPI 是否已有同版本"] +Check --> Exists{"已存在?"} +Exists --> |是| Skip["跳过发布"] +Exists --> |否| Build["pip install -e . && pnpm run build"] +Build --> Dist{"dist 存在?"} +Dist --> |否| Fail["抛出构建失败错误"] +Dist --> |是| Upload["twine upload dist/*"] +Upload --> Done(["结束"]) +Skip --> Done +Fail --> Done +``` + +图表来源 + +- [scripts/publish-to-pypi.mts:14-55](file://scripts/publish-to-pypi.mts#L14-L55) +- [pyproject.toml:45-245](file://pyproject.toml#L45-L245) + +章节来源 + +- [scripts/publish-to-pypi.mts:14-55](file://scripts/publish-to-pypi.mts#L14-L55) +- [pyproject.toml:45-245](file://pyproject.toml#L45-L245) + +### CI/CD 流程与自动化发布 + +- Lint 工作流：在 push 与 pull_request 上自动执行，安装 Python 与 Node 依赖，运行统一 lint 脚本，保障代码风格一致。 +- 发布工作流：在 main/next 分支 push 时触发，但需要满足提交消息为“chore: update versions”的条件；只有满足条件的提交才会执行 PyPI 发布脚本；发布成功后创建 Git Tag 并创建 GitHub Release，内容来自变更日志。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant GH as "GitHub Actions" +participant Lint as "Lint Job" +participant Pub as "Publish Job" +participant PyPI as "PyPI" +participant GHRel as "GitHub Releases" +Dev->>GH : Push 代码(main/next) +GH->>Lint : 触发 lint.yaml +Lint-->>GH : Lint 通过/失败 +GH->>Pub : 触发 publish.yaml +Pub->>PyPI : 上传包 +PyPI-->>Pub : 成功/失败 +Pub->>GHRel : 创建 Tag 与 Release +GHRel-->>Dev : 可访问新版本 +``` + +图表来源 + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:32-42](file://scripts/publish-to-pypi.mts#L32-L42) +- [scripts/create-tag-n-release.mts:88-115](file://scripts/create-tag-n-release.mts#L88-L115) + +章节来源 + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:32-42](file://scripts/publish-to-pypi.mts#L32-L42) +- [scripts/create-tag-n-release.mts:88-115](file://scripts/create-tag-n-release.mts#L88-L115) + +## 依赖关系分析 + +- 包管理：根 package.json 与 pnpm-workspace.yaml 定义了工作区范围与脚本命令，frontend 与 config/lint-config 为独立包。 +- 语言与工具链：Python 侧由 hatchling 构建，Node 侧由 pnpm 管理依赖与脚本；ESLint、Stylelint 由共享 lint 配置包提供。 +- 组件生态：前端依赖 @gradio/\* 与 antd/svelte，文档站点通过 Python 导入组件示例，实现“文档即示例”的开发体验。 + +```mermaid +graph LR +Root["根工程"] --> WS["pnpm-workspace.yaml"] +Root --> Scripts["package.json 脚本"] +WS --> FE["frontend/*"] +WS --> CFG["config/lint-config"] +FE --> Gradio["@gradio/*"] +FE --> Antd["antd/svelte"] +CFG --> ESLint["ESLint/Stylelint 规则"] +``` + +图表来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:8-25](file://package.json#L8-L25) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [config/lint-config/package.json:8-42](file://config/lint-config/package.json#L8-L42) + +章节来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:8-25](file://package.json#L8-L25) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [config/lint-config/package.json:8-42](file://config/lint-config/package.json#L8-L42) + +## 性能考虑 + +- 文档站点的动态导入仅在开发环境启用，生产构建可通过禁用 watch 或调整并发参数优化启动时间。 +- 前端组件按需构建，避免不必要的全量编译；建议在本地开发时仅关注当前组件目录，减少无关文件监听。 +- PyPI 发布前先检查版本是否存在，避免重复上传与网络浪费。 + +## 故障排查指南 + +- 文档站点无法热更新 + - 确认环境变量 GRADIO_WATCH_MODULE_NAME 设置正确，且 docs/app.py 在 dev 模式下运行。 + - 参考路径：[docs/app.py:10](file://docs/app.py#L10) +- 构建失败或 dist 不存在 + - 检查根工程与前端包的依赖安装是否完整，确认构建脚本执行成功。 + - 参考路径：[scripts/publish-to-pypi.mts:22-30](file://scripts/publish-to-pypi.mts#L22-L30) +- PyPI 重复发布被跳过 + - 若版本已在 PyPI 存在，脚本会跳过上传；请确认版本号变更或清理缓存。 + - 参考路径：[scripts/publish-to-pypi.mts:44-51](file://scripts/publish-to-pypi.mts#L44-L51) +- GitHub Release 创建失败 + - 检查 GITHUB_TOKEN 权限与仓库可见性，确认 CHANGELOG 内容可解析。 + - 参考路径：[scripts/create-tag-n-release.mts:88-115](file://scripts/create-tag-n-release.mts#L88-L115) + +章节来源 + +- [docs/app.py:10](file://docs/app.py#L10) +- [scripts/publish-to-pypi.mts:22-30](file://scripts/publish-to-pypi.mts#L22-L30) +- [scripts/publish-to-pypi.mts:44-51](file://scripts/publish-to-pypi.mts#L44-L51) +- [scripts/create-tag-n-release.mts:88-115](file://scripts/create-tag-n-release.mts#L88-L115) + +## 结论 + +ModelScope Studio 采用“文档驱动 + Monorepo + CI/CD 自动化”的开发模式，前端以 Svelte 与 Gradio 生态为核心，后端通过 Python 包打包模板并发布至 PyPI。通过统一的 lint 配置与工作流，团队可以高效协作并保持质量与一致性。建议在新增组件时遵循现有目录结构与命名规范，确保文档站点与发布流程顺畅。 + +## 附录 + +### 本地开发与热重载 + +- 安装依赖与构建 + - 参考路径：[README.md:82-94](file://README.md#L82-L94) +- 启动文档站点（含热重载） + - 参考路径：[package.json:15](file://package.json#L15) +- 版本信息 + - 参考路径：[backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) + +章节来源 + +- [README.md:82-94](file://README.md#L82-L94) +- [package.json:15](file://package.json#L15) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) diff --git "a/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\345\274\200\345\217\221\347\216\257\345\242\203\346\220\255\345\273\272.md" "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\345\274\200\345\217\221\347\216\257\345\242\203\346\220\255\345\273\272.md" new file mode 100644 index 00000000..e3751ccb --- /dev/null +++ "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\345\274\200\345\217\221\347\216\257\345\242\203\346\220\255\345\273\272.md" @@ -0,0 +1,276 @@ +# 开发环境搭建 + + +**本文引用的文件** +- [README.md](file://README.md) +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [pyproject.toml](file://pyproject.toml) +- [frontend/package.json](file://frontend/package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/tsconfig.json](file://frontend/tsconfig.json) +- [tsconfig.json](file://tsconfig.json) +- [svelte-tsconfig.json](file://svelte-tsconfig.json) +- [docs/requirements.txt](file://docs/requirements.txt) +- [docs/app.py](file://docs/app.py) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本指南面向希望在本地搭建并开发 ModelScope Studio 的工程师与贡献者，覆盖系统要求、Node.js 与 Python 环境配置、依赖安装、pnpm 工作空间设置、后端与前端依赖安装、构建流程、开发服务器启动与验证方法，并提供多操作系统下的注意事项与常见问题解决方案。 + +## 项目结构 + +该项目采用双层工作区设计： + +- 根工作区：包含前端子包（antd、antdx、base、pro）、配置包（lint-config、changelog）以及根级脚本与配置。 +- 后端 Python 包：位于 backend/modelscope_studio，通过可编辑安装集成到 Python 环境。 +- 文档与示例：docs 目录提供示例应用与依赖约束。 + +```mermaid +graph TB +Root["根工作区
package.json / pnpm-workspace.yaml"] --> Frontend["前端工作区
frontend/*"] +Root --> Config["配置工作区
config/*"] +Root --> Backend["后端 Python 包
backend/modelscope_studio"] +Docs["文档示例
docs/app.py"] --> Backend +Docs --> Frontend +``` + +图表来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +章节来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [README.md:80-101](file://README.md#L80-L101) + +## 核心组件 + +- 根级脚本与工具链：通过 package.json 定义构建、开发、格式化、校验等命令。 +- pnpm 工作空间：统一管理前端子包与配置包，确保依赖版本一致与增量构建。 +- Python 构建与打包：使用 hatchling 作为构建后端，支持源码分发与轮子分发。 +- 文档站点：基于 Gradio 的 docs/app.py 提供组件演示与导航。 +- 前端工程：Vite + Svelte 5，配合自定义插件与类型配置。 + +章节来源 + +- [package.json:8-25](file://package.json#L8-L25) +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/app.py:577-595](file://docs/app.py#L577-L595) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## 架构总览 + +下图展示了开发时从克隆仓库到启动文档站点的整体流程： + +```mermaid +flowchart TD +A["克隆仓库"] --> B["安装后端依赖
pip install -e '.'"] +B --> C["安装 pnpm
npm install pnpm -g"] +C --> D["安装前端依赖
pnpm install"] +D --> E["构建项目
pnpm build"] +E --> F["启动开发服务器
gradio cc dev docs/app.py"] +F --> G["浏览器访问文档站点"] +``` + +图表来源 + +- [README.md:82-101](file://README.md#L82-L101) +- [package.json:8-16](file://package.json#L8-L16) +- [docs/app.py:592-595](file://docs/app.py#L592-L595) + +## 详细组件分析 + +### 系统要求与前置条件 + +- Python + - 本地开发最低版本：Python 3.8+ + - CI/CD 发布环境：Python 3.12（由 .github/workflows/publish.yaml 指定） + - 推荐使用虚拟环境隔离依赖 +- Node.js + - 最低版本：Node.js 18.0+，推荐使用 20+ 或更新版本 + - 使用 pnpm 作为包管理器；建议安装 pnpm 全局工具 +- 操作系统 + - Linux/macOS/Windows 均可，注意路径分隔符与权限差异 +- 可选：Docker（用于发布流程中的 twine 上传） + +章节来源 + +- [pyproject.toml:15](file://pyproject.toml#L15) +- [README.md:82-101](file://README.md#L82-L101) + +### 克隆与初始化 + +- 克隆仓库至本地 +- 在根目录执行后端可编辑安装，使 Python 环境识别 backend/modelscope_studio +- 全局安装 pnpm +- 在根目录执行 pnpm install 安装所有工作区依赖 +- 执行 pnpm build 完成前端构建 + +章节来源 + +- [README.md:82-101](file://README.md#L82-L101) +- [package.json:8-16](file://package.json#L8-L16) + +### 后端依赖安装（Python） + +- 使用可编辑安装将 backend/modelscope_studio 集成到当前 Python 环境 +- Python 版本需满足 pyproject.toml 中的最低要求 +- 如需发布流程，可参考发布脚本中的 twine 上传步骤 + +章节来源 + +- [pyproject.toml:15](file://pyproject.toml#L15) +- [scripts/publish-to-pypi.mts:22-42](file://scripts/publish-to-pypi.mts#L22-L42) + +### 前端依赖安装与构建 + +- pnpm 工作空间包含多个前端子包与配置包，统一安装可避免版本冲突 +- 前端工程使用 Vite 与 Svelte 5，defineConfig.js 提供插件与预处理配置 +- tsconfig.json 与 svelte-tsconfig.json 提供类型检查与路径别名配置 + +章节来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) +- [tsconfig.json:1-33](file://tsconfig.json#L1-L33) +- [svelte-tsconfig.json:1-4](file://svelte-tsconfig.json#L1-L4) + +### 开发服务器启动与验证 + +- 使用 gradio cc dev docs/app.py 启动文档站点 +- 文档站点会自动扫描 docs/components 与 docs/layout_templates 下的示例应用 +- 访问默认地址（由 Gradio 输出）查看组件演示与导航 + +章节来源 + +- [README.md:96-101](file://README.md#L96-L101) +- [docs/app.py:10,19-61,577-595](file://docs/app.py#L10,L19-L61,L577-L595) + +### 发布与打包（可选） + +- 发布脚本会先执行 pip install -e '.' 与 pnpm run build，再检查 dist 是否存在 +- 若版本未存在于 PyPI，则调用 twine 上传 dist/\* 资源 + +章节来源 + +- [scripts/publish-to-pypi.mts:14-55](file://scripts/publish-to-pypi.mts#L14-L55) + +## 依赖分析 + +- 根级依赖 + - 构建与脚本：gradio cc、rimraf、tsx、husky 等 + - 类型与校验：typescript、svelte-check、eslint、stylelint、prettier +- 前端依赖 + - UI 框架：antd、@ant-design/x、@ant-design/icons + - React/Svelte：react、react-dom、svelte 5 + - 编辑器与可视化：monaco-editor、@monaco-editor/react、mermaid、katex +- Python 依赖 + - 核心：gradio（版本范围约束） + - 构建：hatchling、hatch-requirements-txt、hatch-fancy-pypi-readme + - 可选：openai（文档示例中使用） + +```mermaid +graph LR +RootPkg["根 package.json"] --> Scripts["构建与脚本"] +RootPkg --> Linters["类型与校验"] +FrontPkg["frontend/package.json"] --> UI["UI 框架"] +FrontPkg --> Runtime["React/Svelte 运行时"] +FrontPkg --> Editor["编辑器与可视化"] +PyProj["pyproject.toml"] --> Gradio["gradio 依赖"] +PyProj --> Build["构建后端"] +DocsReq["docs/requirements.txt"] --> OpenAI["openai 示例依赖"] +``` + +图表来源 + +- [package.json:26-52](file://package.json#L26-L52) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [pyproject.toml:2,42-43](file://pyproject.toml#L2,L42-L43) +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-L4) + +章节来源 + +- [package.json:26-52](file://package.json#L26-L52) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [pyproject.toml:2,42-43](file://pyproject.toml#L2,L42-L43) +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-L4) + +## 性能考虑 + +- 使用 pnpm 工作空间统一依赖版本，减少重复安装与内存占用 +- 前端构建目标为 ESNext，结合现代浏览器特性提升运行效率 +- 文档站点按需加载组件示例，避免一次性加载全部资源 +- 在大型项目中建议启用 TypeScript 的 noEmit 与 svelte-check，提前发现类型问题 + +## 故障排除指南 + +- 安装后端依赖失败 + - 确认 Python 版本满足 >=3.8 + - 使用虚拟环境避免全局污染 + - 参考发布脚本中的 pip install -e '.' 流程进行排查 +- pnpm 安装失败或依赖不兼容 + - 清理缓存并重试：删除 node_modules 与 pnpm-lock.yaml 后重新安装 + - 确认 pnpm 版本与工作区配置一致 +- 构建失败 + - 检查是否已执行 pnpm build + - 确认 dist 目录生成 +- 开发服务器无法访问 + - 确认已执行 gradio cc dev docs/app.py + - 检查防火墙与端口占用 + - 如在 Hugging Face Space 中使用，按 README 提示设置 ssr_mode=False + +章节来源 + +- [pyproject.toml:15](file://pyproject.toml#L15) +- [scripts/publish-to-pypi.mts:22-30](file://scripts/publish-to-pypi.mts#L22-L30) +- [README.md:32,96-101](file://README.md#L32,L96-L101) + +## 结论 + +通过以上步骤，您可以在本地成功搭建 ModelScope Studio 的开发环境，完成后端与前端依赖安装、构建与文档站点启动。遇到问题时，可依据本指南的故障排除部分逐项排查。建议在变更前先清理缓存并使用虚拟环境，以确保一致性与可复现性。 + +## 附录 + +### 常用命令速查 + +- 克隆与初始化 + - pip install -e '.' + - npm install pnpm -g + - pnpm install + - pnpm build +- 启动开发服务器 + - gradio cc dev docs/app.py +- 格式化与校验 + - pnpm run lint + - pnpm run format +- 版本与发布（CI） + - pnpm run version + - pnpm run ci:version + - pnpm run ci:publish + +章节来源 + +- [README.md:82-101](file://README.md#L82-L101) +- [package.json:8-25](file://package.json#L8-L25) diff --git "a/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\346\226\207\346\241\243\347\263\273\347\273\237.md" "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\346\226\207\346\241\243\347\263\273\347\273\237.md" new file mode 100644 index 00000000..6cb4651e --- /dev/null +++ "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\346\226\207\346\241\243\347\263\273\347\273\237.md" @@ -0,0 +1,382 @@ +# 文档系统 + + +**本文引用的文件** +- [docs/app.py](file://docs/app.py) +- [docs/helper/Docs.py](file://docs/helper/Docs.py) +- [docs/helper/Site.py](file://docs/helper/Site.py) +- [docs/helper/parse_markdown.py](file://docs/helper/parse_markdown.py) +- [docs/helper/env.py](file://docs/helper/env.py) +- [docs/components/antd/button/README.md](file://docs/components/antd/button/README.md) +- [docs/components/antd/button/app.py](file://docs/components/antd/button/app.py) +- [docs/layout_templates/chatbot/README.md](file://docs/layout_templates/chatbot/README.md) +- [docs/layout_templates/chatbot/app.py](file://docs/layout_templates/chatbot/app.py) +- [docs/demos/example.py](file://docs/demos/example.py) +- [docs/requirements.txt](file://docs/requirements.txt) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [README.md](file://README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本指南面向维护者与贡献者，系统讲解 ModelScope Studio 文档系统的架构与使用方法，涵盖以下主题： + +- 文档站点的整体架构与构建流程 +- 组件文档生成机制（Markdown 解析、示例渲染） +- 示例管理与演示模块加载 +- 多语言支持与环境变量处理 +- Docs 工具类与 Site 工具类的使用 +- 文档更新流程与发布策略 + +## 项目结构 + +文档系统位于 docs 目录，采用“按组件/模板分类 + 辅助工具”的组织方式： + +- docs/app.py：站点入口与路由、菜单、Tab 布局、站点装配 +- docs/helper/：文档解析与站点渲染工具 + - Docs.py：文档读取、Markdown 解析、示例模块加载与渲染 + - Site.py：站点整体布局、菜单联动、响应式侧边栏与内容区 + - parse_markdown.py：自定义 Markdown 解析器，支持 demo/file 标签 + - env.py：环境变量开关（是否为 ModelScope Studio 环境） +- docs/components/antd/button/...：各组件的文档与独立示例页面 +- docs/layout_templates/chatbot/...：布局模板示例页面 +- docs/demos/example.py：示例演示脚本模板 +- docs/requirements.txt：文档站点运行所需依赖 +- .github/workflows/publish.yaml、lint.yaml：CI 发布与代码检查 +- package.json、pyproject.toml：前端与后端构建脚本与打包配置 +- README.md：项目总体说明与开发指引 + +```mermaid +graph TB +A["docs/app.py
站点入口与装配"] --> B["docs/helper/Site.py
站点布局与菜单联动"] +A --> C["docs/helper/Docs.py
文档读取与示例渲染"] +C --> D["docs/helper/parse_markdown.py
Markdown 解析器"] +C --> E["docs/helper/env.py
环境变量开关"] +A --> F["docs/components/*/README.md
组件文档"] +A --> G["docs/layout_templates/*/README.md
布局模板文档"] +C --> H["docs/demos/*.py
示例模块"] +``` + +图表来源 + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [docs/helper/Site.py:1-255](file://docs/helper/Site.py#L1-L255) +- [docs/helper/Docs.py:1-178](file://docs/helper/Docs.py#L1-L178) +- [docs/helper/parse_markdown.py:1-84](file://docs/helper/parse_markdown.py#L1-L84) +- [docs/helper/env.py:1-4](file://docs/helper/env.py#L1-L4) + +章节来源 + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-L4) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +## 核心组件 + +- Docs 工具类 + - 功能：扫描同目录下 Markdown 文件与 demos 子目录；根据环境变量选择中英文文档；解析 Markdown 并渲染示例；收集示例模块样式；统一渲染为 Gradio Blocks 页面。 + - 关键点：支持 demo 标签（name、position、collapsible、fixed、title）与 demo-prefix/demo-suffix 注入；支持 file 标签内联外部文件内容。 +- Site 工具类 + - 功能：组装顶部 Tab 与侧边菜单；在内容区渲染对应文档；处理菜单切换事件；动态控制侧边栏尺寸与可见性；合并所有示例模块的 CSS。 +- Markdown 解析器 + - 功能：基于 HTMLParser 的轻量解析器，识别 demo/file 标签，输出结构化节点序列（文本/示例），供 Docs 渲染。 +- 环境变量处理 + - 功能：通过 MODELSCOPE_ENVIRONMENT 控制是否为 Studio 环境，决定文档命名与过滤规则。 + +章节来源 + +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) +- [docs/helper/Site.py:9-255](file://docs/helper/Site.py#L9-L255) +- [docs/helper/parse_markdown.py:12-84](file://docs/helper/parse_markdown.py#L12-L84) +- [docs/helper/env.py:1-4](file://docs/helper/env.py#L1-L4) + +## 架构总览 + +文档系统以 docs/app.py 为入口，Site 负责整体布局与菜单联动，Docs 负责单个组件或模板的文档渲染。Markdown 解析器将文档中的 demo/file 标签转换为可执行的渲染指令，示例模块由 Docs 动态导入并在页面中渲染。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant APP as "docs/app.py" +participant SITE as "Site.render()" +participant DOCS as "Docs.render()" +participant MD as "parse_markdown.py" +participant DEMO as "示例模块(.py)" +U->>APP : 访问文档站点 +APP->>SITE : 组装 Tabs/菜单/布局 +SITE->>DOCS : 渲染当前组件/模板文档 +DOCS->>MD : 解析 Markdown 中的 demo/file 标签 +MD-->>DOCS : 返回结构化节点 +DOCS->>DEMO : 动态导入并调用 demo.render() +DEMO-->>DOCS : 返回渲染结果 +DOCS-->>SITE : 返回 Blocks 页面 +SITE-->>U : 展示完整文档页面 +``` + +图表来源 + +- [docs/app.py:577-590](file://docs/app.py#L577-L590) +- [docs/helper/Site.py:41-254](file://docs/helper/Site.py#L41-L254) +- [docs/helper/Docs.py:171-178](file://docs/helper/Docs.py#L171-L178) +- [docs/helper/parse_markdown.py:80-84](file://docs/helper/parse_markdown.py#L80-L84) + +## 详细组件分析 + +### Docs 工具类（文档渲染） + +- 初始化与文件发现 + - 扫描同级目录下的 .md 文件，按环境变量过滤中英文版本；自动发现 demos 子目录下的 .py 示例模块并动态导入。 +- Markdown 解析 + - 使用 parse_markdown 将文档转为节点序列，支持 text/demo/file 三类节点。 +- 示例渲染 + - 支持 demo 标签属性：name、position、collapsible、fixed、title；支持 demo-prefix/demo-suffix 注入前缀/后缀代码；支持 file 标签内联外部文件内容。 +- CSS 合并 + - 遍历示例模块，收集 css 字段并注入到页面，解决多 Blocks 场景下样式丢失问题。 + +```mermaid +classDiagram +class Docs { ++__init__(file_path) +-_get_filename(filename) +-_remove_formatter(markdown_text) +-_list_demos(dir_path, prefix) +-_get_demo_modules() +-_read_file(relative_path) +-_render_demo(demo_name, prefix, suffix, position, collapsible, fixed, title) +-_render_markdown(markdown_file) ++get_css() ++render(module_name) +} +``` + +图表来源 + +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) + +章节来源 + +- [docs/helper/Docs.py:12-178](file://docs/helper/Docs.py#L12-L178) +- [docs/helper/parse_markdown.py:12-84](file://docs/helper/parse_markdown.py#L12-L84) + +### Site 工具类（站点布局） + +- Tabs 与菜单 + - 定义多个 Tab（概览、基础组件、高级组件、Antd 组件、Antdx 组件），每个 Tab 可包含 inline 菜单与内容区。 +- 事件联动 + - 顶部菜单与侧边菜单联动，点击菜单项同步更新 active_key 与可见内容；应用挂载时根据屏幕宽度调整侧边栏默认大小。 +- 响应式布局 + - 使用 Splitter 与 Layout 实现侧边栏与内容区的自适应；在小屏设备上隐藏侧边栏并提供内联菜单。 +- CSS 注入 + - 合并所有示例模块的 CSS，保证示例样式生效。 + +```mermaid +classDiagram +class Site { ++__init__(tabs, docs, default_active_tab, logo) +-_render_docs(items, tab) ++render() +} +``` + +图表来源 + +- [docs/helper/Site.py:9-255](file://docs/helper/Site.py#L9-L255) + +章节来源 + +- [docs/helper/Site.py:9-255](file://docs/helper/Site.py#L9-L255) + +### Markdown 解析器（demo/file 标签） + +- 支持标签 + - demo：包含 name、position、collapsible、fixed、title 等属性；用于标识要渲染的示例模块。 + - demo-prefix/demo-suffix：用于在 demo 前后注入额外代码片段。 + - file：内联读取指定路径的文件内容并插入到当前位置。 +- 解析流程 + - 基于 HTMLParser，遇到非允许标签则原样输出；遇到 demo/file 标签则构造相应节点；记录标签栈以便正确闭合。 + +```mermaid +flowchart TD +Start(["开始解析"]) --> Feed["逐段 feed 内容"] +Feed --> Tag{"遇到标签?"} +Tag --> |否| AppendText["追加到当前文本节点"] +Tag --> |是| Allowed{"是否允许标签?"} +Allowed --> |否| OutputRaw["原样输出标签文本"] +Allowed --> |是| HandleDemo["处理 demo 标签
name/position/collapsible/fixed/title"] +Allowed --> |是| HandleFile["处理 file 标签
读取外部文件内容"] +HandleDemo --> Next["继续解析"] +HandleFile --> Next +OutputRaw --> Next +AppendText --> Next +Next --> End(["返回节点序列"]) +``` + +图表来源 + +- [docs/helper/parse_markdown.py:12-84](file://docs/helper/parse_markdown.py#L12-L84) + +章节来源 + +- [docs/helper/parse_markdown.py:12-84](file://docs/helper/parse_markdown.py#L12-L84) + +### 环境变量与多语言支持 + +- 环境变量 + - MODELSCOPE_ENVIRONMENT=studio 时启用中文文档与特定过滤逻辑；否则仅显示英文文档。 +- 文档命名与过滤 + - 中文文档以 -zh_CN.md 结尾；英文文档无后缀；Docs 在初始化时根据环境变量过滤可用文档文件。 + +章节来源 + +- [docs/helper/env.py:1-4](file://docs/helper/env.py#L1-L4) +- [docs/helper/Docs.py:17-31](file://docs/helper/Docs.py#L17-L31) + +### 组件文档与示例管理 + +- 组件文档 + - 每个组件目录下包含 README.md 与 app.py；README.md 使用 demo 标签引用示例模块；app.py 通过 Docs 渲染该组件的文档页面。 +- 示例模块 + - demos 目录下放置 .py 文件，Docs 动态导入并调用其 demo.render() 方法进行渲染；可在示例模块中定义 css 字符串以注入样式。 +- 布局模板 + - layout_templates 目录下提供可复用的页面布局示例，同样通过 app.py 与 Docs 渲染。 + +```mermaid +sequenceDiagram +participant DOC as "组件 README.md" +participant DOCS as "Docs" +participant DEMO as "示例模块(.py)" +DOC->>DOCS : 解析 demo 标签 +DOCS->>DEMO : 动态导入并执行 demo.render() +DEMO-->>DOCS : 返回渲染结果 +DOCS-->>DOC : 渲染到页面 +``` + +图表来源 + +- [docs/components/antd/button/README.md:1-8](file://docs/components/antd/button/README.md#L1-L8) +- [docs/components/antd/button/app.py:1-7](file://docs/components/antd/button/app.py#L1-L7) +- [docs/helper/Docs.py:82-161](file://docs/helper/Docs.py#L82-L161) + +章节来源 + +- [docs/components/antd/button/README.md:1-8](file://docs/components/antd/button/README.md#L1-L8) +- [docs/components/antd/button/app.py:1-7](file://docs/components/antd/button/app.py#L1-L7) +- [docs/layout_templates/chatbot/README.md:1-20](file://docs/layout_templates/chatbot/README.md#L1-L20) +- [docs/layout_templates/chatbot/app.py:1-7](file://docs/layout_templates/chatbot/app.py#L1-L7) +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +## 依赖分析 + +- 运行时依赖 + - docs/requirements.txt 指定 gradio 与 modelscope_studio 版本，确保文档站点与组件库兼容。 +- 构建与脚本 + - package.json 提供 dev/build/publish 等脚本；pyproject.toml 定义后端打包与产物清单。 +- CI 工作流 + - publish.yaml：在分支推送时安装依赖、构建并发布至 PyPI，并创建标签与发布。 + - lint.yaml：执行代码风格与格式化检查。 + +```mermaid +graph LR +R["docs/requirements.txt"] --> APP["docs/app.py"] +PJ["package.json"] --> APP +PY["pyproject.toml"] --> APP +WF1[".github/workflows/publish.yaml"] --> APP +WF2[".github/workflows/lint.yaml"] --> APP +``` + +图表来源 + +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-L4) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) + +章节来源 + +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-L4) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) + +## 性能考虑 + +- 多 Blocks 场景下的 CSS 注入 + - Site 合并所有示例模块的 CSS，避免在多 Blocks 中重复注入导致的样式丢失。 +- 示例模块懒加载 + - Docs 仅在需要时动态导入示例模块，减少启动时的内存占用。 +- 响应式布局优化 + - 侧边栏尺寸根据屏幕宽度动态调整，提升移动端体验。 + +章节来源 + +- [docs/helper/Site.py:55-73](file://docs/helper/Site.py#L55-L73) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) +- [docs/helper/Site.py:241-249](file://docs/helper/Site.py#L241-L249) + +## 故障排查指南 + +- 文档未显示中文或英文不正确 + - 检查 MODELSCOPE_ENVIRONMENT 是否设置为 studio 或未设置；确认 README 文件命名是否符合 -zh_CN.md 规范。 +- 示例无法渲染或报错 + - 确认 demos 目录下存在对应名称的 .py 文件且包含 demo.render()；检查示例模块是否可被动态导入。 +- 页面样式异常 + - 确认示例模块中定义了 css 字符串；Site 会合并这些样式；若仍异常，检查是否有多个 Blocks 导致样式未注入。 +- 启动失败或端口占用 + - 使用 package.json 中的 dev 脚本启动；确保端口未被占用；必要时在 launch 参数中设置 ssr_mode=false。 + +章节来源 + +- [docs/helper/env.py:1-4](file://docs/helper/env.py#L1-L4) +- [docs/helper/Docs.py:58-75](file://docs/helper/Docs.py#L58-L75) +- [docs/helper/Site.py:55-73](file://docs/helper/Site.py#L55-L73) +- [README.md:32-32](file://README.md#L32-L32) +- [package.json:15-15](file://package.json#L15-L15) + +## 结论 + +ModelScope Studio 文档系统通过 Docs 与 Site 两大工具类，结合自定义 Markdown 解析器与示例模块动态加载机制，实现了组件文档与布局模板的统一渲染与多语言支持。借助清晰的目录结构与 CI 流程，维护者可以高效地扩展文档内容、添加示例并发布更新。 + +## 附录 + +### 使用与维护指南（操作步骤） + +- 编写组件文档 + - 在 docs/components/
package.json, pyproject.toml"] --> Frontend["前端工作区
frontend/*"] +Root --> Config["配置包
config/changelog"] +Root --> Scripts["发布脚本
scripts/*"] +Frontend --> Antd["antd 组件包"] +Frontend --> Antdx["antdx 组件包"] +Frontend --> Base["base 组件包"] +Frontend --> Pro["pro 组件包"] +Root --> Backend["后端 Python 包
backend/modelscope_studio"] +``` + +图表来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +章节来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## 核心组件 + +- 前端 Vite 构建插件：负责 React/Svelte 预处理、全局变量注入与外部化策略 +- Python 包构建系统：基于 Hatch，定义 artifacts、wheel/sdist 打包范围与可选依赖 +- 变更集与变更日志：Changesets 驱动的版本与日志生成，支持多包统一管理 +- 自动化发布流水线：GitHub Actions 触发构建、PyPI 发布与 GitHub Release 创建 + +章节来源 + +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [config/changelog/src/index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) + +## 架构总览 + +下图展示从本地开发到自动化发布的整体流程： + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Root as "根包脚本
package.json" +participant FE as "前端构建
Vite 插件" +participant PY as "Python 构建
Hatch" +participant TW as "Twine 发布" +participant GH as "GitHub Actions" +participant Repo as "PyPI 仓库" +Dev->>Root : 运行构建/版本命令 +Root->>FE : pnpm run build +FE-->>Root : 产出 dist/ 前端资源 +Root->>PY : pnpm run build (后端) +PY-->>Root : 产出 wheel/sdist +Root->>TW : pnpm run ci : publish +TW->>Repo : 上传 wheel/sdist +GH->>Root : 触发发布流水线 +Root->>GH : 创建标签与 Release +``` + +图表来源 + +- [package.json:8-25](file://package.json#L8-L25) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:22-55](file://scripts/publish-to-pypi.mts#L22-L55) + +## 详细组件分析 + +### 前端构建与打包 + +- 构建入口与插件链 + - 使用 Vite 插件组合：React SWC 与自定义 ModelScopeStudioVitePlugin + - 定义全局变量映射，将常用依赖外部化至宿主环境（如 window.ms_globals.React） + - 支持按需排除某些外部化项，便于在特定场景内联 +- 别名与预处理 + - 通过别名指向 utils/globals 目录，简化导入路径 + - 关闭 Svelte 预处理以避免与现有方案冲突 +- 生产环境优化 + - 在构建阶段设置 NODE_ENV 为 production + - 对导出的模块进行 AST 转换，将 import/export 重写为对全局对象的访问，减少打包体积 + +```mermaid +flowchart TD +Start(["开始"]) --> DefineCfg["加载 defineConfig 选项"] +DefineCfg --> UsePlugins["启用 React + ModelScopeStudioVitePlugin"] +UsePlugins --> ResolveAlias["@utils/@globals 别名解析"] +ResolveAlias --> Externalize{"是否启用外部化？"} +Externalize --> |是| RollupExt["Rollup 外部化全局映射"] +Externalize --> |否| SkipExt["跳过外部化"] +RollupExt --> Transform["AST 转换：import/export 映射到全局"] +SkipExt --> Transform +Transform --> BuildOut["输出生产构建产物"] +BuildOut --> End(["结束"]) +``` + +图表来源 + +- [frontend/defineConfig.js:8-18](file://frontend/defineConfig.js#L8-L18) +- [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) +- [frontend/plugin.js:77-165](file://frontend/plugin.js#L77-L165) + +章节来源 + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) + +### Python 包构建与分发 + +- 构建后端 Python 包 + - 使用 Hatchling 作为构建后端，读取 pyproject.toml 中的元数据与依赖 + - 指定 artifacts 列表，确保模板与静态资源被包含进 wheel + - wheel/sdist 的目标目录与排除规则明确，避免冗余文件进入发布包 +- 依赖与兼容性 + - 通过 hatch-requirements-txt 与 hatch-fancy-pypi-readme 管理依赖与 README 渲染 + - Python 版本要求与分类器声明清晰，便于 PyPI 展示与安装器识别 +- 版本号一致性 + - 根包与后端版本保持一致，避免发布时出现不匹配 + +```mermaid +flowchart TD +A["读取 pyproject.toml"] --> B["Hatchling 构建"] +B --> C{"目标类型？"} +C --> |wheel| D["打包为 wheel
包含 artifacts"] +C --> |sdist| E["打包为 sdist
包含 backend/modelscope_studio"] +D --> F["校验产物完整性"] +E --> F +F --> G["上传至 PyPITwine"] +``` + +图表来源 + +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) + +章节来源 + +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) + +### 版本管理与变更日志 + +- Changesets 配置 + - 使用自定义 changelog 生成器，支持 PR/Commit/用户链接解析 + - 统一版本基线与预发布标签（beta），便于预览与回滚 +- 变更日志生成 + - 通过 tsup 编译配置包，输出 esm/cjs 两种格式 + - changelog 生成器聚合各包 CHANGELOG 并写入临时状态文件，最终由根包驱动生成统一发布内容 +- 预发布模式 + - pre.json 指定预发布标签与初始版本，配合 Changesets 流程实现灰度发布 + +```mermaid +flowchart TD +CS["Changesets 提交"] --> Gen["执行 version 脚本"] +Gen --> Changelog["生成/更新变更日志"] +Changelog --> Pre["预发布标签beta"] +Pre --> Release["触发发布流水线"] +``` + +图表来源 + +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [config/changelog/src/index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [config/changelog/tsup.config.ts:1-21](file://config/changelog/tsup.config.ts#L1-L21) + +章节来源 + +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [config/changelog/src/index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [config/changelog/tsup.config.ts:1-21](file://config/changelog/tsup.config.ts#L1-L21) + +### 自动化发布流水线 + +- 触发条件 + - 推送至 main/next 分支且提交消息为“chore: update versions” +- 步骤分解 + - 安装 Python 与 Node 依赖，准备构建环境 + - 执行构建：pip 安装可编辑模式、pnpm 运行构建 + - 检查 dist 是否存在，防止构建失败继续发布 + - 使用 Twine 将 dist 内所有产物上传至 PyPI（带跳过已存在） + - 若发布成功，调用脚本创建 Git 标签并推送，随后在 GitHub 创建 Release，正文来自变更日志 + +```mermaid +sequenceDiagram +participant WF as "GitHub Actions" +participant Build as "构建步骤" +participant Check as "版本检查" +participant Upload as "Twine 上传" +participant Tag as "创建标签与 Release" +WF->>Build : 安装依赖并构建 +Build-->>WF : 产出 dist/ +WF->>Check : 检查 PyPI 是否已有同版本 +alt 已存在 +Check-->>WF : 跳过发布 +else 不存在 +WF->>Upload : 上传 dist/* 至 PyPI +Upload-->>WF : 发布完成 +WF->>Tag : 创建 v
脚本与依赖"] --> B[".github/workflows/lint.yaml
代码规范检查"] +A --> C[".github/workflows/publish.yaml
构建与发布"] +D["tests/test.py
基础交互示例"] --> E["Gradio 应用运行时"] +F["tests/test1.py
进度与队列示例"] --> E +G["docs/components/pro/web_sandbox/demos/error_handling.py
错误处理演示"] --> E +H["pyproject.toml
Python 包与构建配置"] --> I["后端组件实现
后端组件类"] +J["frontend/.../alert.error-boundary.tsx
前端错误边界"] --> K["组件桥接与渲染"] +I --> K +``` + +**图表来源** + +- [package.json:1-55](file://package.json#L1-L55) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [tests/test.py:1-17](file://tests/test.py#L1-L17) +- [tests/test1.py:1-15](file://tests/test1.py#L1-L15) +- [docs/components/pro/web_sandbox/demos/error_handling.py:1-28](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L28) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +**章节来源** + +- [package.json:1-55](file://package.json#L1-L55) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +## 核心组件 + +- 测试脚本与演示 + - tests/test.py：展示 Application 与 ConfigProvider 的组合使用，以及按钮点击事件与输入输出的简单交互。 + - tests/test1.py：演示进度条与队列在 Gradio 接口中的使用。 +- 错误处理与边界 + - 前端错误边界：frontend/antd/alert/error-boundary/alert.error-boundary.tsx 将 Ant Design 的 ErrorBoundary 以 sveltify 方式桥接到 Svelte 组件体系。 + - 后端错误边界：backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py 定义了支持 slots 的错误边界组件，skip_api=True 表明其不直接暴露 API。 +- 集成点示例 + - docs/components/pro/web_sandbox/demos/error_handling.py：演示 WebSandbox 在渲染错误、编译错误及自定义编译错误渲染下的行为，适合用于端到端测试与回归验证。 + +**章节来源** + +- [tests/test.py:1-17](file://tests/test.py#L1-L17) +- [tests/test1.py:1-15](file://tests/test1.py#L1-L15) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:20-72](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L20-L72) +- [docs/components/pro/web_sandbox/demos/error_handling.py:1-28](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L28) + +## 架构总览 + +下图展示了从测试脚本到组件渲染与错误处理的关键流程，体现单元级（组件接口）、集成级（前后端桥接）与端到端（应用运行时）的测试视角。 + +```mermaid +sequenceDiagram +participant T as "测试脚本
tests/test.py" +participant G as "Gradio 应用运行时" +participant MS as "后端组件
Application/ConfigProvider" +participant FE as "前端组件
ErrorBoundary" +participant RB as "错误边界组件
后端定义" +T->>G : "启动 Blocks 并注册事件" +G->>MS : "初始化上下文与组件" +MS-->>G : "渲染组件树" +G->>FE : "挂载前端组件" +FE-->>G : "捕获并呈现错误" +MS->>RB : "后端错误边界配置" +RB-->>G : "跳过 API 调用skip_api=True" +``` + +**图表来源** + +- [tests/test.py:10-17](file://tests/test.py#L10-L17) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:55-72](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L55-L72) + +## 详细组件分析 + +### 单元测试：组件接口与数据流 + +- 目标 + - 验证后端组件的 preprocess/postprocess、example_payload/example_value 是否符合预期。 + - 验证前端组件在错误边界场景下的行为是否稳定。 +- 建议用例 + - 对于后端组件：构造输入 payload，断言 preprocess 输出；构造后端值，断言 postprocess 输出；调用 example_payload/example_value 获取示例数据。 + - 对于前端错误边界：模拟异常抛出，断言错误边界是否正确捕获并渲染描述信息。 +- 参考实现位置 + - 后端组件接口定义与示例：[backend/modelscope_studio/components/pro/monaco_editor/**init**.py:87-106](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L87-L106) + - 前端错误边界实现：[frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +```mermaid +flowchart TD +Start(["开始：准备测试用例"]) --> Prep["构造输入 payload 或示例数据"] +Prep --> Pre["调用 preprocess 验证输入转换"] +Pre --> Post["调用 postprocess 验证输出转换"] +Post --> Example["调用 example_payload/example_value 获取示例"] +Example --> FEError["前端错误边界：模拟异常并断言渲染"] +FEError --> End(["结束：记录结果与报告"]) +``` + +**图表来源** + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:87-106](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L87-L106) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +**章节来源** + +- [backend/modelscope_studio/components/pro/monaco_editor/**init**.py:87-106](file://backend/modelscope_studio/components/pro/monaco_editor/__init__.py#L87-L106) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +### 集成测试：前后端桥接与上下文 + +- 目标 + - 验证 Python 组件与前端模板的桥接是否正确，上下文（如 Application、ConfigProvider）是否生效。 +- 建议用例 + - 在测试脚本中组合 Application 与 ConfigProvider，触发组件交互，断言渲染结果与状态变更。 + - 使用进度与队列接口验证异步任务的调度与反馈。 +- 参考实现位置 + - 基础交互示例：[tests/test.py:10-17](file://tests/test.py#L10-L17) + - 进度与队列示例：[tests/test1.py:6-14](file://tests/test1.py#L6-L14) + +```mermaid +sequenceDiagram +participant U as "测试用例" +participant P as "Python 组件
Application/ConfigProvider" +participant R as "Gradio 运行时" +participant F as "前端模板渲染" +U->>P : "创建组件实例与上下文" +P->>R : "注册组件与事件" +R->>F : "下发渲染指令" +F-->>R : "返回渲染结果" +R-->>U : "断言结果与状态" +``` + +**图表来源** + +- [tests/test.py:10-17](file://tests/test.py#L10-L17) +- [tests/test1.py:6-14](file://tests/test1.py#L6-L14) + +**章节来源** + +- [tests/test.py:10-17](file://tests/test.py#L10-L17) +- [tests/test1.py:6-14](file://tests/test1.py#L6-L14) + +### 端到端测试：错误处理与回归验证 + +- 目标 + - 验证 WebSandbox 在渲染错误、编译错误及自定义编译错误渲染下的稳定性与可恢复性。 +- 建议用例 + - 模拟渲染错误：点击按钮触发异常，断言错误提示出现。 + - 模拟编译错误：传入空模板或无效内容，断言编译错误渲染槽位被激活。 + - 自定义编译错误渲染：通过插槽参数映射，断言标题与副标题正确显示。 +- 参考实现位置 + - 错误处理演示：[docs/components/pro/web_sandbox/demos/error_handling.py:1-28](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L28) + +```mermaid +sequenceDiagram +participant E as "用户交互" +participant WS as "WebSandbox 组件" +participant ER as "错误边界/编译错误渲染槽位" +E->>WS : "触发渲染/编译" +WS-->>ER : "捕获异常或编译失败" +ER-->>E : "展示错误信息与标题" +``` + +**图表来源** + +- [docs/components/pro/web_sandbox/demos/error_handling.py:1-28](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L28) + +**章节来源** + +- [docs/components/pro/web_sandbox/demos/error_handling.py:1-28](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L28) + +## 依赖分析 + +- 质量与构建链路 + - Lint 工作流：安装 Python 与 Node 依赖，执行统一 lint 脚本，覆盖 JS/TS、样式与 Python 规范。 + - 发布工作流：在满足条件时执行构建与发布，并创建标签与发布说明。 +- 包与构建配置 + - Python 包通过 hatchling 构建，artifacts 列表包含大量组件模板目录，确保打包完整性。 +- 测试与调试工具 + - Gradio 提供队列与进度能力，适合在测试脚本中验证异步与进度反馈。 + - 前端错误边界组件通过 sveltify 与 ReactSlot 实现插槽渲染，便于在测试中注入自定义错误视图。 + +```mermaid +graph TB +A["lint.yaml
Lint 工作流"] --> B["package.json
lint 脚本"] +C["publish.yaml
发布工作流"] --> D["package.json
ci:publish 脚本"] +E["pyproject.toml
构建与打包配置"] --> F["后端组件模板打包"] +G["tests/test1.py
进度与队列"] --> H["Gradio 运行时"] +I["frontend/.../alert.error-boundary.tsx
错误边界"] --> J["组件渲染与测试"] +``` + +**图表来源** + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [package.json:18-24](file://package.json#L18-L24) +- [pyproject.toml:45-245](file://pyproject.toml#L45-L245) +- [tests/test1.py:6-14](file://tests/test1.py#L6-L14) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +**章节来源** + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [package.json:18-24](file://package.json#L18-L24) +- [pyproject.toml:45-245](file://pyproject.toml#L45-L245) + +## 性能考虑 + +- 异步与队列 + - 使用 Gradio 的 queue() 与 Progress 接口，可在测试脚本中验证任务调度与进度回调的性能表现。 + - 参考：[tests/test1.py:6-14](file://tests/test1.py#L6-L14) +- 前端渲染与错误边界 + - 错误边界组件应尽量避免额外渲染开销，确保在异常情况下快速降级并展示最小化 UI。 + - 参考：[frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- 打包与模板 + - Python 包的 artifacts 列表包含大量组件模板，建议在本地开发时仅加载必要模板，减少构建时间。 + - 参考：[pyproject.toml:45-245](file://pyproject.toml#L45-L245) + +[本节为通用指导，无需具体文件分析] + +## 故障排查指南 + +- 常见问题与定位 + - 渲染错误：通过 docs/components/pro/web_sandbox/demos/error_handling.py 中的演示，确认错误边界是否正确捕获并渲染。 + - 编译错误：当模板为空或语法错误时，检查编译错误渲染槽位是否被激活。 + - 插槽参数映射：若自定义错误视图未生效，检查参数映射是否正确传递至插槽。 +- 调试步骤 + - 启动测试脚本，观察控制台输出与页面交互。 + - 在前端错误边界组件中增加日志或最小化渲染，确认异常路径。 + - 使用 Gradio 的队列与进度接口验证异步任务的响应时间与稳定性。 +- 参考实现位置 + - 错误处理演示：[docs/components/pro/web_sandbox/demos/error_handling.py:1-28](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L28) + - 前端错误边界：[frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +**章节来源** + +- [docs/components/pro/web_sandbox/demos/error_handling.py:1-28](file://docs/components/pro/web_sandbox/demos/error_handling.py#L1-L28) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +## 结论 + +本指南基于仓库现有脚本、工作流与示例，给出了覆盖单元、集成与端到端的测试策略与调试方法。建议在日常开发中： + +- 以组件接口与数据流为核心编写单元测试； +- 以上下文与事件驱动为核心编写集成测试； +- 以错误处理与交互回归为核心编写端到端测试； +- 结合 Gradio 队列与进度能力进行性能验证； +- 借助 GitHub Actions 工作流确保代码质量与发布一致性。 + +[本节为总结，无需具体文件分析] + +## 附录 + +- 执行测试套件 + - 本地执行：参考 package.json 中的脚本，先安装依赖，再运行相应测试脚本。 + - 参考：[package.json:8-24](file://package.json#L8-L24) +- 质量检查与发布 + - Lint 工作流：[lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) + - 发布工作流：[publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- 组件打包与模板 + - Python 包构建配置：[pyproject.toml:45-245](file://pyproject.toml#L45-L245) + +**章节来源** + +- [package.json:8-24](file://package.json#L8-L24) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [pyproject.toml:45-245](file://pyproject.toml#L45-L245) diff --git "a/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\345\211\215\347\253\257\347\273\204\344\273\266\345\274\200\345\217\221.md" "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\345\211\215\347\253\257\347\273\204\344\273\266\345\274\200\345\217\221.md" new file mode 100644 index 00000000..57ce1863 --- /dev/null +++ "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\345\211\215\347\253\257\347\273\204\344\273\266\345\274\200\345\217\221.md" @@ -0,0 +1,418 @@ +# 前端组件开发 + + +**本文引用的文件** +- [frontend/package.json](file://frontend/package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/svelte-preprocess-react/index.ts](file://frontend/svelte-preprocess-react/index.ts) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts](file://frontend/svelte-preprocess-react/sveltify.svelte.ts) +- [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/patchProps.tsx](file://frontend/utils/patchProps.tsx) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/utils/style.ts](file://frontend/utils/style.ts) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/base/text/Index.svelte](file://frontend/base/text/Index.svelte) +- [frontend/base/text/text.tsx](file://frontend/base/text/text.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本指南面向前端开发者，系统讲解如何在 frontend/ 目录下基于 Svelte 5 开发组件，并通过 svelte-preprocess-react 将现有 React 组件桥接为 Svelte 组件。内容涵盖组件结构、生命周期与状态管理、事件处理、样式处理、插槽系统、属性传递、组件间通信与数据流等主题，并提供可直接参考的文件路径与最佳实践。 + +## 项目结构 + +- 根目录包含 Vite 配置与构建入口，前端工程以模块化方式组织，按组件类型分层（antd、antdx、base、pro 等）。 +- 每个具体组件通常由两部分组成：Svelte 层的 Index.svelte（负责属性透传、可见性控制、插槽收集与渲染）与 TSX 层的组件文件（负责实际 UI 渲染与桥接逻辑）。 +- svelte-preprocess-react 提供 sveltify 工具，将 React 组件包装为 Svelte 组件，支持插槽、上下文、节点树管理与挂载桥接。 + +```mermaid +graph TB +subgraph "前端工程" +A["defineConfig.js
Vite 配置"] +B["package.json
依赖与脚本"] +end +subgraph "组件层" +C["antd/button/Index.svelte
属性透传/可见性/插槽"] +D["antd/button/button.tsx
React 组件封装"] +E["base/text/Index.svelte
基础文本组件"] +F["base/text/text.tsx
React 组件封装"] +end +subgraph "桥接层" +G["svelte-preprocess-react/index.ts
导出入口"] +H["svelte-preprocess-react/sveltify.svelte.ts
sveltify 实现"] +I["svelte-preprocess-react/internal/ReactWrapper.svelte
Svelte 包装器"] +J["utils/renderSlot.tsx
插槽渲染工具"] +K["utils/patchProps.tsx
属性补丁工具"] +L["utils/createItemsContext.tsx
项上下文工具"] +M["utils/style.ts
样式转换工具"] +end +A --> C +A --> E +C --> D +E --> F +D --> H +C --> I +F --> H +H --> I +D --> J +F --> J +D --> K +F --> K +D --> L +F --> L +D --> M +F --> M +``` + +**图表来源** + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/base/text/text.tsx:1-11](file://frontend/base/text/text.tsx#L1-L11) +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte:1-82](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte#L1-L82) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) + +**章节来源** + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## 核心组件 + +- Svelte 组件层（Index.svelte） + - 负责接收父组件传入的属性，进行过滤与派生计算，控制可见性，收集插槽并透传给 TSX 层。 + - 使用异步加载导入 TSX 组件，避免阻塞首屏渲染。 +- TSX 组件层（\*.tsx） + - 通过 sveltify 将 React 组件包装为 Svelte 可用的组件，支持插槽映射、属性补丁、上下文注入与节点树管理。 + - 使用 ReactSlot 渲染来自 Svelte 的插槽内容，支持克隆与参数化渲染。 +- 桥接与工具 + - sveltify：建立 Svelte 与 React 的桥接，维护共享根节点与子节点树，负责挂载与卸载。 + - ReactWrapper：在 Svelte 中作为包装器，注入上下文、收集插槽与属性，并在销毁时清理节点树。 + - renderSlot/patchProps/createItemsContext/style：分别负责插槽渲染、属性补丁、项上下文与样式转换。 + +**章节来源** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/base/text/text.tsx:1-11](file://frontend/base/text/text.tsx#L1-L11) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte:1-82](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte#L1-L82) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) + +## 架构总览 + +下图展示了从 Svelte 组件到 React 组件的桥接流程，以及插槽与属性的传递链路。 + +```mermaid +sequenceDiagram +participant SvelteUI as "Svelte 组件(Index.svelte)" +participant Wrapper as "ReactWrapper.svelte" +participant Sveltify as "sveltify.svelte.ts" +participant Bridge as "Bridge(React)" +participant ReactComp as "TSX 组件(button.tsx/text.tsx)" +participant Slot as "ReactSlot" +SvelteUI->>Wrapper : "调用 importComponent 并传入 props/children" +Wrapper->>Sveltify : "svelteInit 初始化节点树" +Sveltify->>Bridge : "创建根节点并渲染 Bridge" +Bridge->>ReactComp : "渲染 React 组件" +ReactComp->>Slot : "根据 slots 渲染插槽内容" +ReactComp-->>Bridge : "返回 React 元素" +Bridge-->>Sveltify : "更新节点树" +Sveltify-->>Wrapper : "完成初始化" +Wrapper-->>SvelteUI : "完成渲染" +``` + +**图表来源** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte:1-82](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte#L1-L82) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) + +## 详细组件分析 + +### 组件结构与生命周期 + +- Svelte 层（Index.svelte） + - 使用 $props/$derived 进行属性派生与可见性判断；通过 importComponent 异步加载 TSX 组件，提升性能。 + - 使用 getProps/processProps 对属性进行过滤与额外处理，确保只传递必要属性。 + - 使用 getSlots 收集插槽，传递给 TSX 层。 +- TSX 层（\*.tsx） + - 使用 sveltify 包装 React 组件，声明支持的插槽键（如 icon、loading.icon），并在渲染时通过 ReactSlot 映射插槽。 + - 通过 useTargets 等工具处理 children 与 value 的优先级，保证渲染一致性。 +- 生命周期与状态 + - ReactWrapper 在初始化时注入上下文、收集插槽与属性；在销毁时从父节点移除自身并触发重渲染。 + - sveltify 内部维护共享根节点与子节点树，节点变更会触发 rerender。 + +```mermaid +flowchart TD +Start(["进入组件"]) --> Props["接收并派生属性
$props/$derived"] +Props --> Visible{"visible 为真？"} +Visible -- 否 --> Hide["不渲染"] +Visible -- 是 --> Import["importComponent 异步加载 TSX 组件"] +Import --> Slots["getSlots 收集插槽"] +Slots --> Render["渲染 TSX 组件并传入 props 与 slots"] +Render --> End(["完成"]) +Hide --> End +``` + +**图表来源** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) + +**章节来源** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/base/text/Index.svelte:1-42](file://frontend/base/text/Index.svelte#L1-L42) +- [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte:1-82](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte#L1-L82) + +### 事件处理与属性传递 + +- 属性传递 + - 通过 processProps 对属性进行过滤与映射，例如将 href_target 映射为 target，保留 restProps 与附加属性。 + - 使用 patchProps/applyPatchToProps 处理 key 等特殊属性，避免冲突。 +- 事件绑定 + - 在 TSX 层直接绑定 React 事件回调，Svelte 层通过 props 透传；注意避免重复绑定或丢失上下文。 +- 插槽映射 + - 在 TSX 层声明支持的插槽键，使用 ReactSlot 渲染对应插槽内容，支持 clone 与参数化渲染。 + +```mermaid +flowchart TD +A["Svelte 层属性"] --> B["processProps 过滤/映射"] +B --> C["patchProps 处理特殊属性"] +C --> D["透传至 TSX 组件"] +D --> E["React 事件绑定"] +D --> F["插槽键声明与映射"] +F --> G["ReactSlot 渲染插槽内容"] +``` + +**图表来源** + +- [frontend/antd/button/Index.svelte:24-52](file://frontend/antd/button/Index.svelte#L24-L52) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/antd/button/button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) + +**章节来源** + +- [frontend/antd/button/Index.svelte:24-52](file://frontend/antd/button/Index.svelte#L24-L52) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/antd/button/button.tsx:8-36](file://frontend/antd/button/button.tsx#L8-L36) + +### 样式处理与单位转换 + +- 样式对象转字符串：将驼峰命名转换为连字符形式，并对数值型属性自动添加 px 单位（除明确无需单位的属性外）。 +- HTML 内联样式：将样式对象转换为可直接用于内联样式的键值对。 +- 在 Svelte 层可通过 elem_style/elem_classes 透传样式与类名，在 TSX 层应用到目标 React 组件。 + +```mermaid +flowchart TD +A["React.CSSProperties"] --> B["styleObject2String
转为字符串样式"] +A --> C["styleObject2HtmlStyle
转为内联样式对象"] +B --> D["Svelte 层应用到元素"] +C --> E["TSX 层应用到目标组件"] +``` + +**图表来源** + +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) +- [frontend/antd/button/Index.svelte:62-63](file://frontend/antd/button/Index.svelte#L62-L63) + +**章节来源** + +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) +- [frontend/antd/button/Index.svelte:62-63](file://frontend/antd/button/Index.svelte#L62-L63) + +### 插槽系统与项上下文 + +- 插槽渲染 + - renderSlot 提供统一的插槽渲染入口，支持 clone、forceClone 与 params 参数化渲染。 + - ReactSlot 接收来自 Svelte 的插槽 DOM，将其渲染为 React 子树。 +- 项上下文（ItemsContext） + - createItemsContext 提供项集合的上下文，支持设置项、监听变更、子项递归构建。 + - ItemHandler 负责将 Svelte 的项描述（props、slots、children）转换为标准化结构并写入上下文。 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 组件" +participant Utils as "renderSlot/patchProps" +participant ReactSlot as "ReactSlot" +participant Items as "createItemsContext" +Svelte->>Utils : "renderSlot(el, options)" +Utils->>ReactSlot : "渲染插槽内容" +Svelte->>Items : "ItemHandler 设置项" +Items-->>Svelte : "onChange 回调通知" +``` + +**图表来源** + +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +**章节来源** + +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +### 组件间通信与数据流 + +- 父子通信 + - 父组件通过 props 与插槽向子组件传递数据与 UI 片段；子组件在 TSX 层解析并渲染。 +- 兄弟/跨层通信 + - 通过 createItemsContext 在多层级中共享项集合，实现兄弟组件之间的数据同步。 +- 事件回传 + - 在 TSX 层绑定回调并通过 props 向上传递给父组件；在 Svelte 层通过事件句柄转发。 + +```mermaid +flowchart TD +Parent["父组件"] --> |props + slots| Child["子组件(Svelte)"] +Child --> |importComponent| TSX["TSX 组件"] +TSX --> |回调/事件| Parent +Siblings["兄弟组件"] --> |ItemsContext| Shared["共享项集合"] +Shared --> Siblings +``` + +**图表来源** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +**章节来源** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +## 依赖关系分析 + +- 依赖与版本 + - 前端工程使用 Svelte 5 与 React 19，配合 @vitejs/plugin-react-swc 与 less、typescript-json-schema 等工具链。 + - svelte-preprocess-react 提供桥接能力，内部包含 Bridge、ReactWrapper、ReactSlot 等核心模块。 +- 关键依赖关系 + - Svelte 组件依赖 @svelte-preprocess-react/component 与 svelte 上下文工具进行属性与插槽处理。 + - TSX 组件依赖 sveltify 与 ReactSlot 进行桥接与插槽渲染。 + - 工具模块（renderSlot、patchProps、createItemsContext、style）贯穿于属性、插槽与样式处理。 + +```mermaid +graph LR +Pkg["package.json 依赖"] --> Svelte["Svelte 5"] +Pkg --> React["React 19"] +Pkg --> Tools["Vite/React-SWC/Less/TS"] +Comp["Svelte 组件(Index.svelte)"] --> Bridge["@svelte-preprocess-react
sveltify/ReactWrapper"] +Comp --> Utils["renderSlot/patchProps/style"] +Comp --> Items["createItemsContext"] +TSX["TSX 组件(button.tsx/text.tsx)"] --> Bridge +TSX --> Utils +TSX --> Items +``` + +**图表来源** + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/utils/style.ts:1-77](file://frontend/utils/style.ts#L1-L77) + +**章节来源** + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) + +## 性能考量 + +- 异步组件加载 + - 使用 importComponent 异步加载 TSX 组件，减少首屏负担，建议将体积较大的组件延迟加载。 +- 属性与插槽最小化 + - processProps 过滤无关属性，避免不必要的重渲染；仅传递必要的 slots 键，降低桥接成本。 +- 节点树管理 + - sveltify 维护共享根节点与子节点树，节点变更触发局部 rerender；避免频繁创建/销毁节点。 +- 样式转换缓存 + - 对样式对象转换结果进行缓存（如使用 useMemoizedEqualValue），减少重复计算。 + +[本节为通用性能建议，无需特定文件引用] + +## 故障排查指南 + +- 插槽未显示 + - 检查 TSX 是否声明了对应的插槽键；确认 renderSlot 的 el 是否存在且未被强制克隆导致内容丢失。 + - 参考路径：[frontend/utils/renderSlot.tsx:13-28](file://frontend/utils/renderSlot.tsx#L13-L28) +- 属性异常或冲突 + - 检查 patchProps/applyPatchToProps 的使用，确保 key 等特殊属性正确处理。 + - 参考路径：[frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- 组件未渲染或闪烁 + - 确认 visible 控制逻辑与 importComponent 加载时机；检查 ReactWrapper 的初始化与销毁钩子。 + - 参考路径：[frontend/antd/button/Index.svelte:59-73](file://frontend/antd/button/Index.svelte#L59-L73)、[frontend/svelte-preprocess-react/internal/ReactWrapper.svelte:60-66](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte#L60-L66) +- 项上下文未更新 + - 检查 ItemHandler 的 setItem 调用与 allowedSlots 配置；确认 onChange 回调是否触发。 + - 参考路径：[frontend/utils/createItemsContext.tsx:124-156](file://frontend/utils/createItemsContext.tsx#L124-L156) +- 样式不生效 + - 检查 styleObject2String/styleObject2HtmlStyle 的转换结果；确认是否遗漏单位或拼写错误。 + - 参考路径：[frontend/utils/style.ts:39-76](file://frontend/utils/style.ts#L39-L76) + +**章节来源** + +- [frontend/utils/renderSlot.tsx:13-28](file://frontend/utils/renderSlot.tsx#L13-L28) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) +- [frontend/antd/button/Index.svelte:59-73](file://frontend/antd/button/Index.svelte#L59-L73) +- [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte:60-66](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte#L60-L66) +- [frontend/utils/createItemsContext.tsx:124-156](file://frontend/utils/createItemsContext.tsx#L124-L156) +- [frontend/utils/style.ts:39-76](file://frontend/utils/style.ts#L39-L76) + +## 结论 + +本指南系统梳理了在 frontend/ 下基于 Svelte 5 与 svelte-preprocess-react 的组件开发方法，覆盖组件结构、生命周期、状态管理、事件处理、样式与插槽、属性传递及组件间通信。通过异步加载、属性过滤、插槽映射与项上下文等机制，既能保持 Svelte 的简洁性，又能高效复用 React 生态资源。建议在新组件开发中遵循本文的文件组织与桥接模式，以获得更好的可维护性与性能表现。 + +## 附录 + +- 新建组件步骤（建议流程） + - 在 frontend/ 目录下创建组件目录（如 frontend/antd/my-component/）。 + - 创建 Index.svelte：定义属性、可见性、插槽收集与 importComponent 异步加载。 + - 创建 my-component.tsx：使用 sveltify 包装 React 组件，声明插槽键并渲染 ReactSlot。 + - 如需样式，使用 style.ts 进行转换；如需插槽参数化，使用 renderSlot/patchProps。 + - 如需跨层共享数据，使用 createItemsContext 提供上下文与 onChange 回调。 +- 参考文件路径 + - [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) + - [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) + - [frontend/base/text/Index.svelte](file://frontend/base/text/Index.svelte) + - [frontend/base/text/text.tsx](file://frontend/base/text/text.tsx) + - [frontend/svelte-preprocess-react/sveltify.svelte.ts](file://frontend/svelte-preprocess-react/sveltify.svelte.ts) + - [frontend/svelte-preprocess-react/internal/ReactWrapper.svelte](file://frontend/svelte-preprocess-react/internal/ReactWrapper.svelte) + - [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) + - [frontend/utils/patchProps.tsx](file://frontend/utils/patchProps.tsx) + - [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) + - [frontend/utils/style.ts](file://frontend/utils/style.ts) diff --git "a/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\345\220\216\347\253\257\347\273\204\344\273\266\345\274\200\345\217\221.md" "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\345\220\216\347\253\257\347\273\204\344\273\266\345\274\200\345\217\221.md" new file mode 100644 index 00000000..54361427 --- /dev/null +++ "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\345\220\216\347\253\257\347\273\204\344\273\266\345\274\200\345\217\221.md" @@ -0,0 +1,363 @@ +# 后端组件开发 + + +**本文引用的文件** +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/__init__.py](file://backend/modelscope_studio/utils/dev/__init__.py) +- [backend/modelscope_studio/components/antd/button/__init__.py](file://backend/modelscope_studio/components/antd/button/__init__.py) +- [backend/modelscope_studio/components/antd/form/__init__.py](file://backend/modelscope_studio/components/antd/form/__init__.py) +- [backend/modelscope_studio/components/base/text/__init__.py](file://backend/modelscope_studio/components/base/text/__init__.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本指南面向后端组件开发者，系统讲解如何在 backend/modelscope_studio/components/ 目录下实现 Python 组件，涵盖组件类的继承体系、属性定义与验证、事件与回调、生命周期钩子、与前端 Svelte 组件的对接，以及 Python 到 JavaScript 的数据转换流程。文档同时给出组件注册机制（**init**.py 与 components.py）的使用方法，并通过真实文件路径指引具体实现步骤。 + +## 项目结构 + +ModelScope Studio 的后端组件采用分层与分类组织：按组件族分为 antd、antdx、base、pro；每个族内以模块化目录组织具体组件；通过各族的 components.py 进行集中导出，再由 components/**init**.py 汇总到顶层命名空间，便于统一导入与使用。 + +```mermaid +graph TB +subgraph "组件包" +A["backend/modelscope_studio/components/"] +A1["antd/"] +A2["antdx/"] +A3["base/"] +A4["pro/"] +end +subgraph "注册入口" +R1["antd/components.py"] +R2["antdx/components.py"] +R3["pro/components.py"] +R4["base/__init__.py"] +R0["components/__init__.py"] +end +A --> A1 +A --> A2 +A --> A3 +A --> A4 +A1 --> R1 +A2 --> R2 +A3 --> R4 +A4 --> R3 +R0 --> R1 +R0 --> R2 +R0 --> R3 +R0 --> R4 +``` + +图表来源 + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +章节来源 + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +## 核心组件 + +后端组件的基类与元类由开发工具模块提供，统一了组件的生命周期、事件绑定、布局与渲染控制、以及与前端目录映射的能力。 + +- 基类与元类 + - ModelScopeComponent：通用组件基类，支持 value、visible、elem\_\*、render 等标准属性，以及 load_fn、inputs、key、every 等高级配置。 + - ModelScopeLayoutComponent：用于布局或容器型组件，强调布局更新与上下文退出行为。 + - ModelScopeDataLayoutComponent：数据驱动的布局组件，融合 Gradio 的 BlockContext 能力，支持 preserved_by_key 等特性。 +- 关键约定 + - EVENTS：组件支持的事件列表，通常通过 EventListener 定义，回调中会更新 \_internal 的绑定标记，以便前端监听。 + - SLOTS：组件支持的插槽名称集合，用于前端渲染时的插槽注入。 + - FRONTEND_DIR：通过 resolve_frontend_dir 解析到对应前端 Svelte 组件目录，确保前后端一致。 + - skip_api：决定该组件是否暴露 API 接口（如某些纯展示组件可跳过 API）。 + - preprocess/postprocess/example_payload/example_value：标准化数据转换与示例值，保证前后端数据契约一致。 + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/utils/dev/**init**.py:9-13](file://backend/modelscope_studio/utils/dev/__init__.py#L9-L13) + +## 架构总览 + +后端组件与前端 Svelte 组件通过统一的目录映射与事件绑定机制对接。组件类在初始化时设置 FRONTEND_DIR，使前端能够定位到对应的 Svelte 实现；事件通过 EVENTS 列表与回调更新 \_internal 标记，前端据此绑定相应行为；数据流通过 preprocess/postprocess 规范化，确保 Python 层与 JS 层的数据形态一致。 + +```mermaid +sequenceDiagram +participant Py as "Python 组件类" +participant Meta as "事件元类/上下文" +participant FE as "前端 Svelte 组件" +Py->>Py : 初始化组件
设置 value/props/SLOTS/EVENTS/FrontendDir +Py->>Meta : 注册事件回调
更新 _internal 标记 +Meta-->>FE : 前端监听事件绑定 +FE-->>Py : 用户交互触发事件 +Py->>Py : preprocess(payload)
规范化输入 +Py->>Py : postprocess(value)
规范化输出 +Py-->>FE : 渲染结果/状态变更 +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) +- [backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) + +## 详细组件分析 + +### 组件类继承体系与职责 + +- ModelScopeComponent：通用组件，适合数据型组件（如文本、输入框、选择器等），支持 value 与标准 UI 属性。 +- ModelScopeLayoutComponent：布局型组件（如按钮、卡片、栅格等），强调布局更新与上下文退出。 +- ModelScopeDataLayoutComponent：数据驱动的布局组件（如表单、表格等），具备 BlockContext 能力，适合复杂交互与状态持久化。 + +```mermaid +classDiagram +class ModelScopeComponent { ++EVENTS ++SLOTS ++FRONTEND_DIR ++skip_api ++preprocess(payload) ++postprocess(value) ++example_payload() ++example_value() +} +class ModelScopeLayoutComponent { ++__exit__() +} +class ModelScopeDataLayoutComponent { ++__exit__() +} +ModelScopeLayoutComponent --|> ModelScopeComponent +ModelScopeDataLayoutComponent --|> ModelScopeComponent +ModelScopeDataLayoutComponent --|> BlockContext +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:54-169](file://backend/modelscope_studio/utils/dev/component.py#L54-L169) + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +### 事件处理与回调机制 + +- 事件定义：通过 EVENTS 列表声明组件支持的事件，如点击、字段变化、提交完成等。 +- 回调逻辑：事件回调中更新 \_internal 的绑定标记，通知前端进行事件绑定。 +- 典型用法：AntdButton 的点击事件、AntdForm 的 fields_change/finish/values_change 等。 + +```mermaid +sequenceDiagram +participant Btn as "AntdButton" +participant Form as "AntdForm" +participant FE as "前端" +Btn->>Btn : 定义 EVENTS["click"] +Btn->>Btn : 回调更新 _internal.bind_click_event +FE-->>Btn : 监听点击事件并执行回调 +Form->>Form : 定义 EVENTS["fields_change","finish","finish_failed","values_change"] +Form->>Form : 回调更新 _internal 绑定标记 +FE-->>Form : 监听表单事件并同步状态 +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) +- [backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) + +章节来源 + +- [backend/modelscope_studio/components/antd/button/**init**.py:41-46](file://backend/modelscope_studio/components/antd/button/__init__.py#L41-L46) +- [backend/modelscope_studio/components/antd/form/**init**.py:23-36](file://backend/modelscope_studio/components/antd/form/__init__.py#L23-L36) + +### 属性定义与验证机制 + +- 属性声明：组件在 **init** 中接收 value、additional_props 及大量 UI 相关参数（如尺寸、形状、颜色、样式等），并通过实例属性保存。 +- 数据模型：部分组件提供自定义数据模型（如 AntdFormData），用于规范化复杂数据结构。 +- 验证与转换：preprocess/postprocess 明确输入输出形态，避免前后端数据不一致。 + +```mermaid +flowchart TD +Start(["进入组件"]) --> Init["接收参数并赋值到实例属性"] +Init --> DataModel{"是否定义数据模型?"} +DataModel --> |是| UseDM["使用数据模型规范化输入"] +DataModel --> |否| SkipDM["跳过数据模型"] +UseDM --> Pre["preprocess(payload) 规范化输入"] +SkipDM --> Pre +Pre --> Process["业务处理/状态更新"] +Process --> Post["postprocess(value) 规范化输出"] +Post --> End(["返回给前端"]) +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/form/**init**.py:13-15](file://backend/modelscope_studio/components/antd/form/__init__.py#L13-L15) +- [backend/modelscope_studio/components/antd/form/**init**.py:120-126](file://backend/modelscope_studio/components/antd/form/__init__.py#L120-L126) + +章节来源 + +- [backend/modelscope_studio/components/antd/button/**init**.py:51-137](file://backend/modelscope_studio/components/antd/button/__init__.py#L51-L137) +- [backend/modelscope_studio/components/antd/form/**init**.py:13-15](file://backend/modelscope_studio/components/antd/form/__init__.py#L13-L15) +- [backend/modelscope_studio/components/antd/form/**init**.py:120-126](file://backend/modelscope_studio/components/antd/form/__init__.py#L120-L126) + +### 生命周期钩子与渲染控制 + +- 初始化：设置 visible、elem_id、elem_classes、elem_style、render、as_item、\_internal 等基础属性。 +- 上下文退出：布局型组件在 **exit** 中更新 layout=True，确保前端重新计算布局。 +- 渲染策略：skip_api 控制是否暴露 API；render 控制是否渲染；preserved_by_key 控制数据保留策略（在数据布局组件中生效）。 + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:24-26](file://backend/modelscope_studio/utils/dev/component.py#L24-L26) +- [backend/modelscope_studio/utils/dev/component.py:125-127](file://backend/modelscope_studio/utils/dev/component.py#L125-L127) +- [backend/modelscope_studio/utils/dev/component.py:161-168](file://backend/modelscope_studio/utils/dev/component.py#L161-L168) + +### 与前端 Svelte 组件的对接 + +- 目录映射：组件类通过 FRONTEND_DIR 指向前端 Svelte 组件目录，确保前后端一一对应。 +- 插槽与事件：SLOTS 定义插槽名，EVENTS 定义事件，前端据此渲染与绑定。 +- 数据转换：preprocess/postprocess 保证 Python 与 JS 之间的数据形态一致。 + +章节来源 + +- [backend/modelscope_studio/components/antd/button/**init**.py:139-156](file://backend/modelscope_studio/components/antd/button/__init__.py#L139-L156) +- [backend/modelscope_studio/components/antd/form/**init**.py:114-132](file://backend/modelscope_studio/components/antd/form/__init__.py#L114-L132) +- [backend/modelscope_studio/components/base/text/**init**.py:39-56](file://backend/modelscope_studio/components/base/text/__init__.py#L39-L56) + +### 创建新组件的步骤与规范 + +- 选择族别与目录 + - 在 antd、antdx、base、pro 中选择合适族别，于对应目录下新建组件子目录。 +- 编写组件类 + - 继承合适的基类（通用/布局/数据布局）。 + - 定义 EVENTS、SLOTS、FRONTEND_DIR。 + - 实现 preprocess/postprocess/example_payload/example_value。 + - 在 **init** 中接收并保存所有对外参数。 +- 注册组件 + - 在族级 components.py 中导入并导出组件类。 + - 若为新增族别，需在 components/**init**.py 中添加导出。 +- 示例参考 + - 文本组件（base/text）：最简组件示例，展示最小化属性与方法。 + - 按钮组件（antd/button）：布局型组件，包含事件与插槽。 + - 表单组件（antd/form）：数据布局型组件，包含数据模型与多事件。 + +章节来源 + +- [backend/modelscope_studio/components/antd/button/**init**.py:15-157](file://backend/modelscope_studio/components/antd/button/__init__.py#L15-L157) +- [backend/modelscope_studio/components/antd/form/**init**.py:17-133](file://backend/modelscope_studio/components/antd/form/__init__.py#L17-L133) +- [backend/modelscope_studio/components/base/text/**init**.py:8-57](file://backend/modelscope_studio/components/base/text/__init__.py#L8-L57) +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) + +## 依赖分析 + +- 组件族导出 + - antd/components.py 导入并导出众多组件类，形成完整生态。 + - antdx/components.py 导出扩展组件族。 + - pro/components.py 导出专业版组件族。 + - base/**init**.py 导出基础组件族。 + - components/**init**.py 汇总上述族导出，作为统一入口。 +- 组件类依赖 + - 所有组件均依赖 utils/dev 下的基类与工具函数（如 resolve_frontend_dir）。 +- 事件与上下文 + - 事件通过 gradio.events.EventListener 定义，回调更新 \_internal 标记，前端据此绑定。 + +```mermaid +graph LR +subgraph "组件族" +ANTDA["antd/components.py"] +ANTDXA["antdx/components.py"] +PROA["pro/components.py"] +BASEA["base/__init__.py"] +end +subgraph "汇总" +ROOTI["components/__init__.py"] +end +ANTDA --> ROOTI +ANTDXA --> ROOTI +PROA --> ROOTI +BASEA --> ROOTI +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) + +章节来源 + +- [backend/modelscope_studio/components/antd/components.py:1-145](file://backend/modelscope_studio/components/antd/components.py#L1-L145) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) + +## 性能考虑 + +- 事件绑定最小化：仅在必要时启用事件绑定，避免频繁更新 \_internal 导致前端重渲染。 +- 数据转换轻量化：preprocess/postprocess 应保持简单高效，避免深度拷贝与复杂计算。 +- 渲染控制：合理使用 render 与 skip_api，减少不必要的 API 暴露与渲染开销。 +- 布局组件优化：布局型组件在 **exit** 中更新 layout=True，应避免在高频事件中重复触发。 + +## 故障排查指南 + +- 事件未生效 + - 检查 EVENTS 是否正确声明，回调是否更新 \_internal 对应标记。 + - 确认前端已根据 \_internal 标记进行事件绑定。 +- 前端找不到组件 + - 检查 FRONTEND_DIR 是否指向正确的 Svelte 目录。 + - 确认 components.py 已导出该组件类，且 components/**init**.py 汇总导出。 +- 数据不一致 + - 检查 preprocess/postprocess 是否对齐前后端数据形态。 + - 对于复杂数据，确认是否使用了自定义数据模型并正确解析/序列化。 +- 渲染异常 + - 检查 skip_api 与 render 设置是否符合预期。 + - 布局组件注意在 **exit** 中的布局更新时机。 + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:15-26](file://backend/modelscope_studio/utils/dev/component.py#L15-L26) +- [backend/modelscope_studio/utils/dev/component.py:125-127](file://backend/modelscope_studio/utils/dev/component.py#L125-L127) +- [backend/modelscope_studio/components/antd/button/**init**.py:139-156](file://backend/modelscope_studio/components/antd/button/__init__.py#L139-L156) +- [backend/modelscope_studio/components/antd/form/**init**.py:114-132](file://backend/modelscope_studio/components/antd/form/__init__.py#L114-L132) + +## 结论 + +通过统一的基类体系、明确的事件与插槽约定、严格的前后端目录映射与数据转换规范，ModelScope Studio 的后端组件开发形成了高内聚、低耦合、易扩展的架构。遵循本文档的结构规范与实现步骤，即可快速创建高质量的组件并与前端 Svelte 生态无缝对接。 + +## 附录 + +- 快速参考 + - 组件基类：ModelScopeComponent / ModelScopeLayoutComponent / ModelScopeDataLayoutComponent + - 关键属性：EVENTS、SLOTS、FRONTEND_DIR、skip_api、preprocess/postprocess、example_payload/example_value + - 注册路径：族级 components.py → components/**init**.py + - 示例组件：antd/button、antd/form、base/text diff --git "a/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\347\273\204\344\273\266\345\274\200\345\217\221.md" "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\347\273\204\344\273\266\345\274\200\345\217\221.md" new file mode 100644 index 00000000..5c8b7c70 --- /dev/null +++ "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\347\273\204\344\273\266\345\274\200\345\217\221.md" @@ -0,0 +1,366 @@ +# 组件开发 + + +**本文引用的文件** +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/pro/__init__.py](file://backend/modelscope_studio/components/pro/__init__.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [frontend/svelte-preprocess-react/index.ts](file://frontend/svelte-preprocess-react/index.ts) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts](file://frontend/svelte-preprocess-react/sveltify.svelte.ts) +- [frontend/svelte-preprocess-react/react-slot.tsx](file://frontend/svelte-preprocess-react/react-slot.tsx) +- [frontend/utils/renderSlot.tsx](file://frontend/utils/renderSlot.tsx) +- [frontend/utils/patchProps.tsx](file://frontend/utils/patchProps.tsx) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/form/Index.svelte](file://frontend/antd/form/Index.svelte) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本指南面向在 ModelScope Studio 中进行组件开发的工程师与产品同学，覆盖后端 Python 组件实现、前端 Svelte 组件开发、React 组件桥接与插槽系统使用，以及组件结构规范、属性定义、事件处理、测试与文档编写最佳实践。通过并行解析后端组件基类与前端桥接机制，帮助你快速扩展现有组件或创建全新组件类型。 + +## 项目结构 + +ModelScope Studio 的组件体系由三层构成： + +- 后端 Python 组件层：统一继承自 Gradio 的组件元类，提供通用生命周期、事件与插槽能力。 +- 前端 Svelte 层：每个组件以 Svelte 包装器形式加载对应的 React 实现，负责属性透传、事件桥接与插槽渲染。 +- React 桥接层：通过 sveltify 将 Ant Design 等 React 组件“桥接”为 Svelte 可用的组件，并支持插槽与样式透传。 + +```mermaid +graph TB +subgraph "后端 Python" +PY_BASE["ModelScopeComponent
ModelScopeLayoutComponent
ModelScopeDataLayoutComponent"] +end +subgraph "前端 Svelte" +SV_WRAPPER["Svelte 包装器
Index.svelte"] +SV_SLOT["插槽渲染工具
renderSlot.tsx"] +end +subgraph "React 桥接" +REACT_SVELTIFY["sveltify 桥接器
sveltify.svelte.ts"] +REACT_SLOT["ReactSlot 插槽桥
react-slot.tsx"] +PATCH_PROPS["属性补丁工具
patchProps.tsx"] +end +PY_BASE --> SV_WRAPPER +SV_WRAPPER --> REACT_SVELTIFY +SV_WRAPPER --> SV_SLOT +SV_SLOT --> REACT_SLOT +REACT_SVELTIFY --> PATCH_PROPS +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) + +章节来源 + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) + +## 核心组件 + +- 后端组件基类 + - ModelScopeComponent：面向数据组件，支持 visible、elem_id、elem_classes、elem_style、value、key、inputs、load_fn 等通用属性；默认暴露 API。 + - ModelScopeLayoutComponent：面向布局组件，支持 as_item、visible、elem_id、elem_classes、elem_style、render 等；默认跳过 API 导出。 + - ModelScopeDataLayoutComponent：数据+布局混合组件，具备 BlockContext 能力与 layout 标记，避免重复渲染。 +- 前端桥接与插槽 + - sveltify：将 React 组件包装为 Svelte 组件，支持 slots 参数声明与插槽树构建。 + - ReactSlot：将 Svelte 插槽内容克隆并挂载到 React 子树中，支持属性与事件透传、MutationObserver 观察。 + - renderSlot：便捷入口，根据是否需要强制克隆或参数化渲染，提供上下文包裹。 + - patchProps/applyPatchToProps：对 key 等内部字段做兼容性转换，保证 React 渲染稳定。 + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) + +## 架构总览 + +下图展示从后端组件到前端 Svelte 包装器再到 React 组件的调用链路，以及插槽系统如何在 React 子树中复用 Svelte 插槽内容。 + +```mermaid +sequenceDiagram +participant PY as "后端组件
ModelScopeComponent" +participant SV as "Svelte 包装器
Index.svelte" +participant BR as "桥接器
sveltify.svelte.ts" +participant RX as "React 组件
button.tsx" +participant RS as "插槽桥接
ReactSlot" +PY->>SV : 初始化并注入属性/值 +SV->>BR : importComponent 加载 React 实现 +BR->>RX : 创建 Svelte 节点树并挂载 +RX->>RS : 使用 slots 与 ReactSlot 渲染插槽 +RS-->>RX : 克隆并挂载插槽 DOM含事件 +RX-->>SV : 事件回调触发 updateProps +SV-->>PY : 更新后端状态如 value、form_action +``` + +图表来源 + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) + +## 详细组件分析 + +### 后端组件基类与生命周期 + +- 继承关系 + - ModelScopeComponent：基础数据组件，支持 value、visible、elem\_\*、key、inputs、load_fn 等。 + - ModelScopeLayoutComponent：布局组件，支持 as*item、visible、elem*\*、render。 + - ModelScopeDataLayoutComponent：兼具数据与布局特性，进入/退出时标记 layout，避免重复渲染。 +- 关键行为 + - 自动记录父组件子节点索引，便于定位与更新。 + - 支持跳过 API 导出（skip_api），用于布局类组件。 + - 与 AppContext 协作，确保应用上下文存在。 + +```mermaid +classDiagram +class ModelScopeComponent { ++EVENTS ++skip_api ++__init__(...) +} +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__(...) +} +class ModelScopeDataLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__(...) +} +ModelScopeLayoutComponent --|> ModelScopeComponent +ModelScopeDataLayoutComponent --|> ModelScopeComponent +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +### 前端 Svelte 包装器与属性处理 + +- 典型流程 + - 通过 importComponent 异步加载对应 React 组件。 + - 使用 getProps/processProps 提取并转换属性，映射命名（如 fields_change → fieldsChange）。 + - 通过 getSlots 获取插槽集合，传递给 React 组件。 + - 在可见性控制下渲染，并将 children 作为默认插槽传入。 +- 事件桥接 + - 对于可变值组件（如 Form），监听 onValueChange 并调用 updateProps 更新后端状态。 + +```mermaid +flowchart TD +Start(["进入 Svelte 包装器"]) --> Load["importComponent 加载 React 组件"] +Load --> Extract["getProps/processProps 提取并转换属性"] +Extract --> Slots["getSlots 获取插槽集合"] +Slots --> Visible{"visible 为真？"} +Visible --> |是| Render["渲染 React 组件并传入 slots/value/事件"] +Visible --> |否| Skip["跳过渲染"] +Render --> Events["绑定事件回调如 onValueChange"] +Events --> Update["updateProps 更新后端状态"] +Update --> End(["完成"]) +Skip --> End +``` + +图表来源 + +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +章节来源 + +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +### React 组件桥接与插槽系统 + +- sveltify + - 接收 React 组件与可选 slots 声明，返回 Sveltified 组件。 + - 内部维护共享根节点与 Portal，按需创建 Bridge 渲染树。 + - 支持 ignore 忽略某些节点，便于复杂场景优化。 +- ReactSlot + - 将 Svelte 插槽克隆到 React 子树，保留事件监听器与子节点。 + - 支持强制克隆（forceClone）、参数化渲染（params）与属性观察（observeAttributes）。 + - 通过 ContextPropsProvider 与 patchProps 工具，确保 key 等内部字段正确传递。 +- 插槽渲染管线 + - renderSlot 根据 options 决定是否包裹 ContextPropsProvider。 + - patchProps/applyPatchToProps 在桥接前后修正 key 字段，避免 React 警告。 + +```mermaid +sequenceDiagram +participant SV as "Svelte 组件" +participant BR as "sveltify" +participant RD as "Bridge/ReactDOM" +participant RS as "ReactSlot" +participant RX as "Antd 组件" +SV->>BR : sveltify(ReactComp, { slots }) +BR->>RD : 创建共享根节点与 Portal +RD-->>BR : 初始化完成 +BR-->>SV : 返回可渲染的 Sveltified 组件 +SV->>RS : 传入 slots 与 props +RS->>RS : 克隆插槽 DOM含事件 +RS-->>RX : 渲染插槽内容 +``` + +图表来源 + +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) + +章节来源 + +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/svelte-preprocess-react/react-slot.tsx:1-224](file://frontend/svelte-preprocess-react/react-slot.tsx#L1-L224) +- [frontend/utils/renderSlot.tsx:1-29](file://frontend/utils/renderSlot.tsx#L1-L29) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) + +### 组件结构规范与属性定义 + +- 结构规范 + - 每个组件目录包含：Index.svelte（包装器）、对应 React 实现（如 button.tsx）、package.json 与 gradio.config.js。 + - 包装器负责属性提取、事件桥接与插槽透传。 +- 属性定义 + - 通用属性：visible、elem_id、elem_classes、elem_style、as_item、\_internal.layout 等。 + - 业务属性：如 Form 的 formAction、name，Button 的 target、loading.icon 等。 + - 映射规则：processProps 支持命名映射（如 fields_change → fieldsChange）。 +- 事件处理 + - 数据组件通过 onValueChange/updateProps 回写后端。 + - 行为组件通过 onClick/onSubmit 等原生事件触发后端动作。 +- 插槽系统 + - 通过 slots.icon、slots['loading.icon'] 等命名插槽注入 ReactSlot。 + - 支持 children 默认插槽与参数化插槽（params）。 + +章节来源 + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) + +### 扩展现有组件与创建全新组件类型 + +- 扩展现有组件 + - 在后端：基于 ModelScopeComponent/ModelScopeLayoutComponent 新增属性与事件，必要时重写 **exit**/**enter**。 + - 在前端：在 Svelte 包装器中扩展 getProps/processProps 映射，新增事件回调与插槽。 + - 在 React：通过 sveltify 增加 slots 声明，使用 ReactSlot 渲染插槽。 +- 创建全新组件类型 + - 后端：选择合适的基类，定义 EVENTS/SLOTS，设置 skip_api。 + - 前端：新建 Index.svelte，引入 importComponent 与 getSlots，配置 processProps。 + - React：实现 sveltify 包装，处理插槽与样式，导出默认组件。 + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [frontend/svelte-preprocess-react/sveltify.svelte.ts:1-119](file://frontend/svelte-preprocess-react/sveltify.svelte.ts#L1-L119) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +## 依赖分析 + +- 组件分类入口 + - 后端 components/**init**.py 汇聚 antd、antdx、base、pro 各模块组件。 + - antd/**init**.py 列举大量 Ant Design 组件别名，便于统一导入。 + - base/**init**.py 汇聚基础布局与文本组件。 + - pro/**init**.py 汇聚专业组件（如 Chatbot、Monaco Editor）。 +- 前端桥接入口 + - svelte-preprocess-react/index.ts 暴露 sveltify 与内部类型，供组件包装器使用。 + +```mermaid +graph TB +A["backend/modelscope_studio/components/__init__.py"] --> B["antd/__init__.py"] +A --> C["antdx/__init__.py"] +A --> D["base/__init__.py"] +A --> E["pro/__init__.py"] +F["frontend/svelte-preprocess-react/index.ts"] --> G["sveltify.svelte.ts"] +F --> H["react-slot.tsx"] +``` + +图表来源 + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/pro/**init**.py:1-7](file://backend/modelscope_studio/components/pro/__init__.py#L1-L7) +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) + +章节来源 + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) + +## 性能考虑 + +- 避免重复渲染 + - 使用 ModelScopeDataLayoutComponent 的 layout 标记，减少 BlockContext 重复渲染。 +- 插槽克隆策略 + - ReactSlot 支持强制克隆（clone/forceClone），在复杂 DOM 变更时保持事件与结构一致性。 + - 使用 MutationObserver 观测插槽变化，按需重绘，降低全量更新成本。 +- 属性透传优化 + - 通过 patchProps/applyPatchToProps 仅在必要时转换 key 等字段，减少 React diff 开销。 +- 异步加载 + - Svelte 包装器使用 importComponent 异步加载 React 组件，避免首屏阻塞。 + +## 故障排查指南 + +- 插槽不生效 + - 检查 Svelte 包装器是否正确调用 getSlots 并传入 React 组件的 slots。 + - 确认 ReactSlot 的 slot 参数是否指向正确的 DOM 节点。 +- 事件未回传 + - 确认组件是否监听 onValueChange 或其他回调，并调用 updateProps 更新后端状态。 + - 对于表单类组件，检查 formAction 是否被清空或重置。 +- 样式与类名异常 + - 检查 elem_id、elem_classes、elem_style 是否正确透传至 React 组件。 + - 确认 ReactSlot 是否正确应用 className 与内联样式。 +- key 冲突或警告 + - 使用 patchProps/applyPatchToProps 处理内部 key 字段，避免 React 报错。 + +章节来源 + +- [frontend/antd/form/Index.svelte:1-99](file://frontend/antd/form/Index.svelte#L1-L99) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/utils/patchProps.tsx:1-39](file://frontend/utils/patchProps.tsx#L1-L39) + +## 结论 + +通过后端组件基类与前端桥接机制的协同，ModelScope Studio 实现了从 Python 到 Svelte 再到 React 的完整组件链路。遵循本文的结构规范、属性定义与事件处理约定，即可高效扩展现有组件或创建全新组件类型，并借助插槽系统实现灵活的内容复用与样式透传。 + +## 附录 + +- 组件开发清单 + - 后端：选择合适基类、定义 EVENTS/SLOTS、设置 skip_api、必要时重写生命周期。 + - 前端：编写 Index.svelte，配置 getProps/processProps 与 getSlots，处理事件回调。 + - React：使用 sveltify 包装，声明 slots，通过 ReactSlot 渲染插槽，应用样式与属性。 + - 测试：覆盖属性映射、事件回传、插槽渲染与错误边界。 + - 文档：按 docs/components 下各组件 README 模板编写，提供最小可用示例与参数说明。 diff --git "a/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\347\273\204\344\273\266\345\274\200\345\217\221\346\234\200\344\275\263\345\256\236\350\267\265.md" "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\347\273\204\344\273\266\345\274\200\345\217\221\346\234\200\344\275\263\345\256\236\350\267\265.md" new file mode 100644 index 00000000..47461040 --- /dev/null +++ "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\347\273\204\344\273\266\345\274\200\345\217\221\346\234\200\344\275\263\345\256\236\350\267\265.md" @@ -0,0 +1,407 @@ +# 组件开发最佳实践 + + +**本文引用的文件** +- [frontend/package.json](file://frontend/package.json) +- [frontend/antd/button/Index.svelte](file://frontend/antd/button/Index.svelte) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [frontend/base/text/text.tsx](file://frontend/base/text/text.tsx) +- [frontend/antd/layout/layout.base.tsx](file://frontend/antd/layout/layout.base.tsx) +- [frontend/antd/grid/context.ts](file://frontend/antd/grid/context.ts) +- [frontend/antd/config-provider/config-provider.tsx](file://frontend/antd/config-provider/config-provider.tsx) +- [frontend/antd/form/context.ts](file://frontend/antd/form/context.ts) +- [frontend/utils/hooks/useFunction.ts](file://frontend/utils/hooks/useFunction.ts) +- [frontend/utils/hooks/useMemoizedFn.ts](file://frontend/utils/hooks/useMemoizedFn.ts) +- [frontend/utils/createFunction.ts](file://frontend/utils/createFunction.ts) +- [frontend/utils/createItemsContext.tsx](file://frontend/utils/createItemsContext.tsx) +- [frontend/antd/table/table.tsx](file://frontend/antd/table/table.tsx) +- [frontend/antd/modal/modal.tsx](file://frontend/antd/modal/modal.tsx) +- [eslint.config.mjs](file://eslint.config.mjs) +- [prettier.config.mjs](file://prettier.config.mjs) + + +## 目录 + +1. [引言](#引言) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 引言 + +本指南面向在 ModelScope Studio 前端生态中进行组件开发的工程师，系统总结设计原则与编码规范，覆盖命名约定、文件组织、代码风格、性能优化、可复用性设计、错误处理与边界情况、国际化与无障碍、跨浏览器兼容等主题，并结合仓库中的真实组件实现给出重构建议与最佳实践。 + +## 项目结构 + +该项目采用多包工作区（pnpm workspace）组织，前端以 Svelte 5 + React 生态为核心，通过预处理层桥接 Ant Design 组件库，形成统一的组件体系。组件按领域分层：antd、antdx、base、pro 等模块，每个组件通常由 Svelte 入口文件与对应的 React 包装器组成，配合工具函数与上下文实现高内聚低耦合。 + +```mermaid +graph TB +subgraph "前端包" +Pkg["package.json
依赖声明"] +end +subgraph "组件层" +AntD["antd/* 组件"] +AntDX["antdx/* 组件"] +Base["base/* 基础组件"] +Pro["pro/* 专业组件"] +end +subgraph "工具与上下文" +Utils["utils/* 工具函数"] +Ctx["createItemsContext.tsx
通用项上下文"] +end +Pkg --> AntD +Pkg --> AntDX +Pkg --> Base +Pkg --> Pro +AntD --> Utils +AntDX --> Utils +Base --> Utils +Pro --> Utils +Utils --> Ctx +``` + +图表来源 + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +章节来源 + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## 核心组件 + +本节聚焦于组件开发的关键模式与规范，包括： + +- 统一的入口与包装：Svelte 入口负责属性透传、懒加载与插槽渲染；React 包装器负责生命周期与状态管理。 +- 可配置的国际化与主题：通过 ConfigProvider 提供语言、主题算法与容器策略。 +- 高内聚上下文：createItemsContext 抽象“项集合”与“子项处理器”，支撑复杂组件的动态列、行选择、展开等场景。 +- 函数式能力：useFunction、useMemoizedFn、createFunction 将字符串或函数式配置安全地转换为运行时函数。 + +章节来源 + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/utils/hooks/useFunction.ts:1-13](file://frontend/utils/hooks/useFunction.ts#L1-L13) +- [frontend/utils/hooks/useMemoizedFn.ts:1-11](file://frontend/utils/hooks/useMemoizedFn.ts#L1-L11) +- [frontend/utils/createFunction.ts:1-38](file://frontend/utils/createFunction.ts#L1-L38) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +## 架构总览 + +下图展示组件从入口到渲染的关键路径，以及与工具函数、上下文的关系。 + +```mermaid +sequenceDiagram +participant Svelte as "Svelte 入口(Index.svelte)" +participant Preprocess as "预处理桥接" +participant ReactComp as "React 包装器(.tsx)" +participant Util as "工具函数(useFunction/createFunction)" +participant Ctx as "上下文(createItemsContext)" +Svelte->>Preprocess : "importComponent 懒加载" +Preprocess-->>Svelte : "Awaited 组件" +Svelte->>ReactComp : "processProps 透传属性/插槽" +ReactComp->>Util : "useFunction/createFunction 安全执行" +ReactComp->>Ctx : "withItemsContextProvider/ItemHandler" +ReactComp-->>Svelte : "渲染最终 UI" +``` + +图表来源 + +- [frontend/antd/button/Index.svelte:10-73](file://frontend/antd/button/Index.svelte#L10-L73) +- [frontend/antd/form/form.tsx:15-76](file://frontend/antd/form/form.tsx#L15-L76) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/createFunction.ts:10-37](file://frontend/utils/createFunction.ts#L10-L37) +- [frontend/utils/createItemsContext.tsx:171-184](file://frontend/utils/createItemsContext.tsx#L171-L184) + +## 详细组件分析 + +### 组件命名与文件组织 + +- 命名约定 + - 组件目录与文件名使用小驼峰或短横线命名，如 button、date-picker、config-provider。 + - Svelte 入口统一命名为 Index.svelte，对应组件源文件命名为组件名.tsx 或组件名.svelte。 +- 文件组织 + - 每个组件包含：入口文件（Index.svelte）、组件实现（_.tsx）、样式（_.less）、配置（package.json、gradio.config.js）。 + - 复杂组件拆分子模块（如 table 的 column、row-selection、expandable），并通过上下文聚合。 + +章节来源 + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) +- [frontend/antd/table/table.tsx:1-200](file://frontend/antd/table/table.tsx#L1-L200) + +### 属性透传与懒加载 + +- 懒加载：通过 importComponent 实现按需加载，避免首屏体积膨胀。 +- 属性透传：processProps 过滤内部字段，保留可见性、样式、类名、ID 等对外属性。 +- 插槽渲染：getSlots 获取默认插槽，结合 ReactSlot 渲染自定义节点。 + +```mermaid +flowchart TD +Start(["进入组件"]) --> Load["懒加载 React 组件"] +Load --> Props["processProps 过滤/合并属性"] +Props --> Slots["getSlots 解析插槽"] +Slots --> Visible{"visible 为真？"} +Visible --> |是| Render["渲染组件并传递属性/插槽"] +Visible --> |否| Hide["不渲染"] +Render --> End(["完成"]) +Hide --> End +``` + +图表来源 + +- [frontend/antd/button/Index.svelte:12-56](file://frontend/antd/button/Index.svelte#L12-L56) + +章节来源 + +- [frontend/antd/button/Index.svelte:12-74](file://frontend/antd/button/Index.svelte#L12-L74) + +### 表单组件：状态同步与动作调度 + +- 动作调度：根据 formAction（reset/submit/validate）触发对应行为，并在完成后重置动作标记。 +- 值同步：value 变化时设置表单值，未提供时重置字段。 +- 插槽与回调：requiredMark、feedbackIcons 优先使用插槽，否则回退到函数或静态值；onValuesChange 同步外部状态。 + +```mermaid +sequenceDiagram +participant UI as "调用方" +participant Form as "Form 组件" +participant AntD as "Antd Form" +UI->>Form : "传入 value / formAction" +Form->>AntD : "初始化 Form 实例" +alt formAction = reset +Form->>AntD : "resetFields()" +else formAction = submit +Form->>AntD : "submit()" +else formAction = validate +Form->>AntD : "validateFields()" +end +Form->>UI : "onResetFormAction()" +UI->>Form : "value 变化" +Form->>AntD : "setFieldsValue(value)" +``` + +图表来源 + +- [frontend/antd/form/form.tsx:32-53](file://frontend/antd/form/form.tsx#L32-L53) +- [frontend/antd/form/form.tsx:15-76](file://frontend/antd/form/form.tsx#L15-L76) + +章节来源 + +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) + +### 布局基础组件：动态选择器 + +- Base 组件根据 component 参数动态选择 Header/Footer/Content/Layout，统一注入类名前缀，便于样式隔离。 + +章节来源 + +- [frontend/antd/layout/layout.base.tsx:1-40](file://frontend/antd/layout/layout.base.tsx#L1-L40) + +### 国际化与主题：ConfigProvider + +- 主题算法：支持暗色与紧凑算法组合，按 themeMode 切换。 +- 语言切换：根据 navigator 语言格式化为可用区域码，动态加载 antd 与 dayjs 本地化资源。 +- 容器策略：getPopupContainer/getTargetContainer 支持字符串或函数，函数通过 useFunction 安全执行。 +- 插槽注入：支持 renderEmpty 等插槽转为 React 节点。 + +```mermaid +flowchart TD +Init["初始化 ConfigProvider"] --> Locale["解析区域码"] +Locale --> LoadRes["异步加载语言资源"] +LoadRes --> ApplyTheme["计算算法数组"] +ApplyTheme --> Render["渲染子树"] +``` + +图表来源 + +- [frontend/antd/config-provider/config-provider.tsx:85-105](file://frontend/antd/config-provider/config-provider.tsx#L85-L105) +- [frontend/antd/config-provider/config-provider.tsx:127-143](file://frontend/antd/config-provider/config-provider.tsx#L127-L143) + +章节来源 + +- [frontend/antd/config-provider/config-provider.tsx:1-154](file://frontend/antd/config-provider/config-provider.tsx#L1-L154) + +### 上下文与项集合：createItemsContext + +- 作用：为复杂组件（如表格、表单项规则）提供“项集合”的收集与传递机制。 +- 关键能力 + - withItemsContextProvider：包裹子树，建立上下文。 + - ItemHandler：将子项（props/slots/children）写入上下文，支持 memo 化与去重。 + - useItems：读取当前项集合，触发 onChange 回调。 +- 使用场景：表格列、展开项、行选择、表单项规则等。 + +```mermaid +classDiagram +class ItemsContextProvider { ++allowedSlots ++onChange(items) ++setItem(slotKey, index, item) +} +class ItemHandler { ++itemIndex ++itemSlotKey ++itemProps(props, items) ++itemChildren(items) ++slots +} +class useItems { ++items ++initial ++setItem(...) +} +ItemsContextProvider --> useItems : "提供" +ItemHandler --> ItemsContextProvider : "写入项" +useItems --> ItemsContextProvider : "读取项" +``` + +图表来源 + +- [frontend/utils/createItemsContext.tsx:108-170](file://frontend/utils/createItemsContext.tsx#L108-L170) +- [frontend/utils/createItemsContext.tsx:190-261](file://frontend/utils/createItemsContext.tsx#L190-L261) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) + +章节来源 + +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) +- [frontend/antd/grid/context.ts:1-7](file://frontend/antd/grid/context.ts#L1-L7) +- [frontend/antd/form/context.ts:1-10](file://frontend/antd/form/context.ts#L1-L10) + +### 表格组件：列、展开、行选择与函数配置 + +- 列与扩展：通过上下文聚合列与展开配置，支持默认列与内置占位符（EXPAND_COLUMN、SELECTION_COLUMN）。 +- 函数配置：getPopupContainer、rowKey、rowClassName、sticky、showSorterTooltip、summary/footer 等均支持字符串或函数，经 createFunction/useFunction 安全执行。 +- 插槽：loading、pagination、tooltip、summary 等支持插槽参数化渲染。 + +章节来源 + +- [frontend/antd/table/table.tsx:41-200](file://frontend/antd/table/table.tsx#L41-L200) + +### 模态框组件：插槽与函数化配置 + +- 插槽优先：okText、cancelText、footer、title、closeIcon、okButtonProps.icon、cancelButtonProps.icon、closable.closeIcon、modalRender 等优先使用插槽。 +- 函数兜底：当插槽不可用时，使用 useFunction 将字符串或函数转换为可执行函数。 +- 容器策略：getContainer 支持字符串选择器或函数。 + +章节来源 + +- [frontend/antd/modal/modal.tsx:1-107](file://frontend/antd/modal/modal.tsx#L1-L107) + +### 基础文本组件：最小实现 + +- 仅接收 value 并渲染，若为空则插入空占位元素，保证 DOM 结构稳定。 + +章节来源 + +- [frontend/base/text/text.tsx:1-11](file://frontend/base/text/text.tsx#L1-L11) + +## 依赖关系分析 + +- 依赖来源：package.json 中集中声明 Ant Design、React、Svelte、国际化与多媒体相关依赖。 +- 组件间耦合：通过预处理桥接与工具函数降低耦合；复杂组件通过上下文解耦。 +- 外部集成：ConfigProvider 与 dayjs 协同实现语言切换；StyleProvider 控制样式哈希优先级。 + +```mermaid +graph LR +AntD["antd"] --> Comp["组件实现(.tsx)"] +React["react + react-dom"] --> Comp +Svelte["svelte"] --> Entry["入口(Index.svelte)"] +Entry --> Comp +Utils["工具函数"] --> Comp +Ctx["createItemsContext"] --> Comp +``` + +图表来源 + +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [frontend/antd/button/Index.svelte:6-10](file://frontend/antd/button/Index.svelte#L6-L10) +- [frontend/utils/createItemsContext.tsx:1-274](file://frontend/utils/createItemsContext.tsx#L1-L274) + +章节来源 + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## 性能考量 + +- 懒加载与按需渲染 + - 使用 importComponent 按需加载，避免一次性引入大量组件导致首屏阻塞。 + - Svelte 条件渲染 visible 字段，减少无效节点挂载。 +- 函数与对象稳定化 + - useFunction/useMemoizedFn/createFunction 将字符串或函数式配置转换为稳定函数，避免重复创建闭包。 + - useMemo/useMemoizedEqualValue 在上下文中缓存昂贵计算与等值比较。 +- 插槽与隐藏渲染 + - 复杂组件常将实际内容隐藏渲染，仅暴露占位，减少初始布局抖动。 +- 主题与样式 + - StyleProvider 配置哈希优先级，避免样式冲突带来的重绘。 +- 事件与回调 + - 对高频回调使用 useMemoizedFn 缓存引用，降低子组件重渲染概率。 + +章节来源 + +- [frontend/antd/button/Index.svelte:59-73](file://frontend/antd/button/Index.svelte#L59-L73) +- [frontend/antd/form/form.tsx:28-30](file://frontend/antd/form/form.tsx#L28-L30) +- [frontend/utils/hooks/useFunction.ts:5-12](file://frontend/utils/hooks/useFunction.ts#L5-L12) +- [frontend/utils/hooks/useMemoizedFn.ts:3-10](file://frontend/utils/hooks/useMemoizedFn.ts#L3-L10) +- [frontend/utils/createFunction.ts:10-37](file://frontend/utils/createFunction.ts#L10-L37) +- [frontend/antd/config-provider/config-provider.tsx:110-110](file://frontend/antd/config-provider/config-provider.tsx#L110-L110) + +## 故障排查指南 + +- 插槽未生效 + - 检查插槽键是否正确（如 footer、title、okText 等），确认是否使用 ReactSlot 包裹。 + - 对于需要参数的插槽，使用 renderParamsSlot 渲染。 +- 函数配置异常 + - 若传入字符串函数，确保格式合法；使用 createFunction/useFunction 安全执行。 +- 主题或语言不生效 + - 确认 themeMode 与 locale 设置；检查语言资源加载是否成功。 +- 上下文项未更新 + - 确保 ItemHandler 的 itemIndex 与 itemSlotKey 正确；检查 setItem 是否被调用。 +- 性能问题 + - 检查是否存在不必要的 props 变更；对回调使用 useMemoizedFn；避免在 render 内创建新函数。 + +章节来源 + +- [frontend/antd/modal/modal.tsx:40-95](file://frontend/antd/modal/modal.tsx#L40-L95) +- [frontend/antd/config-provider/config-provider.tsx:96-105](file://frontend/antd/config-provider/config-provider.tsx#L96-L105) +- [frontend/utils/createFunction.ts:10-37](file://frontend/utils/createFunction.ts#L10-L37) +- [frontend/utils/createItemsContext.tsx:234-254](file://frontend/utils/createItemsContext.tsx#L234-L254) + +## 结论 + +本指南基于仓库现有组件实现，总结了组件开发的设计原则与工程化实践：以 Svelte 入口 + React 包装器的桥接模式实现统一生态；通过上下文与工具函数实现高内聚低耦合；借助懒加载、函数稳定化与插槽机制提升性能与可扩展性。遵循这些最佳实践，可在保证一致性的同时提升组件质量与可维护性。 + +## 附录 + +### 设计原则与编码规范 + +- 命名与组织 + - 组件目录与文件名采用小驼峰或短横线命名；入口统一为 Index.svelte；实现为 \*.tsx。 + - 复杂组件拆分子模块并通过上下文聚合。 +- 属性与插槽 + - 明确区分对外属性与内部属性；对外属性通过 processProps 透传；插槽优先于静态值。 +- 函数与回调 + - 所有字符串函数通过 createFunction/useFunction 安全执行；高频回调使用 useMemoizedFn 缓存。 +- 国际化与主题 + - 使用 ConfigProvider 管理语言与主题；语言资源按需加载；容器策略支持字符串与函数。 +- 样式与主题 + - 使用 StyleProvider 控制样式哈希优先级；为不同组件类型注入统一前缀类名。 +- 错误处理与边界 + - 对不可识别的函数字符串返回 undefined 并降级；对插槽缺失时提供合理默认值。 +- 无障碍与兼容 + - 保持语义化标签与可访问属性；避免仅依赖颜色表达信息；测试主流浏览器与移动端。 + +章节来源 + +- [frontend/antd/button/Index.svelte:24-52](file://frontend/antd/button/Index.svelte#L24-L52) +- [frontend/antd/config-provider/config-provider.tsx:110-149](file://frontend/antd/config-provider/config-provider.tsx#L110-L149) +- [frontend/utils/createFunction.ts:10-37](file://frontend/utils/createFunction.ts#L10-L37) +- [eslint.config.mjs:1-9](file://eslint.config.mjs#L1-L9) +- [prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26) diff --git "a/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\347\273\204\344\273\266\346\226\207\346\241\243\347\274\226\345\206\231.md" "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\347\273\204\344\273\266\346\226\207\346\241\243\347\274\226\345\206\231.md" new file mode 100644 index 00000000..9414b2c8 --- /dev/null +++ "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\347\273\204\344\273\266\345\274\200\345\217\221/\347\273\204\344\273\266\346\226\207\346\241\243\347\274\226\345\206\231.md" @@ -0,0 +1,345 @@ +# 组件文档编写 + + +**本文引用的文件** +- [Docs.py](file://docs/helper/Docs.py) +- [Site.py](file://docs/helper/Site.py) +- [app.py](file://docs/app.py) +- [README.md](file://docs/README.md) +- [FAQ.md](file://docs/FAQ.md) +- [parse_markdown.py](file://docs/helper/parse_markdown.py) +- [button/README.md](file://docs/components/antd/button/README.md) +- [button/app.py](file://docs/components/antd/button/app.py) +- [chatbot/README.md](file://docs/layout_templates/chatbot/README.md) +- [chatbot/app.py](file://docs/layout_templates/chatbot/app.py) +- [example.py](file://docs/demos/example.py) +- [basic.py（按钮示例）](file://docs/components/antd/button/demos/basic.py) +- [basic.py（聊天模板示例）](file://docs/layout_templates/chatbot/demos/basic.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本指南面向为 ModelScope Studio 组件编写完整文档的开发者，覆盖以下主题： + +- README.md 的编写规范与元信息配置 +- demos 目录的组织结构与示例文件命名约定 +- app.py 的配置方法与站点导航构建 +- 文档生成工具 Docs.py 与 Site.py 的功能与用法 +- 示例代码的分层规范：基础用法、高级配置、常见问题 +- 组件分类与导航结构的组织方式 +- 模板与示例路径指引，帮助快速上手 + +## 项目结构 + +文档系统由“组件文档”“布局模板”“辅助工具”三部分组成，并通过统一入口 app.py 构建站点导航与内容渲染。 + +```mermaid +graph TB +A["docs/app.py
站点入口与导航"] --> B["docs/components/
组件文档目录"] +A --> C["docs/layout_templates/
布局模板目录"] +A --> D["docs/helper/Docs.py
文档渲染工具"] +A --> E["docs/helper/Site.py
站点布局与导航"] +D --> F["docs/helper/parse_markdown.py
Markdown 解析器"] +B --> G["README.md
组件说明与示例占位"] +B --> H["app.py
组件文档页面入口"] +B --> I["demos/*.py
示例代码集合"] +C --> J["README.md
模板说明与示例占位"] +C --> K["app.py
模板文档页面入口"] +C --> L["demos/*.py
模板示例集合"] +``` + +图表来源 + +- [app.py:1-598](file://docs/app.py#L1-L598) +- [Docs.py:1-178](file://docs/helper/Docs.py#L1-L178) +- [Site.py:1-255](file://docs/helper/Site.py#L1-L255) +- [parse_markdown.py:1-84](file://docs/helper/parse_markdown.py#L1-L84) + +章节来源 + +- [app.py:1-598](file://docs/app.py#L1-L598) + +## 核心组件 + +- Docs 渲染器：负责解析 README.md 中的
Svelte + React 包装"] +B["frontend/antdx/*
Svelte + React 包装"] +C["frontend/base/*
基础组件"] +D["frontend/pro/*
专业组件"] +end +subgraph "后端" +E["backend/modelscope_studio/
Python 包与模板"] +end +subgraph "测试与CI" +F[".github/workflows/lint.yaml
代码检查"] +G[".github/workflows/publish.yaml
发布流程"] +H[".changeset/*
版本与变更集"] +end +A --> E +B --> E +C --> E +D --> E +F --> A +F --> B +F --> C +F --> D +G --> E +H --> G +``` + +**图表来源** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) + +**章节来源** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) + +## 核心组件 + +- 组件封装模式：前端组件通常由 Svelte 模板负责属性与插槽处理，通过 React 包装层对接 Ant Design 组件，实现与 Gradio 的桥接。 +- 属性与插槽：组件接收标准属性并通过 slots 处理图标、加载态等扩展插槽，支持动态值与可见性控制。 +- 测试入口：仓库提供了基于 Gradio 的简单测试脚本，可作为端到端测试的起点。 + +**章节来源** + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [tests/test.py:1-17](file://tests/test.py#L1-L17) +- [tests/test1.py:1-15](file://tests/test1.py#L1-L15) + +## 架构总览 + +下图展示了从组件到测试与发布的整体流程，以及 Changesets 在版本管理中的作用。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Repo as "仓库(.changeset)" +participant GH as "GitHub Actions" +participant PyPI as "PyPI" +Dev->>Repo : 提交变更集与版本更新 +Repo-->>GH : 触发发布工作流 +GH->>GH : 安装依赖/构建/发布 +GH->>PyPI : 推送包并创建标签与发行版 +PyPI-->>Dev : 发布完成通知 +``` + +**图表来源** + +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) + +**章节来源** + +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [.changeset/README.md:1-9](file://.changeset/README.md#L1-L9) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) + +## 详细组件分析 + +### 组件：按钮（antd.button） + +该组件展示了典型的属性与插槽处理模式，包括： + +- 属性透传：将 Ant Design Button 的属性原样传递给底层组件。 +- 插槽支持：支持 icon 与 loading.icon 插槽，允许自定义图标与加载态。 +- 动态值与可见性：根据 children 与 value 决定渲染内容；visible 控制显示。 + +```mermaid +classDiagram +class ButtonWrapper { ++props : 所有AntD Button属性 ++slots : icon, loading.icon ++value : 文本值 ++children : 子节点 ++render() : ReactElement +} +class AntDButton { ++...props ++icon ++loading +} +ButtonWrapper --> AntDButton : "属性透传与插槽渲染" +``` + +**图表来源** + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) + +```mermaid +sequenceDiagram +participant Svelte as "Index.svelte" +participant Wrapper as "button.tsx" +participant AntD as "AntD Button" +Svelte->>Wrapper : 传入属性与插槽 +Wrapper->>Wrapper : 解析slots与value +Wrapper->>AntD : 渲染Button并注入插槽 +AntD-->>Wrapper : 返回React元素 +Wrapper-->>Svelte : 返回最终组件 +``` + +**图表来源** + +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) + +**章节来源** + +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) + +### 测试场景与实践指导 + +- 属性验证：针对按钮组件，应验证 icon 与 loading.icon 插槽是否正确渲染；value 与 children 的优先级逻辑；visible 对显示的影响。 +- 事件触发：在 Gradio Blocks 中为按钮绑定 click 回调，验证输入输出与回调触发顺序。 +- 状态变化：验证 loading 状态切换、disabled 状态、size 等属性对渲染的影响。 +- 端到端测试：使用 Gradio Interface/Blocks 启动本地服务，通过人工或自动化方式点击按钮、观察输出与日志。 + +```mermaid +flowchart TD +Start(["开始"]) --> Props["准备组件属性与插槽"] +Props --> Render["渲染组件"] +Render --> Event["模拟用户事件(如点击)"] +Event --> Verify["断言结果(属性/事件/状态)"] +Verify --> Report["生成测试报告"] +Report --> End(["结束"]) +``` + +[此图为概念性流程，不直接映射具体源码文件] + +**章节来源** + +- [tests/test.py:1-17](file://tests/test.py#L1-L17) +- [tests/test1.py:1-15](file://tests/test1.py#L1-L15) + +## 依赖分析 + +- 前端依赖：组件依赖 Ant Design 与 Svelte 5，通过 @svelte-preprocess-react 将 React 组件桥接到 Svelte。 +- 后端打包：使用 hatchling 构建 Python 包，包含大量模板文件，确保组件在 Gradio 环境中可用。 +- 版本与发布：Changesets 负责版本号与变更记录管理；发布工作流负责安装依赖、构建与发布到 PyPI。 + +```mermaid +graph LR +A["frontend/package.json"] --> B["@svelte-preprocess-react"] +A --> C["antd/svelte"] +D["pyproject.toml"] --> E["hatchling 构建"] +F["package.json"] --> G["changesets/cli"] +H[".github/workflows/publish.yaml"] --> I["PyPI 发布"] +G --> H +E --> I +``` + +**图表来源** + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) +- [package.json:1-55](file://package.json#L1-L55) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +**章节来源** + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) +- [package.json:1-55](file://package.json#L1-L55) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +## 性能考虑 + +- 组件渲染：尽量减少不必要的属性重算与插槽解析，避免在渲染路径上做重型计算。 +- 事件处理：在 Gradio 中绑定事件时，注意回调函数的幂等性与副作用最小化。 +- 构建与发布：发布工作流已包含安装与构建步骤，建议在本地缓存依赖以提升速度。 + +[本节为通用建议，无需源码引用] + +## 故障排查指南 + +- Lint 工作流失败：检查 Python 与 Node 依赖安装、格式化与类型检查是否通过。 +- 发布工作流失败：确认 PyPI 密钥与 GitHub Token 配置正确；检查版本更新与标签创建步骤。 +- 组件渲染异常：核对插槽名称与属性透传逻辑；检查 Svelte 模板与 React 包装层的兼容性。 + +**章节来源** + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +## 结论 + +本指南基于现有仓库结构与配置，给出了组件测试与持续集成的实施建议。建议在现有 Lint 工作流基础上补充单元与端到端测试步骤，并结合 Changesets 与发布工作流形成完整的质量闭环。 + +## 附录 + +### 使用 Changesets 管理版本与发布 + +- 初始化与配置：仓库已包含 Changesets 配置与说明文档，可直接使用。 +- 常见命令： + - 版本更新：运行版本更新脚本以生成变更集与版本号。 + - 创建变更集：在需要时新增变更集文件描述改动范围与影响。 +- 与发布流程协作：发布工作流会根据版本更新后的提交进行构建与发布。 + +**章节来源** + +- [.changeset/README.md:1-9](file://.changeset/README.md#L1-L9) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [package.json:1-55](file://package.json#L1-L55) + +### 在 GitHub Actions 中添加测试步骤 + +- 当前工作流： + - Lint 工作流：安装依赖并执行代码检查。 + - 发布工作流：安装依赖、构建并发布到 PyPI。 +- 建议新增测试步骤： + - 单元测试：在前端组件目录中增加测试脚本与运行命令。 + - 集成测试：在后端 Python 包中增加测试脚本与运行命令。 + - 端到端测试：使用 Gradio 示例脚本启动服务并进行交互验证。 +- 测试报告：可在测试完成后上传报告或生成摘要信息。 + +**章节来源** + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [tests/test.py:1-17](file://tests/test.py#L1-L17) +- [tests/test1.py:1-15](file://tests/test1.py#L1-L15) + +### 组件测试用例与测试数据编写要点 + +- 用例设计： + - 正常路径：验证属性与插槽的正常渲染与交互。 + - 边界条件：空值、禁用态、加载态、超长文本等。 + - 错误场景：无效属性、缺失插槽等。 +- 测试数据： + - 使用最小化数据集覆盖关键分支。 + - 对于异步场景（如进度条），使用时间片与断言描述。 +- 断言策略： + - 属性断言：校验最终渲染的 DOM 或 React 元素属性。 + - 事件断言：校验回调触发次数与参数。 + - 状态断言：校验组件内部状态变化与外部表现一致。 + +**章节来源** + +- [tests/test1.py:1-15](file://tests/test1.py#L1-L15) +- [frontend/fixtures.d.ts:1-50](file://frontend/fixtures.d.ts#L1-L50) diff --git "a/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\350\264\241\347\214\256\346\214\207\345\215\227.md" "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\350\264\241\347\214\256\346\214\207\345\215\227.md" new file mode 100644 index 00000000..497028e1 --- /dev/null +++ "b/.wiki/zh/\345\274\200\345\217\221\346\214\207\345\215\227/\350\264\241\347\214\256\346\214\207\345\215\227.md" @@ -0,0 +1,317 @@ +# 贡献指南 + + +**本文引用的文件** +- [README.md](file://README.md) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [.commitlintrc.js](file://.commitlintrc.js) +- [.lintstagedrc](file://.lintstagedrc) +- [.editorconfig](file://.editorconfig) +- [.flake8](file://.flake8) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [eslint.config.mjs](file://eslint.config.mjs) +- [prettier.config.mjs](file://prettier.config.mjs) +- [config/lint-config/package.json](file://config/lint-config/package.json) +- [config/lint-config/eslint.mjs](file://config/lint-config/eslint.mjs) +- [config/lint-config/stylelint.js](file://config/lint-config/stylelint.js) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本指南面向希望参与 ModelScope Studio 开发与维护的贡献者，涵盖从环境搭建、代码规范、提交规范到 Pull Request 流程、Bug 报告与功能建议、治理与决策流程等全链路实践。项目采用多包工作区（pnpm workspaces）组织前端组件与后端 Python 包，并通过 Changesets 进行版本与变更集管理，配合 GitHub Actions 自动化执行 Lint 与发布。 + +## 项目结构 + +- 根目录包含前端组件库、Python 后端包、文档站点、脚本与配置等。 +- 前端以 Svelte 5 为基础，按 Ant Design、Ant Design X、Base 组件分包组织；同时存在 Pro 专属组件。 +- 后端为 Python 包，使用 Hatch 构建系统，导出大量模板资源供前端运行时使用。 +- 工作区通过 pnpm-workspace.yaml 统一管理，包含根、配置、前端各子包等。 + +```mermaid +graph TB +Root["根目录
package.json/pyproject.toml"] --> Frontend["前端工作区
frontend/*"] +Root --> Backend["后端工作区
backend/modelscope_studio"] +Root --> Config["配置工作区
config/*"] +Root --> Docs["文档站点
docs/*"] +Frontend --> Antd["antd 子包"] +Frontend --> Antdx["antdx 子包"] +Frontend --> Base["base 子包"] +Frontend --> Pro["pro 子包"] +Config --> LintCfg["lint-config 子包"] +``` + +图表来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +章节来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +## 核心组件 + +- 多包工作区与构建：前端使用 Gradio CLI 构建，根脚本统一管理构建、格式化、类型检查、样式检查与 Lint。 +- 版本与发布：Changesets 负责版本号与变更日志生成；GitHub Actions 在主分支推送时触发发布流程。 +- 提交规范：Commitlint 使用 Conventional Commits 类型，限制类型枚举并放宽大小写与长度限制。 +- 本地钩子：Husky 作为 Git 钩子工具，结合 lint-staged 对暂存文件进行快速 Lint 与格式化。 +- 编辑器一致性：EditorConfig 统一缩进、换行与字符集；Prettier 与 ESLint/Stylelint 分别负责格式化与规则校验。 + +章节来源 + +- [package.json:8-25](file://package.json#L8-L25) +- [.commitlintrc.js:1-30](file://.commitlintrc.js#L1-L30) +- [.lintstagedrc:1-7](file://.lintstagedrc#L1-L7) +- [.editorconfig:1-17](file://.editorconfig#L1-L17) +- [eslint.config.mjs:1-9](file://eslint.config.mjs#L1-L9) +- [prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26) + +## 架构总览 + +下图展示贡献流程的关键节点：本地开发、提交规范、CI Lint、版本与发布。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Git as "Git 钩子
lint-staged" +participant Lint as "Lint/格式化" +participant CI as "GitHub Actions" +participant Cfg as "Changesets" +participant PyPI as "PyPI 发布" +Dev->>Git : "添加文件到暂存区" +Git->>Lint : "对暂存文件执行 Lint/格式化" +Lint-->>Git : "通过/失败" +Dev->>CI : "推送分支" +CI->>CI : "执行 Lint 测试" +Dev->>Cfg : "创建/更新变更集" +Cfg-->>Dev : "生成版本与变更日志" +CI->>PyPI : "满足条件时发布" +``` + +图表来源 + +- [.lintstagedrc:1-7](file://.lintstagedrc#L1-L7) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [package.json:10-25](file://package.json#L10-L25) + +## 详细组件分析 + +### 代码规范与工具链 + +- ESLint 配置：根配置聚合 lint-config 中的基础规则，确保前端 JS/TS/Svelte 规则一致。 +- Prettier 配置：统一缩进、引号、尾随逗号、换行符等；针对 Svelte 文件指定解析器。 +- Stylelint 配置：由 lint-config 提供基础规则，支持 LESS/CSS 检查与修复。 +- EditorConfig：统一编辑器基础风格，避免因工具差异导致的格式漂移。 +- Flake8：Python Lint 规则与忽略项，限定最大行长与忽略特定规则。 + +章节来源 + +- [eslint.config.mjs:1-9](file://eslint.config.mjs#L1-L9) +- [prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26) +- [config/lint-config/eslint.mjs](file://config/lint-config/eslint.mjs) +- [config/lint-config/stylelint.js](file://config/lint-config/stylelint.js) +- [.editorconfig:1-17](file://.editorconfig#L1-L17) +- [.flake8:1-16](file://.flake8#L1-L16) + +### 提交规范与 Commitlint + +- 类型枚举：feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert。 +- 放宽策略：大小写、空 scope、句号与长度限制均关闭或放宽，降低提交门槛。 +- 与 Conventional Commits 兼容：便于下游 Changesets 与自动化发布识别。 + +章节来源 + +- [.commitlintrc.js:1-30](file://.commitlintrc.js#L1-L30) + +### 本地钩子与 lint-staged + +- 按文件类型分组执行 Lint 与格式化：LESS/CSS、JS/TS/Svelte、Markdown/YAML/JSON/HTML、Python。 +- 保证每次提交前的最小质量门禁，减少 CI 压力。 + +章节来源 + +- [.lintstagedrc:1-7](file://.lintstagedrc#L1-L7) + +### CI 流程与发布 + +- Lint 测试：安装 Python 依赖（flake8/isort/yapf），Node 依赖（pnpm），执行 pnpm run lint。 +- 发布流程：在主分支或 next 推送时，安装构建与发布所需依赖，执行版本更新与发布脚本，成功后创建标签与 Release。 + +章节来源 + +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +### Changesets 与版本管理 + +- Changesets 负责版本号推进与变更日志生成；根脚本中提供 version、fix-changelog 等命令。 +- 发布前可先构建变更日志子包，再执行版本更新与修复脚本。 + +章节来源 + +- [package.json:10-25](file://package.json#L10-L25) + +### 新贡献者入门步骤 + +- 克隆仓库并安装依赖：后端使用 pip 安装可编辑模式，前端使用 pnpm 安装与构建。 +- 启动文档站点示例：使用 gradio cc dev 运行 docs/app.py。 +- 修改代码后，确保通过本地 Lint 与格式化；提交前由 lint-staged 自动处理。 + +章节来源 + +- [README.md:80-101](file://README.md#L80-L101) +- [package.json:8-25](file://package.json#L8-L25) + +### Pull Request 流程 + +- 在本地完成修改与本地验证（Lint/格式化/类型检查/样式检查）。 +- 提交前确保 lint-staged 通过；提交信息遵循 Conventional Commits 类型。 +- 创建 PR 并等待 CI Lint 与必要测试通过；根据反馈迭代修改。 +- 维护者审核后合并，随后由发布流程自动处理版本与发布。 + +章节来源 + +- [.lintstagedrc:1-7](file://.lintstagedrc#L1-L7) +- [.commitlintrc.js:1-30](file://.commitlintrc.js#L1-L30) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) + +### Bug 报告与功能请求 + +- 在提交 Issue 前，请确认已阅读相关文档与 FAQ。 +- 提供清晰的复现步骤、期望行为与实际行为，以及环境信息（Python/Node/浏览器版本）。 +- 如涉及前端组件，可附上最小可复现示例或截图。 + +章节来源 + +- [README.md:17-101](file://README.md#L17-L101) + +### 讨论与协作 + +- 优先在 Issues 中进行公开讨论，便于追踪与归档。 +- 对于设计或架构层面的讨论，可在 Discussion 或 Issues 中发起主题帖。 + +章节来源 + +- [README.md:17-101](file://README.md#L17-L101) + +### 治理结构与决策流程 + +- 项目维护者负责审核 PR、Review 代码质量与设计合理性。 +- 发布权限由维护者控制，遵循 Changesets 与 CI 发布流程。 +- 社区贡献者通过 PR 参与改进，重大变更建议通过 Issues 讨论达成共识。 + +章节来源 + +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [package.json:10-25](file://package.json#L10-L25) + +## 依赖关系分析 + +- 工具链依赖：ESLint、Prettier、Stylelint、Husky、lint-staged、Changesets、Commitlint 等。 +- 前端构建：Gradio CLI、Svelte 5、TypeScript、Svelte 检查工具。 +- 后端构建：Hatch、Python 依赖声明与打包配置。 +- 工作区：pnpm-workspace.yaml 统一管理多包，仅构建依赖明确列出。 + +```mermaid +graph LR +Pkg["package.json"] --> ESL["ESLint 配置"] +Pkg --> Prettier["Prettier 配置"] +Pkg --> Husky["Husky 钩子"] +Pkg --> LintStaged["lint-staged"] +Pkg --> Changesets["Changesets"] +Pkg --> Commitlint["Commitlint"] +Pkg --> Gradio["Gradio CLI 构建"] +Py["pyproject.toml"] --> Hatch["Hatch 构建"] +WS["pnpm-workspace.yaml"] --> FE["frontend/*"] +WS --> CFG["config/*"] +WS --> BE["backend/*"] +``` + +图表来源 + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) + +章节来源 + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) + +## 性能考虑 + +- 本地 Lint 与格式化：通过 lint-staged 仅对暂存文件执行，缩短反馈周期。 +- CI 并行任务：Lint 任务拆分 JS/Python/Style/TS 检查并行执行，提升整体效率。 +- 类型检查与样式检查：在 CI 中集中执行，避免本地重复负担。 + +章节来源 + +- [.lintstagedrc:1-7](file://.lintstagedrc#L1-L7) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) + +## 故障排查指南 + +- 提交被拒绝（Commitlint 失败） + - 检查提交信息是否符合类型枚举；若需临时放宽，可在本地调整规则或使用 --no-verify 跳过。 + - 参考路径：[.commitlintrc.js:1-30](file://.commitlintrc.js#L1-L30) +- Lint 失败 + - 按文件类型执行对应 Lint 命令：pnpm run lint:js、pnpm run lint:py、pnpm run lint:style、pnpm run lint:ts。 + - 参考路径：[package.json:18-22](file://package.json#L18-L22) +- 格式化未生效 + - 确认 Prettier 插件与 Svelte 解析器配置正确；检查 .editorconfig 是否被编辑器识别。 + - 参考路径：[prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26)，[.editorconfig:1-17](file://.editorconfig#L1-L17) +- CI Lint 失败 + - 检查 Python 依赖安装与 Node 版本；确认 pnpm 安装与缓存清理。 + - 参考路径：[.github/workflows/lint.yaml:14-34](file://.github/workflows/lint.yaml#L14-L34) +- 发布失败 + - 确认 PyPI Token 有效；检查版本更新与标签创建脚本输出。 + - 参考路径：[.github/workflows/publish.yaml:59-74](file://.github/workflows/publish.yaml#L59-L74) + +章节来源 + +- [.commitlintrc.js:1-30](file://.commitlintrc.js#L1-L30) +- [package.json:18-22](file://package.json#L18-L22) +- [prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26) +- [.editorconfig:1-17](file://.editorconfig#L1-L17) +- [.github/workflows/lint.yaml:14-34](file://.github/workflows/lint.yaml#L14-L34) +- [.github/workflows/publish.yaml:59-74](file://.github/workflows/publish.yaml#L59-L74) + +## 结论 + +本贡献指南基于项目现有配置与工作流，提供了从环境准备、代码与提交规范、PR 流程到发布与故障排查的完整实践路径。建议新贡献者在首次参与时优先完成本地 Lint 与格式化验证，并遵循 Conventional Commits 提交信息规范，以确保顺畅的协作体验。 + +## 附录 + +- 快速命令参考 + - 安装与构建：参见 [README.md:80-101](file://README.md#L80-L101) + - Lint 与格式化：参见 [package.json:18-22](file://package.json#L18-L22) + - Changesets：参见 [package.json:10-25](file://package.json#L10-L25) +- 配置文件索引 + - ESLint：参见 [eslint.config.mjs:1-9](file://eslint.config.mjs#L1-L9) + - Prettier：参见 [prettier.config.mjs:1-26](file://prettier.config.mjs#L1-L26) + - Stylelint：参见 [config/lint-config/stylelint.js](file://config/lint-config/stylelint.js) + - Commitlint：参见 [.commitlintrc.js:1-30](file://.commitlintrc.js#L1-L30) + - EditorConfig：参见 [.editorconfig:1-17](file://.editorconfig#L1-L17) + - Flake8：参见 [.flake8:1-16](file://.flake8#L1-L16) + - 工作区：参见 [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) diff --git "a/.wiki/zh/\345\277\253\351\200\237\345\274\200\345\247\213.md" "b/.wiki/zh/\345\277\253\351\200\237\345\274\200\345\247\213.md" new file mode 100644 index 00000000..1b24101e --- /dev/null +++ "b/.wiki/zh/\345\277\253\351\200\237\345\274\200\345\247\213.md" @@ -0,0 +1,433 @@ +# 快速开始 + + +**本文引用的文件** +- [README.md](file://README.md) +- [pyproject.toml](file://pyproject.toml) +- [docs/requirements.txt](file://docs/requirements.txt) +- [docs/demos/example.py](file://docs/demos/example.py) +- [docs/FAQ.md](file://docs/FAQ.md) +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/base/__init__.py](file://backend/modelscope_studio/components/base/__init__.py) +- [frontend/package.json](file://frontend/package.json) +- [frontend/antd/button/button.tsx](file://frontend/antd/button/button.tsx) +- [frontend/antd/form/form.tsx](file://frontend/antd/form/form.tsx) +- [docs/app.py](file://docs/app.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) + + +## 更新摘要 + +**变更内容** + +- 更新Gradio版本要求：从4.43.0+迁移到6.0.0+ +- 添加版本限制说明和迁移指导 +- 更新依赖范围和版本约束 +- 强化版本兼容性警告 + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能注意事项](#性能注意事项) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本指南面向首次使用 ModelScope Studio 的开发者，帮助你在最短时间内完成安装与运行，并掌握导入组件库、创建基础界面的基本方法。你将学会： + +- 安装与环境准备（Python 版本、依赖） +- 最小可用示例的运行步骤 +- 组件库的导入与使用模式 +- 常见问题的快速解决 + +**重要更新**：ModelScope Studio 2.0.0 已迁移到 Gradio 6.0 生态系统，支持版本范围为 >=6.0.0 且 <=6.8.0。 + +## 项目结构 + +ModelScope Studio 是基于 Gradio 的第三方组件库，提供更丰富的页面布局与组件形态。项目采用"后端 Python 包 + 前端 Svelte/React 组件"的分层设计： + +- 后端：Python 包封装组件接口与模板资源 +- 前端：Svelte/React 组件桥接 Ant Design/Ant Design X，通过 @svelte-preprocess-react 实现桥接 +- 文档与示例：通过 docs/app.py 展示组件与布局模板 + +```mermaid +graph TB +subgraph "后端(Python)" +PY_API["Python API
components/__init__.py"] +PY_ANTD["antd 子模块
components/antd/__init__.py"] +PY_BASE["base 子模块
components/base/__init__.py"] +end +subgraph "前端(JS/TS)" +FE_BTN["Button 组件
frontend/antd/button/button.tsx"] +FE_FORM["Form 组件
frontend/antd/form/form.tsx"] +FE_PKG["依赖清单
frontend/package.json"] +end +subgraph "文档与示例" +DOCS_APP["示例应用
docs/app.py"] +DEMO_EXAMPLE["最小示例
docs/demos/example.py"] +end +PY_API --> PY_ANTD +PY_API --> PY_BASE +PY_ANTD --> FE_BTN +PY_ANTD --> FE_FORM +PY_BASE --> FE_BTN +FE_PKG --> FE_BTN +FE_PKG --> FE_FORM +DOCS_APP --> PY_API +DEMO_EXAMPLE --> PY_API +``` + +**图表来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/antd/form/form.tsx:1-79](file://frontend/antd/form/form.tsx#L1-L79) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +**章节来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## 核心组件 + +- 组件库入口：通过 modelscope_studio.components.\* 导入各子模块 + - antd：Ant Design 组件集合 + - base：基础布局与渲染组件（如 Application、AutoLoading、Slot、Fragment、Div、Text、Markdown 等） +- 关键组件使用模式 + - 使用上下文容器：ms.Application、antd.ConfigProvider、ms.AutoLoading + - 在容器内直接嵌套具体组件（如 antd.DatePicker） + +**章节来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +## 架构总览 + +下图展示了从 Python 应用到前端组件的调用链路，以及文档站点对组件的动态加载机制。 + +```mermaid +sequenceDiagram +participant Dev as "开发者脚本
docs/demos/example.py" +participant Blocks as "Gradio Blocks" +participant MSApp as "ms.Application" +participant CFG as "antd.ConfigProvider" +participant Auto as "ms.AutoLoading" +participant Comp as "antd.DatePicker" +Dev->>Blocks : 创建 Blocks 上下文 +Blocks->>MSApp : 进入 Application 容器 +MSApp->>CFG : 进入 ConfigProvider 容器 +CFG->>Auto : 进入 AutoLoading 容器 +Auto->>Comp : 渲染 DatePicker +Comp-->>Dev : 页面显示组件 +``` + +**图表来源** + +- [docs/demos/example.py:5-10](file://docs/demos/example.py#L5-L10) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +**章节来源** + +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## 详细组件分析 + +### 组件使用模式与最佳实践 + +- 使用容器组合 + - 建议在最外层包裹 ms.Application，内部再包裹 antd.ConfigProvider 与 ms.AutoLoading，以获得全局配置与自动加载反馈 +- 组件导入与实例化 + - 通过 modelscope_studio.components.antd 或 modelscope_studio.components.base 导入所需组件 + - 在容器作用域内直接实例化组件 +- 常用组件示例 + - 基础组件：Button、Text、Div、Markdown + - 数据录入：Form、Input、DatePicker、Select + - 反馈与提示：Message、Modal、Notification、Spin + +**章节来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) + +### 组件类关系（代码级） + +以下类图展示了前端组件与 Ant Design 的映射关系，体现组件桥接与插槽机制。 + +```mermaid +classDiagram +class Button { ++属性 : "antd Button Props" ++插槽 : "icon, loading.icon" ++行为 : "渲染 Antd Button" +} +class Form { ++属性 : "value, onValueChange, formAction" ++事件 : "onValuesChange" ++行为 : "表单状态管理与动作触发" +} +class AntdButton { ++属性 : "GetProps
antd/base"] +Import --> Ctx["进入容器
Application/ConfigProvider/AutoLoading"] +Ctx --> Render["渲染具体组件
如 DatePicker/Button/Form"] +Render --> Feedback["自动加载反馈
AutoLoading 显示"] +Feedback --> End(["完成"]) +``` + +**图表来源** + +- [docs/demos/example.py:5-10](file://docs/demos/example.py#L5-L10) +- [docs/FAQ.md:7-19](file://docs/FAQ.md#L7-L19) + +**章节来源** + +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) + +## 依赖关系分析 + +- Python 环境与版本 + - Python 版本要求：>=3.8 + - **Gradio 依赖范围**：>=6.0.0 且 <=6.8.0 + - **重要说明**：当前示例使用 5.34.1，但 2.0.0 版本已迁移到 Gradio 6.0 生态系统 +- 前端依赖 + - Ant Design 6.x、Ant Design X 2.x、React 19、Svelte 5、@gradio/\* 系列等 +- 文档与示例依赖 + - 示例脚本与文档站点使用 modelscope_studio==2.0.0 + +**重要更新**：版本迁移详情请参阅 [迁移说明](#迁移指导) + +```mermaid +graph LR +PyVer["Python >=3.8"] --> Install["pip 安装 modelscope_studio"] +Install --> Gradio["Gradio 6.0 生态系统
(>=6.0.0, <=6.8.0)"] +Gradio --> Front["前端组件运行时"] +Front --> Antd["Antd 6/Antd X 2 组件"] +``` + +**图表来源** + +- [pyproject.toml:15-26](file://pyproject.toml#L15-L26) +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-4) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) + +**章节来源** + +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-L4) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +### 版本迁移指导 + +**Gradio 6.0 迁移指南** + +ModelScope Studio 2.0.0 已完成从 Gradio 4.x 到 6.x 的重大迁移，涉及以下关键变更： + +#### 版本范围说明 + +- **支持版本**：>=6.0.0 且 <=6.8.0 +- **不支持版本**：<6.0.0 或 >6.8.0 +- **迁移原因**：Gradio 6.0 引入了重大架构变更，需要相应的组件适配 + +#### 迁移前版本使用 + +如果您的项目仍在使用 Gradio 4.43.0 到 6.0.0 之前的版本，请使用 1.x 版本： + +```bash +pip install modelscope_studio~=1.0 +``` + +#### 迁移后的版本使用 + +对于 Gradio 6.0+ 的新项目，使用最新版本： + +```bash +pip install modelscope_studio==2.0.0 +``` + +#### 兼容性注意事项 + +- **Hugging Face Space**：仍需使用 `ssr_mode=False` +- **组件 API**：大部分 API 保持向后兼容 +- **性能提升**：Gradio 6.0 提供更好的性能和稳定性 + +**章节来源** + +- [README.md:36-50](file://README.md#L36-L50) +- [pyproject.toml:26](file://pyproject.toml#L26) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) + +## 性能注意事项 + +- 交互延迟与加载反馈 + - 组件库独立提供了加载反馈机制，建议在全局启用 AutoLoading，以减少用户等待感知 +- 并发与队列 + - 文档站点示例使用了队列与并发限制参数，实际项目可根据需求调整 + +**章节来源** + +- [docs/FAQ.md:7-19](file://docs/FAQ.md#L7-L19) +- [docs/app.py:592-594](file://docs/app.py#L592-L594) + +## 故障排查指南 + +- Hugging Face Space 页面不显示 + - 在 demo.launch() 中添加 ssr_mode=False 参数 +- 操作响应慢或无反馈 + - 缺少 AutoLoading 容器会导致无加载反馈，建议在应用顶层加入 ms.AutoLoading +- **Gradio 版本冲突** + - 确保 Gradio 版本在 >=6.0.0 且 <=6.8.0 范围内 + - 如果使用旧版本 Gradio，请降级到 modelscope_studio 1.x + - 如果使用新版本 Gradio，请升级到 modelscope_studio 2.0.0 + +**章节来源** + +- [docs/FAQ.md:3-5](file://docs/FAQ.md#L3-L5) +- [docs/FAQ.md:7-19](file://docs/FAQ.md#L7-L19) +- [docs/requirements.txt:1-4](file://docs/requirements.txt#L1-L4) +- [README.md:36-50](file://README.md#L36-L50) + +## 结论 + +通过本指南，你已了解： + +- 如何安装与准备环境 +- 如何导入组件库并创建最小可用示例 +- 如何使用容器与组件的基本模式 +- 常见问题的快速定位与修复 +- **Gradio 版本迁移的重要注意事项** + +建议在后续开发中逐步引入更多组件（如 Form、Table、Modal 等），并结合 AutoLoading 优化用户体验。同时注意版本兼容性，确保 Gradio 版本符合当前支持范围。 + +## 附录 + +### 安装与运行步骤 + +- 安装 + - 使用 pip 安装 modelscope_studio +- 运行 + - 参考最小示例脚本，直接运行即可启动本地服务 + +**章节来源** + +- [README.md:38-57](file://README.md#L38-L57) +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +### 最小示例（路径） + +- 示例脚本路径：[docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) +- 运行命令参考：在示例脚本所在目录执行 Python 文件 + +**章节来源** + +- [docs/demos/example.py:1-11](file://docs/demos/example.py#L1-L11) + +### 组件导入与使用（路径） + +- 导入 antd 组件：[backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- 导入 base 组件：[backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- 组件库入口聚合：[backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- Python 包导出入口：[backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) + +**章节来源** + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/base/**init**.py:1-11](file://backend/modelscope_studio/components/base/__init__.py#L1-L11) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) + +### 文档站点与示例入口（路径） + +- 文档站点入口：[docs/app.py:1-595](file://docs/app.py#L1-L595) + +**章节来源** + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +### 版本兼容性矩阵 + +| Gradio 版本 | ModelScope Studio 版本 | 支持状态 | +| ----------------- | ---------------------- | --------- | +| >=4.43.0,<6.0.0 | 1.x | ✅ 支持 | +| >=6.0.0,<=6.8.0 | 2.0.0 | ✅ 支持 | +| <4.43.0 或 >6.8.0 | 任意 | ❌ 不支持 | + +> **⚠️ 说明：Gradio >6.8.0 不支持的原因** +> 当前版本尚未对 Gradio 6.8.0 以上版本进行全面测试与适配。Gradio 新版本可能包含组件 API、辺界行为和内部接口的变更，在未经验证全部覆盖之前不建议使用。如需使用更高版本，请关注官方仓库发布的兼容性更新公告。 + +**章节来源** + +- [README.md:36-50](file://README.md#L36-L50) +- [pyproject.toml:26](file://pyproject.toml#L26) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) diff --git "a/.wiki/zh/\346\225\205\351\232\234\346\216\222\351\231\244.md" "b/.wiki/zh/\346\225\205\351\232\234\346\216\222\351\231\244.md" new file mode 100644 index 00000000..97662de1 --- /dev/null +++ "b/.wiki/zh/\346\225\205\351\232\234\346\216\222\351\231\244.md" @@ -0,0 +1,400 @@ +# 故障排除 + + +**本文引用的文件** +- [README.md](file://README.md) +- [README-zh_CN.md](file://README-zh_CN.md) +- [FAQ.md](file://docs/FAQ.md) +- [FAQ-zh_CN.md](file://docs/FAQ-zh_CN.md) +- [docs/app.py](file://docs/app.py) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [backend/modelscope_studio/components/base/auto_loading/__init__.py](file://backend/modelscope_studio/components/base/auto_loading/__init__.py) +- [frontend/base/auto-loading/useLoadingStatus.ts](file://frontend/base/auto-loading/useLoadingStatus.ts) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/process_links.py](file://backend/modelscope_studio/utils/dev/process_links.py) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx) +- [backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py) +- [frontend/svelte-preprocess-react/component/import.ts](file://frontend/svelte-preprocess-react/component/import.ts) +- [frontend/utils/tick.ts](file://frontend/utils/tick.ts) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本指南面向使用 ModelScope Studio 的开发者，聚焦于安装、配置、运行时错误、性能等常见问题的系统性排查与解决。内容来源于仓库内的官方文档、FAQ、示例站点与源码实现，覆盖前端组件、后端组件桥接、自动加载反馈、错误边界、链接处理、开发与发布流程等关键路径。 + +## 项目结构 + +ModelScope Studio 是一个基于 Gradio 的第三方组件库，提供 Ant Design、Ant Design X 以及 Pro 组件生态。项目采用前后端分离与多包工作区组织方式： + +- 前端（Svelte + React 预处理）：位于 frontend 目录，按组件拆分，每个组件有独立的构建配置与模板目录 +- 后端（Python）：位于 backend/modelscope_studio，提供组件桥接到 Gradio 的能力 +- 文档与示例：docs 目录包含示例站点与组件文档 +- 构建与发布：package.json 与 pyproject.toml 定义脚本与打包规则；GitHub Actions 负责 Lint 与发布 + +```mermaid +graph TB +subgraph "文档与示例" +DOCS_APP["docs/app.py"] +DOCS_FAQ["docs/FAQ.md"] +end +subgraph "前端" +FE_AUTOLOAD["frontend/base/auto-loading/useLoadingStatus.ts"] +FE_ERROR_BOUNDARY["frontend/antd/alert/error-boundary/alert.error-boundary.tsx"] +FE_IMPORT["frontend/svelte-preprocess-react/component/import.ts"] +FE_TICK["frontend/utils/tick.ts"] +end +subgraph "后端" +BE_AUTOLOAD["backend/modelscope_studio/components/base/auto_loading/__init__.py"] +BE_COMPONENT["backend/modelscope_studio/utils/dev/component.py"] +BE_PROCESS_LINKS["backend/modelscope_studio/utils/dev/process_links.py"] +end +DOCS_APP --> FE_AUTOLOAD +DOCS_APP --> FE_ERROR_BOUNDARY +DOCS_APP --> BE_AUTOLOAD +DOCS_APP --> BE_COMPONENT +DOCS_APP --> BE_PROCESS_LINKS +FE_AUTOLOAD --> BE_AUTOLOAD +FE_ERROR_BOUNDARY --> BE_COMPONENT +FE_IMPORT --> BE_COMPONENT +FE_TICK --> BE_COMPONENT +``` + +**图表来源** + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:1-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L1-L65) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [backend/modelscope_studio/utils/dev/process_links.py:1-61](file://backend/modelscope_studio/utils/dev/process_links.py#L1-L61) + +**章节来源** + +- [README.md:1-101](file://README.md#L1-L101) +- [README-zh_CN.md:1-101](file://README-zh_CN.md#L1-L101) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## 核心组件 + +- 自动加载反馈（AutoLoading） + - 后端组件：提供全局加载状态、队列位置、ETA 等信息的桥接与渲染控制 + - 前端 Hook：useLoadingStatus 将 Gradio 的状态追踪转换为可展示的计时与 ETA 格式化 +- 错误边界（Alert.ErrorBoundary） + - 前端：通过 sveltify 包裹 Ant Design 的 ErrorBoundary，支持插槽注入消息与描述 + - 后端：对应组件定义，声明跳过 API 调用，仅用于前端渲染 +- 组件基类与上下文 + - 后端：ModelScopeComponent/ModelScopeLayoutComponent 等，统一组件生命周期与 App 上下文校验 +- 链接处理 + - 后端：process_links 将 Markdown/HTML 中的相对链接转换为可访问的 /file=... 资源路径 + +**章节来源** + +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:1-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L1-L65) +- [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:20-72](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L20-L72) +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) +- [backend/modelscope_studio/utils/dev/process_links.py:1-61](file://backend/modelscope_studio/utils/dev/process_links.py#L1-L61) + +## 架构总览 + +下图展示了从示例站点到组件渲染的关键调用链路，包括自动加载反馈与错误边界的协作。 + +```mermaid +sequenceDiagram +participant User as "用户" +participant Site as "Site 渲染(docs/app.py)" +participant AutoLoading as "AutoLoading(后端)" +participant Hook as "useLoadingStatus(前端)" +participant ErrorBoundary as "Alert.ErrorBoundary(前端)" +participant Comp as "具体组件(如 Button)" +User->>Site : 访问示例站点 +Site->>AutoLoading : 初始化全局加载反馈 +AutoLoading-->>Hook : 提供加载状态(ETA/队列/消息) +Hook-->>User : 展示计时/ETA/队列信息 +User->>Comp : 触发交互 +Comp-->>AutoLoading : 触发加载 +AutoLoading-->>Hook : 更新状态 +Hook-->>User : 实时更新 +Note over ErrorBoundary,Comp : 若组件抛错，由 ErrorBoundary 捕获并展示 +``` + +**图表来源** + +- [docs/app.py:577-595](file://docs/app.py#L577-L595) +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:1-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L1-L65) +- [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + +## 详细组件分析 + +### 自动加载反馈（AutoLoading） + +- 设计要点 + - 后端组件不参与常规 API 调用，仅负责渲染与状态桥接 + - 前端 Hook 使用 requestAnimationFrame 实现平滑计时，结合 ETA 与队列信息格式化输出 +- 常见问题定位 + - 若无 AutoLoading，Gradio 默认加载状态可能不显示，导致用户感知延迟 + - 队列过大或后台任务耗时长会导致 ETA 波动，需结合队列大小与并发限制评估 + +```mermaid +flowchart TD +Start(["进入交互"]) --> CheckAutoLoading["是否存在 AutoLoading 组件?"] +CheckAutoLoading --> |否| ShowDefault["显示 Gradio 默认加载状态"] +CheckAutoLoading --> |是| UseHook["useLoadingStatus 订阅状态"] +UseHook --> UpdateUI["更新 ETA/计时/队列信息"] +ShowDefault --> WaitResponse["等待响应"] +UpdateUI --> WaitResponse +WaitResponse --> End(["交互完成"]) +``` + +**图表来源** + +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:1-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L1-L65) +- [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) + +**章节来源** + +- [backend/modelscope_studio/components/base/auto_loading/**init**.py:1-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L1-L65) +- [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) + +### 错误边界（Alert.ErrorBoundary） + +- 设计要点 + - 前端通过 sveltify 包裹 Ant Design 的 ErrorBoundary，支持 slots 注入 message/description + - 后端组件声明 skip_api，避免被当作普通组件进行 API 调用 +- 常见问题定位 + - 组件内部异常未被捕获会直接中断 UI，应确保关键区域包裹 ErrorBoundary + - 插槽内容为空时回退到 props，保证错误信息可见性 + +```mermaid +sequenceDiagram +participant FE as "前端组件" +participant EB as "ErrorBoundary" +participant BE as "后端组件(声明 skip_api)" +FE->>EB : 抛出异常 +EB-->>FE : 渲染 message/description 插槽 +BE-->>EB : 不参与 API 调用(skip_api) +``` + +**图表来源** + +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:20-72](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L20-L72) + +**章节来源** + +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:20-72](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L20-L72) + +### 组件基类与上下文（ModelScopeComponent/Layout） + +- 设计要点 + - 统一继承 Gradio 组件元类与 BlockContext，确保父子关系与渲染顺序正确 + - 布局型组件默认 skip_api，数据型组件参与 API 流程 +- 常见问题定位 + - 未处于 Application 上下文中会触发断言失败 + - 布局组件退出时需同步 layout 标记，避免渲染错位 + +**章节来源** + +- [backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) + +### 链接处理（process_links） + +- 设计要点 + - 将 Markdown/HTML 中的相对链接转换为 /file= 缓存路径，便于 Gradio 安全访问 +- 常见问题定位 + - 文件不存在或路径错误时原样返回，检查资源绝对路径与 block 缓存映射 + +**章节来源** + +- [backend/modelscope_studio/utils/dev/process_links.py:1-61](file://backend/modelscope_studio/utils/dev/process_links.py#L1-L61) + +## 依赖关系分析 + +- 前后端依赖 + - 前端使用 Svelte 5 与 React 预处理，配合 Gradio 的状态追踪与组件桥接 + - 后端依赖 Gradio 版本范围，确保兼容性 +- 构建与发布 + - 前端脚本包含构建、开发、格式化、Lint 等；后端通过 hatchling 打包 + - GitHub Actions 负责 Lint 与发布流程 + +```mermaid +graph LR +Pkg["package.json
前端脚本与依赖"] --> FE["前端构建/开发"] +Py["pyproject.toml
后端打包配置"] --> BE["后端打包/发布"] +FE --> DOCS["docs/app.py 示例站点"] +BE --> DOCS +Lint["lint.yaml"] --> FE +Lint --> BE +Pub["publish.yaml"] --> BE +``` + +**图表来源** + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/app.py:577-595](file://docs/app.py#L577-L595) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +**章节来源** + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +## 性能考虑 + +- 加载反馈与队列 + - 使用 AutoLoading 与 useLoadingStatus 可提升用户感知性能，但需合理设置并发与队列上限 +- SSR 与空间部署 + - 在 Hugging Face Space 中需禁用 SSR，否则自定义组件可能无法正常显示 +- 构建与缓存 + - 前端构建脚本与 Gradio 资源缓存策略影响首开与切换性能 + +**章节来源** + +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) +- [docs/FAQ-zh_CN.md:1-20](file://docs/FAQ-zh_CN.md#L1-L20) +- [docs/app.py:592-595](file://docs/app.py#L592-L595) + +## 故障排除指南 + +### 1. 安装与环境 `🛠 全版本通用` + +- 依赖版本 + - 后端依赖 Gradio 版本范围，确保与当前环境兼容 + - **Gradio 6.0+ 特定**：使用 modelscope_studio 2.x 时，需确保 gradio>=6.0,<=6.8.0 +- 前端依赖 + - 使用 pnpm 安装依赖并执行构建；开发模式通过 docs/app.py 启动 +- 常见症状 + - 安装后组件不可用或报导入错误，优先检查 Gradio 版本与 Python 环境 +- 解决步骤 + - 确认 Gradio 版本满足要求 + - 清理缓存并重新安装依赖 + - 使用示例站点验证环境 + +**章节来源** + +- [pyproject.toml:26-26](file://pyproject.toml#L26-L26) +- [package.json:8-25](file://package.json#L8-L25) +- [README.md:34-42](file://README.md#L34-L42) +- [README-zh_CN.md:34-42](file://README-zh_CN.md#L34-L42) + +### 2. 配置问题 `🛠 全版本通用` + +- SSR 模式 + - 在 Hugging Face Space 中必须禁用 SSR，否则界面显示异常 + - **适用版本**：Gradio 6.0+ 特定（Gradio 6.0 之前版本也存在此问题） +- 自动加载反馈 + - 若未放置 AutoLoading，Gradio 默认加载状态可能不显示，建议全局至少使用一次 AutoLoading +- 构建与开发 + - 开发模式使用 docs/app.py；生产构建使用前端脚本 + +**章节来源** + +- [docs/FAQ.md:3-5](file://docs/FAQ.md#L3-L5) +- [docs/FAQ-zh_CN.md:3-5](file://docs/FAQ-zh_CN.md#L3-L5) +- [docs/FAQ.md:7-19](file://docs/FAQ.md#L7-L19) +- [docs/FAQ-zh_CN.md:7-19](file://docs/FAQ-zh_CN.md#L7-L19) +- [docs/app.py:592-595](file://docs/app.py#L592-L595) + +### 3. 运行时错误 `🛠 Gradio 6.0+ 特定` + +- 错误边界 + - 组件内部异常会被 ErrorBoundary 捕获并展示 message/description；若未生效，检查是否正确包裹 +- 初始化与懒加载 + - 组件懒加载依赖初始化 Promise，若未完成可能导致组件未就绪；确保等待初始化完成 +- 链接访问 + - 相对资源需经 process_links 转换为 /file= 路径；若资源缺失，原样返回，检查路径与缓存 + +**章节来源** + +- [frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) +- [backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:20-72](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L20-L72) +- [frontend/svelte-preprocess-react/component/import.ts:1-20](file://frontend/svelte-preprocess-react/component/import.ts#L1-L20) +- [backend/modelscope_studio/utils/dev/process_links.py:48-61](file://backend/modelscope_studio/utils/dev/process_links.py#L48-L61) + +### 4. 性能问题 `🛠 全版本通用` + +- 加载等待与 ETA 波动 + - 队列过大或后台任务耗时长会导致 ETA 波动；可通过减少并发、优化任务逻辑缓解 +- 计时与渲染 + - useLoadingStatus 使用 requestAnimationFrame 实时更新，确保 UI 流畅；避免在高频事件中重复创建实例 +- SSR 与空间部署 + - 禁用 SSR 可避免自定义组件在 SSR 场景下的兼容性问题 + +**章节来源** + +- [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [docs/FAQ.md:7-9](file://docs/FAQ.md#L7-L9) +- [docs/FAQ-zh_CN.md:7-9](file://docs/FAQ-zh_CN.md#L7-L9) +- [docs/app.py:592-595](file://docs/app.py#L592-L595) + +### 5. 调试技巧 `🛠 全版本通用` + +- 日志与状态 + - 利用 useLoadingStatus 输出 ETA、计时、队列位置等信息，辅助定位卡顿原因 +- 组件初始化 + - 等待 initializePromise 完成后再动态导入组件，避免未初始化导致的异常 +- 链接与资源 + - 使用 process_links 将相对链接转换为 /file= 路径，确保资源可访问 + +**章节来源** + +- [frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) +- [frontend/svelte-preprocess-react/component/import.ts:1-20](file://frontend/svelte-preprocess-react/component/import.ts#L1-L20) +- [backend/modelscope_studio/utils/dev/process_links.py:48-61](file://backend/modelscope_studio/utils/dev/process_links.py#L48-L61) + +### 6. 社区支持与问题反馈 `🛠 全版本通用` + +- 官方文档与示例 + - 使用示例站点验证问题复现与修复效果 +- 提交问题 + - 在仓库中提交 Issue，附带环境信息、依赖版本、最小复现与期望行为 +- 参考脚本 + - Lint 与发布脚本可用于检查与验证本地环境 + +**章节来源** + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +## 结论 + +通过理解 AutoLoading、ErrorBoundary、组件基类与链接处理等核心机制，开发者可以系统性地定位与解决安装、配置、运行时与性能相关问题。建议在 Hugging Face Space 中禁用 SSR，并在全局启用 AutoLoading 以改善用户体验；出现问题时优先检查初始化、错误边界与资源链接，结合示例站点进行最小复现与验证。 + +## 附录 + +- 关键文件索引 + - 示例站点与菜单：[docs/app.py:1-595](file://docs/app.py#L1-L595) + - 自动加载反馈（后端）：[backend/modelscope_studio/components/base/auto_loading/**init**.py:1-65](file://backend/modelscope_studio/components/base/auto_loading/__init__.py#L1-L65) + - 自动加载反馈（前端）：[frontend/base/auto-loading/useLoadingStatus.ts:1-94](file://frontend/base/auto-loading/useLoadingStatus.ts#L1-L94) + - 错误边界（前端）：[frontend/antd/alert/error-boundary/alert.error-boundary.tsx:1-34](file://frontend/antd/alert/error-boundary/alert.error-boundary.tsx#L1-L34) + - 错误边界（后端）：[backend/modelscope_studio/components/antd/alert/error_boundary/**init**.py:20-72](file://backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py#L20-L72) + - 组件基类：[backend/modelscope_studio/utils/dev/component.py:1-169](file://backend/modelscope_studio/utils/dev/component.py#L1-L169) + - 链接处理：[backend/modelscope_studio/utils/dev/process_links.py:1-61](file://backend/modelscope_studio/utils/dev/process_links.py#L1-L61) + - 前端脚本：[package.json:1-55](file://package.json#L1-L55) + - 后端打包：[pyproject.toml:1-257](file://pyproject.toml#L1-L257) + - Lint 工作流：[.github/workflows/lint.yaml:1-34](file://.github/workflows/lint.yaml#L1-L34) + - 发布工作流：[.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) diff --git "a/.wiki/zh/\351\203\250\347\275\262\346\214\207\345\215\227/\345\217\221\345\270\203\346\265\201\347\250\213.md" "b/.wiki/zh/\351\203\250\347\275\262\346\214\207\345\215\227/\345\217\221\345\270\203\346\265\201\347\250\213.md" new file mode 100644 index 00000000..74aa1dc5 --- /dev/null +++ "b/.wiki/zh/\351\203\250\347\275\262\346\214\207\345\215\227/\345\217\221\345\270\203\346\265\201\347\250\213.md" @@ -0,0 +1,441 @@ +# 发布流程 + + +**本文引用的文件** +- [publish.yaml](file://.github/workflows/publish.yaml) +- [lint.yaml](file://.github/workflows/lint.yaml) +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) +- [create-tag-n-release.mts](file://scripts/create-tag-n-release.mts) +- [.changeset/config.json](file://.changeset/config.json) +- [.changeset/pre.json](file://.changeset/pre.json) +- [version.py](file://backend/modelscope_studio/version.py) +- [CHANGELOG.md](file://CHANGELOG.md) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [index.ts](file://config/changelog/src/index.ts) +- [package.json](file://config/changelog/package.json) +- [frontend/package.json](file://frontend/package.json) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向需要管理 ModelScope Studio 项目发布的维护者与高级开发者，系统性阐述从本地开发到 PyPI 正式发布（含预发布、热修复）的完整流程，覆盖版本管理、变更日志生成、自动化流水线、质量保障与回滚策略。内容基于仓库内现有发布脚本、GitHub Actions 工作流与变更集配置，确保可落地、可追溯、可复现。 + +## 项目结构 + +ModelScope Studio 采用多包工作区（pnpm workspace）组织，根目录包含 Python 包元数据与前端组件源码；发布相关的关键位置如下： + +- 根级包元数据与构建配置：pyproject.toml +- 发布脚本与工作流：scripts/ 与 .github/workflows/ +- 变更集与变更日志生成器：.changeset/ 与 config/changelog/ +- 版本号来源：backend/modelscope_studio/version.py 与各包 package.json +- 工作区定义：pnpm-workspace.yaml + +```mermaid +graph TB +A["根工作区
pnpm-workspace.yaml"] --> B["Python 包
pyproject.toml"] +A --> C["前端包
frontend/package.json"] +A --> D["变更日志生成器
config/changelog/"] +A --> E["发布脚本
scripts/"] +A --> F["GitHub Actions
.github/workflows/"] +B --> G["版本号来源
backend/modelscope_studio/version.py"] +D --> H["变更集配置
.changeset/config.json"] +D --> I[".changeset/pre.json"] +``` + +图表来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) + +章节来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) + +## 核心组件 + +- 版本与元数据 + - Python 包版本与元信息由 pyproject.toml 提供，同时 Python 模块版本由 backend/modelscope_studio/version.py 同步维护。 + - 前端包与子包版本在各自 package.json 中声明。 +- 变更集与变更日志 + - 使用 Changesets 管理跨包版本与变更摘要，通过自定义 changelog 生成器将变更归类并写入各包 CHANGELOG.md。 +- 自动化发布流水线 + - GitHub Actions 在主分支或 next 分支检测“更新版本”提交时触发，执行构建与发布，并在成功后打标签与创建 GitHub Release。 +- 发布脚本 + - scripts/publish-to-pypi.mts 负责检查版本是否已存在、构建产物、上传至 PyPI。 + - scripts/create-tag-n-release.mts 负责生成合并后的变更日志、打标签并创建 Release。 + +章节来源 + +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +## 架构总览 + +下图展示从代码提交到 PyPI 发布与 GitHub Release 的整体流程，包括版本检查、构建、上传、打标签与发布。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Repo as "仓库(main/next)" +participant GH as "GitHub Actions" +participant Script as "发布脚本
publish-to-pypi.mts" +participant PyPI as "PyPI" +participant Tag as "标签与Release
create-tag-n-release.mts" +Dev->>Repo : 推送带有“更新版本”的提交 +Repo-->>GH : 触发 publish 工作流 +GH->>Script : 执行构建与发布 +Script->>PyPI : 检查版本并上传 +PyPI-->>Script : 返回发布结果 +Script-->>GH : 输出已发布标记 +GH->>Tag : 若已发布则打标签并创建Release +Tag-->>Repo : 推送标签与发布说明 +``` + +图表来源 + +- [publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +章节来源 + +- [publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +## 详细组件分析 + +### 组件一：版本与元数据管理 + +- Python 包版本与元信息 + - pyproject.toml 定义了包名、版本、许可证、依赖与构建目标，wheel 与 sdist 的打包范围明确。 + - backend/modelscope_studio/version.py 作为 Python 模块版本入口，需与 pyproject.toml 版本保持一致。 +- 前端与子包版本 + - 各包 package.json（如 frontend/package.json）声明独立版本，便于多包协同发布。 +- 工作区与多包 + - pnpm-workspace.yaml 明确包含根、config/\*、frontend 及其子包，确保发布脚本能正确解析包元数据。 + +```mermaid +flowchart TD +Start(["开始"]) --> ReadMeta["读取包元数据
pyproject.toml / package.json"] +ReadMeta --> CompareVer{"版本一致性校验"} +CompareVer --> |不一致| FixVer["同步版本"] +CompareVer --> |一致| Next["进入变更集流程"] +FixVer --> Next +Next --> End(["结束"]) +``` + +图表来源 + +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) + +章节来源 + +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) + +### 组件二：变更集与变更日志生成 + +- Changesets 配置 + - .changeset/config.json 指定使用自定义 changelog 生成器与仓库信息，关闭提交记录，设置基础分支为 main。 + - .changeset/pre.json 定义预发布模式与初始版本映射，支持以 beta 标签进行预发布。 +- 自定义 changelog 生成器 + - index.ts 实现 getReleaseLine 与 getDependencyReleaseLine，按 feat/fix/chore 归类变更，提取 PR/Commit/User 信息，写入各包 CHANGELOG.md。 +- 生成流程 + - package.json 中的 version 脚本调用 changeset version 并修复变更日志，随后构建 changelog 包。 + +```mermaid +flowchart TD +CS["变更集摘要"] --> Parse["解析摘要
PR/Commit/User/类型"] +Parse --> Classify{"分类 feat/fix/chore"} +Classify --> Write["写入各包 CHANGELOG.md"] +Write --> Done["完成"] +``` + +图表来源 + +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [package.json:1-55](file://package.json#L1-L55) +- [config/changelog/package.json:1-32](file://config/changelog/package.json#L1-L32) + +章节来源 + +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [package.json:1-55](file://package.json#L1-L55) +- [config/changelog/package.json:1-32](file://config/changelog/package.json#L1-L32) + +### 组件三：PyPI 发布脚本 + +- 功能职责 + - publish-to-pypi.mts 在发布前检查 PyPI 是否已存在同版本，避免重复上传；随后执行安装与构建，最后通过 twine 上传。 +- 关键逻辑 + - 使用 @manypkg/get-packages 获取工作区包元数据，读取根包版本。 + - 通过 PyPI JSON API 查询版本是否存在，若存在则跳过。 + - 构建完成后检查 dist 目录存在性，再上传。 + - 设置 GitHub Actions 输出变量 published=true，供后续步骤判断。 + +```mermaid +flowchart TD +S(["开始"]) --> Check["查询 PyPI 是否已存在该版本"] +Check --> Exists{"已存在？"} +Exists --> |是| Skip["跳过发布并输出标记"] +Exists --> |否| Build["安装与构建"] +Build --> Dist{"dist 存在？"} +Dist --> |否| Fail["抛出构建失败错误"] +Dist --> |是| Upload["twine 上传"] +Upload --> SetOut["设置 published=true"] +Skip --> End(["结束"]) +SetOut --> End +Fail --> End +``` + +图表来源 + +- [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) + +章节来源 + +- [publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) + +### 组件四：标签与 Release 创建 + +- 功能职责 + - create-tag-n-release.mts 从根与各子包 CHANGELOG.md 汇总本次版本的变更说明，创建 Git 标签并推送，随后调用 GitHub API 创建 Release。 +- 关键逻辑 + - 解析 CHANGELOG.md，按版本号截取对应条目，拼接为 Release Body。 + - 使用 GitHub Token 调用 createRelease，根据版本号是否包含连字符决定是否标记为预发布。 + - 配置 Git 用户名与邮箱，确保标签推送到远端。 + +```mermaid +flowchart TD +R(["开始"]) --> ReadCL["读取根与子包 CHANGELOG.md"] +ReadCL --> Merge["汇总为 Release Body"] +Merge --> Tag["创建 v
@utils/@globals/svelte-preprocess-react"] +Alias --> External{"是否启用 external?"} +External --> |是| MarkExt["标记 external 列表"] +External --> |否| SkipExt["跳过 external"] +MarkExt --> DefineEnv["定义生产环境常量"] +SkipExt --> DefineEnv +DefineEnv --> Transform["AST 遍历与转换
import/export -> window.ms_globals.*"] +Transform --> End(["完成配置"]) +``` + +**图表来源** + +- [frontend/defineConfig.js:5-18](file://frontend/defineConfig.js#L5-L18) +- [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) +- [frontend/plugin.js:77-167](file://frontend/plugin.js#L77-L167) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) +- [svelte-tsconfig.json:1-4](file://svelte-tsconfig.json#L1-L4) + +**章节来源** + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) +- [svelte-tsconfig.json:1-4](file://svelte-tsconfig.json#L1-L4) + +### Svelte 组件编译与 React 桥接 + +- 组件导出：每个前端组件包通过 package.json 的 exports 字段声明 Gradio 入口（Index.svelte）。 +- 配置继承：组件级 gradio.config.js 通过 defineConfig 生成统一配置。 +- 组件实现： + - Svelte 层：Index.svelte 使用 svelte-preprocess-react 的 getProps/processProps/getSlots 等 API，将 Gradio 传入的 props 与 slots 转换为 React 组件可用形态。 + - React 层：button.tsx 使用 sveltify 将 Ant Design Button 包装为可被 Svelte 使用的 React 组件，支持 slots 与 children 渲染。 +- 槽位与属性：通过 ReactSlot 与 useTargets 实现复杂子节点与图标等插槽渲染。 + +```mermaid +sequenceDiagram +participant Gradio as "Gradio 运行时" +participant Svelte as "Index.svelte" +participant Bridge as "svelte-preprocess-react" +participant React as "button.tsx" +Gradio->>Svelte : 传入 props 与 slots +Svelte->>Bridge : getProps()/processProps()/getSlots() +Bridge-->>Svelte : 标准化后的 props/slots +Svelte->>React : importComponent 加载 React 组件 +React-->>Svelte : 渲染 Ant Design Button +Svelte-->>Gradio : 输出最终 DOM +``` + +**图表来源** + +- [frontend/antd/button/package.json:1-15](file://frontend/antd/button/package.json#L1-L15) +- [frontend/antd/button/gradio.config.js:1-4](file://frontend/antd/button/gradio.config.js#L1-L4) +- [frontend/antd/button/Index.svelte:10-55](file://frontend/antd/button/Index.svelte#L10-L55) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) + +**章节来源** + +- [frontend/antd/button/package.json:1-15](file://frontend/antd/button/package.json#L1-L15) +- [frontend/antd/button/gradio.config.js:1-4](file://frontend/antd/button/gradio.config.js#L1-L4) +- [frontend/antd/button/Index.svelte:1-74](file://frontend/antd/button/Index.svelte#L1-L74) +- [frontend/antd/button/button.tsx:1-39](file://frontend/antd/button/button.tsx#L1-L39) +- [frontend/svelte-preprocess-react/index.ts:1-8](file://frontend/svelte-preprocess-react/index.ts#L1-L8) + +### Python 包构建与发布 + +- 构建后端：pyproject.toml 使用 hatchling 作为构建后端，配合 hatch-requirements-txt、hatch-fancy-pypi-readme。 +- 依赖与元数据：声明 Python 版本要求、许可证、关键字、分类器与核心依赖（如 Gradio）。 +- 打包范围：tool.hatch.build.artifacts 明确列出大量模板目录，确保前端组件模板随包分发；wheel/sdist 的包含/排除规则清晰。 +- 版本同步：Python 包 version 与前端版本保持一致，便于统一发布与追踪。 +- 发布脚本：scripts/publish-to-pypi.mts 在 CI 中执行安装、构建、版本检查与 twine 上传，避免重复发布。 + +```mermaid +flowchart TD +A["读取根 package.json 版本"] --> B["安装项目到可编辑模式"] +B --> C["执行前端构建"] +C --> D{"dist 是否存在?"} +D --> |否| E["抛出构建失败错误"] +D --> |是| F["检查 PyPI 是否已存在该版本"] +F --> |存在| G["跳过发布"] +F --> |不存在| H["twine 上传 dist/*"] +H --> I["输出 published=true"] +``` + +**图表来源** + +- [pyproject.toml:1-44](file://pyproject.toml#L1-L44) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [scripts/publish-to-pypi.mts:14-55](file://scripts/publish-to-pypi.mts#L14-L55) + +**章节来源** + +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) + +## 依赖关系分析 + +- 工作区与包管理：pnpm-workspace.yaml 声明了根、config、frontend 及其子包，确保跨包引用与构建一致性。 +- 前端依赖：frontend/package.json 指定 React 19、Svelte 5、Ant Design 6、Monaco Editor 等核心依赖。 +- 外部化与别名：ModelScopeStudioVitePlugin 将 React、ReactDOM、antd、antdx 等映射为 window.ms_globals.\*，减少重复打包。 +- Python 依赖：pyproject.toml 仅声明 Gradio 依赖，其他前端资源通过 artifacts 与模板目录打包。 + +```mermaid +graph LR +WS["pnpm-workspace.yaml"] --> FE["frontend/package.json"] +FE --> React["react / react-dom"] +FE --> Svelte["svelte 5"] +FE --> Antd["antd 6"] +FE --> Monaco["monaco-editor"] +FE --> Gradio["@gradio/*"] +Py["pyproject.toml"] --> Hatch["hatchling"] +Py --> Artifacts["artifacts 模板集合"] +Py --> Wheel["wheel/sdist 配置"] +``` + +**图表来源** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [pyproject.toml:1-44](file://pyproject.toml#L1-L44) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) + +**章节来源** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +## 性能考虑 + +- 外部化与共享依赖：通过 ModelScopeStudioVitePlugin 的 external 与全局映射，避免 React、antd 等大包重复打包，显著降低产物体积与构建时间。 +- AST 转换与按需加载：在构建阶段将 import/export 重写为全局访问，结合动态 import（如 importComponent）实现按需加载，提升首屏性能。 +- 模块别名：合理使用 @utils、@globals、svelte-preprocess-react 别名，减少路径解析开销。 +- 打包粒度：artifacts 精确列出模板目录，避免无关文件进入包体，缩短打包与发布时间。 +- 类型检查：开启 svelte-check 与 TypeScript 检查，提前发现类型问题，减少运行时错误导致的回退成本。 + +[本节为通用性能建议，不直接分析具体文件，故无“章节来源”] + +## 故障排查指南 + +- 构建失败（dist 不存在） + - 现象：发布脚本报错“Build Failed”。 + - 排查：确认前端构建命令执行成功，检查 defineConfig 与插件配置是否正确应用。 + - 参考 + - [scripts/publish-to-pypi.mts:22-30](file://scripts/publish-to-pypi.mts#L22-L30) + - [frontend/defineConfig.js:8-18](file://frontend/defineConfig.js#L8-L18) +- 版本重复发布 + - 现象：PyPI 已存在相同版本，脚本跳过发布。 + - 排查：确认版本号未变更或手动清理缓存。 + - 参考 + - [scripts/publish-to-pypi.mts:44-51](file://scripts/publish-to-pypi.mts#L44-L51) +- 外部化依赖缺失 + - 现象：运行时报 window.ms_globals 未定义。 + - 排查：检查 ModelScopeStudioVitePlugin 的 external/excludes 配置，确认全局映射是否覆盖所需依赖。 + - 参考 + - [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) + - [frontend/plugin.js:5-20](file://frontend/plugin.js#L5-L20) +- Svelte/React 槽位渲染异常 + - 现象：插槽内容未显示或图标/加载态不生效。 + - 排查：确认 Index.svelte 的 getProps/processProps/getSlots 使用正确，button.tsx 的 ReactSlot 与 useTargets 实现符合预期。 + - 参考 + - [frontend/antd/button/Index.svelte:10-55](file://frontend/antd/button/Index.svelte#L10-L55) + - [frontend/antd/button/button.tsx:11-36](file://frontend/antd/button/button.tsx#L11-L36) +- Python 打包遗漏模板 + - 现象：安装后组件模板缺失。 + - 排查：核对 pyproject.toml 的 artifacts 列表与 wheel/sdist 包含路径。 + - 参考 + - [pyproject.toml:45-257](file://pyproject.toml#L45-L257) + +**章节来源** + +- [scripts/publish-to-pypi.mts:22-51](file://scripts/publish-to-pypi.mts#L22-L51) +- [frontend/plugin.js:5-20](file://frontend/plugin.js#L5-L20) +- [frontend/antd/button/Index.svelte:10-55](file://frontend/antd/button/Index.svelte#L10-L55) +- [frontend/antd/button/button.tsx:11-36](file://frontend/antd/button/button.tsx#L11-L36) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) + +## 结论 + +本项目的构建体系围绕“前端 Vite + Svelte + React 桥接 + Python 打包”的组合展开。通过外部化共享依赖、AST 转换与精确的模板打包策略，实现了高效的构建与稳定的运行时行为。遵循本文档的配置与排障建议，可有效提升本地与 CI 的构建稳定性与性能。 + +[本节为总结性内容，不直接分析具体文件，故无“章节来源”] + +## 附录 + +### 本地构建环境设置 + +- Node.js + - 版本要求：满足前端依赖（React 19、Svelte 5、Ant Design 6）需求。 + - 包管理：使用 pnpm，确保与 workspace 配置一致。 + - 参考 + - [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) + - [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- Python + - 版本要求：满足 pyproject.toml 中 requires-python。 + - 构建工具：安装 hatchling 与 twine，确保可执行。 + - 参考 + - [pyproject.toml:1-7](file://pyproject.toml#L1-L7) + - [pyproject.toml:42-43](file://pyproject.toml#L42-L43) +- 前端构建 + - 执行根脚本进行构建与开发，确保 defineConfig 与插件正常加载。 + - 参考 + - [package.json:8-25](file://package.json#L8-L25) + - [frontend/defineConfig.js:5-18](file://frontend/defineConfig.js#L5-L18) + - [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) + +**章节来源** + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-44](file://pyproject.toml#L1-L44) +- [package.json:8-25](file://package.json#L8-L25) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) diff --git "a/.wiki/zh/\351\203\250\347\275\262\346\214\207\345\215\227/\347\216\257\345\242\203\351\205\215\347\275\256.md" "b/.wiki/zh/\351\203\250\347\275\262\346\214\207\345\215\227/\347\216\257\345\242\203\351\205\215\347\275\256.md" new file mode 100644 index 00000000..1312a0d3 --- /dev/null +++ "b/.wiki/zh/\351\203\250\347\275\262\346\214\207\345\215\227/\347\216\257\345\242\203\351\205\215\347\275\256.md" @@ -0,0 +1,315 @@ +# 环境配置 + + +**本文引用的文件** +- [README.md](file://README.md) +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [docs/app.py](file://docs/app.py) +- [frontend/package.json](file://frontend/package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [backend/modelscope_studio/utils/dev/app_context.py](file://backend/modelscope_studio/utils/dev/app_context.py) +- [backend/modelscope_studio/utils/dev/process_links.py](file://backend/modelscope_studio/utils/dev/process_links.py) +- [backend/modelscope_studio/utils/dev/resolve_frontend_dir.py](file://backend/modelscope_studio/utils/dev/resolve_frontend_dir.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向运维与开发者，提供 ModelScope Studio 的环境配置与部署最佳实践，覆盖本地开发、测试与生产环境的配置要点，包括环境变量、依赖管理、容器化（Docker/Kubernetes）与性能监控、日志配置、环境迁移与升级策略，以及不同平台的部署差异与注意事项。 + +## 项目结构 + +仓库采用多包工作区组织方式，后端以 Python 包形式发布，前端以 Svelte + Vite 构建，文档站点通过 Gradio CC 启动。关键目录与职责如下： + +- backend/modelscope_studio：Python 后端组件与工具 +- frontend：前端组件与构建配置 +- docs：文档站点与示例应用 +- config：共享的 Lint 与变更日志配置 +- 根级配置：pyproject.toml（Python 打包）、package.json（Node 工作区脚本）、pnpm-workspace.yaml（工作区定义） + +```mermaid +graph TB +A["根目录"] --> B["backend/modelscope_studio
Python 包与组件"] +A --> C["frontend
Svelte/Vite 前端"] +A --> D["docs
Gradio CC 文档站点"] +A --> E["config
共享配置"] +A --> F["pyproject.toml
Python 打包与元数据"] +A --> G["package.json
Node 工作区脚本"] +A --> H["pnpm-workspace.yaml
工作区与仅构建依赖"] +``` + +**图表来源** + +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) + +**章节来源** + +- [README.md](file://README.md) +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) + +## 核心组件 + +- Python 打包与分发：使用 Hatchling 构建，包含后端组件模板清单与打包目标 +- Node 工作区：统一脚本与依赖管理，支持多子包并行开发 +- 文档站点：基于 Gradio CC 的 docs/app.py，提供组件与布局模板的可视化文档 +- 前端构建：Vite + React SWC 插件，配合自定义插件与 Svelte 预处理 + +**章节来源** + +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [docs/app.py](file://docs/app.py) +- [frontend/package.json](file://frontend/package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) + +## 架构总览 + +下图展示了从开发到运行的关键路径：本地开发通过 Gradio CC 启动 docs/app.py；构建阶段由前端 Vite 与后端打包共同完成；运行时由 Python 后端与前端静态资源协同提供服务。 + +```mermaid +graph TB +Dev["开发者"] --> CC["Gradio CC 开发服务器
docs/app.py"] +CC --> FE["前端构建
Vite + 插件"] +FE --> Dist["静态资源产物"] +CC --> Py["Python 后端组件
modelscope_studio"] +Py --> Serve["服务启动与页面渲染"] +Dist --> Serve +``` + +**图表来源** + +- [docs/app.py](file://docs/app.py) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/package.json](file://frontend/package.json) +- [pyproject.toml](file://pyproject.toml) + +## 详细组件分析 + +### 环境变量与运行参数 + +- 文档站点默认并发与线程数在入口处设置，可按需调整以适配不同环境的吞吐与资源限制 +- 开发模式通过环境变量触发 Gradio Watch Module，便于热更新与调试 + +建议的环境变量与用途（示例，非固定值）： + +- GRADIO_WATCH_MODULE_NAME：用于启用开发监听 +- PYTHONPATH 或工作区路径：确保 Python 可导入后端包 +- NODE_ENV：控制前端构建模式（开发/生产） +- PORT/APP_HOST：服务监听地址与端口（如需自定义） + +**章节来源** + +- [docs/app.py](file://docs/app.py) +- [package.json](file://package.json) + +### 依赖管理策略 + +- Python 依赖 + - 核心依赖：Gradio 版本范围约束 + - 打包与分发：Hatchling + hatch-requirements-txt + - 模板清单：构建阶段包含大量前端模板目录，确保产物完整 +- Node.js 依赖 + - 工作区：pnpm workspace + 仅构建依赖声明 + - 脚本：统一的构建、开发、格式化、检查等命令 + - 前端依赖：React、Svelte、Ant Design、Monaco Editor 等 +- 工作空间配置 + - pnpm-workspace.yaml 定义了 packages 与 onlyBuiltDependencies，减少不必要的构建开销 + +**章节来源** + +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [frontend/package.json](file://frontend/package.json) + +### 容器化部署（Docker 与 Kubernetes） + +以下为通用实践步骤，具体镜像与编排需结合实际环境定制： + +- Docker 构建流程 + - 基础镜像：选择包含 Python 与 Node 的基础镜像 + - 安装依赖：先安装系统依赖，再安装 Python 与 Node 依赖 + - 构建后端：pip 安装后端包或以可编辑模式安装 + - 构建前端：执行前端构建脚本生成静态资源 + - 运行：启动 Python 服务并提供静态资源 +- Kubernetes 部署 + - 使用 Deployment 管理 Pod 副本 + - 使用 Service 暴露服务 + - 使用 ConfigMap/Secret 管理环境变量与敏感信息 + - 使用 PersistentVolume/ PVC 存储日志与临时文件（如需） + - 健康检查：配置 liveness/readiness 探针 + - 资源限制：根据并发与线程配置设置 CPU/内存请求与限制 + +[本节为通用实践说明，不直接分析具体文件，故无“章节来源”] + +### 性能监控与日志配置 + +- 性能监控 + - 在 Python 层面：记录请求耗时、队列长度、并发限制等指标 + - 在前端层面：监控首屏时间、资源加载耗时、错误率 + - 在容器层面：采集 CPU/内存/网络等指标，结合日志进行关联分析 +- 日志配置 + - Python：使用标准日志模块，按环境输出到 stdout/stderr，并结合容器日志收集 + - 前端：避免在生产环境输出过量调试日志，必要时使用条件日志 + - 文档站点：注意并发与线程配置对资源占用的影响 + +[本节为通用实践说明，不直接分析具体文件，故无“章节来源”] + +### 环境迁移与升级 + +- Python 升级 + - 更新 Python 版本要求与依赖版本范围，确保兼容性 + - 重新打包并验证构建产物完整性 +- Node 升级 + - 更新 Node 版本与依赖，执行 lint 与类型检查 + - 重新构建前端并验证静态资源可用性 +- 文档站点升级 + - 更新 Gradio CC 版本与相关依赖 + - 验证各组件与布局模板的渲染一致性 +- 迁移策略 + - 小步快跑：逐步替换旧组件与模板 + - 回滚预案：保留上一版本镜像与配置，确保快速回退 + - 数据与配置：确保环境变量与配置文件的向后兼容 + +[本节为通用实践说明，不直接分析具体文件，故无“章节来源”] + +### 不同平台的部署差异与注意事项 + +- 本地开发 + - 使用 Gradio CC 的开发服务器，启用热更新 + - 注意跨平台路径与权限问题 +- 测试环境 + - 与生产隔离的独立服务与存储 + - 严格控制并发与线程数，模拟真实负载 +- 生产环境 + - 使用稳定版本与长期支持的基础镜像 + - 配置健康检查与自动扩缩容 + - 严格的日志与监控策略 + +[本节为通用实践说明，不直接分析具体文件，故无“章节来源”] + +## 依赖分析 + +- Python 侧 + - 依赖：Gradio 版本范围约束 + - 打包：Hatchling 构建，artifacts 列表包含大量前端模板目录 +- Node 侧 + - 工作区：packages 与 onlyBuiltDependencies + - 脚本：统一的构建、开发、格式化、检查命令 + - 前端依赖：React、Svelte、Ant Design、Monaco Editor 等 + +```mermaid +graph LR +P["pyproject.toml
Python 依赖与打包"] --> B["后端组件
modelscope_studio"] +N["package.json
Node 脚本与依赖"] --> F["前端构建
Vite + 插件"] +W["pnpm-workspace.yaml
工作区与仅构建依赖"] --> N +F --> R["静态资源产物"] +B --> R +``` + +**图表来源** + +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) + +**章节来源** + +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [frontend/package.json](file://frontend/package.json) + +## 性能考虑 + +- 并发与线程 + - 文档站点入口设置了默认并发与最大线程数，应根据硬件与业务负载调优 +- 构建优化 + - 使用 pnpm 与 onlyBuiltDependencies 减少无关依赖的构建 + - 前端构建目标设为 modules，提升兼容性与加载效率 +- 资源与缓存 + - 将静态资源置于 CDN 或反向代理缓存 + - 控制模板与资源体积，避免冗余文件进入产物 + +**章节来源** + +- [docs/app.py](file://docs/app.py) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) + +## 故障排查指南 + +- 文档站点无法启动或页面空白 + - 检查 GRADIO_WATCH_MODULE_NAME 是否正确设置以启用开发监听 + - 确认后端包已正确安装且可导入 +- 前端构建失败 + - 检查 Node 版本与依赖是否满足要求 + - 清理 node_modules 与构建缓存后重试 +- 链接与资源 404 + - 确认静态资源路径与服务路由一致 + - 检查链接转换逻辑与资源缓存路径映射 +- 开发上下文缺失警告 + - 确保在顶层使用 Application 组件，避免运行时上下文为空 + +```mermaid +flowchart TD +Start(["开始排查"]) --> CheckEnv["检查环境变量与依赖版本"] +CheckEnv --> BuildFE["执行前端构建并查看错误"] +BuildFE --> FixFE["修复前端依赖或构建配置"] +CheckEnv --> RunDocs["启动文档站点并观察行为"] +RunDocs --> FixDocs["修正运行参数与并发设置"] +FixFE --> Verify["验证静态资源可用性"] +FixDocs --> Verify +Verify --> End(["结束"]) +``` + +**图表来源** + +- [docs/app.py](file://docs/app.py) +- [package.json](file://package.json) +- [backend/modelscope_studio/utils/dev/process_links.py](file://backend/modelscope_studio/utils/dev/process_links.py) +- [backend/modelscope_studio/utils/dev/app_context.py](file://backend/modelscope_studio/utils/dev/app_context.py) + +**章节来源** + +- [docs/app.py](file://docs/app.py) +- [backend/modelscope_studio/utils/dev/process_links.py](file://backend/modelscope_studio/utils/dev/process_links.py) +- [backend/modelscope_studio/utils/dev/app_context.py](file://backend/modelscope_studio/utils/dev/app_context.py) + +## 结论 + +通过明确的环境变量与运行参数、规范的依赖管理与工作区配置、可扩展的容器化与监控策略，以及严谨的迁移与升级流程，ModelScope Studio 可在不同环境中稳定运行。建议在生产环境优先采用受控版本与完善的可观测性体系，持续优化构建与运行时性能。 + +## 附录 + +- 快速启动与开发 + - 安装后端与前端依赖并执行构建 + - 使用 Gradio CC 启动文档站点进行开发与调试 +- 参考命令 + - 后端安装与构建：参见根级 README 的安装与开发说明 + - 前端安装与构建：参见 package.json 中的脚本与 frontend/package.json 的依赖 + +**章节来源** + +- [README.md](file://README.md) +- [package.json](file://package.json) +- [frontend/package.json](file://frontend/package.json) diff --git "a/.wiki/zh/\351\203\250\347\275\262\346\214\207\345\215\227/\351\203\250\347\275\262\346\214\207\345\215\227.md" "b/.wiki/zh/\351\203\250\347\275\262\346\214\207\345\215\227/\351\203\250\347\275\262\346\214\207\345\215\227.md" new file mode 100644 index 00000000..b9e872fb --- /dev/null +++ "b/.wiki/zh/\351\203\250\347\275\262\346\214\207\345\215\227/\351\203\250\347\275\262\346\214\207\345\215\227.md" @@ -0,0 +1,333 @@ +# 部署指南 + + +**本文引用的文件** +- [pyproject.toml](file://pyproject.toml) +- [package.json](file://package.json) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) +- [scripts/create-tag-n-release.mts](file://scripts/create-tag-n-release.mts) +- [frontend/package.json](file://frontend/package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [README.md](file://README.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排除指南](#故障排除指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本指南面向运维与开发者，系统化说明 ModelScope Studio 的构建流程、发布策略与部署实践，覆盖以下主题： + +- 前端组件构建与打包策略 +- Python 包构建与发布到 PyPI +- CI/CD 流水线配置与使用 +- 不同部署环境（本地开发、生产、云平台）的配置方法 +- 性能优化与监控建议 +- 常见问题排查与解决方案 + +## 项目结构 + +该项目采用多包工作区组织方式，根目录通过 pnpm 工作区统一管理前端子包与配置模块，后端 Python 包位于 backend/modelscope_studio 目录中，并通过 pyproject.toml 定义构建与打包规则。 + +```mermaid +graph TB +Root["仓库根目录"] --> Backend["后端 Python 包
backend/modelscope_studio"] +Root --> Frontend["前端工作区
frontend/*"] +Root --> Config["配置工具集
config/*"] +Root --> Scripts["发布脚本
scripts/*"] +Root --> Workflows["CI/CD 流水线
.github/workflows/*"] +Frontend --> Antd["Ant Design 组件库
frontend/antd/*"] +Frontend --> Antdx["Ant Design X 组件库
frontend/antdx/*"] +Frontend --> Pro["专业组件库
frontend/pro/*"] +Frontend --> Base["基础组件库
frontend/base/*"] +``` + +图表来源 + +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [frontend/package.json](file://frontend/package.json) +- [pyproject.toml](file://pyproject.toml) + +章节来源 + +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [frontend/package.json](file://frontend/package.json) +- [pyproject.toml](file://pyproject.toml) + +## 核心组件 + +- 构建与打包 + - 前端：基于 Vite 与自定义插件，实现 React/Svelte 混编与外部化策略，输出可被 Gradio 使用的组件资源。 + - 后端：使用 Hatchling 构建，通过工具链将模板与组件资源打包进 Python 包。 +- 发布与版本管理 + - 使用 Changesets 进行版本与变更日志管理；CI 中执行构建、上传至 PyPI、创建 Git Tag 与 GitHub Release。 +- 质量保障 + - Lint 流水线在 PR 与 Push 时运行，确保代码风格与静态检查一致。 + +章节来源 + +- [package.json](file://package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) +- [pyproject.toml](file://pyproject.toml) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) + +## 架构总览 + +下图展示从本地到云端的完整部署路径：本地开发构建 → CI 触发 → PyPI 发布 → 生成 Tag 与 Release。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Local as "本地构建" +participant GH as "GitHub Actions" +participant PyPI as "PyPI" +participant Git as "Git 仓库" +Dev->>Local : 执行构建脚本 +Local-->>Dev : 产出 dist/ 前端产物 +Dev->>GH : 推送分支/触发流水线 +GH->>GH : 拉取代码/安装依赖 +GH->>GH : 构建 Python 包并校验版本 +GH->>PyPI : 上传轮子与源码包 +PyPI-->>GH : 返回发布结果 +GH->>Git : 创建 Tag 并推送 +GH->>Git : 创建 GitHub Release +``` + +图表来源 + +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) +- [scripts/create-tag-n-release.mts](file://scripts/create-tag-n-release.mts) + +## 详细组件分析 + +### 前端构建与打包 + +- 构建入口与命令 + - 通过根 package.json 的构建脚本调用 Gradio 自定义组件 CLI 进行构建（使用 --no-generate-docs 参数禁用自动文档生成以加速构建）。 + - 完整命令：rimraf dist && gradio cc build --no-generate-docs +- Vite 插件与别名 + - 自定义 Vite 插件负责： + - 在构建阶段设置环境变量为生产模式 + - 将指定依赖外部化，减少包体体积 + - 通过 Babel AST 转换导入/导出语句，将模块映射到全局对象，便于在浏览器环境中按需加载 + - 别名映射到工具与全局组件模块，提升开发体验与一致性。 +- 外部化策略 + - 对 React、Ant Design 及其生态进行外部化处理，避免重复打包，降低体积并提升缓存命中率。 + +```mermaid +flowchart TD +Start(["开始构建"]) --> LoadCfg["加载 Vite 配置与插件"] +LoadCfg --> SetEnv["设置生产环境变量"] +SetEnv --> Externalize["配置外部化依赖列表"] +Externalize --> Alias["配置模块别名"] +Alias --> Transform["Babel AST 转换导入/导出"] +Transform --> Bundle["Rollup 打包产物"] +Bundle --> End(["完成"]) +``` + +图表来源 + +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) + +章节来源 + +- [package.json](file://package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) + +### Python 包构建与发布 + +- 构建系统与元数据 + - 使用 Hatchling 作为构建后端，声明依赖与可选依赖，定义分类器与关键字。 +- 资源打包 + - 通过工具链将大量组件模板与静态资源纳入打包范围，确保运行时可直接使用。 +- 版本与元信息 + - 根 pyproject.toml 与后端版本文件保持一致，保证发布版本号统一。 + +```mermaid +flowchart TD +A["读取 pyproject.toml 元数据"] --> B["安装构建依赖"] +B --> C["执行构建命令生成 dist/"] +C --> D{"dist/ 是否存在？"} +D --> |否| E["抛出构建失败错误"] +D --> |是| F["校验 PyPI 是否已存在该版本"] +F --> |存在| G["跳过发布"] +F --> |不存在| H["使用 Twine 上传到 PyPI"] +H --> I["标记发布成功"] +``` + +图表来源 + +- [pyproject.toml](file://pyproject.toml) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) + +章节来源 + +- [pyproject.toml](file://pyproject.toml) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) + +### CI/CD 流水线 + +- 发布流水线 + - 触发条件：推送到 main 或 next 分支 + - 步骤：安装 Python 与 Node.js、安装 pnpm、安装依赖、构建前端与后端、上传 PyPI、创建 Tag 与 Release +- Lint 流水线 + - 触发条件：Push 与 Pull Request + - 步骤：安装 Python 与 Node.js、安装依赖、运行 Lint 任务 + +```mermaid +sequenceDiagram +participant Push as "推送事件" +participant PubWF as "发布流水线" +participant LintWF as "Lint 流水线" +participant PyPI as "PyPI" +participant GH as "GitHub" +Push->>PubWF : 触发发布 +PubWF->>PubWF : 安装依赖/构建 +PubWF->>PyPI : 上传包 +PubWF->>GH : 创建 Tag 与 Release +Push->>LintWF : 触发 Lint +LintWF->>LintWF : 运行代码风格与静态检查 +``` + +图表来源 + +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) + +章节来源 + +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) + +### 版本与变更日志管理 + +- Changesets + - 使用 Changesets 进行版本推进与变更日志生成，配合脚本在 CI 中自动执行版本更新与修复。 +- Tag 与 Release + - 发布成功后，脚本根据根与各子包的变更日志生成统一 Release 内容，并创建 Git Tag 推送至远端。 + +章节来源 + +- [package.json](file://package.json) +- [scripts/create-tag-n-release.mts](file://scripts/create-tag-n-release.mts) + +## 依赖分析 + +- 前端依赖 + - React 与 Svelte 生态、Ant Design 与 Ant Design X、Monaco Editor、Mermaid 等，构成组件库的核心能力。 +- 构建工具 + - Vite、@vitejs/plugin-react-swc、Babel、Rollup（由 Vite 驱动） +- Python 依赖 + - Gradio 作为运行时框架，Hatchling 用于构建，Twine 用于上传 + +```mermaid +graph LR +FE["前端构建"] --> Vite["Vite"] +FE --> Babel["Babel"] +FE --> Rollup["Rollup"] +BE["后端构建"] --> Hatch["Hatchling"] +BE --> Gradio["Gradio"] +Pub["发布"] --> Twine["Twine"] +Pub --> PyPI["PyPI"] +``` + +图表来源 + +- [frontend/package.json](file://frontend/package.json) +- [pyproject.toml](file://pyproject.toml) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) + +章节来源 + +- [frontend/package.json](file://frontend/package.json) +- [pyproject.toml](file://pyproject.toml) + +## 性能考虑 + +- 前端体积优化 + - 外部化策略：将 React、Ant Design 等大依赖外部化，减少包体与重复打包。 + - AST 转换：通过插件在构建期将导入/导出转换为全局访问，避免运行时冗余逻辑。 + - 按需加载：结合 Gradio 加载机制，仅在需要时引入组件资源。 +- 构建效率 + - 禁用文档生成的构建选项可显著缩短前端构建时间。 + - 使用 pnpm 工作区统一依赖，减少磁盘占用与安装时间。 +- Python 包体积 + - 仅打包必要的模板与资源，避免不必要的文件进入分发包。 + +章节来源 + +- [frontend/plugin.js](file://frontend/plugin.js) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) + +## 故障排除指南 + +- 构建失败 + - 现象：dist/ 未生成或构建报错 + - 排查：确认前端构建脚本是否执行、Node.js 与 pnpm 版本是否满足要求、依赖安装是否成功 + - 参考：根 package.json 的构建脚本与前端 defineConfig 配置 +- PyPI 上传失败 + - 现象：Twine 上传报错或版本已存在 + - 排查：检查 PYPI_TOKEN 是否正确配置、版本是否已在 PyPI 存在、网络连通性 + - 参考：发布脚本中的版本检查与上传逻辑 +- CI 流水线中断 + - 现象：Lint 或发布步骤失败 + - 排查：查看对应工作流日志、确认环境变量与权限、核对触发条件 + - 参考：lint 与 publish 工作流配置 +- 文档与示例 + - 参考：根 README 的安装与快速开始说明，确保本地开发环境与依赖版本一致 + +章节来源 + +- [package.json](file://package.json) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [.github/workflows/lint.yaml](file://.github/workflows/lint.yaml) +- [README.md](file://README.md) + +## 结论 + +本指南提供了从本地到云端的一体化部署方案：通过前端 Vite 插件与外部化策略优化体积，借助 Hatchling 与 Twine 实现 Python 包的稳定发布，配合 GitHub Actions 完成自动化流水线与版本管理。建议在生产与云平台部署时，结合外部化与缓存策略进一步优化加载性能，并在 CI 中持续运行 Lint 以保障质量。 + +## 附录 + +### 不同部署环境的配置方法 + +- 本地开发 + - 安装依赖：使用 pnpm 安装工作区依赖 + - 启动开发服务器：运行 Gradio 自定义组件开发命令 + - 参考：根 README 的开发说明与 package.json 脚本 +- 生产环境 + - 构建产物：执行前端构建脚本生成 dist/，确保外部化依赖在运行时可用 + - Python 包：使用 Hatchling 构建，确保模板与资源被打包 +- 云平台部署 + - 使用 CI 触发发布流水线，自动上传至 PyPI 并创建 Tag/Release + - 在目标平台安装 Python 包并启动应用 + +章节来源 + +- [README.md](file://README.md) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) diff --git "a/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\345\272\224\347\224\250\345\234\272\346\231\257.md" "b/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\345\272\224\347\224\250\345\234\272\346\231\257.md" new file mode 100644 index 00000000..7977162c --- /dev/null +++ "b/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\345\272\224\347\224\250\345\234\272\346\231\257.md" @@ -0,0 +1,337 @@ +# 应用场景 + + +**本文引用的文件** +- [README-zh_CN.md](file://README-zh_CN.md) +- [README.md](file://README.md) +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [frontend/pro/package.json](file://frontend/pro/package.json) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [frontend/pro/chatbot/Index.svelte](file://frontend/pro/chatbot/Index.svelte) +- [frontend/pro/multimodal-input/Index.svelte](file://frontend/pro/multimodal-input/Index.svelte) +- [frontend/pro/web-sandbox/Index.svelte](file://frontend/pro/web-sandbox/Index.svelte) +- [frontend/pro/monaco-editor/Index.svelte](file://frontend/pro/monaco-editor/Index.svelte) +- [docs/layout_templates/chatbot/README-zh_CN.md](file://docs/layout_templates/chatbot/README-zh_CN.md) +- [docs/layout_templates/coder_artifacts/README-zh_CN.md](file://docs/layout_templates/coder_artifacts/README-zh_CN.md) +- [docs/demos/example.py](file://docs/demos/example.py) +- [docs/README-zh_CN.md](file://docs/README-zh_CN.md) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +ModelScope Studio 是一个基于 Gradio 的第三方组件库，为开发者提供更定制化的界面搭建能力与更丰富的组件使用形式。它支持 Ant Design 与 Ant Design X 两大 UI 生态，并提供了 Pro 场景化组件（如聊天机器人、多模态输入、代码编辑器、网页沙盒等），适合在机器学习与人工智能应用中快速构建专业级前端界面。 + +- 相比 Gradio 原生组件，ModelScope Studio 更强调页面布局与组件灵活性，适合追求视觉与交互体验的项目。 +- 当应用需要在 Python 端进行大量内置数据处理时，可结合 Gradio 原生组件；ModelScope Studio 可作为优化层提升前端表现。 +- 在 Hugging Face Space 中使用时，需在 demo.launch() 中设置 ssr_mode=False，以避免页面渲染异常。 + +章节来源 + +- [README-zh_CN.md:26-32](file://README-zh_CN.md#L26-L32) +- [README.md:26-32](file://README.md#L26-L32) + +## 项目结构 + +该项目采用前后端分离与多包组织方式： + +- 后端 Python 包：提供组件导出与版本信息，统一对外暴露组件集合。 +- 前端 Svelte 包：按模块拆分为 antd、antdx、base、pro 等子包，分别对应 UI 组件、基础能力与 Pro 场景化组件。 +- 文档与示例：包含组件文档、布局模板与演示脚本，便于开发者快速上手。 + +```mermaid +graph TB +subgraph "后端" +PY_PKG["Python 包
backend/modelscope_studio"] +PY_INIT["__init__.py"] +PY_VER["version.py"] +end +subgraph "前端" +FE_ANTD["@modelscope-studio/antd
package.json"] +FE_PRO["@modelscope-studio/pro
package.json"] +FE_BASE["base 组件"] +FE_ANTDX["antdx 组件"] +end +PY_PKG --> PY_INIT +PY_PKG --> PY_VER +PY_PKG --> FE_ANTD +PY_PKG --> FE_PRO +PY_PKG --> FE_BASE +PY_PKG --> FE_ANTDX +``` + +图表来源 + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) + +章节来源 + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) + +## 核心组件 + +- Ant Design 组件族：覆盖表单、布局、反馈、导航、数据录入、展示等全链路 UI 组件，满足常规业务界面需求。 +- Pro 场景化组件：面向 AI/ML 应用的专用组件，包括聊天机器人、多模态输入、代码编辑器、网页沙盒等。 +- 基础组件：提供应用上下文、自动加载、文本/段落/插槽等通用能力，支撑复杂布局与动态渲染。 + +章节来源 + +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [docs/README-zh_CN.md:14-26](file://docs/README-zh_CN.md#L14-L26) + +## 架构总览 + +ModelScope Studio 的前端组件以 Svelte 实现，通过 @svelte-preprocess-react 将 React 组件桥接到 Svelte 上下文中，实现与 Gradio 的无缝对接。Pro 组件进一步封装了与 Gradio 共享状态（如主题、API 前缀、根路径）的逻辑，确保在不同部署环境下的稳定性。 + +```mermaid +graph TB +GR["Gradio 应用"] +MS_APP["ms.Application
应用上下文"] +CFG["antd.ConfigProvider
配置提供者"] +AUTOLOAD["ms.AutoLoading
自动加载"] +CHAT["Pro 聊天机器人
chatbot"] +MM["Pro 多模态输入
multimodal-input"] +EDIT["Pro 代码编辑器
monaco-editor"] +SANDBOX["Pro 网页沙盒
web-sandbox"] +GR --> MS_APP --> CFG --> AUTOLOAD +MS_APP --> CHAT +MS_APP --> MM +MS_APP --> EDIT +MS_APP --> SANDBOX +``` + +图表来源 + +- [docs/demos/example.py:5-10](file://docs/demos/example.py#L5-L10) +- [frontend/pro/chatbot/Index.svelte:12-88](file://frontend/pro/chatbot/Index.svelte#L12-L88) +- [frontend/pro/multimodal-input/Index.svelte:13-96](file://frontend/pro/multimodal-input/Index.svelte#L13-L96) +- [frontend/pro/monaco-editor/Index.svelte:12-98](file://frontend/pro/monaco-editor/Index.svelte#L12-L98) +- [frontend/pro/web-sandbox/Index.svelte:12-74](file://frontend/pro/web-sandbox/Index.svelte#L12-L74) + +## 详细组件分析 + +### 聊天机器人（Pro Chatbot） + +- 适用场景：AI 聊天机器人界面、多轮对话管理、对话历史编辑/重算/删除、中断提示、输入建议、附件上传等。 +- 关键特性：支持多会话并发、历史记录细粒度控制、输入建议触发、附件上传限制与格式控制。 +- 使用建议：结合 Gradio 的共享状态与主题配置，确保在不同部署环境下一致的外观与行为。 + +```mermaid +sequenceDiagram +participant U as "用户" +participant C as "Pro Chatbot" +participant G as "Gradio 共享状态" +U->>C : 输入消息/触发建议 +C->>G : 读取主题/API 前缀/根路径 +C->>U : 展示对话/历史/建议 +U->>C : 中断/清空/编辑/重算 +C->>G : 更新状态并渲染 +``` + +图表来源 + +- [frontend/pro/chatbot/Index.svelte:67-88](file://frontend/pro/chatbot/Index.svelte#L67-L88) +- [docs/layout_templates/chatbot/README-zh_CN.md:7-11](file://docs/layout_templates/chatbot/README-zh_CN.md#L7-L11) + +章节来源 + +- [frontend/pro/chatbot/Index.svelte:12-88](file://frontend/pro/chatbot/Index.svelte#L12-L88) +- [docs/layout_templates/chatbot/README-zh_CN.md:1-20](file://docs/layout_templates/chatbot/README-zh_CN.md#L1-L20) + +### 多模态输入（Pro Multimodal Input） + +- 适用场景：AI 应用中需要同时输入文本与多媒体（图片/文件）的界面，如图像描述、文档问答、代码生成等。 +- 关键特性：支持文件上传、粘贴上传、值变更回调、与 Gradio 客户端集成。 +- 使用建议：合理设置上传数量与格式限制，结合后端处理流程保证安全性与性能。 + +```mermaid +flowchart TD +Start(["进入组件"]) --> CheckVisible{"是否可见"} +CheckVisible --> |否| End(["退出"]) +CheckVisible --> |是| Upload["文件上传/粘贴"] +Upload --> Prepare["准备文件数据"] +Prepare --> CallAPI["调用 Gradio 客户端上传"] +CallAPI --> Update["更新组件值"] +Update --> Render["渲染输出"] +Render --> End +``` + +图表来源 + +- [frontend/pro/multimodal-input/Index.svelte:68-96](file://frontend/pro/multimodal-input/Index.svelte#L68-L96) + +章节来源 + +- [frontend/pro/multimodal-input/Index.svelte:13-96](file://frontend/pro/multimodal-input/Index.svelte#L13-L96) + +### 代码编辑器（Pro Monaco Editor） + +- 适用场景：AI 助手/代码生成工具、在线 IDE 预览、代码对比与差异编辑。 +- 关键特性：支持 CDN/本地加载器模式、主题适配、值变更回调、插槽扩展。 +- 使用建议：根据部署环境选择合适的加载器模式，避免跨域与资源加载问题。 + +```mermaid +sequenceDiagram +participant E as "Monaco Editor" +participant L as "加载器" +participant P as "属性处理器" +participant G as "Gradio 主题" +E->>P : 获取组件属性 +P->>E : 传递样式/类名/ID/值 +E->>L : 初始化加载器(CDN/Local) +L-->>E : 加载完成 +E->>G : 读取主题模式 +E-->>P : 触发值变更回调 +``` + +图表来源 + +- [frontend/pro/monaco-editor/Index.svelte:61-89](file://frontend/pro/monaco-editor/Index.svelte#L61-L89) + +章节来源 + +- [frontend/pro/monaco-editor/Index.svelte:12-98](file://frontend/pro/monaco-editor/Index.svelte#L12-L98) + +### 网页沙盒（Pro Web Sandbox） + +- 适用场景：在线预览/调试 HTML/CSS/JS 片段，适合 AI 辅助开发与教学演示。 +- 关键特性：编译错误/成功事件、渲染错误事件、主题模式适配、插槽扩展。 +- 使用建议：严格控制沙盒内容与权限，避免执行不受信任代码。 + +```mermaid +flowchart TD +Enter(["进入沙盒"]) --> Load["加载内容"] +Load --> Compile{"编译成功?"} +Compile --> |否| OnError["触发编译错误事件"] +Compile --> |是| Render["渲染输出"] +Render --> Done["完成"] +OnError --> Done +``` + +图表来源 + +- [frontend/pro/web-sandbox/Index.svelte:60-74](file://frontend/pro/web-sandbox/Index.svelte#L60-L74) + +章节来源 + +- [frontend/pro/web-sandbox/Index.svelte:12-74](file://frontend/pro/web-sandbox/Index.svelte#L12-L74) + +### Ant Design 组件族 + +- 适用场景：通用业务界面构建，如表单填写、列表展示、分页导航、通知提醒等。 +- 关键特性：覆盖 UI 设计体系的完整组件矩阵，支持国际化与主题切换。 +- 使用建议：结合 ConfigProvider 进行全局配置，配合 AutoLoading 提升首屏体验。 + +章节来源 + +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [docs/demos/example.py:5-10](file://docs/demos/example.py#L5-L10) + +## 依赖关系分析 + +- 版本与命名：前端包 @modelscope-studio/antd 与 @modelscope-studio/pro 均标注为 2.0.0，后端包 version.py 亦指向相同语义版本，确保前后端一致性。 +- 与 Gradio 的集成：组件通过 Gradio 共享状态（root、api_prefix、theme）进行渲染与交互，确保在不同部署环境（含 Hugging Face Space）下的一致性。 +- 部署注意事项：在 Hugging Face Space 中使用时，需在 demo.launch() 设置 ssr_mode=False，避免 SSR 导致的页面渲染问题。 + +```mermaid +graph LR +VER["version.py
2.0.0"] +ANTDPKG["@modelscope-studio/antd
2.0.0"] +PROPkg["@modelscope-studio/pro
2.0.0"] +VER --> ANTDPKG +VER --> PROPkg +``` + +图表来源 + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) + +章节来源 + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) +- [README-zh_CN.md:32](file://README-zh_CN.md#L32) +- [README.md:32](file://README.md#L32) + +## 性能考量 + +- 按需加载与懒加载：Pro 组件普遍采用 importComponent 与 import 动态导入，减少初始包体与首屏阻塞。 +- 主题与资源：Monaco Editor 支持 CDN/本地加载器，可根据网络与安全策略选择，避免不必要的资源下载。 +- 文件上传：多模态输入组件通过 Gradio 客户端上传文件，建议在前端限制文件大小与类型，降低后端压力。 +- SSR 注意：在 Hugging Face Space 中禁用 SSR，避免服务端渲染导致的兼容性问题。 + +章节来源 + +- [frontend/pro/monaco-editor/Index.svelte:61-70](file://frontend/pro/monaco-editor/Index.svelte#L61-L70) +- [frontend/pro/multimodal-input/Index.svelte:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) +- [README-zh_CN.md:32](file://README-zh_CN.md#L32) +- [README.md:32](file://README.md#L32) + +## 故障排查指南 + +- 页面不显示或渲染异常：在 demo.launch() 中添加 ssr_mode=False，尤其在 Hugging Face Space 环境。 +- 组件不可见：检查组件的 visible 属性与父容器布局，确认 ms.Application 包裹层级正确。 +- 编辑器加载失败：确认 \_loader 配置（cdn/local）与 cdn_url 是否有效，避免跨域与资源路径问题。 +- 上传失败：检查文件类型与数量限制，确认 Gradio 客户端上传接口可用。 + +章节来源 + +- [README-zh_CN.md:32](file://README-zh_CN.md#L32) +- [README.md:32](file://README.md#L32) +- [frontend/pro/monaco-editor/Index.svelte:61-70](file://frontend/pro/monaco-editor/Index.svelte#L61-L70) +- [frontend/pro/multimodal-input/Index.svelte:68-75](file://frontend/pro/multimodal-input/Index.svelte#L68-L75) + +## 结论 + +ModelScope Studio 通过 Ant Design 与 Pro 场景化组件，为机器学习与人工智能应用提供了高可定制、高性能的前端界面解决方案。它在以下方面具备显著优势： + +- 与 Gradio 深度集成，简化 AI 应用的前端开发流程。 +- 提供聊天机器人、多模态输入、代码编辑器、网页沙盒等面向 AI 的专用组件，覆盖常见业务场景。 +- 支持灵活的主题与国际化配置，适配多种部署环境。 + +何时选择： + +- 需要构建美观、交互丰富的 AI 应用界面。 +- 需要多模态输入、对话管理、代码编辑与在线预览等场景化能力。 +- 对部署环境有差异化要求（如 Hugging Face Space），需要 SSR 控制。 + +何时不适合： + +- 应用需要在 Python 端进行大量内置数据处理与计算，优先使用 Gradio 原生组件。 +- 对前端性能与资源占用极为敏感，且无需复杂 UI 与交互。 + +## 附录 + +- 快速开始示例：在 Blocks 中使用 ms.Application、antd.ConfigProvider 与 ms.AutoLoading 包裹组件，然后启动 demo。 +- 布局模板：聊天机器人与代码产物（Coder Artifacts）模板提供了开箱即用的场景化界面。 + +章节来源 + +- [docs/demos/example.py:5-10](file://docs/demos/example.py#L5-L10) +- [docs/layout_templates/chatbot/README-zh_CN.md:1-20](file://docs/layout_templates/chatbot/README-zh_CN.md#L1-L20) +- [docs/layout_templates/coder_artifacts/README-zh_CN.md:1-8](file://docs/layout_templates/coder_artifacts/README-zh_CN.md#L1-L8) diff --git "a/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\346\212\200\346\234\257\346\240\210.md" "b/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\346\212\200\346\234\257\346\240\210.md" new file mode 100644 index 00000000..e833a0d7 --- /dev/null +++ "b/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\346\212\200\346\234\257\346\240\210.md" @@ -0,0 +1,397 @@ +# 技术栈 + + +**本文引用的文件** +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [pnpm-workspace.yaml](file://pnpm-workspace.yaml) +- [frontend/package.json](file://frontend/package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) +- [frontend/tsconfig.json](file://frontend/tsconfig.json) +- [svelte-tsconfig.json](file://svelte-tsconfig.json) +- [docs/app.py](file://docs/app.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [backend/modelscope_studio/components/antd/__init__.py](file://backend/modelscope_studio/components/antd/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [config/lint-config/package.json](file://config/lint-config/package.json) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖关系分析](#依赖关系分析) +7. [性能考量](#性能考量) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向 ModelScope Studio 项目的开发者与维护者，系统梳理并解释项目的技术栈与架构设计，重点覆盖： + +- Python 后端技术栈：Gradio 6.0–6.8.0、组件库组织与打包策略 +- 前端技术栈：Svelte 5.55.2、Ant Design 6.3.5、Ant Design X、React 19.2.4、Vite 构建与插件体系 +- Monorepo 架构：工作区划分、包管理与构建流程 +- 开发工具链：ESLint、Stylelint、Prettier、TypeScript、Svelte 检查 +- 测试与发布：变更集版本管理、PyPI 发布脚本 +- 最佳实践：组件化架构、插件系统、构建优化与错误处理 + +## 项目结构 + +ModelScope Studio 采用 Monorepo 架构，根目录通过 pnpm 工作区统一管理多个子包与配置模块。前端以 Svelte 为核心，结合 React 生态与 Ant Design/Ant Design X 组件体系；后端基于 Gradio 的自定义组件机制，提供丰富的 UI 组件与高级能力。 + +```mermaid +graph TB +Root["仓库根目录"] --> Frontend["前端包
frontend/"] +Root --> Backend["Python 包
backend/modelscope_studio/"] +Root --> Config["配置与工具链
config/"] +Root --> Docs["文档站点
docs/"] +Root --> Scripts["脚本与发布
scripts/"] +Frontend --> Antd["Antd 组件集合
frontend/antd/"] +Frontend --> Antdx["AntdX 组件集合
frontend/antdx/"] +Frontend --> Pro["Pro 高级组件
frontend/pro/"] +Frontend --> Base["基础组件
frontend/base/"] +Frontend --> Utils["工具与别名
frontend/utils/"] +Frontend --> Plugin["Vite 插件
frontend/plugin.js"] +Frontend --> Define["Vite 配置工厂
frontend/defineConfig.js"] +Backend --> PyPkg["Python 打包配置
pyproject.toml"] +Backend --> Version["版本号
backend/modelscope_studio/version.py"] +Backend --> Components["组件导出入口
backend/modelscope_studio/components/antd/__init__.py"] +Backend --> DevUtil["开发工具与上下文
backend/modelscope_studio/utils/dev/component.py"] +Docs --> AppPy["文档应用入口
docs/app.py"] +Config --> Lint["Lint 配置包
config/lint-config/package.json"] +``` + +图表来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +章节来源 + +- [pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## 核心组件 + +- Python 后端 + - Gradio 6.0–6.8.0：作为组件运行时与页面渲染的基础框架，负责组件生命周期、事件与状态管理。 + - 组件组织：按功能域拆分至 antd、antdx、pro、base 四大命名空间，便于按需引入与文档生成。 + - 打包与分发：使用 Hatchling 构建，artifacts 明确导出各组件模板资源，wheel 仅包含 backend 包路径。 +- 前端 + - Svelte 5.55.2：组件编译与运行时，具备更小体积与更快的热更新体验。 + - Ant Design 6.3.5 与 Ant Design X：前者提供通用 UI 能力，后者聚焦对话与协作场景。 + - React 19.2.4：通过 Vite 插件桥接 React 生态，实现与 Svelte 的混编与共享全局对象。 + - Vite 构建：通过自定义插件进行外部化与别名映射，减少产物体积并提升加载效率。 +- 文档与站点 + - docs/app.py：动态扫描组件与布局模板，生成多标签页文档站点，支持中英文切换与主题化。 + +章节来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +## 架构总览 + +整体架构由“前端组件层 + 后端组件层 + 文档与工具链”构成。前端通过 Vite 插件将 React/AntD 等依赖外部化到宿主全局，Svelte 组件在浏览器侧直接消费；后端通过 Gradio 将 Python 组件注册为可复用模块，并在文档站点中统一渲染与演示。 + +```mermaid +graph TB +subgraph "前端" +Svelte["Svelte 5.55.2"] +Antd["Antd 6.3.5"] +Antdx["AntdX"] +React["React 19.2.4"] +Vite["Vite 构建"] +Plugin["ModelScopeStudioVitePlugin"] +end +subgraph "后端" +Gradio["Gradio 6.0–6.8.0"] +PyPkg["Python 打包(Hatchling)"] +Components["组件导出(antd/antdx/pro/base)"] +end +subgraph "文档与工具" +DocsApp["docs/app.py"] +LintCfg["Lint 配置包"] +end +Svelte --> Antd +Svelte --> Antdx +React --> Antd +Vite --> Plugin +Plugin --> React +Plugin --> Antd +Gradio --> Components +PyPkg --> Components +DocsApp --> Gradio +DocsApp --> Components +LintCfg --> Vite +``` + +图表来源 + +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [config/lint-config/package.json:1-48](file://config/lint-config/package.json#L1-L48) + +## 详细组件分析 + +### 前端 Vite 插件与构建优化 + +该插件负责： + +- 将 React、Ant Design、AntdX、dayjs、monaco-loader 等依赖外部化为 window.ms_globals.\*，避免重复打包 +- 在构建阶段设置 define 常量，确保生产环境行为一致 +- 通过别名映射 @utils、@globals、svelte-preprocess-react，简化导入路径 +- 在 renderChunk 阶段对 import/export 声明进行转换，将模块引用重写为全局访问，减少运行时开销 + +```mermaid +flowchart TD +Start(["开始构建"]) --> ReadConfig["读取 Vite 配置"] +ReadConfig --> SetDefine["设置 define 常量"] +SetDefine --> AliasMap["配置别名(@utils/@globals/svelte-preprocess-react)"] +AliasMap --> Externalize{"是否启用外部化?"} +Externalize --> |是| RollupExt["Rollup 外部化配置"] +Externalize --> |否| SkipExt["跳过外部化"] +RollupExt --> Transform["renderChunk 中转译 import/export"] +SkipExt --> Transform +Transform --> Output(["输出优化后的产物"]) +``` + +图表来源 + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:41-168](file://frontend/plugin.js#L41-L168) + +章节来源 + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) + +### 组件导出与命名空间 + +- antd：覆盖 Ant Design 官方组件体系，按模块化拆分，提供完整类型与模板资源 +- antdx：面向对话与协作场景的扩展组件集合，如 Bubble、Conversations、Sender 等 +- pro：高级业务组件，如 Chatbot、Monaco Editor、Web Sandbox +- base：基础渲染与布局组件，如 Application、AutoLoading、Slot、Fragment、Each、Filter、Markdown 等 + +```mermaid +graph LR +A["antd/*"] --> ExportA["__init__.py 导出"] +B["antdx/*"] --> ExportB["components.py 导出"] +C["pro/*"] --> ExportC["独立包/模板"] +D["base/*"] --> ExportD["components.py 导出"] +ExportA --> PyPkg["pyproject.toml artifacts"] +ExportB --> PyPkg +ExportC --> PyPkg +ExportD --> PyPkg +``` + +图表来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) + +章节来源 + +- [backend/modelscope_studio/components/antd/**init**.py:1-150](file://backend/modelscope_studio/components/antd/__init__.py#L1-L150) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) + +### 文档站点与动态路由 + +docs/app.py 动态扫描组件与布局模板，构建多标签页文档站点： + +- 支持中英文文案切换 +- 为每个组件生成菜单与文档索引 +- 通过 Site 渲染统一入口，queue 与并发参数调优 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant App as "docs/app.py" +participant Scan as "动态扫描" +participant Site as "Site 渲染" +participant Gradio as "Gradio 运行时" +Dev->>App : 启动开发服务器 +App->>Scan : 扫描组件与布局模板 +Scan-->>App : 返回组件与模板清单 +App->>Site : 构建菜单与文档索引 +Site->>Gradio : 注册组件与页面 +Gradio-->>Dev : 展示文档站点 +``` + +图表来源 + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +章节来源 + +- [docs/app.py:1-595](file://docs/app.py#L1-L595) + +### 组件基类与上下文 + +后端提供了三类组件基类，用于统一生命周期、插槽与渲染控制： + +- ModelScopeComponent：标准组件基类，支持事件、可见性、样式等属性 +- ModelScopeLayoutComponent：布局组件基类，支持 BlockContext 与内部布局标记 +- ModelScopeDataLayoutComponent：数据与布局混合组件，继承组件与上下文能力 + +```mermaid +classDiagram +class ModelScopeComponent { ++EVENTS ++skip_api ++__init__(...) ++elem_style ++as_item +} +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++__exit__(...) ++__init__(...) ++elem_style ++as_item +} +class ModelScopeDataLayoutComponent { ++EVENTS ++SLOTS ++__exit__(...) ++__init__(...) ++preserved_by_key +} +ModelScopeDataLayoutComponent --|> ModelScopeComponent +ModelScopeDataLayoutComponent --|> BlockContext +``` + +图表来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +章节来源 + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +## 依赖关系分析 + +- 前端依赖 + - React 与 Ant Design：通过 Vite 插件外部化，减少打包体积 + - Svelte 5.55.2：作为核心编译器与运行时 + - Ant Design X：提供对话与协作相关组件生态 + - Monaco Editor 与 React 生态：用于代码编辑与高亮 +- 后端依赖 + - Gradio 6.0–6.8.0：组件运行时与页面渲染 + - 打包工具：Hatchling、Hatch-requirements-txt、Fancy-PyPI-Readme + - artifacts 明确导出各组件模板，wheel 仅包含 backend 路径 +- 工具链 + - ESLint、Stylelint、Prettier、TypeScript、Svelte 检查 + - Changesets 用于版本管理与变更记录 + +```mermaid +graph TB +subgraph "前端" +R["React 19.2.4"] +AD["Antd 6.3.5"] +AFX["@ant-design/x 2.5.0"] +SV["Svelte 5.55.2"] +ME["Monaco Editor"] +VR["Vite + 插件"] +end +subgraph "后端" +GR["Gradio 6.0–6.8.0"] +HN["Hatchling"] +ART["artifacts 模板导出"] +end +R --> AD +R --> AFX +SV --> AD +SV --> AFX +VR --> R +VR --> SV +GR --> ART +HN --> ART +``` + +图表来源 + +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) +- [frontend/plugin.js:5-20](file://frontend/plugin.js#L5-L20) + +章节来源 + +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) + +## 性能考量 + +- 外部化策略：通过 Vite 插件将 React、Antd、AntdX 等依赖外部化，显著降低前端包体与首屏加载时间 +- 构建目标：ESNext 模块化目标，配合现代浏览器特性，减少转译成本 +- 组件模板：后端通过 artifacts 精准导出模板资源，避免冗余文件进入 wheel +- 并发与队列：文档站点启动时设置 queue 与并发上限，保障演示稳定性 + +章节来源 + +- [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) +- [frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) +- [docs/app.py:592-595](file://docs/app.py#L592-L595) + +## 故障排查指南 + +- 构建失败或外部化异常 + - 检查 Vite 插件是否正确配置 external 与 alias + - 确认全局变量 window.ms_globals 是否暴露所需模块 +- 组件未显示或样式缺失 + - 核对 artifacts 路径与模板导出是否匹配 + - 确保 Gradio 版本在 6.0–6.8.0 范围内 +- 文档站点无法启动 + - 查看 docs/app.py 的扫描逻辑与菜单构建 + - 确认组件 app.py 是否存在且包含 docs 字段 +- Lint 或格式化报错 + - 使用统一的 lint 配置包，确保规则一致 + - 优先执行格式化与类型检查，再进行 ESLint/Stylelint + +章节来源 + +- [frontend/plugin.js:41-76](file://frontend/plugin.js#L41-L76) +- [pyproject.toml:45-257](file://pyproject.toml#L45-L257) +- [docs/app.py:19-61](file://docs/app.py#L19-L61) +- [config/lint-config/package.json:1-48](file://config/lint-config/package.json#L1-L48) + +## 结论 + +ModelScope Studio 以 Monorepo 为骨架，前端以 Svelte 与 React 双引擎协同，后端以 Gradio 为基础，形成“组件即服务”的可复用生态。通过 Vite 插件的外部化与别名映射、artifacts 精准导出、以及统一的 Lint/格式化工具链，项目在可维护性、性能与开发体验上取得平衡。建议在后续迭代中持续完善组件文档与自动化测试，进一步提升交付质量与团队协作效率。 + +## 附录 + +- 版本号与元信息 + - 仓库版本：2.0.0 + - Python 包版本：与仓库版本保持一致 +- 关键配置参考 + - 前端工作区与依赖：[frontend/package.json:1-59](file://frontend/package.json#L1-L59) + - Python 打包与导出：[pyproject.toml:45-257](file://pyproject.toml#L45-L257) + - 工作区声明：[pnpm-workspace.yaml:1-12](file://pnpm-workspace.yaml#L1-L12) + - TypeScript 与 Svelte 配置：[frontend/tsconfig.json:1-8](file://frontend/tsconfig.json#L1-L8)、[svelte-tsconfig.json:1-4](file://svelte-tsconfig.json#L1-L4) + - 文档站点入口：[docs/app.py:1-595](file://docs/app.py#L1-L595) + - Lint 配置包：[config/lint-config/package.json:1-48](file://config/lint-config/package.json#L1-L48) diff --git "a/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\346\240\270\345\277\203\347\211\271\346\200\247.md" "b/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\346\240\270\345\277\203\347\211\271\346\200\247.md" new file mode 100644 index 00000000..ef29b7b4 --- /dev/null +++ "b/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\346\240\270\345\277\203\347\211\271\346\200\247.md" @@ -0,0 +1,321 @@ +# 核心特性 + + +**本文引用的文件** +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/components/pro/components.py](file://backend/modelscope_studio/components/pro/components.py) +- [frontend/package.json](file://frontend/package.json) +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [frontend/antdx/package.json](file://frontend/antdx/package.json) +- [pyproject.toml](file://pyproject.toml) +- [docs/README.md](file://docs/README.md) +- [docs/FAQ.md](file://docs/FAQ.md) +- [docs/app.py](file://docs/app.py) +- [frontend/antd/config-provider/locales.ts](file://frontend/antd/config-provider/locales.ts) +- [docs/components/antd/config_provider/demos/basic.py](file://docs/components/antd/config_provider/demos/basic.py) +- [docs/components/base/application/demos/theme_adaptation.py](file://docs/components/base/application/demos/theme_adaptation.py) +- [docs/components/pro/web_sandbox/demos/react.py](file://docs/components/pro/web_sandbox/demos/react.py) + + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +ModelScope Studio 是一个基于 Gradio 的第三方组件库，旨在为开发者提供更丰富的 UI 组件与更强的页面布局能力。它在保持与原生 Gradio 组件良好兼容的同时，引入了 Ant Design（Antd）与 Ant Design X（Antdx）两大 UI 生态，并扩展出 Pro 高级组件族，覆盖从通用交互到 AI 场景的多种需求。其核心特性包括： + +- 支持的 UI 库：Ant Design、Ant Design X +- 组件数量统计：Antd 组件族包含大量常用 UI 组件；Antdx 专注于对话与提示场景；Pro 组件提供聊天机器人、多模态输入、代码编辑器与网页沙盒等高级能力 +- Gradio 集成能力：与 Gradio 事件系统、状态管理、队列与并发控制无缝衔接 +- 优势对比：相较原生 Gradio 组件，ModelScope Studio 更注重页面布局优化与组件灵活性，适合构建更美观、可维护的用户界面 +- 开发场景：机器学习应用、AI 交互界面、多模态体验、可视化与演示空间 +- 国际化与主题：内置多语言映射与主题定制能力，支持明暗模式与紧凑算法 +- 性能优化：通过前端组件按需打包与模板缓存、Gradio 队列并发配置等手段提升响应速度 + +## 项目结构 + +该项目采用前后端分离与多包组织方式： + +- 后端 Python 包：提供组件导出与打包元数据 +- 前端 Svelte 包：按模块拆分 Antd/Antdx/Base/Pro，每个组件以独立目录与模板形式存在 +- 文档与示例：通过 docs 应用聚合各组件示例与布局模板 + +```mermaid +graph TB +subgraph "后端" +PY["Python 包
modelscope_studio"] +PY --> ANTDCOMP["antd 组件导出"] +PY --> ANTDXCOMP["antdx 组件导出"] +PY --> PROCOMP["pro 组件导出"] +end +subgraph "前端" +FE_PKG["frontend/package.json"] +ANTD_PKG["@modelscope-studio/antd"] +ANTDX_PKG["@modelscope-studio/antdx"] +FE_PKG --> ANTD_PKG +FE_PKG --> ANTDX_PKG +end +subgraph "文档与示例" +DOCS["docs/app.py"] +DOCS --> DEMOS["各组件示例与布局模板"] +end +PY --- FE_PKG +DOCS --- FE_PKG +``` + +图表来源 + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:577-590](file://docs/app.py#L577-L590) + +章节来源 + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:577-590](file://docs/app.py#L577-L590) + +## 核心组件 + +ModelScope Studio 的核心由三大组件族构成： + +- Antd 组件族：覆盖通用、布局、导航、数据录入、数据展示、反馈与全局配置等类别，组件数量丰富，适配复杂业务场景 +- Antdx 组件族：面向 AI 交互的专用组件，如对话气泡、提示集、发送器、思考链、欢迎语等 +- Pro 组件族：提供高级能力，如聊天机器人、多模态输入、Monaco 编辑器、网页沙盒等 + +章节来源 + +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +## 架构总览 + +下图展示了 ModelScope Studio 在 Gradio 生态中的位置与交互关系： + +```mermaid +graph TB +GR["Gradio 应用"] +MS["ModelScope Studio 组件库"] +ANTD["Ant Design 组件"] +ANTCFG["ConfigProvider 全局配置"] +ANTDX["Ant Design X 组件"] +PRO["Pro 高级组件"] +BASE["Base 基础组件"] +GR --> MS +MS --> ANTD +MS --> ANTDX +MS --> PRO +MS --> BASE +ANTD --> ANTCFG +``` + +图表来源 + +- [docs/README.md:32-42](file://docs/README.md#L32-L42) +- [docs/app.py:577-590](file://docs/app.py#L577-L590) + +章节来源 + +- [docs/README.md:32-42](file://docs/README.md#L32-L42) +- [docs/app.py:577-590](file://docs/app.py#L577-L590) + +## 详细组件分析 + +### Antd 组件族 + +Antd 组件族是 ModelScope Studio 的主体，覆盖广泛的功能域，适合构建企业级或复杂交互的界面。典型组件包括： + +- 布局类：Layout、Grid、Flex、Space、Splitter +- 导航类：Anchor、Breadcrumb、Dropdown、Menu、Pagination、Steps +- 数据录入类：AutoComplete、Cascader、Checkbox、ColorPicker、DatePicker、Form、Input、InputNumber、Mentions、Radio、Rate、Select、Slider、Switch、TimePicker、Transfer、TreeSelect、Upload +- 数据展示类：Avatar、Badge、Calendar、Card、Carousel、Collapse、Descriptions、Empty、Image、List、Popover、QRCode、Segmented、Statistic、Table、Tabs、Tag、Timeline、Tooltip、Tour、Tree +- 反馈类：Alert、Drawer、Message、Modal、Notification、Popconfirm、Progress、Result、Skeleton、Spin、Watermark +- 通用类：Button、FloatButton、Icon、Typography +- 全局配置：ConfigProvider（主题、语言、方向） + +组件数量统计（依据后端导出清单）： + +- Antd 主体组件：约 120+ 个具体组件（含子模块） +- Antdx 专用组件：约 30+ 个组件 +- Pro 高级组件：约 4 个组件 + +章节来源 + +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) +- [pyproject.toml:48-244](file://pyproject.toml#L48-L244) + +### Antdx 组件族 + +Antdx 专为 AI 交互设计，强调“唤醒—表达—确认—反馈—工具”的完整对话链路： + +- 唤醒：Welcome、Prompts +- 表达：Attachments、Sender、Suggestion +- 确认：ThoughtChain +- 反馈：Actions +- 工具：XProvider +- 通用：Bubble、Conversations + +这些组件与 ConfigProvider、主题与国际化配合，可快速搭建高质量的 AI 会话界面。 + +章节来源 + +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) + +### Pro 组件族 + +Pro 组件聚焦高级交互与演示场景： + +- Chatbot：对话型应用 +- MultimodalInput：多模态输入 +- MonacoEditor：代码编辑器 +- WebSandbox：网页沙盒预览 + +章节来源 + +- [backend/modelscope_studio/components/pro/components.py:1-8](file://backend/modelscope_studio/components/pro/components.py#L1-L8) + +### 国际化与主题定制 + +- 国际化：前端提供多语言映射，支持从语言代码到 Antd/dayjs 本地化的转换 +- 主题定制：ConfigProvider 支持主题算法（明暗、紧凑）、主色与方向切换 +- 示例：文档中提供了基础主题与颜色调整示例，以及应用级主题适配示例 + +```mermaid +flowchart TD +Start(["进入页面"]) --> DetectLang["检测语言代码"] +DetectLang --> LoadLocales["动态加载 Antd 与 dayjs 本地化"] +LoadLocales --> ApplyTheme["应用主题配置明暗/紧凑"] +ApplyTheme --> RenderUI["渲染组件"] +RenderUI --> End(["完成"]) +``` + +图表来源 + +- [frontend/antd/config-provider/locales.ts:12-87](file://frontend/antd/config-provider/locales.ts#L12-L87) +- [docs/components/antd/config_provider/demos/basic.py:54-74](file://docs/components/antd/config_provider/demos/basic.py#L54-L74) +- [docs/components/base/application/demos/theme_adaptation.py:6-8](file://docs/components/base/application/demos/theme_adaptation.py#L6-L8) + +章节来源 + +- [frontend/antd/config-provider/locales.ts:12-87](file://frontend/antd/config-provider/locales.ts#L12-L87) +- [docs/components/antd/config_provider/demos/basic.py:54-74](file://docs/components/antd/config_provider/demos/basic.py#L54-L74) +- [docs/components/base/application/demos/theme_adaptation.py:6-8](file://docs/components/base/application/demos/theme_adaptation.py#L6-L8) + +### Gradio 集成与页面布局优化 + +- 事件与状态：通过 Application、AutoLoading 等基础组件与 Gradio 事件系统协同 +- 布局优化：使用 Flex、Grid、Layout、Space、Splitter 等组件进行灵活布局 +- 交互反馈：AutoLoading 组件用于在交互过程中显示加载反馈，避免 Gradio 默认加载状态缺失导致的空白等待 + +```mermaid +sequenceDiagram +participant U as "用户" +participant G as "Gradio 应用" +participant APP as "Application" +participant AL as "AutoLoading" +participant C as "组件" +U->>G : 触发交互 +G->>APP : 进入上下文 +APP->>AL : 显示加载反馈 +AL-->>U : 展示加载状态 +G->>C : 执行处理逻辑 +C-->>G : 返回结果 +G-->>U : 更新界面 +``` + +图表来源 + +- [docs/FAQ.md:7-19](file://docs/FAQ.md#L7-L19) +- [docs/app.py:577-590](file://docs/app.py#L577-L590) + +章节来源 + +- [docs/FAQ.md:7-19](file://docs/FAQ.md#L7-L19) +- [docs/app.py:577-590](file://docs/app.py#L577-L590) + +## 依赖分析 + +- Python 侧依赖：Gradio 版本范围约束，确保与不同版本的兼容性 +- 前端依赖：Ant Design、Ant Design X、React、Svelte、Monaco Editor、Mermaid、KaTeX、Prism 等 +- 打包与发布：通过 hatchling 构建，artifact 列表包含大量模板资源，便于前端按需加载 + +```mermaid +graph LR +PY["pyproject.toml 依赖"] +FE["frontend/package.json 依赖"] +PY --> |约束| GR["Gradio"] +FE --> |组件生态| ANT["antd"] +FE --> |X 生态| ANTX["@ant-design/x"] +FE --> |编辑器| MONACO["monaco-editor"] +FE --> |可视化| MERMAID["mermaid"] +FE --> |语法高亮| PRISM["prismjs"] +``` + +图表来源 + +- [pyproject.toml:26-26](file://pyproject.toml#L26-L26) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) + +章节来源 + +- [pyproject.toml:26-26](file://pyproject.toml#L26-L26) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) + +## 性能考虑 + +- 并发与队列：示例应用启用了 queue 与并发限制，有助于在高负载下稳定运行 +- 模板与资源：artifact 列表包含大量模板资源，建议在生产环境按需加载，减少首屏体积 +- SSR 注意：在 Hugging Face Space 中需禁用 SSR，以避免自定义组件渲染问题 + +章节来源 + +- [docs/app.py:592-594](file://docs/app.py#L592-L594) +- [docs/FAQ.md:3-5](file://docs/FAQ.md#L3-L5) +- [pyproject.toml:48-244](file://pyproject.toml#L48-L244) + +## 故障排查指南 + +- Hugging Face Space 页面不显示：添加参数 ssr_mode=False +- 交互后等待时间较长：未使用 AutoLoading 组件时，Gradio 默认加载状态可能不显示，建议全局使用 AutoLoading +- 主题/语言未生效：检查 ConfigProvider 的 theme 与 locale 设置是否正确传递至组件树 + +章节来源 + +- [docs/FAQ.md:3-19](file://docs/FAQ.md#L3-L19) +- [docs/components/antd/config_provider/demos/basic.py:54-74](file://docs/components/antd/config_provider/demos/basic.py#L54-L74) + +## 结论 + +ModelScope Studio 通过 Antd、Antdx 与 Pro 三大组件族，结合 Gradio 的事件与状态机制，在页面布局、组件灵活性与 AI 交互体验方面提供了显著增强。其国际化与主题定制能力、完善的示例与文档，使其成为构建机器学习与 AI 交互界面的理想选择。对于需要复杂布局与丰富交互的场景，ModelScope Studio 能够有效提升开发效率与用户体验。 + +## 附录 + +- 使用场景示例 + - 机器学习模型演示：使用 Layout、Grid、Form、Table、Modal 等组件组合展示数据与结果 + - AI 会话界面：使用 Antdx 的 Bubble、Sender、Prompts、ThoughtChain 等组件构建自然对话流程 + - 代码与可视化：使用 Pro 的 MonacoEditor 与 Mermaid 实现代码编辑与流程图展示 + - 多模态输入：使用 Pro 的 MultimodalInput 构建图文/音频输入场景 + - 网页预览：使用 Pro 的 WebSandbox 快速嵌入外部页面进行演示 + +章节来源 + +- [docs/components/pro/web_sandbox/demos/react.py:74-97](file://docs/components/pro/web_sandbox/demos/react.py#L74-L97) +- [docs/components/antd/config_provider/demos/basic.py:54-74](file://docs/components/antd/config_provider/demos/basic.py#L54-L74) +- [docs/components/base/application/demos/theme_adaptation.py:18-30](file://docs/components/base/application/demos/theme_adaptation.py#L18-L30) diff --git "a/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\347\211\210\346\234\254\344\277\241\346\201\257.md" "b/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\347\211\210\346\234\254\344\277\241\346\201\257.md" new file mode 100644 index 00000000..7404d834 --- /dev/null +++ "b/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\347\211\210\346\234\254\344\277\241\346\201\257.md" @@ -0,0 +1,335 @@ +# 版本信息 + + +**本文引用的文件** +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [CHANGELOG.md](file://CHANGELOG.md) +- [.changeset/config.json](file://.changeset/config.json) +- [.changeset/pre.json](file://.changeset/pre.json) +- [.github/workflows/publish.yaml](file://.github/workflows/publish.yaml) +- [scripts/create-tag-n-release.mts](file://scripts/create-tag-n-release.mts) +- [scripts/publish-to-pypi.mts](file://scripts/publish-to-pypi.mts) +- [config/changelog/src/index.ts](file://config/changelog/src/index.ts) +- [README.md](file://README.md) +- [docs/FAQ.md](file://docs/FAQ.md) + + +## 更新摘要 + +**变更内容** + +- 版本号从 2.0.0-beta.0 更新为 2.0.0 +- Gradio 依赖版本要求更新为标准语法格式 +- 更新变更日志以反映 2.0.0 版本的特性 + +## 目录 + +1. [简介](#简介) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 简介 + +本文件面向 ModelScope Studio 用户与维护者，系统化梳理项目版本信息，包括版本历史、当前版本状态、升级路径、兼容性策略、长期支持与支持周期、已知问题与安全更新、变更日志查看方式以及发布频率等。特别地，针对 1.0 版本的重大变更与迁移路径，提供可操作的升级步骤与最佳实践。 + +## 项目结构 + +ModelScope Studio 采用多包工作区（pnpm workspace）组织，核心后端以 Python 包形式发布，前端以 Svelte 组件库形式构建，同时通过 Changesets 工具链管理版本与变更日志生成。发布流程由 GitHub Actions 自动化执行，完成构建、上传 PyPI、打 Tag 并创建 GitHub Release。 + +```mermaid +graph TB +A["根目录
package.json"] --> B["后端 Python 包
pyproject.toml"] +A --> C["前端组件库
frontend/*"] +A --> D["变更集配置
.changeset/config.json"] +D --> E["变更集预发布配置
.changeset/pre.json"] +A --> F["发布工作流
.github/workflows/publish.yaml"] +F --> G["PyPI 发布脚本
scripts/publish-to-pypi.mts"] +F --> H["打 Tag 与发布脚本
scripts/create-tag-n-release.mts"] +A --> I["变更日志生成器
config/changelog/src/index.ts"] +A --> J["变更日志
CHANGELOG.md"] +``` + +**图表来源** + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) +- [config/changelog/src/index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) + +**章节来源** + +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) + +## 核心组件 + +- **当前版本状态** + - 后端 Python 包版本：2.0.0 + - 前端与工作区根包版本：2.0.0 +- **版本号来源** + - 后端 Python 包版本号在 [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) 定义 + - 根包版本号在 [package.json:1-55](file://package.json#L1-L55) 中定义 + - Python 包版本号在 [pyproject.toml:1-258](file://pyproject.toml#L1-L258) 中定义 +- **变更日志** + - 根级变更日志在 [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) + - 变更集工具链配置在 [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) 与 [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) + - 变更日志生成器在 [config/changelog/src/index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) + +**章节来源** + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [config/changelog/src/index.ts:1-222](file://config/changelog/src/index.ts#L1-L222) + +## 架构总览 + +发布与版本管理的端到端流程如下： + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant CS as "Changesets" +participant WF as "GitHub Actions
publish.yaml" +participant PYPI as "PyPI" +participant GH as "GitHub Releases" +Dev->>CS : 提交变更集与版本更新 +CS-->>Dev : 生成/更新变更日志 +Dev->>WF : 推送分支触发工作流 +WF->>PYPI : 调用发布脚本上传包 +WF->>GH : 打 Tag 并创建 Release +GH-->>Dev : 发布完成通知 +``` + +**图表来源** + +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +**章节来源** + +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) +- [scripts/publish-to-pypi.mts:1-60](file://scripts/publish-to-pypi.mts#L1-L60) +- [scripts/create-tag-n-release.mts:1-131](file://scripts/create-tag-n-release.mts#L1-L131) + +## 详细组件分析 + +### 版本历史与当前状态 + +- **最新稳定版本** + - 当前后端版本：2.0.0 + - 前端与根包版本：2.0.0 +- **历史版本与重大里程碑** + - 2.0.0：新增 Ant Design 和 Ant Design X 的完整新功能 + - 2.0.0-beta.0：Gradio 6.0、Ant Design 6.0、Ant Design X 2.0 的整体迁移 + - 1.x 系列：包含大量组件增强、Pro 组件引入、i18n 支持、表单动作等 + - 1.0.0：Gradio 迁移至 5，集成 Ant Design + - 0.x 系列：早期版本，逐步引入自定义组件与 Gradio 5 迁移准备 + +**章节来源** + +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) + +### 升级路径与 1.0 重大变更 + +- **1.0 版本重大变更** + - Gradio 从 4.x 迁移到 5.x + - 组件参数与生命周期调整，确保事件绑定正确 + - 新增 AutoLoading 组件，优化加载反馈 +- **从旧版本到 1.0 的升级步骤** + - 在应用最外层包裹 Application 组件，保持现有组件导入与使用不变 + - 如需继续使用 legacy 模块中的组件，可按 README 示例进行导入 + - 若在 Hugging Face Space 部署，需在 demo.launch() 中添加 ssr_mode=False 参数 + +```mermaid +flowchart TD +Start(["开始升级"]) --> CheckLegacy["检查是否使用 legacy 组件"] +CheckLegacy --> |是| ImportMgr["按 README 示例导入 legacy 模块"] +CheckLegacy --> |否| SkipMgr["跳过 legacy 导入"] +ImportMgr --> WrapApp["在最外层包裹 ms.Application()"] +SkipMgr --> WrapApp +WrapApp --> HFSSR["如部署于 Hugging Face Space，设置 ssr_mode=False"] +HFSSR --> Test["运行测试，确认组件行为正常"] +Test --> Done(["完成"]) +``` + +**图表来源** + +- [README.md:64-78](file://README.md#L64-L78) +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) + +**章节来源** + +- [README.md:64-78](file://README.md#L64-L78) +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) + +### 版本兼容性政策 + +- **Python 兼容性** + - Python 版本要求：>=3.8 + - Gradio 依赖范围：gradio>=6.0,<=6.8.0（当前 2.0.0） +- **前后端版本对齐** + - 根包与后端 Python 包版本均声明为 2.0.0，建议保持一致 +- **浏览器与运行环境** + - 建议在主流浏览器中进行开发与测试 + - 在 Hugging Face Space 部署时需禁用 SSR + +**章节来源** + +- [pyproject.toml:15-26](file://pyproject.toml#L15-L26) +- [package.json:1-55](file://package.json#L1-L55) +- [README.md:34-37](file://README.md#L34-L37) +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) + +### 长期支持版本与支持周期 + +- **当前未公开明确的 LTS 计划与支持周期声明** +- **建议关注根级 CHANGELOG.md 与发布工作流，以获取最新版本动态与发布节奏** + +**章节来源** + +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +### 已知问题、安全更新与 Bug 修复 + +- **已知问题** + - Hugging Face Space 默认启用 SSR，可能导致自定义组件显示异常；需手动禁用 + - 早期版本存在编码与事件绑定问题，已在后续版本修复 +- **安全更新与 Bug 修复** + - 变更日志中包含大量修复项（Fixes），涵盖上传逻辑、样式、渲染、事件绑定等方面 + - 建议优先升级至包含对应修复的版本 + +**章节来源** + +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) + +### 版本选择建议 + +- **生产环境** + - 优先选择稳定版本（非 beta）；若必须使用预发布，请结合变更日志评估风险 +- **开发与实验** + - 可选择 beta 版本体验新特性，但需关注潜在的 API 变更与兼容性问题 +- **与 Gradio 生态集成** + - 确保 Gradio 版本满足依赖范围（gradio>=6.0,<=6.8.0） + +**章节来源** + +- [pyproject.toml:26-26](file://pyproject.toml#L26-L26) +- [package.json:1-55](file://package.json#L1-L55) + +### 变更日志查看方式与发布频率 + +- **查看变更日志** + - 根级 CHANGELOG.md 记录了所有版本的变更摘要 + - 变更集工具链会基于提交信息生成条目，便于追踪 PR、提交与贡献者 +- **发布频率** + - 发布工作流在主分支推送时触发，具体频率取决于提交频率与变更集策略 + - 变更集预发布配置支持以 beta 标签进行预发布管理 + +**章节来源** + +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) +- [.changeset/config.json:1-15](file://.changeset/config.json#L1-L15) +- [.changeset/pre.json:1-16](file://.changeset/pre.json#L1-L16) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) + +## 依赖分析 + +- **版本号一致性** + - 后端 Python 包版本与根包版本保持一致（2.0.0），有利于发布与回溯 +- **依赖范围** + - Gradio 依赖范围严格限定，避免与高版本不兼容 +- **发布链路** + - Changesets 生成变更日志 → GitHub Actions 触发构建与发布 → PyPI 上传 → 打 Tag 与创建 Release + +```mermaid +graph LR +V["版本号
2.0.0"] --> P["Python 包
pyproject.toml"] +V --> R["根包
package.json"] +P --> PYPI["PyPI"] +R --> PYPI +PYPI --> REL["GitHub Releases"] +``` + +**图表来源** + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) + +**章节来源** + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-258](file://pyproject.toml#L1-L258) + +## 性能考虑 + +- **加载反馈** + - 建议全局使用 AutoLoading 组件，以减少前端与后端交互等待时的空白或闪烁 +- **渲染与事件绑定** + - 1.0 版本优化了事件绑定逻辑，升级后可减少不必要的重渲染 +- **上传与文件处理** + - 多个版本修复了上传逻辑与文件保留问题，建议升级至包含相应修复的版本 + +**章节来源** + +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) + +## 故障排查指南 + +- **Hugging Face Space 显示异常** + - 解决方案：在 demo.launch() 中添加 ssr_mode=False +- **上传组件行为异常** + - 建议升级至包含上传逻辑修复的版本 +- **事件绑定与渲染问题** + - 1.0 版本已修复相关问题，建议升级至 1.0 或更高版本 + +**章节来源** + +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) + +## 结论 + +ModelScope Studio 当前正式版本为 2.0.0，围绕 Gradio 6 与 Ant Design 6 的全面迁移带来显著的功能增强与稳定性提升。该版本新增了 Ant Design 和 Ant Design X 的完整新功能，进一步完善了组件生态。升级至 1.0 的关键在于在应用最外层包裹 Application 组件，并在必要时禁用 SSR 以适配 Hugging Face Space。 + +## 附录 + +- **快速参考** + - 当前版本：2.0.0 + - Python 兼容性：>=3.8 + - Gradio 依赖：gradio>=6.0,<=6.8.0 + - 变更日志：根级 CHANGELOG.md + - 发布工作流：.github/workflows/publish.yaml + +**章节来源** + +- [CHANGELOG.md:1-455](file://CHANGELOG.md#L1-L455) +- [pyproject.toml:15-26](file://pyproject.toml#L15-L26) +- [package.json:1-55](file://package.json#L1-L55) +- [.github/workflows/publish.yaml:1-74](file://.github/workflows/publish.yaml#L1-L74) diff --git "a/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\351\241\271\347\233\256\344\273\213\347\273\215.md" "b/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\351\241\271\347\233\256\344\273\213\347\273\215.md" new file mode 100644 index 00000000..39e73329 --- /dev/null +++ "b/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\351\241\271\347\233\256\344\273\213\347\273\215.md" @@ -0,0 +1,441 @@ +# 项目介绍 + + +**本文引用的文件** +- [README.md](file://README.md) +- [README-zh_CN.md](file://README-zh_CN.md) +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [docs/app.py](file://docs/app.py) +- [frontend/antd/package.json](file://frontend/antd/package.json) +- [frontend/antdx/package.json](file://frontend/antdx/package.json) +- [frontend/pro/package.json](file://frontend/pro/package.json) + + +## 目录 + +1. [引言](#引言) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 引言 + +ModelScope Studio 是一个基于 Gradio 的第三方组件库，旨在为开发者提供更丰富、更灵活的界面构建能力。它通过整合 Ant Design 与 Ant Design X（Antd/Antdx）生态，以及自研的基础与专业组件体系，帮助用户在保持 Gradio 易用性的前提下，快速搭建美观、可维护的交互界面。 + +- 核心价值主张 + - 更强的页面布局与组件灵活性：相比 Gradio 原生组件，ModelScope Studio 更专注于页面布局与组件组合能力，适合追求视觉与交互体验的应用场景。 + - 与 Gradio 生态无缝衔接：既可独立使用，也可与现有 Gradio 组件混合使用，满足不同复杂度的界面需求。 + - 适配多平台部署：支持 ModelScope Studio、Hugging Face Space 等平台，提供一致的开发与发布体验。 + +- 设计理念 + - 以“组件即服务”为核心，提供可复用、可组合的 UI 组件。 + - 通过上下文与插槽机制，简化复杂布局与数据流管理。 + - 保持与 Gradio 的深度兼容，降低迁移成本与学习成本。 + +- 与 ModelScope 和 Gradio 生态的关系 + - 依托 Gradio 的 Blocks/Interface 渲染与事件系统，ModelScope Studio 将 Antd/Antdx 组件与专业组件以 Gradio 组件的形式暴露出来，使 Python 端可以直接声明式地组合前端组件。 + - 在 ModelScope Studio 平台与 Hugging Face Space 上，用户可直接运行示例与模板，快速验证界面效果。 + +- 发展背景与目标 + - 背景：Gradio 为模型应用提供了极简的界面入口，但在复杂布局与专业交互方面仍有提升空间；Ant Design 生态成熟但与 Gradio 的直接结合不够顺畅。 + - 目标：打造“轻量接入、强大组合”的组件库，覆盖从基础布局到专业交互的全栈 UI 需求，推动模型应用的界面工程化与标准化。 + +- 解决的核心问题 + - 页面布局复杂度高：通过布局组件与插槽机制，降低嵌套层级与逻辑复杂度。 + - 组件复用与一致性：统一的 Antd/Antdx 组件体系，保证跨模块的一致性与可维护性。 + - 多端部署一致性：提供稳定的 SSR/CSR 配置建议，避免在不同平台出现显示异常。 + +- 开源理念与社区贡献 + - 开源协议：采用 Apache-2.0，鼓励企业与个人在合规前提下使用与贡献。 + - 贡献方式：欢迎通过 Issues/PR 反馈问题、补充文档、完善组件或修复缺陷；遵循代码规范与变更流程。 + - 发布与版本：通过 Changesets 管理版本与变更日志，CI 流水线负责构建与发布。 + +- 未来规划 + - 扩展组件矩阵：持续完善 Antd/Antdx 与专业组件，覆盖更多业务场景。 + - 优化开发体验：改进文档站点、示例模板与调试工具链。 + - 平台适配：增强对 ModelScope Studio、Hugging Face Space 等平台的适配与最佳实践。 + +**章节来源** + +- [README.md:17-32](file://README.md#L17-L32) +- [README-zh_CN.md:17-32](file://README-zh_CN.md#L17-L32) + +## 项目结构 + +该项目采用前后端分离的多包工作区结构，后端 Python 包提供组件注册与版本信息，前端以 Svelte 实现各组件并与 Gradio 构建工具链集成；文档站点通过 Python 动态加载各组件示例与模板。 + +```mermaid +graph TB +subgraph "后端(Python)" +PY_PKG["Python 包
modelscope_studio"] +CMPTS["组件导出
components/__init__.py"] +ANTD_ALL["Antd 组件聚合
antd/components.py"] +VERSION["版本号
version.py"] +end +subgraph "前端(Svelte)" +FE_ANTD["@modelscope-studio/antd
antd/*"] +FE_ANTDX["@modelscope-studio/antdx
antdx/*"] +FE_PRO["@modelscope-studio/pro
pro/*"] +end +subgraph "文档与脚本" +DOCS_APP["文档站点入口
docs/app.py"] +PKG_JSON["根包配置
package.json"] +PYPROJ["Python 构建配置
pyproject.toml"] +end +PY_PKG --> CMPTS +CMPTS --> ANTD_ALL +PY_PKG --> VERSION +DOCS_APP --> FE_ANTD +DOCS_APP --> FE_ANTDX +DOCS_APP --> FE_PRO +PKG_JSON --> DOCS_APP +PYPROJ --> PY_PKG +``` + +**图表来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +**章节来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:1-257](file://pyproject.toml#L1-L257) + +## 核心组件 + +ModelScope Studio 的组件体系分为三大类： + +- 基础组件（base）：提供布局、渲染控制与上下文能力，如 Application、AutoLoading、Slot、Fragment、Each、Filter、Div、Span、Text、Markdown 等。 +- Ant Design 组件（antd）：覆盖 Antd 的通用、布局、导航、数据录入、数据展示、反馈等类别，包含大量子组件与组合形态。 +- Ant Design X 组件（antdx）：面向对话与协作场景的专业组件集合，如 Bubble、Conversations、Sender、ThoughtChain、Actions 等。 +- 专业组件（pro）：面向特定业务的高级组件，如 Chatbot、Monaco Editor、Multimodal Input、Web Sandbox 等。 + +这些组件通过统一的注册与导出机制在 Python 端暴露，便于在 Blocks 中按需组合使用。 + +**章节来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [docs/app.py:189-509](file://docs/app.py#L189-L509) + +## 架构总览 + +ModelScope Studio 的整体架构围绕“Python 组件定义 + Svelte 前端实现 + Gradio 渲染管线”展开。Python 端通过组件基类与上下文机制，将前端组件以 Gradio 组件的形式注入 Blocks；前端使用 Svelte 实现组件 UI，并通过 Gradio 的构建工具链进行打包与分发；文档站点动态加载各组件示例与模板，形成“开发—演示—发布”的闭环。 + +```mermaid +graph TB +subgraph "Python 层" +MC["ModelScopeComponent 基类
utils/dev/component.py"] +ML["ModelScopeLayoutComponent 基类
utils/dev/component.py"] +APP_CTX["AppContext
utils/dev/component.py"] +CMPTS_PY["组件注册
components/__init__.py"] +end +subgraph "前端层(Svelte)" +CMP_SVELTE["组件实现
frontend/antd/*
frontend/antdx/*
frontend/pro/*"] +end +subgraph "运行时" +GRADIO["Gradio 渲染管线"] +DOCS["文档站点
docs/app.py"] +end +MC --> GRADIO +ML --> GRADIO +APP_CTX --> MC +APP_CTX --> ML +CMPTS_PY --> MC +CMP_SVELTE --> GRADIO +DOCS --> CMPTS_PY +DOCS --> CMP_SVELTE +``` + +**图表来源** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [docs/app.py:1-595](file://docs/app.py#L1-L595) +- [frontend/antd/package.json:1-6](file://frontend/antd/package.json#L1-L6) +- [frontend/antdx/package.json:1-6](file://frontend/antdx/package.json#L1-L6) +- [frontend/pro/package.json:1-6](file://frontend/pro/package.json#L1-L6) + +## 详细组件分析 + +### 组件基类与上下文机制 + +ModelScope Studio 通过三类基类支撑组件体系： + +- ModelScopeComponent：面向数据型组件，具备值传递、事件绑定、渲染控制等能力。 +- ModelScopeLayoutComponent：面向布局型组件，支持布局标记与上下文切换。 +- ModelScopeDataLayoutComponent：兼具数据与布局特性，用于复杂容器组件。 + +这些基类统一了组件生命周期、属性注入与上下文关联，确保组件在 Blocks 中的行为一致。 + +```mermaid +classDiagram +class ModelScopeComponent { ++EVENTS ++skip_api ++__init__(...) ++elem_style ++as_item +} +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__(...) ++__init__(...) ++elem_style ++as_item +} +class ModelScopeDataLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__(...) ++__init__(...) ++preserved_by_key ++elem_style ++as_item +} +ModelScopeDataLayoutComponent <|-- ModelScopeComponent +ModelScopeLayoutComponent <|-- ModelScopeDataLayoutComponent +``` + +**图表来源** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +**章节来源** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +### Ant Design 组件聚合 + +Antd 组件通过集中导出文件统一暴露，涵盖通用、布局、导航、数据录入、数据展示、反馈等类别，便于在 Python 端按需导入与使用。 + +```mermaid +graph LR +ANTD_ALL["antd/components.py"] --> BUTTON["Button"] +ANTD_ALL --> INPUT["Input"] +ANTD_ALL --> FORM["Form"] +ANTD_ALL --> TABLE["Table"] +ANTD_ALL --> MODAL["Modal"] +ANTD_ALL --> LAYOUT["Layout"] +ANTD_ALL --> MENU["Menu"] +ANTD_ALL --> TREE["Tree"] +ANTD_ALL --> UPLOAD["Upload"] +ANTD_ALL --> PROGRESS["Progress"] +ANTD_ALL --> ALERT["Alert"] +ANTD_ALL --> DRAWER["Drawer"] +ANTD_ALL --> PAGINATION["Pagination"] +ANTD_ALL --> SPIN["Spin"] +ANTD_ALL --> MESSAGE["Message"] +ANTD_ALL --> NOTIFICATION["Notification"] +ANTD_ALL --> TYPGRAPHY["Typography"] +ANTD_ALL --> GRID["Grid"] +ANTD_ALL --> SPACE["Space"] +ANTD_ALL --> SPLITTER["Splitter"] +ANTD_ALL --> STATISTIC["Statistic"] +ANTD_ALL --> TOUR["Tour"] +ANTD_ALL --> WATERMARK["Watermark"] +ANTD_ALL --> QR_CODE["QRCode"] +ANTD_ALL --> CALENDAR["Calendar"] +ANTD_ALL --> CAROUSEL["Carousel"] +ANTD_ALL --> COLLAPSE["Collapse"] +ANTD_ALL --> DESCRIPTIONS["Descriptions"] +ANTD_ALL --> EMPTY["Empty"] +ANTD_ALL --> IMAGE["Image"] +ANTD_ALL --> LIST["List"] +ANTD_ALL --> POPOVER["Popover"] +ANTD_ALL --> SEGMENTED["Segmented"] +ANTD_ALL --> TIME_PICKER["TimePicker"] +ANTD_ALL --> TIMELINE["Timeline"] +ANTD_ALL --> TOOLTIP["Tooltip"] +ANTD_ALL --> TRANSFER["Transfer"] +ANTD_ALL --> TREE_SELECT["TreeSelect"] +ANTD_ALL --> SKELETON["Skeleton"] +ANTD_ALL --> SWITCH["Switch"] +ANTD_ALL --> SLIDER["Slider"] +ANTD_ALL --> SELECT["Select"] +ANTD_ALL --> RADIO["Radio"] +ANTD_ALL --> RATE["Rate"] +ANTD_ALL --> CHECKBOX["Checkbox"] +ANTD_ALL --> COLOR_PICKER["ColorPicker"] +ANTD_ALL --> DATE_PICKER["DatePicker"] +ANTD_ALL --> AUTO_COMPLETE["AutoComplete"] +ANTD_ALL --> CASCADER["Cascader"] +ANTD_ALL --> MENTIONS["Mentions"] +ANTD_ALL --> FLOAT_BUTTON["FloatButton"] +ANTD_ALL --> ICON["Icon"] +ANTD_ALL --> DIVIDER["Divider"] +ANTD_ALL --> DROPDOWN["Dropdown"] +ANTD_ALL --> BADGE["Badge"] +ANTD_ALL --> AVATAR["Avatar"] +ANTD_ALL --> RESULT["Result"] +ANTD_ALL --> POPCONFIRM["Popconfirm"] +``` + +**图表来源** + +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) + +**章节来源** + +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) + +### 文档站点与示例加载 + +文档站点通过动态导入各组件目录下的 app.py，聚合组件示例与说明，形成统一的导航与展示界面；同时支持布局模板与多语言环境切换。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Docs as "文档站点入口
docs/app.py" +participant Loader as "组件/模板加载器" +participant Site as "Site 渲染器" +Dev->>Docs : 启动文档站点 +Docs->>Loader : 扫描组件与模板目录 +Loader-->>Docs : 返回组件/模板元数据 +Docs->>Site : 组织菜单与文档映射 +Site-->>Dev : 渲染统一站点 +``` + +**图表来源** + +- [docs/app.py:19-61](file://docs/app.py#L19-L61) +- [docs/app.py:577-595](file://docs/app.py#L577-L595) + +**章节来源** + +- [docs/app.py:19-61](file://docs/app.py#L19-L61) +- [docs/app.py:577-595](file://docs/app.py#L577-L595) + +### 概念性概览 + +以下为概念性流程图，展示从组件声明到页面渲染的关键步骤，帮助初学者理解整体工作流。 + +```mermaid +flowchart TD +Start(["开始"]) --> Import["导入组件库与组件"] +Import --> Blocks["在 Blocks 中声明布局"] +Blocks --> Compose["组合基础/专业/Antd/Antdx 组件"] +Compose --> Render["Gradio 渲染管线生成页面"] +Render --> Deploy["部署到 ModelScope Studio/Hugging Face Space"] +Deploy --> End(["结束"]) +``` + +[此图为概念性流程图，不对应具体源码文件，故无图表来源] + +## 依赖分析 + +- 运行时依赖 + - Gradio：作为核心渲染与事件系统，ModelScope Studio 在其之上扩展组件能力。 +- 构建与开发依赖 + - Gradio CLI：提供组件构建与开发服务器功能。 + - TypeScript/Svelte：前端组件实现与类型检查。 + - Prettier/ESLint/Stylelint：代码风格与质量保障。 +- 发布与版本管理 + - Changesets：版本与变更日志管理。 + - CI 脚本：自动化构建、校验与发布。 + +```mermaid +graph TB +GR["Gradio(>=4.43.0)"] --> PY["Python 包
pyproject.toml"] +TS["TypeScript/Svelte"] --> FE["@modelscope-studio/* 前端包"] +ESLINT["ESLint"] --> FE +STYLE["Stylelint"] --> FE +PRETTIER["Prettier"] --> FE +CHANGES["Changesets"] --> PKG["package.json 脚本"] +CI["CI 脚本"] --> PKG +PY --> FE +FE --> DOCS["文档站点"] +``` + +**图表来源** + +- [pyproject.toml:26](file://pyproject.toml#L26) +- [package.json:8-25](file://package.json#L8-L25) + +**章节来源** + +- [pyproject.toml:26](file://pyproject.toml#L26) +- [package.json:8-25](file://package.json#L8-L25) + +## 性能考虑 + +- 组件懒加载与按需导入：优先按需导入所需组件，减少初始包体积。 +- 前端构建优化：利用 Gradio CLI 的构建能力与缓存策略，缩短二次构建时间。 +- 渲染并发与队列：在文档站点与示例中合理设置并发与队列大小，避免阻塞。 +- 平台差异：在 Hugging Face Space 使用时，注意 ssr_mode 参数配置，避免页面渲染异常。 + +[本节为通用指导，不涉及具体文件分析] + +## 故障排查指南 + +- Hugging Face Space 页面显示异常 + - 现象：页面空白或组件未正确渲染。 + - 处理：在 demo.launch() 中添加 ssr_mode=False 参数。 + - 参考：[README.md:32](file://README.md#L32)、[README-zh_CN.md:32](file://README-zh_CN.md#L32)、[docs/app.py:594](file://docs/app.py#L594) + +- 组件导入路径错误 + - 现象：找不到模块或组件。 + - 处理：确认组件命名空间与导入路径是否匹配，例如 modelscope_studio.components.antd、modelscope_studio.components.base 等。 + - 参考：[backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) + +- 文档站点开发模式 + - 现象：本地开发无法热更新或示例不显示。 + - 处理：使用 gradio cc dev docs/app.py 启动开发服务器，并确保 docs 目录存在对应 app.py。 + - 参考：[README.md:96-100](file://README.md#L96-L100)、[docs/app.py:10](file://docs/app.py#L10) + +**章节来源** + +- [README.md:32](file://README.md#L32) +- [README-zh_CN.md:32](file://README-zh_CN.md#L32) +- [docs/app.py:594](file://docs/app.py#L594) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [README.md:96-100](file://README.md#L96-L100) +- [docs/app.py:10](file://docs/app.py#L10) + +## 结论 + +ModelScope Studio 以 Gradio 为基础，融合 Ant Design 与 Ant Design X 生态，构建了覆盖基础、专业与 Antd/Antdx 的完整组件体系。它在保持 Gradio 易用性的同时，显著提升了页面布局与组件组合能力，适用于从原型到生产的各类模型应用界面开发。通过完善的文档站点、版本管理与平台适配，项目为初学者与资深开发者都提供了清晰的上手路径与稳定的技术支撑。 + +[本节为总结性内容，不涉及具体文件分析] + +## 附录 + +- 快速开始 + - 安装：pip install modelscope_studio + - 示例：在 Blocks 中组合 ms.Application、antd.ConfigProvider、antd.DatePicker 等组件。 + - 参考：[README.md:38-57](file://README.md#L38-L57)、[README-zh_CN.md:38-57](file://README-zh_CN.md#L38-L57) + +- 版本与发布 + - 当前版本：2.0.0 + - 发布脚本：build、dev、version、ci:\* 等 + - 参考：[backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2)、[package.json:8-25](file://package.json#L8-L25) + +**章节来源** + +- [README.md:38-57](file://README.md#L38-L57) +- [README-zh_CN.md:38-57](file://README-zh_CN.md#L38-L57) +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [package.json:8-25](file://package.json#L8-L25) diff --git "a/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\351\241\271\347\233\256\346\246\202\350\277\260.md" "b/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\351\241\271\347\233\256\346\246\202\350\277\260.md" new file mode 100644 index 00000000..ed8ec4b6 --- /dev/null +++ "b/.wiki/zh/\351\241\271\347\233\256\346\246\202\350\277\260/\351\241\271\347\233\256\346\246\202\350\277\260.md" @@ -0,0 +1,432 @@ +# 项目概述 + + +**本文引用的文件** +- [README.md](file://README.md) +- [README-zh_CN.md](file://README-zh_CN.md) +- [package.json](file://package.json) +- [pyproject.toml](file://pyproject.toml) +- [backend/modelscope_studio/version.py](file://backend/modelscope_studio/version.py) +- [backend/modelscope_studio/__init__.py](file://backend/modelscope_studio/__init__.py) +- [backend/modelscope_studio/components/__init__.py](file://backend/modelscope_studio/components/__init__.py) +- [backend/modelscope_studio/components/antd/components.py](file://backend/modelscope_studio/components/antd/components.py) +- [backend/modelscope_studio/components/antdx/components.py](file://backend/modelscope_studio/components/antdx/components.py) +- [backend/modelscope_studio/utils/dev/component.py](file://backend/modelscope_studio/utils/dev/component.py) +- [backend/modelscope_studio/utils/dev/app_context.py](file://backend/modelscope_studio/utils/dev/app_context.py) +- [frontend/package.json](file://frontend/package.json) +- [frontend/defineConfig.js](file://frontend/defineConfig.js) +- [frontend/plugin.js](file://frontend/plugin.js) +- [docs/README.md](file://docs/README.md) +- [docs/app.py](file://docs/app.py) +- [docs/FAQ.md](file://docs/FAQ.md) + + +## 目录 + +1. [引言](#引言) +2. [项目结构](#项目结构) +3. [核心组件](#核心组件) +4. [架构总览](#架构总览) +5. [详细组件分析](#详细组件分析) +6. [依赖分析](#依赖分析) +7. [性能考虑](#性能考虑) +8. [故障排查指南](#故障排查指南) +9. [结论](#结论) +10. [附录](#附录) + +## 引言 + +ModelScope Studio 是一个基于 Gradio 的第三方组件库，旨在为开发者提供更定制化的界面搭建能力与更丰富的组件使用形态。项目同时支持 Ant Design 与 Ant Design X 两大 UI 生态，并通过统一的 Python 组件接口与前端 Svelte/React 技术栈实现跨框架的组件桥接与渲染。 + +- 核心目标 + - 提升页面布局与组件灵活性，帮助构建更美观的用户界面 + - 与 Gradio 原生组件良好兼容，满足从简单到复杂的多种交互需求 + - 通过 Application 上下文与 AutoLoading 加载反馈机制，提升开发体验与用户体验 + +- 主要特性 + - 三层组件体系：基础组件（base）、Ant Design 组件（antd）、Ant Design X 组件（antdx）、专业组件（pro） + - 前端采用 Vite + Svelte + React 预处理桥接，配合自定义 Vite 插件进行模块别名与外部化处理 + - 支持多语言站点与文档系统，覆盖中文、英文、日文 + +- 应用场景 + - 快速搭建数据可视化与交互式演示页面 + - 在 Hugging Face Space 或 ModelScope Studio 平台部署交互式应用 + - 需要复杂表单、表格、图表与对话式交互的工作流 + +- 设计理念 + - 以 Gradio Blocks 为宿主，通过 Python 组件封装前端 Svelte 组件，实现“Python 逻辑 + 可定制 UI”的一体化开发 + - 通过 ConfigProvider、Application、AutoLoading 等上下文组件，统一主题、生命周期与加载状态管理 + +- 与 Ant Design/Ant Design X 的关系 + - antd 组件直接映射至 Ant Design 的组件生态，提供更丰富的布局与交互能力 + - antdx 组件聚焦对话式体验与知识工作流，如 Bubble、Sender、ThoughtChain 等 + - pro 组件提供专业级交互能力，如 Chatbot、Monaco Editor、Web Sandbox 等 + +- 技术架构 + - 后端：Python 包含组件导出与版本信息，组件注册集中在 components 子包 + - 前端：Svelte 组件树 + React 预处理桥接，Vite 构建与插件注入全局变量 + - 文档：基于 docs 站点与动态加载各组件示例，支持多语言与布局模板 + +- 发展历程与版本 + - 当前版本：2.0.0 + - 许可证：Apache-2.0 + - 依赖范围：Gradio >= 4.43.0 且 <= 6.8.0 + +- 使用建议 + - 在 Hugging Face Space 部署时需设置 ssr_mode=False + - 全局引入 AutoLoading 以获得一致的加载反馈 + - 如需迁移旧版组件，可在外层包裹 ms.Application 即可继续使用 + +**章节来源** + +- [README.md:17-101](file://README.md#L17-L101) +- [README-zh_CN.md:17-101](file://README-zh_CN.md#L17-L101) +- [docs/README.md:32-75](file://docs/README.md#L32-L75) +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) + +## 项目结构 + +项目采用前后端分离与多包协作的组织方式： + +- backend/modelscope_studio：Python 后端组件与打包配置 +- frontend：前端组件（Svelte/React）与构建配置 +- docs：文档站点与示例应用 +- config/scripts：变更集、发布脚本与 Lint 配置 + +```mermaid +graph TB +subgraph "后端" +PY["Python 包
modelscope_studio"] +CMP["components 子包
antd/antdx/base/pro"] +VER["version.py
版本号"] +end +subgraph "前端" +FE_PKG["frontend/package.json
依赖与脚本"] +FE_CFG["defineConfig.js
Vite 配置"] +FE_PLG["plugin.js
Vite 插件"] +FE_ANTD["antd/*
Svelte 组件"] +FE_ANTDX["antdx/*
Svelte 组件"] +FE_BASE["base/*
Svelte 组件"] +FE_PRO["pro/*
Svelte 组件"] +end +subgraph "文档" +DOCS_APP["docs/app.py
站点入口"] +DOCS_MD["docs/README.md
文档说明"] +DOCS_FAQ["docs/FAQ.md
常见问题"] +end +PY --> CMP +PY --> VER +FE_PKG --> FE_ANTD +FE_PKG --> FE_ANTDX +FE_PKG --> FE_BASE +FE_PKG --> FE_PRO +FE_CFG --> FE_PLG +DOCS_APP --> CMP +DOCS_APP --> DOCS_MD +DOCS_APP --> DOCS_FAQ +``` + +**图示来源** + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [docs/app.py:1-200](file://docs/app.py#L1-L200) +- [docs/README.md:1-75](file://docs/README.md#L1-L75) +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) + +**章节来源** + +- [backend/modelscope_studio/**init**.py:1-3](file://backend/modelscope_studio/__init__.py#L1-L3) +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:1-200](file://docs/app.py#L1-L200) + +## 核心组件 + +- 组件分类 + - antd：覆盖 Ant Design 的通用、布局、导航、数据录入、数据展示、反馈等全量组件族 + - antdx：面向对话式体验的组件族，如 Bubble、Sender、ThoughtChain、Prompts 等 + - base：基础布局与渲染辅助组件，如 Application、AutoLoading、Slot、Fragment、Each、Filter、Markdown 等 + - pro：专业交互组件，如 Chatbot、Monaco Editor、Web Sandbox、Multimodal Input 等 + +- 导出与聚合 + - 后端 components/**init**.py 将 antd、antdx、base、pro 的组件集中导出，便于按命名空间导入使用 + - antd/components.py 与 antdx/components.py 分别列出各子模块组件类，形成统一的 Python API + +- 关键上下文组件 + - Application：应用级上下文，用于建立组件树与生命周期管理 + - AutoLoading：自动加载反馈组件，确保交互操作具备一致的加载提示 + - ConfigProvider：主题与国际化配置提供者，贯穿 antd 组件树 + +- 开发期组件基类 + - ModelScopeComponent/ModelScopeLayoutComponent/ModelScopeDataLayoutComponent：为组件提供统一的生命周期、插槽与渲染控制 + +**章节来源** + +- [backend/modelscope_studio/components/**init**.py:1-5](file://backend/modelscope_studio/components/__init__.py#L1-L5) +- [backend/modelscope_studio/components/antd/components.py:1-144](file://backend/modelscope_studio/components/antd/components.py#L1-L144) +- [backend/modelscope_studio/components/antdx/components.py:1-40](file://backend/modelscope_studio/components/antdx/components.py#L1-L40) +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +## 架构总览 + +整体架构围绕“Python 组件 → 前端 Svelte 组件 → Gradio 渲染”展开，前端通过 Vite 插件将 React/antd/antdx 等依赖映射为全局变量，减少打包体积并提升加载效率。 + +```mermaid +graph TB +PY_API["Python 组件 API
components.antd / antdx / base / pro"] +APP_CTX["Application 上下文
AppContext"] +AUTOLOAD["AutoLoading
加载反馈"] +CFG["ConfigProvider
主题/国际化"] +subgraph "前端构建" +VITE["Vite 构建"] +PLG["ModelScopeStudioVitePlugin
外部化与别名"] +REACT["React 全局映射"] +ANTD["antd/antdx 全局映射"] +end +subgraph "组件实现" +SVELTE["Svelte 组件树"] +UTILS["工具函数与上下文"] +end +PY_API --> VITE +APP_CTX --> PY_API +AUTOLOAD --> PY_API +CFG --> PY_API +VITE --> PLG +PLG --> REACT +PLG --> ANTD +REACT --> SVELTE +ANTD --> SVELTE +UTILS --> SVELTE +``` + +**图示来源** + +- [backend/modelscope_studio/utils/dev/app_context.py:1-25](file://backend/modelscope_studio/utils/dev/app_context.py#L1-L25) +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) + +## 详细组件分析 + +### 组件类层次结构 + +以下类图展示了后端组件基类与其典型派生组件的关系，体现统一的生命周期与渲染策略。 + +```mermaid +classDiagram +class Component +class BlockContext +class ComponentMeta +class ModelScopeComponent { ++EVENTS ++skip_api ++__init__(...) +} +class ModelScopeLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__(...) ++__init__(...) +} +class ModelScopeDataLayoutComponent { ++EVENTS ++SLOTS ++skip_api ++__exit__(...) ++__init__(...) +} +ModelScopeComponent --|> Component +ModelScopeLayoutComponent --|> BlockContext +ModelScopeLayoutComponent --|> Component +ModelScopeDataLayoutComponent --|> ModelScopeComponent +ModelScopeDataLayoutComponent --|> BlockContext +``` + +**图示来源** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +**章节来源** + +- [backend/modelscope_studio/utils/dev/component.py:11-169](file://backend/modelscope_studio/utils/dev/component.py#L11-L169) + +### 文档站点与示例加载流程 + +文档站点通过动态扫描 docs/components 下的各组件 app.py，聚合生成侧边栏与文档内容；同时支持布局模板与多语言切换。 + +```mermaid +sequenceDiagram +participant Dev as "开发者" +participant Docs as "docs/app.py" +participant FS as "文件系统" +participant Comp as "组件 app.py" +participant Site as "站点渲染" +Dev->>Docs : 启动 gradio cc dev docs/app.py +Docs->>FS : 扫描 layout_templates 与 components +FS-->>Docs : 返回组件目录列表 +loop 遍历组件 +Docs->>Comp : 动态导入 app.py +Comp-->>Docs : 返回 docs 字典 +end +Docs->>Site : 渲染菜单与文档内容 +Site-->>Dev : 展示组件示例与说明 +``` + +**图示来源** + +- [docs/app.py:19-61](file://docs/app.py#L19-L61) + +**章节来源** + +- [docs/app.py:19-61](file://docs/app.py#L19-L61) + +### 前端构建与模块外部化 + +前端通过自定义 Vite 插件将 React、antd、antdx 等依赖映射为全局变量，避免重复打包，同时在构建阶段进行外部化处理，减少产物体积。 + +```mermaid +flowchart TD +Start(["开始"]) --> ReadCfg["读取 defineConfig.js"] +ReadCfg --> InitPlugin["初始化 ModelScopeStudioVitePlugin"] +InitPlugin --> Build{"构建命令？"} +Build --> |是| ExtDeps["收集全局映射依赖"] +Build --> |否| Alias["配置别名与解析规则"] +ExtDeps --> RollupExt["Rollup 外部化"] +Alias --> Transform["遍历 AST 替换导入语句"] +Transform --> Emit["输出转换后的代码"] +RollupExt --> Emit +Emit --> End(["结束"]) +``` + +**图示来源** + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:41-168](file://frontend/plugin.js#L41-L168) + +**章节来源** + +- [frontend/defineConfig.js:1-19](file://frontend/defineConfig.js#L1-L19) +- [frontend/plugin.js:1-168](file://frontend/plugin.js#L1-L168) + +### 组件命名空间与导入约定 + +- Python 端通过 modelscope_studio.components.antd、antdx、base、pro 导入对应组件 +- 建议在应用最外层包裹 ms.Application，以启用上下文与生命周期管理 +- 若使用旧版 legacy 组件，同样可通过 ms.Application 包裹继续使用 + +**章节来源** + +- [README.md:49-78](file://README.md#L49-L78) +- [docs/README.md:64-75](file://docs/README.md#L64-L75) + +## 依赖分析 + +- Python 侧 + - 依赖：Gradio（版本范围约束） + - 可选依赖：构建与发布相关工具 + - 打包：通过 hatchling 构建，artifact 列表包含大量组件模板资源 + +- 前端侧 + - 依赖：antd、@ant-design/x、@gradio/\*、monaco-editor、svelte、react 等 + - 构建：Vite + React-SWC + Less，插件负责外部化与别名替换 + +- 文档与站点 + - 基于 docs/app.py 动态加载组件示例，支持多语言与布局模板 + +```mermaid +graph LR +PY["pyproject.toml
依赖与打包"] +FE["frontend/package.json
依赖与脚本"] +DOC["docs/app.py
示例加载"] +GR["Gradio
版本约束"] +PY --> GR +FE --> ANTD["antd"] +FE --> REACT["react"] +FE --> SVLT["svelte"] +DOC --> PY +DOC --> FE +``` + +**图示来源** + +- [pyproject.toml:26](file://pyproject.toml#L26) +- [frontend/package.json:8-40](file://frontend/package.json#L8-L40) +- [docs/app.py:19-61](file://docs/app.py#L19-L61) + +**章节来源** + +- [pyproject.toml:9-43](file://pyproject.toml#L9-L43) +- [frontend/package.json:1-59](file://frontend/package.json#L1-L59) +- [docs/app.py:19-61](file://docs/app.py#L19-L61) + +## 性能考虑 + +- 前端外部化与别名 + - 通过 Vite 插件将 React、antd、antdx 等映射为全局变量，减少重复打包与体积 + - 构建阶段 Rollup 外部化，进一步降低产物大小 + +- 组件加载反馈 + - AutoLoading 提供统一的加载占位，改善交互延迟带来的感知性能 + - 建议在全局至少引入一次 AutoLoading，避免 Gradio 默认加载状态缺失 + +- 文档与示例 + - docs/app.py 采用按需动态导入组件 app.py，减少初始加载压力 + +**章节来源** + +- [frontend/plugin.js:41-168](file://frontend/plugin.js#L41-L168) +- [docs/FAQ.md:7-20](file://docs/FAQ.md#L7-L20) +- [docs/app.py:19-61](file://docs/app.py#L19-L61) + +## 故障排查指南 + +- Hugging Face Space 页面不显示或样式异常 + - 解决方案：在 demo.launch() 中添加 ssr_mode=False 参数 + +- 操作响应慢或无反馈 + - 原因：组件独立的加载反馈机制与 Gradio 前后端通信导致的等待时间 + - 解决方案：全局引入 AutoLoading 组件，确保加载状态可见 + +- 缺少 Application 上下文警告 + - 现象：未在最外层包裹 ms.Application 时会触发警告 + - 解决方案：在外层包裹 ms.Application + +**章节来源** + +- [docs/FAQ.md:1-20](file://docs/FAQ.md#L1-L20) +- [backend/modelscope_studio/utils/dev/app_context.py:16-21](file://backend/modelscope_studio/utils/dev/app_context.py#L16-L21) +- [README.md:32](file://README.md#L32) + +## 结论 + +ModelScope Studio 以 Gradio 为核心，结合 Ant Design 与 Ant Design X 的丰富组件生态，提供了从基础布局到专业交互的一体化解决方案。通过统一的 Python 组件 API、前端 Svelte/React 桥接与 Vite 插件优化，项目在易用性与性能之间取得平衡。对于初学者，建议从基础组件与 Application/AutoLoading 入手；对于有经验的开发者，可深入 antdx 与 pro 组件，快速构建对话式与专业级交互应用。 + +## 附录 + +- 版本与许可证 + - 版本：2.0.0 + - 许可证：Apache-2.0 + - 作者：ModelScope team + +- 安装与快速开始 + - pip 安装 modelscope_studio + - 在 Blocks 中使用 modelscope_studio.components.antd 与 modelscope_studio.components.base + +- 开发与贡献 + - 后端安装：pip install -e '.' + - 前端安装：pnpm install + - 构建：pnpm build + - 启动文档：gradio cc dev docs/app.py + +**章节来源** + +- [backend/modelscope_studio/version.py:1-2](file://backend/modelscope_studio/version.py#L1-L2) +- [package.json:1-55](file://package.json#L1-L55) +- [pyproject.toml:9-43](file://pyproject.toml#L9-L43) +- [README.md:38-101](file://README.md#L38-L101) +- [README-zh_CN.md:38-101](file://README-zh_CN.md#L38-L101) diff --git a/CHANGELOG.md b/CHANGELOG.md index 998bcfb8..4a2620c6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # modelscope_studio +## 2.0.0-beta.1 + +### Features + +- [`e009cd0`](https://github.com/modelscope/modelscope-studio/commit/e009cd0408d4505f4105e494af192c6f832fa48c) - complete new features of antd & antdx. Thanks [@Col0ring](https://github.com/Col0ring)! + +## 2.0.0-beta.0 + +### Misc Changes + +- [`26ea248`](https://github.com/modelscope/modelscope-studio/commit/26ea2485990098ea60e95ff8b3e71dad713a3aba) - migrate to Gradio 6.0, Ant Design 6.0, Ant Design X 2.0. Thanks [@Col0ring](https://github.com/Col0ring)! + ## 1.6.1 ### Features diff --git a/README-zh_CN.md b/README-zh_CN.md index 162d52bd..32d6c213 100644 --- a/README-zh_CN.md +++ b/README-zh_CN.md @@ -33,7 +33,9 @@ ## 依赖 -- Gradio >= 4.43.0 +- Gradio >= 6.0.0 + +> 注意：您的 Gradio 版本必须`<=6.8.0`，[为什么？](https://github.com/gradio-app/gradio/issues/13131) ## 安装 @@ -41,6 +43,12 @@ pip install modelscope_studio ``` +如果您需要使用`4.43.0 <= Gradio < 6.0.0`，请使用 1.x 版本： + +```sh +pip install modelscope_studio~=1.0 +``` + ## 快速开始 ```python @@ -61,21 +69,9 @@ demo.queue().launch() - ModelScope: [中文](https://modelscope.cn/studios/modelscope/modelscope-studio) - Hugging Face: [English](https://huggingface.co/spaces/modelscope/modelscope-studio) -## 迁移到 1.0 - -如果您在之前使用了`modelscope_studio`的组件，并且想要在新版本中继续使用。不需要对原有组件做任何修改，只需要在外层引入`ms.Application`即可。 +## Wiki -```python -import gradio as gr -import modelscope_studio.components.base as ms -import modelscope_studio.components.legacy as mgr - -with gr.Blocks() as demo: - with ms.Application(): - mgr.Chatbot() - -demo.launch() -``` +[链接](./.wiki/zh) ## 开发 diff --git a/README.md b/README.md index 0e894a9b..dd6156a0 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,9 @@ However, when your application needs Gradio to handle more built-in data on the ## Dependencies -- Gradio >= 4.43.0 +- Gradio >= 6.0.0 + +> Note: Your Gradio version must`<=6.8.0`, [why?](https://github.com/gradio-app/gradio/issues/13131) ## Installation @@ -41,6 +43,12 @@ However, when your application needs Gradio to handle more built-in data on the pip install modelscope_studio ``` +If you need to use `4.43.0 <= Gradio < 6.0.0`, please use 1.x version: + +```sh +pip install modelscope_studio~=1.0 +``` + ## Quick Start ```python @@ -61,21 +69,9 @@ demo.queue().launch() - ModelScope: [中文](https://modelscope.cn/studios/modelscope/modelscope-studio) - Hugging Face: [English](https://huggingface.co/spaces/modelscope/modelscope-studio) -## Migration to 1.0 - -If you have used the `modelscope_studio` component before and want to continue using it in the new version, you do not need to make any changes to the original component, just import `ms.Application` in the outer layer. +## Wiki -```python -import gradio as gr -import modelscope_studio.components.base as ms -import modelscope_studio.components.legacy as mgr - -with gr.Blocks() as demo: - with ms.Application(): - mgr.Chatbot() - -demo.launch() -``` +[Link](./.wiki/en) ## Development diff --git a/backend/modelscope_studio/__init__.py b/backend/modelscope_studio/__init__.py index 7bcd44fb..9b7ef04e 100644 --- a/backend/modelscope_studio/__init__.py +++ b/backend/modelscope_studio/__init__.py @@ -1,3 +1,2 @@ from .components import * -from .external import load from .version import __version__ diff --git a/backend/modelscope_studio/components/__init__.py b/backend/modelscope_studio/components/__init__.py index aafcf6e1..77949fda 100644 --- a/backend/modelscope_studio/components/__init__.py +++ b/backend/modelscope_studio/components/__init__.py @@ -1,5 +1,4 @@ from .antd.components import * from .antdx.components import * from .base import * -from .legacy.components import * from .pro.components import * diff --git a/backend/modelscope_studio/components/antd/__init__.py b/backend/modelscope_studio/components/antd/__init__.py index 89ac0cd6..e4ade5ad 100644 --- a/backend/modelscope_studio/components/antd/__init__.py +++ b/backend/modelscope_studio/components/antd/__init__.py @@ -70,6 +70,8 @@ from .list import AntdList as List from .list.item import AntdListItem as ListItem from .list.item.meta import AntdListItemMeta as ListItemMeta +from .masonry import AntdMasonry as Masonry +from .masonry.item import AntdMasonryItem as MasonryItem from .mentions import AntdMentions as Mentions from .mentions.option import AntdMentionsOption as MentionsOption from .menu import AntdMenu as Menu @@ -123,6 +125,10 @@ from .tabs.item import AntdTabsItem as TabsItem from .tag import AntdTag as Tag from .tag.checkable_tag import AntdTagCheckableTag as TagCheckableTag +from .tag.checkable_tag_group import \ + AntdTagCheckableTagGroup as TagCheckableTagGroup +from .tag.checkable_tag_group.option import \ + AntdTagCheckableTagGroupOption as TagCheckableTagGroupOption from .time_picker import AntdTimePicker as TimePicker from .time_picker.range_picker import \ AntdTimePickerRangePicker as TimePickerRangePicker diff --git a/backend/modelscope_studio/components/antd/affix/__init__.py b/backend/modelscope_studio/components/antd/affix/__init__.py index 6ae92694..f6270717 100644 --- a/backend/modelscope_studio/components/antd/affix/__init__.py +++ b/backend/modelscope_studio/components/antd/affix/__init__.py @@ -27,12 +27,14 @@ class AntdAffix(ModelScopeLayoutComponent): def __init__( self, - props: dict | None = None, + additional_props: dict | None = None, *, offset_bottom: int | float | None = None, offset_top: int | float | None = None, get_target: str | None = None, root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -55,7 +57,9 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.offset_bottom = offset_bottom self.offset_top = offset_top self.get_target = get_target diff --git a/backend/modelscope_studio/components/antd/alert/__init__.py b/backend/modelscope_studio/components/antd/alert/__init__.py index a57562f0..fe3df16f 100644 --- a/backend/modelscope_studio/components/antd/alert/__init__.py +++ b/backend/modelscope_studio/components/antd/alert/__init__.py @@ -16,7 +16,13 @@ class AntdAlert(ModelScopeLayoutComponent): EVENTS = [ EventListener("close", callback=lambda block: block._internal.update( - bind_close_event=True)) + bind_close_event=True)), + EventListener("click", + callback=lambda block: block._internal.update( + bind_click_event=True)), + EventListener("closable_close", + callback=lambda block: block._internal.update( + bind_closable_close_event=True)) ] # supported slots @@ -24,7 +30,7 @@ class AntdAlert(ModelScopeLayoutComponent): def __init__( self, - props: dict | None = None, + additional_props: dict | None = None, *, action: str | None = None, after_close: str | None = None, @@ -36,6 +42,8 @@ def __init__( show_icon: bool | None = None, type: Literal['success', 'info', 'warning', 'error'] | None = None, root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -52,7 +60,9 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.action = action self.after_close = after_close self.banner = banner diff --git a/backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py b/backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py index a7a9f711..abf3d4bd 100644 --- a/backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py +++ b/backend/modelscope_studio/components/antd/alert/error_boundary/__init__.py @@ -22,11 +22,13 @@ class AntdAlertErrorBoundary(ModelScopeLayoutComponent): def __init__( self, - props: dict | None = None, + additional_props: dict | None = None, *, description: str | None = None, message: str | None = None, root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -43,7 +45,9 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.description = description self.message = message self.root_class_name = root_class_name diff --git a/backend/modelscope_studio/components/antd/anchor/__init__.py b/backend/modelscope_studio/components/antd/anchor/__init__.py index be357fae..241c3dfc 100644 --- a/backend/modelscope_studio/components/antd/anchor/__init__.py +++ b/backend/modelscope_studio/components/antd/anchor/__init__.py @@ -37,7 +37,7 @@ class AntdAnchor(ModelScopeLayoutComponent): def __init__( self, - props: dict | None = None, + additional_props: dict | None = None, *, affix: bool | dict = True, bounds: int | float = 5, @@ -50,6 +50,8 @@ def __init__( direction: Literal['vertical', 'horizontal'] = 'vertical', replace: bool | None = None, root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -79,7 +81,9 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.affix = affix self.bounds = bounds self.get_container = get_container diff --git a/backend/modelscope_studio/components/antd/anchor/item/__init__.py b/backend/modelscope_studio/components/antd/anchor/item/__init__.py index d4df5b3d..e44b7a65 100644 --- a/backend/modelscope_studio/components/antd/anchor/item/__init__.py +++ b/backend/modelscope_studio/components/antd/anchor/item/__init__.py @@ -20,7 +20,7 @@ class AntdAnchorItem(ModelScopeLayoutComponent): def __init__( self, title: str | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, key: str | None = None, replace: bool | None = None, @@ -50,7 +50,7 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.additional_props = additional_props self.title = title self.key = key self.replace = replace diff --git a/backend/modelscope_studio/components/antd/auto_complete/__init__.py b/backend/modelscope_studio/components/antd/auto_complete/__init__.py index 590f518b..a451aedb 100644 --- a/backend/modelscope_studio/components/antd/auto_complete/__init__.py +++ b/backend/modelscope_studio/components/antd/auto_complete/__init__.py @@ -40,6 +40,9 @@ class AntdAutoComplete(ModelScopeDataLayoutComponent): EventListener("popup_visible_change", callback=lambda block: block._internal.update( bind_popupVisibleChange_event=True)), + EventListener("show_search_search", + callback=lambda block: block._internal.update( + bind_showSearch_search_event=True)), ] # supported slots @@ -51,7 +54,7 @@ class AntdAutoComplete(ModelScopeDataLayoutComponent): def __init__( self, value: str | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, allow_clear: bool | dict = False, auto_focus: bool | None = None, @@ -76,8 +79,9 @@ def __init__( status: Literal['error', 'warning'] | None = None, variant: Literal['outlined', 'borderless', 'filled'] | None = None, - class_names: dict | None = None, - styles: dict | None = None, + show_search: bool | dict | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, root_class_name: str | None = None, as_item: str | None = None, _internal: None = None, @@ -96,7 +100,7 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.additional_props = additional_props self.allow_clear = allow_clear self.auto_focus = auto_focus self.backfill = backfill @@ -118,6 +122,7 @@ def __init__( self.variant = variant self.placement = placement self.size = size + self.show_search = show_search self.class_names = class_names self.styles = styles self.root_class_name = root_class_name diff --git a/backend/modelscope_studio/components/antd/auto_complete/option/__init__.py b/backend/modelscope_studio/components/antd/auto_complete/option/__init__.py index 01e19432..5b6cd7ec 100644 --- a/backend/modelscope_studio/components/antd/auto_complete/option/__init__.py +++ b/backend/modelscope_studio/components/antd/auto_complete/option/__init__.py @@ -19,7 +19,7 @@ def __init__( self, value: str | None = None, label: str | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, as_item: str | None = None, _internal: None = None, @@ -37,7 +37,7 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.additional_props = additional_props self.value = value self.label = label diff --git a/backend/modelscope_studio/components/antd/avatar/__init__.py b/backend/modelscope_studio/components/antd/avatar/__init__.py index a6d60579..bde4114a 100644 --- a/backend/modelscope_studio/components/antd/avatar/__init__.py +++ b/backend/modelscope_studio/components/antd/avatar/__init__.py @@ -33,7 +33,7 @@ class AntdAvatar(ModelScopeDataLayoutComponent): def __init__( self, value: str | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, alt: str | None = None, gap: int | None = None, @@ -46,6 +46,8 @@ def __init__( cross_origin: Literal['anonymous', 'use-credentials', ''] | None = None, root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -63,6 +65,8 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) + self.class_names = class_names + self.styles = styles self.alt = alt self.gap = gap self.icon = icon @@ -72,7 +76,7 @@ def __init__( self.draggable = draggable self.cross_origin = cross_origin self.root_class_name = root_class_name - self.props = props + self.additional_props = additional_props FRONTEND_DIR = resolve_frontend_dir("avatar") diff --git a/backend/modelscope_studio/components/antd/avatar/group/__init__.py b/backend/modelscope_studio/components/antd/avatar/group/__init__.py index 87ebe0bc..a3b6e3b7 100644 --- a/backend/modelscope_studio/components/antd/avatar/group/__init__.py +++ b/backend/modelscope_studio/components/antd/avatar/group/__init__.py @@ -15,13 +15,15 @@ class AntdAvatarGroup(ModelScopeLayoutComponent): def __init__( self, - props: dict | None = None, + additional_props: dict | None = None, *, max: dict | None = None, size: int | Literal['large', 'small', 'default'] | dict | None = None, shape: Literal['circle', 'square'] | None = None, root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -38,7 +40,9 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.max = max self.size = size self.shape = shape diff --git a/backend/modelscope_studio/components/antd/badge/__init__.py b/backend/modelscope_studio/components/antd/badge/__init__.py index a67af5fe..3129a490 100644 --- a/backend/modelscope_studio/components/antd/badge/__init__.py +++ b/backend/modelscope_studio/components/antd/badge/__init__.py @@ -20,10 +20,10 @@ class AntdBadge(ModelScopeLayoutComponent): def __init__( self, count: int | float | str | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, color: str | None = None, - class_names: dict | None = None, + class_names: dict | str | None = None, dot: bool | None = None, offset: tuple[int | float, int | float] | None = None, overflow_count: int = 99, @@ -33,7 +33,7 @@ def __init__( 'warning'] | None = None, text: str | None = None, title: str | None = None, - styles: dict | None = None, + styles: dict | str | None = None, root_class_name: str | None = None, as_item: str | None = None, _internal: None = None, @@ -64,7 +64,7 @@ def __init__( self.title = title self.styles = styles self.root_class_name = root_class_name - self.props = props + self.additional_props = additional_props FRONTEND_DIR = resolve_frontend_dir("badge") diff --git a/backend/modelscope_studio/components/antd/badge/ribbon/__init__.py b/backend/modelscope_studio/components/antd/badge/ribbon/__init__.py index b4c1b0a4..f53f4b96 100644 --- a/backend/modelscope_studio/components/antd/badge/ribbon/__init__.py +++ b/backend/modelscope_studio/components/antd/badge/ribbon/__init__.py @@ -14,11 +14,13 @@ class AntdBadgeRibbon(ModelScopeLayoutComponent): def __init__( self, text: str | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, color: str | None = None, placement: Literal['start', 'end'] = 'end', root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -35,7 +37,9 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.color = color self.placement = placement self.root_class_name = root_class_name diff --git a/backend/modelscope_studio/components/antd/breadcrumb/__init__.py b/backend/modelscope_studio/components/antd/breadcrumb/__init__.py index 443570b1..64842e5a 100644 --- a/backend/modelscope_studio/components/antd/breadcrumb/__init__.py +++ b/backend/modelscope_studio/components/antd/breadcrumb/__init__.py @@ -15,17 +15,20 @@ class AntdBreadcrumb(ModelScopeLayoutComponent): EVENTS = [] # supported slots - SLOTS = ['separator', 'itemRender', 'items'] + SLOTS = ['separator', 'itemRender', 'items', 'dropdownIcon'] def __init__( self, - props: dict | None = None, + additional_props: dict | None = None, *, item_render: str | None = None, params: dict | None = None, items: list[dict] | None = None, separator: str | None = None, + dropdown_icon: str | None = None, root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -42,12 +45,15 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.item_render = item_render self.params = params self.items = items self.separator = separator self.root_class_name = root_class_name + self.dropdown_icon = dropdown_icon FRONTEND_DIR = resolve_frontend_dir("breadcrumb") diff --git a/backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py b/backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py index a51c8663..8f38773c 100644 --- a/backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py +++ b/backend/modelscope_studio/components/antd/breadcrumb/item/__init__.py @@ -61,7 +61,7 @@ class AntdBreadcrumbItem(ModelScopeLayoutComponent): def __init__( self, title: str | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, dropdown_props: dict | None = None, href: str | None = None, @@ -85,7 +85,7 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.additional_props = additional_props self.title = title self.dropdown_props = dropdown_props self.href = href diff --git a/backend/modelscope_studio/components/antd/button/__init__.py b/backend/modelscope_studio/components/antd/button/__init__.py index a2d12fe3..c730d459 100644 --- a/backend/modelscope_studio/components/antd/button/__init__.py +++ b/backend/modelscope_studio/components/antd/button/__init__.py @@ -51,11 +51,11 @@ class AntdButton(ModelScopeLayoutComponent): def __init__( self, value: str | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, auto_insert_space: bool = True, block: bool | None = None, - class_names: dict | None = None, + class_names: dict | str | None = None, danger: bool | None = None, disabled: bool | None = None, ghost: bool | None = None, @@ -63,10 +63,11 @@ def __init__( html_type: Literal["button", "submit", "reset"] | None = None, icon: str | None = None, icon_position: Literal["start", "end"] | None = None, + icon_placement: Literal["start", "end"] | None = None, loading: bool | dict | None = None, shape: Literal["default", "circle", "round"] | None = None, size: Literal["large", "middle", "small"] | None = None, - styles: dict | None = None, + styles: dict | str | None = None, href_target: str | None = None, type: Literal["primary", "dashed", "link", "text", "default"] | None = None, @@ -113,7 +114,7 @@ def __init__( elem_style=elem_style, **kwargs) self.value = value - self.props = props + self.additional_props = additional_props self.auto_insert_space = auto_insert_space self.block = block self.class_names = class_names @@ -124,6 +125,7 @@ def __init__( self.html_type = html_type self.icon = icon self.icon_position = icon_position + self.icon_placement = icon_placement self.loading = loading self.shape = shape self.size = size diff --git a/backend/modelscope_studio/components/antd/button/group/__init__.py b/backend/modelscope_studio/components/antd/button/group/__init__.py index f4fec3ec..e7b988bb 100644 --- a/backend/modelscope_studio/components/antd/button/group/__init__.py +++ b/backend/modelscope_studio/components/antd/button/group/__init__.py @@ -13,9 +13,11 @@ class AntdButtonGroup(ModelScopeLayoutComponent): def __init__( self, - props: dict | None = None, + additional_props: dict | None = None, *, size: Literal['small', 'middle', 'large'] | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -32,7 +34,9 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.size = size FRONTEND_DIR = resolve_frontend_dir("button", 'group') diff --git a/backend/modelscope_studio/components/antd/calendar/__init__.py b/backend/modelscope_studio/components/antd/calendar/__init__.py index 3e1bb46d..1fd35308 100644 --- a/backend/modelscope_studio/components/antd/calendar/__init__.py +++ b/backend/modelscope_studio/components/antd/calendar/__init__.py @@ -31,7 +31,7 @@ class AntdCalendar(ModelScopeComponent): def __init__( self, value: int | str | float | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, cell_render: str | None = None, full_cell_render: str | None = None, @@ -45,6 +45,8 @@ def __init__( valid_range: tuple[int | str | float, int | str | float] | None = None, root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -62,7 +64,9 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.cell_render = cell_render self.full_cell_render = full_cell_render self.default_value = default_value diff --git a/backend/modelscope_studio/components/antd/card/__init__.py b/backend/modelscope_studio/components/antd/card/__init__.py index b25e63ff..e0398148 100644 --- a/backend/modelscope_studio/components/antd/card/__init__.py +++ b/backend/modelscope_studio/components/antd/card/__init__.py @@ -55,7 +55,7 @@ def __exit__(self, *args, **kwargs): def __init__( self, - props: dict | None = None, + additional_props: dict | None = None, *, actions: str | None = None, active_tab_key: str | None = None, @@ -72,8 +72,8 @@ def __init__( tab_props: dict | None = None, title: str | None = None, type: str | None = None, - class_names: dict | None = None, - styles: dict | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, root_class_name: str | None = None, as_item: str | None = None, _internal: None = None, @@ -99,8 +99,8 @@ def __init__( tab_bar_extra_content: Extra content in tab bar. title: Card title. type: Card style type, can be set to inner or not set. - class_names: Config Card build-in module's className. - styles: Config Card build-in module's style. + class_names: dict | str | None + styles: dict | str | None """ super().__init__(visible=visible, elem_id=elem_id, @@ -109,7 +109,7 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.additional_props = additional_props self.actions = actions self.active_tab_key = active_tab_key self.bordered = bordered diff --git a/backend/modelscope_studio/components/antd/card/grid/__init__.py b/backend/modelscope_studio/components/antd/card/grid/__init__.py index 035406af..185257a4 100644 --- a/backend/modelscope_studio/components/antd/card/grid/__init__.py +++ b/backend/modelscope_studio/components/antd/card/grid/__init__.py @@ -24,9 +24,11 @@ class AntdCardGrid(ModelScopeLayoutComponent): def __init__( self, - props: dict | None = None, + additional_props: dict | None = None, *, hoverable: bool | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -47,7 +49,9 @@ def __init__( elem_style=elem_style, as_item=as_item, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.hoverable = hoverable FRONTEND_DIR = resolve_frontend_dir("card", "grid") diff --git a/backend/modelscope_studio/components/antd/card/meta/__init__.py b/backend/modelscope_studio/components/antd/card/meta/__init__.py index 8593e657..1a302f2c 100644 --- a/backend/modelscope_studio/components/antd/card/meta/__init__.py +++ b/backend/modelscope_studio/components/antd/card/meta/__init__.py @@ -19,7 +19,7 @@ class AntdCardMeta(ModelScopeLayoutComponent): def __init__( self, - props: dict | None = None, + additional_props: dict | None = None, *, avatar: str | None = None, description: str | None = None, @@ -46,7 +46,7 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.additional_props = additional_props self.avatar = avatar self.description = description self.title = title diff --git a/backend/modelscope_studio/components/antd/carousel/__init__.py b/backend/modelscope_studio/components/antd/carousel/__init__.py index e86158c4..1b5ac697 100644 --- a/backend/modelscope_studio/components/antd/carousel/__init__.py +++ b/backend/modelscope_studio/components/antd/carousel/__init__.py @@ -14,7 +14,7 @@ class AntdCarousel(ModelScopeLayoutComponent): def __init__( self, - props: dict | None = None, + additional_props: dict | None = None, *, arrows: bool | None = None, autoplay: bool | dict | None = None, @@ -22,6 +22,8 @@ def __init__( adaptive_height: bool | None = None, dot_position: Literal['top', 'bottom', 'left', 'right'] | None = 'bottom', + dot_placement: Literal['top', 'bottom', 'start', 'end'] + | None = None, dots: bool | dict | None = True, draggable: bool | None = None, fade: bool | None = None, @@ -33,6 +35,8 @@ def __init__( before_change: str | None = None, wait_for_animate: bool | None = None, root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -49,12 +53,15 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.arrows = arrows self.autoplay = autoplay self.autoplay_speed = autoplay_speed self.adaptive_height = adaptive_height self.dot_position = dot_position + self.dot_placement = dot_placement self.dots = dots self.draggable = draggable self.fade = fade diff --git a/backend/modelscope_studio/components/antd/cascader/__init__.py b/backend/modelscope_studio/components/antd/cascader/__init__.py index 4882ac10..bb783a5c 100644 --- a/backend/modelscope_studio/components/antd/cascader/__init__.py +++ b/backend/modelscope_studio/components/antd/cascader/__init__.py @@ -37,24 +37,16 @@ class AntdCascader(ModelScopeDataLayoutComponent): # supported slots SLOTS = [ - 'allowClear.clearIcon', - 'suffixIcon', - 'maxTagPlaceholder', - 'notFoundContent', - 'expandIcon', - 'removeIcon', - 'prefix', - 'displayRender', - 'tagRender', - 'dropdownRender', - 'popupRender' - 'showSearch.render', + 'allowClear.clearIcon', 'suffixIcon', 'maxTagPlaceholder', + 'notFoundContent', 'expandIcon', 'removeIcon', 'prefix', + 'displayRender', 'tagRender', 'dropdownRender', 'popupRender' + 'showSearch.render', 'optionRender' ] def __init__( self, value: list[str] | list[int | float] | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, allow_clear: bool | dict = False, auto_clear_search_value: bool = True, @@ -95,8 +87,8 @@ def __init__( dropdown_menu_column_style: dict | None = None, option_render: str | None = None, root_class_name: str | None = None, - class_names: dict | None = None, - styles: dict | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -114,7 +106,7 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.additional_props = additional_props self.allow_clear = allow_clear self.auto_clear_search_value = auto_clear_search_value self.auto_focus = auto_focus diff --git a/backend/modelscope_studio/components/antd/cascader/option/__init__.py b/backend/modelscope_studio/components/antd/cascader/option/__init__.py index e4e5c9a9..1a6ba6a9 100644 --- a/backend/modelscope_studio/components/antd/cascader/option/__init__.py +++ b/backend/modelscope_studio/components/antd/cascader/option/__init__.py @@ -21,7 +21,7 @@ def __init__( self, value: str | None = None, label: str | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, disabled: bool | None = None, is_leaf: bool | None = None, @@ -41,7 +41,7 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.additional_props = additional_props self.value = value self.label = label self.disabled = disabled diff --git a/backend/modelscope_studio/components/antd/cascader/panel/__init__.py b/backend/modelscope_studio/components/antd/cascader/panel/__init__.py index d204ad5b..03c438a7 100644 --- a/backend/modelscope_studio/components/antd/cascader/panel/__init__.py +++ b/backend/modelscope_studio/components/antd/cascader/panel/__init__.py @@ -23,12 +23,12 @@ class AntdCascaderPanel(ModelScopeDataLayoutComponent): ] # supported slots - SLOTS = ['notFoundContent', 'expandIcon'] + SLOTS = ['notFoundContent', 'expandIcon', 'optionRender'] def __init__( self, value: list[str] | list[int | float] | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, change_on_select: bool | None = None, default_value: str | None = None, @@ -40,7 +40,10 @@ def __init__( multiple: bool | None = None, show_checked_strategy: Literal['SHOW_PARENT', 'SHOW_CHILD'] | None = None, + option_render: str | None = None, root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -58,7 +61,9 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.change_on_select = change_on_select self.default_value = default_value self.expand_icon = expand_icon @@ -69,6 +74,7 @@ def __init__( self.multiple = multiple self.show_checked_strategy = show_checked_strategy self.root_class_name = root_class_name + self.option_render = option_render FRONTEND_DIR = resolve_frontend_dir("cascader", "panel") diff --git a/backend/modelscope_studio/components/antd/checkbox/__init__.py b/backend/modelscope_studio/components/antd/checkbox/__init__.py index 2ab9cc73..926d62de 100644 --- a/backend/modelscope_studio/components/antd/checkbox/__init__.py +++ b/backend/modelscope_studio/components/antd/checkbox/__init__.py @@ -24,13 +24,15 @@ class AntdCheckbox(ModelScopeDataLayoutComponent): def __init__( self, value: bool | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, auto_focus: bool | None = None, default_checked: bool | None = None, disabled: bool | None = None, indeterminate: bool | None = None, root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -48,7 +50,9 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.auto_focus = auto_focus self.default_checked = default_checked self.disabled = disabled diff --git a/backend/modelscope_studio/components/antd/checkbox/group/__init__.py b/backend/modelscope_studio/components/antd/checkbox/group/__init__.py index 014132a9..8d06965c 100644 --- a/backend/modelscope_studio/components/antd/checkbox/group/__init__.py +++ b/backend/modelscope_studio/components/antd/checkbox/group/__init__.py @@ -29,12 +29,14 @@ class AntdCheckboxGroup(ModelScopeDataLayoutComponent): def __init__( self, value: list[str | int | float | bool] | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, default_value: list[str | int | float | bool] | None = None, disabled: bool | None = None, options: list[str] | list[int | float] | list[dict] | None = None, root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -52,7 +54,9 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.default_value = default_value self.disabled = disabled self.options = options diff --git a/backend/modelscope_studio/components/antd/checkbox/group/option/__init__.py b/backend/modelscope_studio/components/antd/checkbox/group/option/__init__.py index 1e45b74f..43dcdc80 100644 --- a/backend/modelscope_studio/components/antd/checkbox/group/option/__init__.py +++ b/backend/modelscope_studio/components/antd/checkbox/group/option/__init__.py @@ -20,7 +20,7 @@ class AntdCheckboxGroupOption(ModelScopeLayoutComponent): def __init__( self, value: str | int | float | bool | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, label: str | None = None, disabled: bool | None = None, @@ -40,7 +40,7 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.additional_props = additional_props self.value = value self.label = label self.disabled = disabled diff --git a/backend/modelscope_studio/components/antd/collapse/__init__.py b/backend/modelscope_studio/components/antd/collapse/__init__.py index 0cbfdb52..ee6f9bea 100644 --- a/backend/modelscope_studio/components/antd/collapse/__init__.py +++ b/backend/modelscope_studio/components/antd/collapse/__init__.py @@ -25,7 +25,7 @@ class AntdCollapse(ModelScopeLayoutComponent): def __init__( self, - props: dict | None = None, + additional_props: dict | None = None, *, accordion: bool | None = None, active_key: str | float | list[int | float] | list[str] @@ -38,10 +38,13 @@ def __init__( destroy_on_hidden: bool | None = None, expand_icon: str | None = None, expand_icon_position: Literal['start', 'end'] | None = None, + expand_icon_placement: Literal['start', 'end'] | None = None, ghost: bool | None = None, items: list[dict] | None = None, size: Literal['large', 'middle', 'small'] | None = None, root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -58,7 +61,9 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.accordion = accordion self.active_key = active_key self.bordered = bordered @@ -68,6 +73,7 @@ def __init__( self.destroy_inactive_panel = destroy_inactive_panel self.expand_icon = expand_icon self.expand_icon_position = expand_icon_position + self.expand_icon_placement = expand_icon_placement self.ghost = ghost self.items = items self.size = size diff --git a/backend/modelscope_studio/components/antd/collapse/item/__init__.py b/backend/modelscope_studio/components/antd/collapse/item/__init__.py index a460b8fa..7b7936f4 100644 --- a/backend/modelscope_studio/components/antd/collapse/item/__init__.py +++ b/backend/modelscope_studio/components/antd/collapse/item/__init__.py @@ -25,14 +25,14 @@ def __init__( self, label: str | None = None, key: str | float | int | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, - class_names: dict | None = None, + class_names: dict | str | None = None, collapsible: Literal['header', 'icon', 'disabled'] | None = None, extra: str | None = None, force_render: bool | None = None, show_arrow: bool = True, - styles: dict | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -50,7 +50,7 @@ def __init__( elem_style=elem_style, **kwargs) self.label = label - self.props = props + self.additional_props = additional_props self.key = key self.class_names = class_names self.collapsible = collapsible diff --git a/backend/modelscope_studio/components/antd/color_picker/__init__.py b/backend/modelscope_studio/components/antd/color_picker/__init__.py index 42d857d2..80752636 100644 --- a/backend/modelscope_studio/components/antd/color_picker/__init__.py +++ b/backend/modelscope_studio/components/antd/color_picker/__init__.py @@ -39,7 +39,7 @@ class AntdColorPicker(ModelScopeDataLayoutComponent): def __init__( self, value: str | list[dict] | None = None, - props: dict | None = None, + additional_props: dict | None = None, *, value_format: Literal['hex', 'rgb', 'hsb'] = 'hex', allow_clear: bool | None = None, @@ -63,6 +63,8 @@ def __init__( panel_render: str | None = None, size: Literal['small', 'middle', 'large'] | None = None, root_class_name: str | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, # gradio properties @@ -80,7 +82,9 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.value_format = value_format self.allow_clear = allow_clear self.arrow = arrow diff --git a/backend/modelscope_studio/components/antd/color_picker/preset/__init__.py b/backend/modelscope_studio/components/antd/color_picker/preset/__init__.py index 7c41adaa..bab311a1 100644 --- a/backend/modelscope_studio/components/antd/color_picker/preset/__init__.py +++ b/backend/modelscope_studio/components/antd/color_picker/preset/__init__.py @@ -15,7 +15,7 @@ class AntdColorPickerPreset(ModelScopeLayoutComponent): def __init__( self, - props: dict | None = None, + additional_props: dict | None = None, *, label: str | None = None, colors: list[str] | None = None, @@ -37,7 +37,7 @@ def __init__( as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.additional_props = additional_props self.label = label self.key = key self.colors = colors diff --git a/backend/modelscope_studio/components/antd/components.py b/backend/modelscope_studio/components/antd/components.py index 33414c9e..2a721e34 100644 --- a/backend/modelscope_studio/components/antd/components.py +++ b/backend/modelscope_studio/components/antd/components.py @@ -67,6 +67,8 @@ from .list import AntdList from .list.item import AntdListItem from .list.item.meta import AntdListItemMeta +from .masonry import AntdMasonry +from .masonry.item import AntdMasonryItem from .mentions import AntdMentions from .mentions.option import AntdMentionsOption from .menu import AntdMenu @@ -119,6 +121,8 @@ from .tabs.item import AntdTabsItem from .tag import AntdTag from .tag.checkable_tag import AntdTagCheckableTag +from .tag.checkable_tag_group import AntdTagCheckableTagGroup +from .tag.checkable_tag_group.option import AntdTagCheckableTagGroupOption from .time_picker import AntdTimePicker from .time_picker.range_picker import AntdTimePickerRangePicker from .timeline import AntdTimeline diff --git a/backend/modelscope_studio/components/antd/config_provider/__init__.py b/backend/modelscope_studio/components/antd/config_provider/__init__.py index c7535ae6..4b6bdf82 100644 --- a/backend/modelscope_studio/components/antd/config_provider/__init__.py +++ b/backend/modelscope_studio/components/antd/config_provider/__init__.py @@ -1,5 +1,6 @@ from __future__ import annotations +import warnings from typing import Any, Literal from ....utils.dev import ModelScopeLayoutComponent, resolve_frontend_dir @@ -28,7 +29,7 @@ class AntdConfigProvider(ModelScopeLayoutComponent): SLOTS = ["renderEmpty"] def __init__(self, - props: dict | None = None, + additional_props: dict | None = None, *, component_disabled: bool | None = None, component_size: Literal['small', 'middle', 'large'] @@ -44,10 +45,13 @@ def __init__(self, prefix_cls: str | None = None, render_empty: str | None = None, theme: dict | None = None, + theme_config: dict | None = None, variant: Literal['outlined', 'filled', 'borderless'] | None = None, virtual: bool | None = None, warning: dict | None = None, + class_names: dict | str | None = None, + styles: dict | str | None = None, as_item: str | None = None, _internal: None = None, visible: bool = True, @@ -63,7 +67,9 @@ def __init__(self, as_item=as_item, elem_style=elem_style, **kwargs) - self.props = props + self.class_names = class_names + self.styles = styles + self.additional_props = additional_props self.component_disabled = component_disabled self.component_size = component_size self.csp = csp @@ -77,6 +83,11 @@ def __init__(self, self.prefix_cls = prefix_cls self.render_empty = render_empty self.theme = theme + if theme: + warnings.warn( + """
- 当传入 dict 时，必须包含有avatar字段。
- 当传入 list 时，一般对应多 bot 模式，每一项可以接收前面所有的值，每个 bot 的头像与 message 中 bot 的位置一一对应 | -| avatar_image_align | Literal['top', 'middle', 'bottom'] | 'bottom' | 控制头像与 message 的对齐方式，默认为下对齐 | -| avatar_image_width | int | 45 | 头像与名称的宽度 | -| flushing_speed | int | 3 | 打字机速度，值为 1 - 10，值越大速度越快 | -| llm_thinking_presets | list\[dict\] | \[\] | llm 思考链路解析预设，可以将 llm 调用工具的输出格式转为固定的前端展示格式，需要从modelscope_studio.Chatbot.llm_thinking_presets引入，目前支持：qwen | -| custom_components | dict\[str, CustomComponentDict\] CustomComponentDict 定义见下方 | None | 支持用户定义自定义标签，并通过 js 控制标签渲染样式与触发 python 事件。 | - -**CustomComponentDict 定义如下** - -```python -class CustomComponentDict(TypedDict): - props: Optional[List[str]] - template: Optional[str] - js: Optional[str] -``` - -### 内置的自定义标签 - -见
- index：当前 message 的 index tuple。
- value：当前 message value。 | -| `mgr.Chatbot.custom(fn, ···)` | 自定义标签触发事件时触发，EventData 为：
- index：当前 message 的 index tuple ([message index, user group(index 0) or bot group(index 1), user/bot group index])。
- tag：当前触发的标签。
- tag_index：当前触发标签的 index，此 index 在 message 的 index tuple 基础上重新计算。
- value：自定义传入的值。 | diff --git a/docs/components/legacy/Chatbot/README.md b/docs/components/legacy/Chatbot/README.md deleted file mode 100644 index ef41002e..00000000 --- a/docs/components/legacy/Chatbot/README.md +++ /dev/null @@ -1,143 +0,0 @@ -# Chatbot - -Upgraded gradio Chatbot. - -- Supports uniform frontend streaming output of messages -- Supports output of multimodal content (audio, video, image, text) -- Built-in tags (chart, select-box, accordion) -- Supports multi-agent scenarios -- Supports custom rendering components and interaction with Python events - -## How to Use - -### Basic Usage - -
- When passing a dict, it must include an avatar field.
- When passing a list, it generally corresponds to the multi-bot mode, where each item can receive all the aforementioned values, and each bot’s avatar matches with the position of the bot in the messages. | -| avatar_image_align | Literal['top', 'middle', 'bottom'] | 'bottom' | Controls the alignment of the avatar with the messages, default is bottom-aligned. | -| avatar_image_width | int | 45 | The width of the avatar and name. | -| flushing_speed | int | 3 | Typewriter speed, values range from 1 - 10, with larger values indicating faster speeds. | -| llm_thinking_presets | list\[dict\] | \[\] | llm thinking link presets, which can convert the output format of llm calling tools into a fixed front-end display format. It needs to be imported from modelscope_studio.Chatbot.llm_thinking_presets, and currently supports: qwen. | -| custom_components | dict\[str, CustomComponentDict\] CustomComponentDict is defined below | None | Allows users to define custom tags and control tag rendering styles and trigger Python events through JS. | - -**Definition of CustomComponent is as follows:** - -```python -class CustomComponentDict(TypedDict): - props: Optional[List[str]] - template: Optional[str] - js: Optional[str] -``` - -### Built-in Custom Tags - -See
- index: The index tuple of the current message.
- value: The current message value. | -| `mgr.Chatbot.custom(fn, ···)` | Triggered when a custom tag event occurs. EventData is:
- index: The index tuple of the current message ([message index, user group(index 0) or bot group(index 1), user/bot group index]).
- tag: The current tag that triggered the event.
- tag_index: The index of the current triggered tag, re-calculated based on the message’s index tuple.
- value: The custom value passed in. | diff --git a/docs/components/legacy/Chatbot/demos/accordion.py b/docs/components/legacy/Chatbot/demos/accordion.py deleted file mode 100644 index 2c00ebfc..00000000 --- a/docs/components/legacy/Chatbot/demos/accordion.py +++ /dev/null @@ -1,51 +0,0 @@ -import os - -import gradio as gr -import modelscope_studio.components.base as ms -import modelscope_studio.components.legacy as mgr -from modelscope_studio.components.legacy.Chatbot.llm_thinking_presets import \ - qwen - - -def resolve_assets(relative_path): - return os.path.join(os.path.dirname(__file__), "../../resources", - relative_path) - - -conversation = [ - [ - None, { - "text": f""" -Use accordion tag: - -
- id：当前触发节点 id。
- node：当前触发节点类型。
- attr：当前触发节点属性。
- index：当前触发节点属性索引，当节点属性为 list 时有值。
- value：自定义传入的值。 | diff --git a/docs/components/legacy/Flow/README.md b/docs/components/legacy/Flow/README.md deleted file mode 100644 index b7ebf875..00000000 --- a/docs/components/legacy/Flow/README.md +++ /dev/null @@ -1,108 +0,0 @@ -# Flow - -A Flow component implemented based on [reactflow](https://reactflow.dev/). - -- Supports customization of node rendering through a schema. -- Allows for custom node render components with interaction from Python. - -## How to Use - -### Defining Schema Nodes (Important) - -See:
- `id`: ID of the currently triggered node.
- `node`: Type of the currently triggered node.
- `attr`: Attributes of the currently triggered node.
- `index`: Index of the attribute if it's a list.
- `value`: Custom passed-in value. | diff --git a/docs/components/legacy/Flow/define_schema-zh_CN.md b/docs/components/legacy/Flow/define_schema-zh_CN.md deleted file mode 100644 index dfd15303..00000000 --- a/docs/components/legacy/Flow/define_schema-zh_CN.md +++ /dev/null @@ -1,266 +0,0 @@ -# Define Schema - -在使用 Flow 组件前，需要预先创建 Schema 定义 node 节点，schema 类型定义如下： - -```ts -export interface FlowSchema { - nodes: FlowNodeSchema[]; -} - -export interface FlowNodeSchema { - /** - * 作为节点的唯一标识。必填。 - */ - name: string; - - /** - * 节点显示图标。 - */ - icon?: string; - - /** - * 节点标题，如果没有提供则默认使用 name。 - */ - title?: string; - - /** - * 节点的简短描述。 - */ - description?: string; - - /** - * 节点宽度。 - */ - width?: number; - - /** - * 节点高度。 - */ - height?: number; - - /** - * 显示/隐藏工具栏（删除、复制、重命名等）。 - * @default true - */ - show_toolbar?: boolean; - - /** - * 启用/禁止添加更多此类节点实例。 - * @default true - */ - addable?: boolean; - - /** - * 启用/禁止删除现有此类节点实例。 - * @default true - */ - deletable?: boolean; - - /** - * 可以同时存在的此类节点的最大数量。 - */ - max?: number; - - /** - * 可以同时存在的此类节点的最小数量。 - */ - min?: number; - - /** - * 节点连接端口的配置。 - */ - ports?: { - /** - * 节点作为连接的源端口。 - * @default ['right'] - */ - source?: Position[]; - - /** - * 允许此节点 source 端口连接到的其他节点或属性。默认为所有节点和属性。 - * @default [] - */ - sourceConnections?: PortConnection[]; - - /** - * 节点作为连接的目标端口。 - * @default ['left'] - */ - target?: Position[]; - - /** - * 其他允许连接到此节点 target 端口的节点或属性。默认为所有节点和属性 - * @default [] - */ - targetConnections?: PortConnection[]; - }; - - /** - * 节点的属性配置。 - */ - attrs?: FlowNodeAttrSchema[]; - - /** - * 创建新实例时节点属性的初始值。 - */ - template?: { - /** - * 在`attrs`字段中与其名称相对应的属性值，例如 { "a": 1, "b": 2 }。 - */ - attrs?: Attrs; - }; -} - -export interface FlowNodeAttrSchema { - /** - * 唯一的属性名称，在 node data 中用作 key。必填。 - */ - name: string; - - /** - * 属性标题，如果没有提供则默认使用 name。 - */ - title?: string; - - /** - * 属性的简短描述 - */ - description?: string; - - /** - * 禁用用户编辑属性值。默认情况下，属性是可编辑的。 - * @default false - */ - disabled?: boolean; - - /** - * 属性输入类型。可以是内置的 Ant Design 组件或自定义组件之一。默认为'input'。 - * @default 'input' - */ - type?: - | 'input' - | 'textarea' - | 'radio' - | 'checkbox' - | 'number' - | 'select' - | 'switch' - | 'upload' - // 自定义 - | (string & {}); - - /** - * 针对所选组件类型的特定配置选项，支持 Ant Design 组件({@link https://ant.design/components/overview/})或自定义组件的属性。 - */ - props?: Record
- tag_index：当前触发标签的 index。
- value：自定义传入的值。 | diff --git a/docs/components/legacy/Markdown/README.md b/docs/components/legacy/Markdown/README.md deleted file mode 100644 index 9a705158..00000000 --- a/docs/components/legacy/Markdown/README.md +++ /dev/null @@ -1,92 +0,0 @@ -# Markdown - -Upgraded gradio Markdown. - -- Supports output of multimodal content (audio, video, image, text) -- Built-in tags (chart, select-box, accordion) -- Supports custom rendering components and interaction with Python events - -## How to Use - -### Basic Usage - -
- tag: The current tag that triggered the event.
- tag_index: The index of the current triggered tag.
- value: The custom value passed in. | diff --git a/docs/components/legacy/Markdown/app.py b/docs/components/legacy/Markdown/app.py deleted file mode 100644 index 7b991a9d..00000000 --- a/docs/components/legacy/Markdown/app.py +++ /dev/null @@ -1,20 +0,0 @@ -import os - -from components.legacy.Docs import Docs - - -def resolve(relative_path: str): - return os.path.join(os.path.dirname(__file__), relative_path) - - -docs = Docs( - __file__, - markdown_files=(["README.md", "README-zh_CN.md"] + [ - f"custom_tags/{filename}" - for filename in os.listdir(resolve('custom_tags')) - if filename.endswith(".md") - ]), -) - -if __name__ == "__main__": - docs.render().queue().launch() diff --git a/docs/components/legacy/Markdown/custom_tags/accordion-zh_CN.md b/docs/components/legacy/Markdown/custom_tags/accordion-zh_CN.md deleted file mode 100644 index 6a627125..00000000 --- a/docs/components/legacy/Markdown/custom_tags/accordion-zh_CN.md +++ /dev/null @@ -1,23 +0,0 @@ -# accordion - -在 markdown 文本中添加手风琴效果。 - -## 如何使用 - -### 基本使用 - -
- xs：屏幕 < 576px
- sm：屏幕 ≥ 576px
- md：屏幕 ≥ 768px
- lg：屏幕 ≥ 992px
- xl：屏幕 ≥ 1200px
- xxl：屏幕 ≥ 1600px 当direction为vertical时此配置不生效。 | -| item-width | string | | 当shape="card"时才生效。每个选项的宽度，如：'auto'、'100px'，默认使用 columns 自动分配的宽度。 | -| item-height | string | | 当shape="card"时才生效。每个选项的高度，默认自适应元素高度。 | -| img-height | string | '160px' | 当shape="card"时才生效。每个选项中图片的高度。 | -| equal-height | boolean | false | 当shape="card"时才生效。是否每一行的选项高度都相等，会使用高度最高的选项。 | diff --git a/docs/components/legacy/Markdown/custom_tags/select-box.md b/docs/components/legacy/Markdown/custom_tags/select-box.md deleted file mode 100644 index fb2b210a..00000000 --- a/docs/components/legacy/Markdown/custom_tags/select-box.md +++ /dev/null @@ -1,45 +0,0 @@ -# select-box - -Add a selection interaction box to markdown text. - -## How to Use - -### Basic Usage - -
- xs: screen < 576px
- sm: screen ≥ 576px
- md: screen ≥ 768px
- lg: screen ≥ 992px
- xl: screen ≥ 1200px
- xxl: screen ≥ 1600px This configuration does not take effect when direction is vertical. | -| item-width | string | | Effective only when shape="card". The width of each option, such as: 'auto', '100px', the default uses the width automatically allocated by columns. | -| item-height | string | | Effective only when shape="card". The height of each option, defaults to adapt to the height of the element. | -| img-height | string | '160px' | Effective only when shape="card". The height of the images within each option. | -| equal-height | boolean | false | Effective only when shape="card". Whether the height of the options in each row should be equal, using the height of the tallest option. | diff --git a/docs/components/legacy/Markdown/demos/accordion.py b/docs/components/legacy/Markdown/demos/accordion.py deleted file mode 100644 index 6bc3615a..00000000 --- a/docs/components/legacy/Markdown/demos/accordion.py +++ /dev/null @@ -1,28 +0,0 @@ -import gradio as gr -import modelscope_studio.components.base as ms -import modelscope_studio.components.legacy as mgr - -with gr.Blocks() as demo, ms.Application(): - mgr.Markdown(""" -
{value}
"
- }
- })
-
-if __name__ == "__main__":
- demo.queue().launch()
diff --git a/docs/components/legacy/Markdown/demos/custom-tag2.py b/docs/components/legacy/Markdown/demos/custom-tag2.py
deleted file mode 100644
index ecb3acef..00000000
--- a/docs/components/legacy/Markdown/demos/custom-tag2.py
+++ /dev/null
@@ -1,55 +0,0 @@
-import gradio as gr
-import modelscope_studio.components.base as ms
-import modelscope_studio.components.legacy as mgr
-
-with gr.Blocks() as demo, ms.Application():
- mgr.Markdown(
- """
-custom tag:ModelScope Studio
- -
- 
-
- ✖️
-
- 
-
- -
-GitHub | 🤖 ModelScope Studio ｜ 🤗 Hugging Face Space
-
-`modelscope_studio` 是一套基于 gradio 4.x 的扩展组件库，致力于服务于 ModelScope 创空间中对于 gradio 应用的各类扩展需求，目前主要聚集在对话场景增强、多模态场景以及一些其他垂直场景支持。
-
-## Install
-
-```sh
-pip install modelscope_studio
-```
-
-## API
-
--
ModelScope Studio
- -
-
-
- ✖️
-
-
-
- -
-GitHub | 🤖 ModelScope Studio ｜ 🤗 Hugging Face Space
-
-`modelscope_studio` is a set of extension component libraries based on gradio 4.x, dedicated to serving the various extension needs of gradio applications within the ModelScope Studio. It mainly focuses on enhancing conversational scenarios, supporting multimodal contexts, and providing assistance for various other specialized scenarios.
-
-## Install
-
-```sh
-pip install modelscope_studio
-```
-
-## API
-
--
- 如果传入 int, 则应用于所有尺寸屏幕；
- 如果传入 tuple, 当给出的断点少于 6 个, 则最后一个断点将用于所有后续断点；
- 如果传入 dict, 则可以以 [xs,sm,md,lg,xl,xll] 为键表示每个尺寸屏幕的图像数量。 |
-| gap | tuple \| int | 8 | 图片之间的间隙 (px)。 如果传递一个元组，则第一个值是宽度的间隙，第二个值是高度的间隙。如果传递数字，则宽度和高度的间隙相同 |
-| action_label | str | 'Click' | action 按钮的文案。当 `clickable`为 True 时才展示 |
-| likeable | bool | None | 是否显示喜欢或不喜欢按钮。 可以通过显示绑定 `.like` 方法自动设置。 |
-| clickable | bool | None | 是否显示 action 按钮。 可以通过显示绑定 `.click` 方法自动设置。 |
-
-### event listeners
-
-| 事件 | 描述 |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mgr.WaterfallGallery.load_more(fn, ···)` | “加载更多”按钮被点击时触发。 |
-| `mgr.WaterfallGallery.like(fn, ···)` | 当点赞/点踩按钮被点击时触发，EventData 为：
- index：当前图片索引。
- value：当前图片信息。
- liked：当前图片的喜欢/不喜欢状态，可以为 None，代表用户取消操作。 |
-| `mgr.WaterfallGallery.click(fn, ···)` | action 按钮被点击时触发，EventData 为：
- index：当前图片索引。
- value：当前图片信息。 |
diff --git a/docs/components/legacy/WaterfallGallery/README.md b/docs/components/legacy/WaterfallGallery/README.md
deleted file mode 100644
index 392fe320..00000000
--- a/docs/components/legacy/WaterfallGallery/README.md
+++ /dev/null
@@ -1,71 +0,0 @@
-# WaterfallGallery
-
-gradio Gallery with waterfall flow.
-
-- Support waterfall flow display images
-- Added a like button, support additional binding of `like` events to images
-- Added an action button, support additional binding of `click` event to images
-- Responsive columns
-
-## How to Use
-
-### Basic Usage
-
-
- If int is passed in, it will apply to all screen sizes;
- If tuple is passed in, when less than 6 breakpoints are given, the last breakpoint will be used for all subsequent breakpoints ;
- If a dict is passed in, you can represents the number of images for each size screen with [xs,sm,md,lg,xl,xll] as the key. |
-| gap | tuple \| int | 8 | The gap (px) between images. If a tuple is passed, the first value is the gap for width and the second value is the gap for height.If a number is passed, the gap will be the same for width and height. |
-| action_label | str | 'Click' | The label for the action button. Only displayed if `clickable` is set to True. |
-| likeable | bool | None | Whether the gallery image display a like or dislike button. Set automatically by the .like method but has to be present in the signature for it to show up in the config. |
-| clickable | bool | None | Whether the gallery image display an action button. Set automatically by the .click method but has to be present in the signature for it to show up in the config. |
-
-### Event Listeners
-
-| Event | Description |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mgr.WaterfallGallery.load_more(fn, ···)` | Triggered when the "Load More" button is clicked. |
-| `mgr.WaterfallGallery.like(fn, ···)` | Triggered when the Like/Dislike button is clicked. EventData is:
- index: current image index.
- value: current image info.
- liked: like/dislike status of the current image, which can be None, indicating that the user cancels the operation. |
-| `mgr.WaterfallGallery.click(fn, ···)` | Triggered when the action button is clicked, EventData is:
- index: current image index.
- value: current image info. |
diff --git a/docs/components/legacy/WaterfallGallery/app.py b/docs/components/legacy/WaterfallGallery/app.py
deleted file mode 100644
index ea841f78..00000000
--- a/docs/components/legacy/WaterfallGallery/app.py
+++ /dev/null
@@ -1,6 +0,0 @@
-from components.legacy.Docs import Docs
-
-docs = Docs(__file__)
-
-if __name__ == "__main__":
- docs.render().queue().launch()
diff --git a/docs/components/legacy/WaterfallGallery/demos/basic.py b/docs/components/legacy/WaterfallGallery/demos/basic.py
deleted file mode 100644
index 1071ef06..00000000
--- a/docs/components/legacy/WaterfallGallery/demos/basic.py
+++ /dev/null
@@ -1,30 +0,0 @@
-import os
-
-import gradio as gr
-import modelscope_studio.components.base as ms
-import modelscope_studio.components.legacy as mgr
-
-
-def resolve_assets(relative_path):
- return os.path.join(os.path.dirname(__file__), "../../resources",
- relative_path)
-
-
-with gr.Blocks() as demo, ms.Application():
- mgr.WaterfallGallery(
- value=[
- resolve_assets('modelscope.svg'),
- # pass a tuple
- [resolve_assets('bot.jpeg'), 'bot'],
- # pass a dict
- {
- "image": resolve_assets('user.jpeg'),
- "caption": "user",
- },
- resolve_assets('screen.jpeg'),
- ],
- columns=2,
- height=600)
-
-if __name__ == "__main__":
- demo.queue().launch()
diff --git a/docs/components/legacy/WaterfallGallery/demos/like_click_feedback.py b/docs/components/legacy/WaterfallGallery/demos/like_click_feedback.py
deleted file mode 100644
index 64299d85..00000000
--- a/docs/components/legacy/WaterfallGallery/demos/like_click_feedback.py
+++ /dev/null
@@ -1,37 +0,0 @@
-import os
-
-import gradio as gr
-import modelscope_studio.components.base as ms
-import modelscope_studio.components.legacy as mgr
-
-
-def resolve_assets(relative_path):
- return os.path.join(os.path.dirname(__file__), "../../resources",
- relative_path)
-
-
-def fn(data: gr.EventData):
- print(data._data)
-
-
-with gr.Blocks() as demo, ms.Application():
- gallery = mgr.WaterfallGallery(
- value=[
- resolve_assets('modelscope.svg'),
- # pass a tuple
- [resolve_assets('bot.jpeg'), 'bot'],
- # pass a dict
- {
- "image": resolve_assets('user.jpeg'),
- "caption": "user",
- },
- resolve_assets('screen.jpeg'),
- ],
- action_label="Click Me!",
- columns=2,
- height=600)
- gallery.like(fn=fn)
- gallery.click(fn=fn)
-
-if __name__ == "__main__":
- demo.queue().launch()
diff --git a/docs/components/legacy/WaterfallGallery/demos/load_more.py b/docs/components/legacy/WaterfallGallery/demos/load_more.py
deleted file mode 100644
index 28fe008e..00000000
--- a/docs/components/legacy/WaterfallGallery/demos/load_more.py
+++ /dev/null
@@ -1,45 +0,0 @@
-import os
-import time
-
-import gradio as gr
-import modelscope_studio.components.base as ms
-import modelscope_studio.components.legacy as mgr
-
-
-def resolve_assets(relative_path):
- return os.path.join(os.path.dirname(__file__), "../../resources",
- relative_path)
-
-
-def load_more(_gallery):
- time.sleep(1)
- _gallery.append(resolve_assets('modelscope.svg'))
- _gallery.append(resolve_assets('bot.jpeg'))
- _gallery.append(resolve_assets('user.jpeg'))
- _gallery.append(resolve_assets('screen.jpeg'))
- has_more = True
- if (len(_gallery) > 10):
- has_more = False
- return gr.update(value=_gallery, has_more=has_more)
-
-
-with gr.Blocks() as demo, ms.Application():
- gallery = mgr.WaterfallGallery(
- value=[
- resolve_assets('modelscope.svg'),
- # pass a tuple
- [resolve_assets('bot.jpeg'), 'bot'],
- # pass a dict
- {
- "image": resolve_assets('user.jpeg'),
- "caption": "user",
- },
- resolve_assets('screen.jpeg'),
- ],
- has_more=True,
- columns=2,
- height=600)
- gallery.load_more(fn=load_more, inputs=[gallery], outputs=[gallery])
-
-if __name__ == "__main__":
- demo.queue().launch()
diff --git a/docs/components/legacy/WaterfallGallery/demos/responsive_columns.py b/docs/components/legacy/WaterfallGallery/demos/responsive_columns.py
deleted file mode 100644
index dcea88d8..00000000
--- a/docs/components/legacy/WaterfallGallery/demos/responsive_columns.py
+++ /dev/null
@@ -1,35 +0,0 @@
-import os
-
-import gradio as gr
-import modelscope_studio.components.base as ms
-import modelscope_studio.components.legacy as mgr
-
-
-def resolve_assets(relative_path):
- return os.path.join(os.path.dirname(__file__), "../../resources",
- relative_path)
-
-
-def fn():
- return gr.update(columns={"xs": 2, "lg": 3})
-
-
-with gr.Blocks() as demo, ms.Application():
- gallery = mgr.WaterfallGallery(
- value=[
- resolve_assets('modelscope.svg'),
- # pass a tuple
- [resolve_assets('bot.jpeg'), 'bot'],
- # pass a dict
- {
- "image": resolve_assets('user.jpeg'),
- "caption": "user",
- },
- resolve_assets('screen.jpeg'),
- ],
- columns=[2, 3, 4],
- height=600)
- gr.Button("Update Columns").click(fn=fn, outputs=[gallery])
-
-if __name__ == "__main__":
- demo.queue().launch()
diff --git a/docs/components/legacy/app.py b/docs/components/legacy/app.py
deleted file mode 100644
index 3606901a..00000000
--- a/docs/components/legacy/app.py
+++ /dev/null
@@ -1,34 +0,0 @@
-import gradio as gr
-import modelscope_studio.components.base as ms
-from api.app import docs as api_docs
-from components.legacy.Chatbot.app import docs as chatbot_docs
-from components.legacy.Docs import Docs
-from components.legacy.Flow.app import docs as flow_docs
-from components.legacy.Lifecycle.app import docs as lifecycle_docs
-from components.legacy.Markdown.app import docs as markdown_docs
-from components.legacy.MultimodalInput.app import docs as multimodel_input_docs
-from components.legacy.WaterfallGallery.app import \
- docs as waterfall_gallery_docs
-
-readme_docs = Docs(__file__)
-
-docs = [
- ["Quick Start", readme_docs],
- ["API", api_docs],
- ["Chatbot", chatbot_docs],
- ["MultimodalInput", multimodel_input_docs],
- ["Markdown", markdown_docs],
- ["Lifecycle", lifecycle_docs],
- ["WaterfallGallery", waterfall_gallery_docs],
- ["Flow", flow_docs],
-]
-
-with gr.Blocks() as legacy_demo:
- with ms.Application():
- with gr.Tabs() as components_tabs:
- for doc in docs:
- with gr.TabItem(doc[0], id=doc[0]):
- doc[1].render(components_tabs)
-
-if __name__ == "__main__":
- legacy_demo.launch()
diff --git a/docs/components/legacy/parse_markdown.py b/docs/components/legacy/parse_markdown.py
deleted file mode 100644
index 56074f51..00000000
--- a/docs/components/legacy/parse_markdown.py
+++ /dev/null
@@ -1,85 +0,0 @@
-from html.parser import HTMLParser
-
-
-def default_read_file(path):
- with open(path, "r") as f:
- return f.read()
-
-
-enable_tags = ["demo", "demo-prefix", "demo-suffix", "file"]
-
-
-class MarkdownParser(HTMLParser):
-
- def __init__(self, read_file=None):
- super().__init__()
- self.value = [{"type": "text", "value": ""}]
- self.tag_stack = []
- self.read_file = read_file or default_read_file
- self.current_tag = None
-
- def get_value(self):
- return self.value
-
- def handle_data(self, data: str) -> None:
- if self.value[-1]["type"] == "text":
- self.value[-1]["value"] += data
- elif self.current_tag is None:
- self.value.append({"type": "text", "value": data})
- elif self.current_tag == "demo-prefix":
- self.value[-1]["prefix"] += data
- elif self.current_tag == "demo-suffix":
- self.value[-1]["suffix"] += data
-
- def handle_startendtag(self, tag: str, attrs) -> None:
- if tag not in enable_tags:
- self.handle_data(self.get_starttag_text())
- return
-
- def handle_starttag(self, tag: str, attrs) -> None:
- if (tag not in enable_tags):
- self.handle_data(self.get_starttag_text())
- return
- if tag == "demo":
- self.value.append({
- "type":
- "demo",
- "code_position":
- dict(attrs).get("code-position", 'left'),
- "name":
- dict(attrs)["name"],
- "prefix":
- "",
- "suffix":
- ""
- })
- elif tag == "file":
- content = self.read_file(dict(attrs)["src"])
- if self.value[-1]["type"] == "text":
- self.value[-1]["value"] += content
- elif self.current_tag == "demo-prefix":
- self.value[-1]["prefix"] += content
- elif self.current_tag == "demo-suffix":
- self.value[-1]["suffix"] += content
- self.current_tag = tag
- self.tag_stack.append(self.current_tag)
-
- def handle_endtag(self, tag: str) -> None:
-
- if (tag not in enable_tags):
- self.handle_data(f"")
- return
- if (len(self.tag_stack) > 0):
- self.tag_stack.pop()
- if (len(self.tag_stack) > 0):
- self.current_tag = self.tag_stack[-1]
- else:
- self.current_tag = None
- else:
- self.current_tag = None
-
-
-def parse_markdown(markdown: str, read_file=None):
- parser = MarkdownParser(read_file=read_file)
- parser.feed(markdown)
- return parser.get_value()
diff --git a/docs/components/legacy/resources/audio.wav b/docs/components/legacy/resources/audio.wav
deleted file mode 100644
index 105190ad..00000000
Binary files a/docs/components/legacy/resources/audio.wav and /dev/null differ
diff --git a/docs/components/legacy/resources/bot.jpeg b/docs/components/legacy/resources/bot.jpeg
deleted file mode 100644
index 5fde8cc4..00000000
Binary files a/docs/components/legacy/resources/bot.jpeg and /dev/null differ
diff --git a/docs/components/legacy/resources/custom_components/custom_select.js b/docs/components/legacy/resources/custom_components/custom_select.js
deleted file mode 100644
index f4a1cb40..00000000
--- a/docs/components/legacy/resources/custom_components/custom_select.js
+++ /dev/null
@@ -1,29 +0,0 @@
-(props, cc, { el, onUpdate }) => {
- const options = JSON.parse(props.options);
- el.innerHTML = `
- ${options
- .map((option) => {
- return `
-
-
`;
- })
- .join('')}
- `;
- onUpdate(
- () => {
- const inputs = Array.from(el.getElementsByTagName('input'));
- Array.from(el.getElementsByTagName('label')).forEach((label, i) => {
- label.addEventListener('click', () => {
- inputs.forEach((input) => {
- input.checked = false;
- });
- const input = label.getElementsByTagName('input')[0];
- input.checked = true;
- // Use cc.dispatch to trigger events.
- cc.dispatch(options[i]);
- });
- });
- },
- { callAfterMount: true }
- );
-};
diff --git a/docs/components/legacy/resources/image-bot.jpeg b/docs/components/legacy/resources/image-bot.jpeg
deleted file mode 100644
index 5df101fe..00000000
Binary files a/docs/components/legacy/resources/image-bot.jpeg and /dev/null differ
diff --git a/docs/components/legacy/resources/modelscope.svg b/docs/components/legacy/resources/modelscope.svg
deleted file mode 100644
index 093ba6fe..00000000
--- a/docs/components/legacy/resources/modelscope.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/components/legacy/resources/music-bot.jpeg b/docs/components/legacy/resources/music-bot.jpeg
deleted file mode 100644
index 00288fb5..00000000
Binary files a/docs/components/legacy/resources/music-bot.jpeg and /dev/null differ
diff --git a/docs/components/legacy/resources/screen.jpeg b/docs/components/legacy/resources/screen.jpeg
deleted file mode 100644
index 574735ac..00000000
Binary files a/docs/components/legacy/resources/screen.jpeg and /dev/null differ
diff --git a/docs/components/legacy/resources/user.jpeg b/docs/components/legacy/resources/user.jpeg
deleted file mode 100644
index 536948b6..00000000
Binary files a/docs/components/legacy/resources/user.jpeg and /dev/null differ
diff --git a/docs/components/legacy/tab-link.js b/docs/components/legacy/tab-link.js
deleted file mode 100644
index bcd9143d..00000000
--- a/docs/components/legacy/tab-link.js
+++ /dev/null
@@ -1,15 +0,0 @@
-(props, cc, { onMount, el }) => {
- onMount(() => {
- el.addEventListener('click', () => {
- cc.dispatch({
- tab: props.tab,
- component_tab: props['component-tab'],
- });
- });
- });
- const children = props.children[0].value;
- el.innerHTML = `${children}`;
- el.style.display = 'inline-block';
- el.style.cursor = 'pointer';
- el.style.color = 'var(--link-text-color)';
-};
diff --git a/docs/components/pro/chatbot/README-zh_CN.md b/docs/components/pro/chatbot/README-zh_CN.md
index 56840caa..5856b10f 100644
--- a/docs/components/pro/chatbot/README-zh_CN.md
+++ b/docs/components/pro/chatbot/README-zh_CN.md
@@ -72,10 +72,10 @@
### 插槽
```python
-SLOTS=["roles"]
+SLOTS=["role"]
```
-另外，如果已有的 role 样式不符合预期，也可以和`Ant Design X`的`Bubble`组件一样使用`ms.Slot("roles")`进行自定义。
+另外，如果已有的 role 样式不符合预期，也可以和`Ant Design X`的`Bubble`组件一样使用`ms.Slot("role")`进行自定义。
### 类型
@@ -107,7 +107,7 @@ class ChatbotPromptsConfig(GradioModel):
# Ant Design X welcome props: https://x.ant.design/components/welcome
class ChatbotWelcomeConfig(GradioModel):
variant: Optional[Literal['borderless', 'filled']] = 'borderless'
- icon: Optional[Union[str, Path]] = None
+ icon: Optional[Union[str, Path, dict]] = None
title: Optional[str] = None
description: Optional[str] = None
extra: Optional[str] = None
@@ -277,6 +277,8 @@ class ChatbotDataFileContentOptions(GradioModel):
gap: Optional[Union[Literal["small", "middle", "large"], str, int,
float]] = "small"
image_props: Optional[dict] = None
+ video_props: Optional[dict] = None
+ audio_props: Optional[dict] = None
# Ant Design X prompts props: https://x.ant.design/components/prompts
@@ -318,7 +320,8 @@ class ChatbotDataMessageContent(GradioModel):
class ChatbotDataMessage(ChatbotBotConfig):
- role: Union[Literal['user', 'assistant', 'system'], str] = None
+ role: Union[Literal['user', 'assistant', 'system', 'divider'], str] = None
+ divider_props: Optional[dict] = None
key: Optional[Union[str, int, float]] = None
# If status is 'pending', the message will not render the footer area (including 'actions' and 'footer').
status: Optional[Literal['pending', 'done']] = None
diff --git a/docs/components/pro/chatbot/README.md b/docs/components/pro/chatbot/README.md
index c9cedad3..55763eb3 100644
--- a/docs/components/pro/chatbot/README.md
+++ b/docs/components/pro/chatbot/README.md
@@ -71,10 +71,10 @@ The `message` object includes all configurations from `bot_config` and `user_con
### Slots
```python
-SLOTS=["roles"]
+SLOTS=["role"]
```
-Additionally, if the role style does not meet your expectations, you can also use `ms.Slot("roles")` to customize it, just like the `Bubble` component of `Ant Design X`.
+Additionally, if the role style does not meet your expectations, you can also use `ms.Slot("role")` to customize it, just like the `Bubble` component of `Ant Design X`.
### Types
@@ -106,7 +106,7 @@ class ChatbotPromptsConfig(GradioModel):
# Ant Design X welcome props: https://x.ant.design/components/welcome
class ChatbotWelcomeConfig(GradioModel):
variant: Optional[Literal['borderless', 'filled']] = 'borderless'
- icon: Optional[Union[str, Path]] = None
+ icon: Optional[Union[str, Path, dict]] = None
title: Optional[str] = None
description: Optional[str] = None
extra: Optional[str] = None
@@ -276,6 +276,8 @@ class ChatbotDataFileContentOptions(GradioModel):
gap: Optional[Union[Literal["small", "middle", "large"], str, int,
float]] = "small"
image_props: Optional[dict] = None
+ video_props: Optional[dict] = None
+ audio_props: Optional[dict] = None
# Ant Design X prompts props: https://x.ant.design/components/prompts
@@ -317,7 +319,8 @@ class ChatbotDataMessageContent(GradioModel):
class ChatbotDataMessage(ChatbotBotConfig):
- role: Union[Literal['user', 'assistant', 'system'], str] = None
+ role: Union[Literal['user', 'assistant', 'system', 'divider'], str] = None
+ divider_props: Optional[dict] = None
key: Optional[Union[str, int, float]] = None
# If status is 'pending', the message will not render the footer area (including 'actions' and 'footer').
status: Optional[Literal['pending', 'done']] = None
diff --git a/docs/components/pro/chatbot/demos/multimodal.py b/docs/components/pro/chatbot/demos/multimodal.py
index 1d0b11dd..bd495449 100644
--- a/docs/components/pro/chatbot/demos/multimodal.py
+++ b/docs/components/pro/chatbot/demos/multimodal.py
@@ -19,7 +19,7 @@
api_key=os.getenv("MODELSCOPE_ACCESS_TOKEN"), # ModelScope Token
)
-model = "Qwen/Qwen2.5-VL-72B-Instruct"
+model = "Qwen/Qwen3-VL-8B-Instruct"
def prompt_select(input_value, e: gr.EventData):
diff --git a/docs/components/pro/multimodal_input/README-zh_CN.md b/docs/components/pro/multimodal_input/README-zh_CN.md
index 95ae0d42..f966a55a 100644
--- a/docs/components/pro/multimodal_input/README-zh_CN.md
+++ b/docs/components/pro/multimodal_input/README-zh_CN.md
@@ -39,11 +39,16 @@
| placeholder | `str \| None` | None | 输入框的提示信息。 |
| disabled | `bool \| None` | None | 是否禁用。 |
| upload_config | `MultimodalInputUploadConfig \| dict \| None` | None | 文件上传配置。 |
+| slot_config | `dict \| None` | None | 词槽配置，配置后输入框将变为词槽模式，支持结构化输入，此模式 value 配置将无效。 |
+| skill | `dict \| None` | None | 技能配置，输入框将变为词槽模式，支持结构化输入，此模式 value 配置将无效。 |
### 插槽
```python
-SLOTS=['actions', "prefix", 'footer', 'header']
+SLOTS = [
+ 'suffix', 'header', 'prefix', 'footer', 'skill.title',
+ 'skill.toolTip.title', 'skill.closable.closeIcon'
+]
```
### 类型
@@ -110,5 +115,4 @@ class MultimodalInputUploadConfig(GradioModel):
class MultimodalInputValue(GradioModel):
files: Optional[ListFiles] = None
text: Optional[str] = None
-
```
diff --git a/docs/components/pro/multimodal_input/README.md b/docs/components/pro/multimodal_input/README.md
index f3ecec28..b7bbe126 100644
--- a/docs/components/pro/multimodal_input/README.md
+++ b/docs/components/pro/multimodal_input/README.md
@@ -28,22 +28,27 @@ A multimodal input component based on [Ant Design X](https://x.ant.design), supp
### Props
-| Attribute | Type | Default Value | Description |
-| ------------- | -------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------- |
-| value | `dict \| MultimodalInputValue \| None` | None | Default value to display, formatted as `{ "text":"", "files":[] }`. |
-| loading | `bool \| None` | None | Whether the input is in a loading state, in which case the `cancel` event can be triggered. |
-| mode | `inline \| block` | 'inline' | The rending mode of the input box. If `block`, the input box and the submit button will be rendered separately. |
-| auto_size | `bool \| { minRows?: number; maxRows?: number } \| None` | { "maxRows": 8 } | Height auto size feature, can be set to True \| False or an object { "minRows": 2, "maxRows": 6 }. |
-| read_only | `bool \| None` | None | Whether the input is read-only. |
-| submit_type | `Literal['enter', 'shiftEnter'] \| None` | 'enter' | How the input box triggers the `submit` event. |
-| placeholder | `str \| None` | None | Input placeholder text. |
-| disabled | `bool \| None` | None | Whether to disable. |
-| upload_config | `MultimodalInputUploadConfig \| dict \| None` | None | File upload configuration. |
+| Attribute | Type | Default Value | Description |
+| ------------- | -------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| value | `dict \| MultimodalInputValue \| None` | None | Default value to display, formatted as `{ "text":"", "files":[] }`. |
+| loading | `bool \| None` | None | Whether the input is in a loading state, in which case the `cancel` event can be triggered. |
+| mode | `inline \| block` | 'inline' | The rending mode of the input box. If `block`, the input box and the submit button will be rendered separately. |
+| auto_size | `bool \| { minRows?: number; maxRows?: number } \| None` | { "maxRows": 8 } | Height auto size feature, can be set to True \| False or an object { "minRows": 2, "maxRows": 6 }. |
+| read_only | `bool \| None` | None | Whether the input is read-only. |
+| submit_type | `Literal['enter', 'shiftEnter'] \| None` | 'enter' | How the input box triggers the `submit` event. |
+| placeholder | `str \| None` | None | Input placeholder text. |
+| disabled | `bool \| None` | None | Whether to disable. |
+| upload_config | `MultimodalInputUploadConfig \| dict \| None` | None | File upload configuration. |
+| slot_config | `dict \| None` | None | Slot configuration, after configuration the input box will switch to slot mode, supporting structured input. In this mode, value configurations will be invalid. |
+| skill | `dict \| None` | None | Skill configuration, after configuration the input box will switch to slot mode, supporting structured input. In this mode, value configurations will be invalid. |
### Slots
```python
-SLOTS=['actions', "prefix", 'footer', 'header']
+SLOTS = [
+ 'suffix', 'header', 'prefix', 'footer', 'skill.title',
+ 'skill.toolTip.title', 'skill.closable.closeIcon'
+]
```
### Types
@@ -106,6 +111,7 @@ class MultimodalInputUploadConfig(GradioModel):
}
})
+
class MultimodalInputValue(GradioModel):
files: Optional[ListFiles] = None
text: Optional[str] = None
diff --git a/docs/helper/Site.py b/docs/helper/Site.py
index 26eca9a1..bdb7e8f8 100644
--- a/docs/helper/Site.py
+++ b/docs/helper/Site.py
@@ -32,6 +32,7 @@ def _render_docs(self, items: list, tab: dict):
if key in tab_docs:
with antd.Tabs.Item(
key=key,
+ additional_props=dict(ms_auto_loading=False),
visible=True if tab.get("default_active_key")
== key else False) as docs_tab:
docs_tabs.append(docs_tab)
@@ -57,20 +58,22 @@ def on_tab_menu_select(e: gr.EventData):
for category in self.docs:
for component in self.docs[category]:
css += self.docs[category][component].get_css()
- with gr.Blocks(css=css + """
+ css = css + """
.gradio-container {
max-width: 100% !important;
padding: 0 !important;
}
-.gradio-container > main.fillable {
+.gradio-container > .main.fillable {
max-width: 100% !important;
padding: 0 !important;
+ margin:0 !important;
}
.docs-layout-sider {
width: 100% !important;
max-width: 100% !important;
}
-""") as demo:
+"""
+ with gr.Blocks() as demo:
with ms.Application() as app:
with antd.ConfigProvider():
with antd.Layout(elem_style=dict(
@@ -105,6 +108,8 @@ def on_tab_menu_select(e: gr.EventData):
for tab in self.tabs:
with antd.Tabs.Item(
key=tab["key"],
+ additional_props=dict(
+ ms_auto_loading=False),
elem_style=dict(
height=
"calc(100vh - var(--size-4) - var(--body-text-size) * 1.5 - 64px)"
@@ -167,7 +172,10 @@ def on_tab_menu_select(e: gr.EventData):
else:
tab["extra_menu_footer"].render(
)
- with antd.Splitter.Panel():
+ with antd.Splitter.Panel(
+ elem_style=dict(
+ overflow="auto"
+ )):
with antd.Layout(
elem_style=dict(
width=
@@ -251,4 +259,4 @@ def on_app_mount(e: gr.EventData):
tab_menu.select(
fn=on_tab_menu_select,
outputs=[tab_menu, tabs, *tab_components])
- return demo
+ return demo, css
diff --git a/docs/layout_templates/chatbot/demos/basic.py b/docs/layout_templates/chatbot/demos/basic.py
index 5bf8cdbf..a9e54b20 100644
--- a/docs/layout_templates/chatbot/demos/basic.py
+++ b/docs/layout_templates/chatbot/demos/basic.py
@@ -25,7 +25,7 @@
api_key=MODELSCOPE_ACCESS_TOKEN,
)
-model = "Qwen/Qwen2.5-VL-72B-Instruct"
+model = "Qwen/Qwen3-VL-8B-Instruct"
save_history = False
@@ -468,7 +468,7 @@ def logo():
ms.Span("Chatbot")
-with gr.Blocks(css=css, fill_width=True) as demo:
+with gr.Blocks(fill_width=True) as demo:
state = gr.State({
"conversations_history": {},
"conversations": [],
@@ -476,7 +476,8 @@ def logo():
})
with ms.Application(), antdx.XProvider(
- theme=DEFAULT_THEME, locale=DEFAULT_LOCALE), ms.AutoLoading():
+ theme_config=DEFAULT_THEME,
+ locale=DEFAULT_LOCALE), ms.AutoLoading():
with antd.Row(gutter=[20, 20], wrap=False, elem_id="chatbot"):
# Left Column
with antd.Col(md=dict(flex="0 0 260px", span=24, order=0),
@@ -694,4 +695,4 @@ def logo():
queue=False)
if __name__ == "__main__":
- demo.queue().launch(ssr_mode=False)
+ demo.queue().launch(css=css, ssr_mode=False)
diff --git a/docs/layout_templates/chatbot/demos/copilot.py b/docs/layout_templates/chatbot/demos/copilot.py
index ac88cdfb..33c29ea0 100644
--- a/docs/layout_templates/chatbot/demos/copilot.py
+++ b/docs/layout_templates/chatbot/demos/copilot.py
@@ -19,7 +19,7 @@
api_key=os.getenv("MODELSCOPE_ACCESS_TOKEN"), # ModelScope Token
)
-model = "Qwen/Qwen2.5-72B-Instruct"
+model = "Qwen/Qwen3-VL-8B-Instruct"
def prompt_select(input_value, e: gr.EventData):
@@ -171,7 +171,7 @@ def resize_window(e: gr.EventData):
}
"""
-with gr.Blocks(css=css) as demo, ms.Application() as app, antdx.XProvider():
+with gr.Blocks() as demo, ms.Application() as app, antdx.XProvider():
with antd.Row(elem_classes="copilot-container", wrap=True):
# Content column
with antd.Col(md=16, xs=24,
@@ -322,4 +322,4 @@ def resize_window(e: gr.EventData):
fn=resize_window,
outputs=[copilot_open_btn, copilot_close_btn])
if __name__ == "__main__":
- demo.queue().launch()
+ demo.queue().launch(css=css)
diff --git a/docs/layout_templates/chatbot/demos/fine_grained_control.py b/docs/layout_templates/chatbot/demos/fine_grained_control.py
index b32234f1..6171f333 100644
--- a/docs/layout_templates/chatbot/demos/fine_grained_control.py
+++ b/docs/layout_templates/chatbot/demos/fine_grained_control.py
@@ -18,7 +18,7 @@
api_key=MODELSCOPE_ACCESS_TOKEN,
)
-model = "Qwen/Qwen2.5-VL-72B-Instruct"
+model = "Qwen/Qwen3-VL-8B-Instruct"
save_history = False
@@ -525,7 +525,7 @@ def logo():
ms.Span("Chatbot")
-with gr.Blocks(css=css, fill_width=True) as demo:
+with gr.Blocks(fill_width=True) as demo:
state = gr.State({
"conversations_history": {},
"conversations": [],
@@ -535,7 +535,8 @@ def logo():
})
with ms.Application(), antdx.XProvider(
- theme=DEFAULT_THEME, locale=DEFAULT_LOCALE), ms.AutoLoading():
+ theme_config=DEFAULT_THEME,
+ locale=DEFAULT_LOCALE), ms.AutoLoading():
with antd.Row(gutter=[20, 20], wrap=False, elem_id="chatbot"):
# Left Column
with antd.Col(md=dict(flex="0 0 260px", span=24, order=0),
@@ -575,14 +576,16 @@ def logo():
with antdx.Bubble.List(
items=DEFAULT_CONVERSATIONS_HISTORY,
elem_classes="chatbot-chat-messages") as chatbot:
- # Define Chatbot Roles
- with ms.Slot("roles"):
+ # Define Chatbot Role
+ with ms.Slot("role"):
# Placeholder Role
with antdx.Bubble.List.Role(
role="placeholder",
- styles=dict(content=dict(width="100%")),
+ styles=dict(content=dict(width="100%"),
+ root=dict(paddingInlineEnd=0),
+ body=dict(width='100%')),
variant="borderless"):
- with ms.Slot("messageRender"):
+ with ms.Slot("contentRender"):
with antd.Space(
direction="vertical",
size=16,
@@ -633,12 +636,12 @@ def logo():
with antd.Avatar():
with ms.Slot("icon"):
antd.Icon("UserOutlined")
- with ms.Slot("messageRender",
+ with ms.Slot("contentRender",
params_mapping="""(content) => {
if (typeof content === 'string') {
return { content, files: [], files_container: { style: { display: 'none' }} }
}
- return { content: content.text, files_container: content.files?.length > 0 ? undefined : { style: { display: 'none' }}, files: (content.files || []).map(file => ({ item: file }))}
+ return { content: content.text, files_container: content.files?.length > 0 ? undefined : { style: { display: 'none' }}, files: (content.files || []).map(file => file)}
}"""):
with antd.Flex(vertical=True,
@@ -648,16 +651,17 @@ def logo():
wrap=True,
as_item="files_container"):
with ms.Each(as_item="files"):
- antdx.Attachments.FileCard()
+ antdx.FileCard()
ms.Markdown(as_item="content")
with ms.Slot("footer",
- params_mapping="""(bubble) => {
+ params_mapping=
+ """(content, info, bubble) => {
return {
copy_btn: {
copyable: { text: typeof bubble.content === 'string' ? bubble.content : bubble.content?.text, tooltips: false },
},
- edit_btn: { conversationKey: bubble.key, disabled: bubble.meta.disabled },
- delete_btn: { conversationKey: bubble.key, disabled: bubble.meta.disabled },
+ edit_btn: { conversationKey: bubble.key, disabled: bubble.meta?.disabled },
+ delete_btn: { conversationKey: bubble.key, disabled: bubble.meta?.disabled },
};
}"""):
with antd.Typography.Text(
@@ -712,9 +716,9 @@ def logo():
with antd.Avatar():
with ms.Slot("icon"):
antd.Icon("RobotOutlined")
- with ms.Slot(
- "messageRender",
- params_mapping="""(content, bubble) => {
+ with ms.Slot("contentRender",
+ params_mapping=
+ """(content, info, bubble) => {
if (bubble.meta?.canceled) {
return { value: content }
}
@@ -727,15 +731,16 @@ def logo():
as_item="canceled",
type="warning")
with ms.Slot("footer",
- params_mapping="""(bubble) => {
+ params_mapping=
+ """(content, info, bubble) => {
if (bubble?.meta?.end) {
return {
copy_btn: {
copyable: { text: bubble.content, tooltips: false },
},
- regenerate_btn: { conversationKey: bubble.key, disabled: bubble.meta.disabled },
- delete_btn: { conversationKey: bubble.key, disabled: bubble.meta.disabled },
- edit_btn: { conversationKey: bubble.key, disabled: bubble.meta.disabled },
+ regenerate_btn: { conversationKey: bubble.key, disabled: bubble.meta?.disabled },
+ delete_btn: { conversationKey: bubble.key, disabled: bubble.meta?.disabled },
+ edit_btn: { conversationKey: bubble.key, disabled: bubble.meta?.disabled },
like_btn: {
conversationKey: bubble.key,
color: bubble.meta?.action === 'like' ? 'primary' : 'default',
@@ -1034,4 +1039,4 @@ def logo():
queue=False)
if __name__ == "__main__":
- demo.queue().launch(ssr_mode=False)
+ demo.queue().launch(css=css, ssr_mode=False)
diff --git a/docs/layout_templates/coder_artifacts/demos/app.py b/docs/layout_templates/coder_artifacts/demos/app.py
index 302e8e97..45cb2702 100644
--- a/docs/layout_templates/coder_artifacts/demos/app.py
+++ b/docs/layout_templates/coder_artifacts/demos/app.py
@@ -15,7 +15,7 @@
client = OpenAI(api_key=MODELSCOPE_ACCESS_TOKEN,
base_url="https://api-inference.modelscope.cn/v1")
-model = "Qwen/Qwen2.5-Coder-32B-Instruct"
+model = "Qwen/Qwen3-Coder-480B-A35B-Instruct"
# =========== Configuration
DEFAULT_SYSTEM_PROMPT = """You are a web development engineer, writing web pages according to the instructions below. You are a powerful code editing assistant capable of writing code and creating artifacts in conversations with users, or modifying and updating existing artifacts as requested by users.
@@ -212,16 +212,17 @@ def clear_history(e: gr.EventData, state_value):
#coder-artifacts-code-drawer .output-code {
flex:1;
}
-#coder-artifacts-code-drawer .output-code .ms-gr-ant-spin-nested-loading {
+#coder-artifacts-code-drawer .output-code .ms-gr-ant-spin {
min-height: 100%;
}
"""
-with gr.Blocks(css=css) as demo:
+with gr.Blocks() as demo:
# Global State
state = gr.State({"system_prompt": DEFAULT_SYSTEM_PROMPT, "history": []})
with ms.Application(elem_id="coder-artifacts") as app:
- with antd.ConfigProvider(theme=DEFAULT_THEME, locale=DEFAULT_LOCALE):
+ with antd.ConfigProvider(theme_config=DEFAULT_THEME,
+ locale=DEFAULT_LOCALE):
# Header
with antd.Flex(justify="center", align="center", gap="middle"):
antd.Typography.Title("Coder-Artifacts",
@@ -382,7 +383,6 @@ def clear_history(e: gr.EventData, state_value):
width="750px") as history_drawer:
history_output = gr.Chatbot(
show_label=False,
- type="messages",
height='100%',
elem_classes="history_chatbot")
# Tour
@@ -476,4 +476,4 @@ def clear_history(e: gr.EventData, state_value):
outputs=[output_code_drawer])
if __name__ == "__main__":
- demo.queue().launch(ssr_mode=False)
+ demo.queue().launch(css=css, ssr_mode=False)
diff --git a/docs/legacy_app.py b/docs/legacy_app.py
deleted file mode 100644
index d7b855df..00000000
--- a/docs/legacy_app.py
+++ /dev/null
@@ -1,6 +0,0 @@
-from components.legacy.app import legacy_demo
-
-demo = legacy_demo
-
-if __name__ == "__main__":
- demo.launch()
diff --git a/docs/requirements.txt b/docs/requirements.txt
index ce3aef6b..f2402e34 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,3 @@
gradio==5.34.1
-modelscope_studio==1.6.1
+modelscope_studio==2.0.0-beta.1
openai
diff --git a/docs/src/pyproject.toml b/docs/src/pyproject.toml
index 9b7984c0..fd4e02ea 100644
--- a/docs/src/pyproject.toml
+++ b/docs/src/pyproject.toml
@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
[project]
name = "modelscope_studio"
-version = "1.6.1"
+version = "2.0.0-beta.1"
description = "A third-party component library based on Gradio."
readme = "README.md"
license = "Apache-2.0"
@@ -45,12 +45,6 @@ dev = ["build", "twine"]
[tool.hatch.build]
artifacts = [
"*.pyi",
- "backend/modelscope_studio/components/legacy/Chatbot/templates",
- "backend/modelscope_studio/components/legacy/Flow/templates",
- "backend/modelscope_studio/components/legacy/MultimodalInput/templates",
- "backend/modelscope_studio/components/legacy/Markdown/templates",
- "backend/modelscope_studio/components/legacy/WaterfallGallery/templates",
- "/backend/modelscope_studio/components/legacy/Lifecycle/templates",
"/backend/modelscope_studio/components/antd/button/templates",
"/backend/modelscope_studio/components/antd/card/templates",
"/backend/modelscope_studio/components/antd/card/grid/templates",
@@ -198,11 +192,6 @@ artifacts = [
"/backend/modelscope_studio/components/antd/upload/dragger/templates",
"/backend/modelscope_studio/components/antd/splitter/templates",
"/backend/modelscope_studio/components/antd/splitter/panel/templates",
- "/backend/modelscope_studio/components/legacy/Chatbot/templates",
- "/backend/modelscope_studio/components/legacy/Flow/templates",
- "/backend/modelscope_studio/components/legacy/Markdown/templates",
- "/backend/modelscope_studio/components/legacy/MultimodalInput/templates",
- "/backend/modelscope_studio/components/legacy/WaterfallGallery/templates",
"/backend/modelscope_studio/components/antd/form/provider/templates",
"/backend/modelscope_studio/components/antd/modal/static/templates",
"/backend/modelscope_studio/components/antdx/bubble/templates",
diff --git a/frontend/CHANGELOG.md b/frontend/CHANGELOG.md
index 0d0056cb..132b9a99 100644
--- a/frontend/CHANGELOG.md
+++ b/frontend/CHANGELOG.md
@@ -1,5 +1,17 @@
# @modelscope-studio/frontend
+## 2.0.0-beta.1
+
+### Features
+
+- [`e009cd0`](https://github.com/modelscope/modelscope-studio/commit/e009cd0408d4505f4105e494af192c6f832fa48c) - complete new features of antd & antdx. Thanks [@Col0ring](https://github.com/Col0ring)!
+
+## 2.0.0-beta.0
+
+### Misc Changes
+
+- [`26ea248`](https://github.com/modelscope/modelscope-studio/commit/26ea2485990098ea60e95ff8b3e71dad713a3aba) - migrate to Gradio 6.0, Ant Design 6.0, Ant Design X 2.0. Thanks [@Col0ring](https://github.com/Col0ring)!
+
## 1.6.1
No significant changes to this package were made in this release.
diff --git a/frontend/antd/CHANGELOG.md b/frontend/antd/CHANGELOG.md
index 65ec8e36..9ccb4d98 100644
--- a/frontend/antd/CHANGELOG.md
+++ b/frontend/antd/CHANGELOG.md
@@ -1,5 +1,17 @@
# @modelscope-studio/antd
+## 2.0.0-beta.1
+
+### Features
+
+- [`e009cd0`](https://github.com/modelscope/modelscope-studio/commit/e009cd0408d4505f4105e494af192c6f832fa48c) - complete new features of antd & antdx. Thanks [@Col0ring](https://github.com/Col0ring)!
+
+## 2.0.0-beta.0
+
+### Misc Changes
+
+- [`26ea248`](https://github.com/modelscope/modelscope-studio/commit/26ea2485990098ea60e95ff8b3e71dad713a3aba) - migrate to Gradio 6.0, Ant Design 6.0, Ant Design X 2.0. Thanks [@Col0ring](https://github.com/Col0ring)!
+
## 1.6.1
No significant changes to this package were made in this release.
diff --git a/frontend/antd/affix/Index.svelte b/frontend/antd/affix/Index.svelte
index 1e2cb70c..1597e2eb 100644
--- a/frontend/antd/affix/Index.svelte
+++ b/frontend/antd/affix/Index.svelte
@@ -1,75 +1,68 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/affix/package.json b/frontend/antd/affix/package.json
index 97da442b..567eca5b 100644
--- a/frontend/antd/affix/package.json
+++ b/frontend/antd/affix/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/alert/Index.svelte b/frontend/antd/alert/Index.svelte
index aa2c3668..5ebe4440 100644
--- a/frontend/antd/alert/Index.svelte
+++ b/frontend/antd/alert/Index.svelte
@@ -1,70 +1,62 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/alert/alert.tsx b/frontend/antd/alert/alert.tsx
index 177c4872..0c139802 100644
--- a/frontend/antd/alert/alert.tsx
+++ b/frontend/antd/alert/alert.tsx
@@ -4,6 +4,13 @@ import React from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { Alert as AAlert, type GetProps } from 'antd';
+function getConfig(value: T): Partial> {
+ if (typeof value === 'object' && value !== null) {
+ return value as any;
+ }
+ return {} as any;
+}
+
export const Alert = sveltify<
GetProps & {
children?: React.ReactNode;
@@ -11,6 +18,8 @@ export const Alert = sveltify<
['action', 'closable.closeIcon', 'description', 'icon', 'message']
>(({ slots, afterClose, children, ...props }) => {
const afterCloseFunction = useFunction(afterClose);
+ const closableConfig = getConfig(props.closable);
+ const closableAfterCloseFunction = useFunction(closableConfig.afterClose);
return (
<>
-
{/await}
{/if}
diff --git a/frontend/antd/alert/error-boundary/package.json b/frontend/antd/alert/error-boundary/package.json
index 81358d1f..1f06e225 100644
--- a/frontend/antd/alert/error-boundary/package.json
+++ b/frontend/antd/alert/error-boundary/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/alert/package.json b/frontend/antd/alert/package.json
index 08fb77c3..4cbf0891 100644
--- a/frontend/antd/alert/package.json
+++ b/frontend/antd/alert/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/anchor/Index.svelte b/frontend/antd/anchor/Index.svelte
index fda27a02..ba3bae81 100644
--- a/frontend/antd/anchor/Index.svelte
+++ b/frontend/antd/anchor/Index.svelte
@@ -1,70 +1,62 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/anchor/item/Index.svelte b/frontend/antd/anchor/item/Index.svelte
index d072b51b..df06df1f 100644
--- a/frontend/antd/anchor/item/Index.svelte
+++ b/frontend/antd/anchor/item/Index.svelte
@@ -1,83 +1,74 @@
-
- {#if $mergedProps.visible}
-
{/await}
diff --git a/frontend/antd/anchor/item/package.json b/frontend/antd/anchor/item/package.json
index 8a407e76..0f8defe1 100644
--- a/frontend/antd/anchor/item/package.json
+++ b/frontend/antd/anchor/item/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/anchor/package.json b/frontend/antd/anchor/package.json
index 40ee8290..7b9f83f5 100644
--- a/frontend/antd/anchor/package.json
+++ b/frontend/antd/anchor/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/auto-complete/Index.svelte b/frontend/antd/auto-complete/Index.svelte
index 2294d659..f894e2e1 100644
--- a/frontend/antd/auto-complete/Index.svelte
+++ b/frontend/antd/auto-complete/Index.svelte
@@ -1,85 +1,87 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
- {setSlotParams}
>
-
{/await}
{/if}
diff --git a/frontend/antd/auto-complete/auto-complete.tsx b/frontend/antd/auto-complete/auto-complete.tsx
index 877c3e8e..dd943c10 100644
--- a/frontend/antd/auto-complete/auto-complete.tsx
+++ b/frontend/antd/auto-complete/auto-complete.tsx
@@ -1,7 +1,6 @@
import { sveltify } from '@svelte-preprocess-react';
-import { AutoCompleteContext } from '@svelte-preprocess-react/context';
+import { AutoCompleteContext } from '@svelte-preprocess-react/react-contexts';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { forwardRef, useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { useValueChange } from '@utils/hooks/useValueChange';
@@ -30,10 +29,16 @@ const AutoCompleteChildrenWrapper = forwardRef<
);
});
+function getConfig(value: T): Partial> {
+ if (typeof value === 'object' && value !== null) {
+ return value as any;
+ }
+ return {} as any;
+}
+
export const AutoComplete = sveltify<
GetProps & {
onValueChange: (value: string) => void;
- setSlotParams: SetSlotParams;
},
[
'allowClear.clearIcon',
@@ -55,10 +60,15 @@ export const AutoComplete = sveltify<
getPopupContainer,
dropdownRender,
popupRender,
+ showSearch,
elRef,
- setSlotParams,
...props
}) => {
+ const showSearchConfig = getConfig(showSearch);
+ const showSearchConfigFilterOption = useFunction(
+ showSearchConfig.filterOption
+ );
+
const getPopupContainerFunction = useFunction(getPopupContainer);
const filterOptionFunction = useFunction(filterOption);
const dropdownRenderFunction = useFunction(dropdownRender);
@@ -78,6 +88,16 @@ export const AutoComplete = sveltify<
-
{/await}
{/if}
diff --git a/frontend/antd/auto-complete/option/package.json b/frontend/antd/auto-complete/option/package.json
index cc09764f..593db2ec 100644
--- a/frontend/antd/auto-complete/option/package.json
+++ b/frontend/antd/auto-complete/option/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/auto-complete/package.json b/frontend/antd/auto-complete/package.json
index 511f48a1..4e15dfd0 100644
--- a/frontend/antd/auto-complete/package.json
+++ b/frontend/antd/auto-complete/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/avatar/Index.svelte b/frontend/antd/avatar/Index.svelte
index c5068973..a4f31417 100644
--- a/frontend/antd/avatar/Index.svelte
+++ b/frontend/antd/avatar/Index.svelte
@@ -1,84 +1,75 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/avatar/group/Index.svelte b/frontend/antd/avatar/group/Index.svelte
index 8a0568c1..32ab4d65 100644
--- a/frontend/antd/avatar/group/Index.svelte
+++ b/frontend/antd/avatar/group/Index.svelte
@@ -1,74 +1,61 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/avatar/group/package.json b/frontend/antd/avatar/group/package.json
index 9353d3bd..28ee1871 100644
--- a/frontend/antd/avatar/group/package.json
+++ b/frontend/antd/avatar/group/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/avatar/package.json b/frontend/antd/avatar/package.json
index 433e0199..20ea887c 100644
--- a/frontend/antd/avatar/package.json
+++ b/frontend/antd/avatar/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/badge/Index.svelte b/frontend/antd/badge/Index.svelte
index 88aeeadf..9a5a414f 100644
--- a/frontend/antd/badge/Index.svelte
+++ b/frontend/antd/badge/Index.svelte
@@ -1,74 +1,64 @@
-
-
{:else}
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/badge/ribbon/package.json b/frontend/antd/badge/ribbon/package.json
index 2ca52113..ad384563 100644
--- a/frontend/antd/badge/ribbon/package.json
+++ b/frontend/antd/badge/ribbon/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/breadcrumb/Index.svelte b/frontend/antd/breadcrumb/Index.svelte
index a8487ee9..d4210350 100644
--- a/frontend/antd/breadcrumb/Index.svelte
+++ b/frontend/antd/breadcrumb/Index.svelte
@@ -1,86 +1,77 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/breadcrumb/breadcrumb.tsx b/frontend/antd/breadcrumb/breadcrumb.tsx
index 35dc6a78..49d9dc75 100644
--- a/frontend/antd/breadcrumb/breadcrumb.tsx
+++ b/frontend/antd/breadcrumb/breadcrumb.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React, { useMemo } from 'react';
import { renderItems } from '@utils/renderItems';
import { renderParamsSlot } from '@utils/renderParamsSlot';
@@ -10,14 +9,12 @@ import type { ItemType } from 'antd/es/breadcrumb/Breadcrumb';
import { useItems, withItemsContextProvider } from './context';
export const Breadcrumb = sveltify<
- GetProps & {
- setSlotParams: SetSlotParams;
- },
- ['separator', 'itemRender']
+ GetProps,
+ ['separator', 'itemRender', 'dropdownIcon']
>(
withItemsContextProvider(
['default', 'items'],
- ({ slots, items, setSlotParams, children, ...props }) => {
+ ({ slots, items, children, ...props }) => {
const { items: slotItems } = useItems<['default', 'items']>();
const resolvedSlotItems =
slotItems.items.length > 0 ? slotItems.items : slotItems.default;
@@ -26,11 +23,17 @@ export const Breadcrumb = sveltify<
- {#if $mergedProps.visible}
-
{/await}
diff --git a/frontend/antd/breadcrumb/item/breadcrumb.item.tsx b/frontend/antd/breadcrumb/item/breadcrumb.item.tsx
index 996b54c5..01ebbcbb 100644
--- a/frontend/antd/breadcrumb/item/breadcrumb.item.tsx
+++ b/frontend/antd/breadcrumb/item/breadcrumb.item.tsx
@@ -1,5 +1,4 @@
import { sveltify } from '@svelte-preprocess-react';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React from 'react';
import { createFunction } from '@utils/createFunction';
import { renderItems } from '@utils/renderItems';
@@ -16,13 +15,25 @@ import { ItemHandler, type ItemHandlerProps } from '../context';
export const BreadcrumbItem = sveltify<
BreadcrumbItemProps &
ItemHandlerProps & {
- setSlotParams: SetSlotParams;
- itemSlots: Record;
+ itemSlots: Record<
+ [
+ 'title',
+ 'menu.expandIcon',
+ 'menu.overflowedIndicator',
+ 'menu.items',
+ 'dropdownProps.dropdownRender',
+ 'dropdownProps.popupRender',
+ 'dropdownProps.menu.expandIcon',
+ 'dropdownProps.menu.overflowedIndicator',
+ 'dropdownProps.menu.items',
+ ][number],
+ HTMLElement
+ >;
}
>(
withMenuItemsContextProvider(
['menu.items', 'dropdownProps.menu.items'],
- ({ setSlotParams, itemSlots: slots, ...props }) => {
+ ({ itemSlots: slots, ...props }) => {
const {
items: {
'menu.items': menuItems,
@@ -36,7 +47,7 @@ export const BreadcrumbItem = sveltify<
const menu = {
...(itemProps.menu || {}),
items:
- itemProps.menu?.items || menuItems.length > 0
+ itemProps.menu?.items || menuItems?.length > 0
? renderItems(menuItems, {
clone: true,
})
@@ -44,7 +55,6 @@ export const BreadcrumbItem = sveltify<
expandIcon:
renderParamsSlot(
{
- setSlotParams,
slots: slots,
key: 'menu.expandIcon',
},
@@ -60,7 +70,7 @@ export const BreadcrumbItem = sveltify<
...(itemProps.dropdownProps?.menu || {}),
items:
itemProps.dropdownProps?.menu?.items ||
- dropdownMenuItems.length > 0
+ dropdownMenuItems?.length > 0
? renderItems(dropdownMenuItems, {
clone: true,
})
@@ -68,7 +78,6 @@ export const BreadcrumbItem = sveltify<
expandIcon:
renderParamsSlot(
{
- setSlotParams,
slots: slots,
key: 'dropdownProps.menu.expandIcon',
},
@@ -86,7 +95,6 @@ export const BreadcrumbItem = sveltify<
dropdownRender: slots['dropdownProps.dropdownRender']
? renderParamsSlot(
{
- setSlotParams,
slots: slots,
key: 'dropdownProps.dropdownRender',
},
@@ -98,7 +106,6 @@ export const BreadcrumbItem = sveltify<
popupRender: slots['dropdownProps.popupRender']
? renderParamsSlot(
{
- setSlotParams,
slots: slots,
key: 'dropdownProps.popupRender',
},
@@ -112,8 +119,10 @@ export const BreadcrumbItem = sveltify<
? dropdownMenu
: undefined,
};
+
return {
...itemProps,
+ title: renderSlot(slots.title) || itemProps.title,
menu:
Object.values(menu).filter(Boolean).length > 0
? menu
diff --git a/frontend/antd/breadcrumb/item/package.json b/frontend/antd/breadcrumb/item/package.json
index 5bc17e02..9352277f 100644
--- a/frontend/antd/breadcrumb/item/package.json
+++ b/frontend/antd/breadcrumb/item/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/breadcrumb/package.json b/frontend/antd/breadcrumb/package.json
index 79d543ea..b3938a9f 100644
--- a/frontend/antd/breadcrumb/package.json
+++ b/frontend/antd/breadcrumb/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/button/Index.svelte b/frontend/antd/button/Index.svelte
index 0ebbd2de..b400ede0 100644
--- a/frontend/antd/button/Index.svelte
+++ b/frontend/antd/button/Index.svelte
@@ -1,83 +1,73 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/button/group/package.json b/frontend/antd/button/group/package.json
index 2a274c55..26eba872 100644
--- a/frontend/antd/button/group/package.json
+++ b/frontend/antd/button/group/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/button/package.json b/frontend/antd/button/package.json
index 7c409d28..dd5a6047 100644
--- a/frontend/antd/button/package.json
+++ b/frontend/antd/button/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/calendar/Index.svelte b/frontend/antd/calendar/Index.svelte
index d94f23c9..eaf5005b 100644
--- a/frontend/antd/calendar/Index.svelte
+++ b/frontend/antd/calendar/Index.svelte
@@ -1,85 +1,83 @@
- {
- value = val;
+ updateProps({
+ value: val,
+ });
}}
- {setSlotParams}
>
-
{/await}
{/if}
diff --git a/frontend/antd/calendar/calendar.tsx b/frontend/antd/calendar/calendar.tsx
index 5b0eaf3e..4e4f7b63 100644
--- a/frontend/antd/calendar/calendar.tsx
+++ b/frontend/antd/calendar/calendar.tsx
@@ -1,5 +1,4 @@
import { sveltify } from '@svelte-preprocess-react';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderParamsSlot } from '@utils/renderParamsSlot';
@@ -21,7 +20,6 @@ export const Calendar = sveltify<
onPanelChange?: (date: number, ...args: any[]) => void;
onSelect?: (date: number, ...args: any[]) => void;
onValueChange: (date: number) => void;
- setSlotParams: SetSlotParams;
children?: React.ReactNode;
},
['cellRender', 'fullCellRender', 'headerRender']
@@ -35,7 +33,6 @@ export const Calendar = sveltify<
onPanelChange,
onSelect,
onValueChange,
- setSlotParams,
cellRender,
fullCellRender,
headerRender,
@@ -69,21 +66,20 @@ export const Calendar = sveltify<
disabledDate={disabledDateFunction}
cellRender={
slots.cellRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'cellRender' })
+ ? renderParamsSlot({ slots, key: 'cellRender' })
: cellRenderFunction
}
fullCellRender={
slots.fullCellRender
? renderParamsSlot({
slots,
- setSlotParams,
key: 'fullCellRender',
})
: fullCellRenderFunction
}
headerRender={
slots.headerRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'headerRender' })
+ ? renderParamsSlot({ slots, key: 'headerRender' })
: headerRenderFunction
}
onChange={(date, ...args) => {
diff --git a/frontend/antd/calendar/package.json b/frontend/antd/calendar/package.json
index 08c25085..4f970df6 100644
--- a/frontend/antd/calendar/package.json
+++ b/frontend/antd/calendar/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/card/Index.svelte b/frontend/antd/card/Index.svelte
index 5f34b190..ebeeed23 100644
--- a/frontend/antd/card/Index.svelte
+++ b/frontend/antd/card/Index.svelte
@@ -1,77 +1,67 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/card/card.tsx b/frontend/antd/card/card.tsx
index 693f5ead..8aa6caaa 100644
--- a/frontend/antd/card/card.tsx
+++ b/frontend/antd/card/card.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React, { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { useTargets } from '@utils/hooks/useTargets';
@@ -17,7 +16,6 @@ import {
export const Card = sveltify<
GetProps & {
containsGrid?: boolean;
- setSlotParams: SetSlotParams;
},
[
'actions',
@@ -38,15 +36,7 @@ export const Card = sveltify<
>(
withTabsItemsContextProvider(
['tabList'],
- ({
- children,
- containsGrid,
- slots,
- tabList,
- tabProps,
- setSlotParams,
- ...props
- }) => {
+ ({ children, containsGrid, slots, tabList, tabProps, ...props }) => {
const targets = useTargets(children, 'actions');
const {
items: { tabList: tabListItems },
@@ -71,7 +61,6 @@ export const Card = sveltify<
renderTabBar: slots['tabProps.renderTabBar']
? renderParamsSlot({
slots,
- setSlotParams,
key: 'tabProps.renderTabBar',
})
: renderTabBarFunction,
diff --git a/frontend/antd/card/grid/Index.svelte b/frontend/antd/card/grid/Index.svelte
index 67b08232..2438f197 100644
--- a/frontend/antd/card/grid/Index.svelte
+++ b/frontend/antd/card/grid/Index.svelte
@@ -1,65 +1,59 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/card/grid/package.json b/frontend/antd/card/grid/package.json
index 3289638e..e3b4a347 100644
--- a/frontend/antd/card/grid/package.json
+++ b/frontend/antd/card/grid/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/card/meta/Index.svelte b/frontend/antd/card/meta/Index.svelte
index 18c1b36c..43cf0a64 100644
--- a/frontend/antd/card/meta/Index.svelte
+++ b/frontend/antd/card/meta/Index.svelte
@@ -1,70 +1,59 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/card/meta/package.json b/frontend/antd/card/meta/package.json
index ccd84493..55ac3d74 100644
--- a/frontend/antd/card/meta/package.json
+++ b/frontend/antd/card/meta/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/card/package.json b/frontend/antd/card/package.json
index e4606ae9..23692a8d 100644
--- a/frontend/antd/card/package.json
+++ b/frontend/antd/card/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/carousel/Index.svelte b/frontend/antd/carousel/Index.svelte
index 35df4afc..e350c50f 100644
--- a/frontend/antd/carousel/Index.svelte
+++ b/frontend/antd/carousel/Index.svelte
@@ -1,70 +1,61 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/carousel/package.json b/frontend/antd/carousel/package.json
index 90bdf99f..3752adc0 100644
--- a/frontend/antd/carousel/package.json
+++ b/frontend/antd/carousel/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/cascader/Index.svelte b/frontend/antd/cascader/Index.svelte
index 10ffea6f..a9ec309f 100644
--- a/frontend/antd/cascader/Index.svelte
+++ b/frontend/antd/cascader/Index.svelte
@@ -1,86 +1,83 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
- {setSlotParams}
>
-
{/await}
{/if}
diff --git a/frontend/antd/cascader/cascader.tsx b/frontend/antd/cascader/cascader.tsx
index 97454a13..ef89a880 100644
--- a/frontend/antd/cascader/cascader.tsx
+++ b/frontend/antd/cascader/cascader.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { useValueChange } from '@utils/hooks/useValueChange';
@@ -21,7 +20,6 @@ export const Cascader = sveltify<
CascaderProps & {
onValueChange: (value: string[] | number[]) => void;
onLoadData?: (...args: any[]) => void;
- setSlotParams: SetSlotParams;
},
[
'allowClear.clearIcon',
@@ -36,6 +34,7 @@ export const Cascader = sveltify<
'dropdownRender',
'popupRender',
'showSearch.render',
+ 'optionRender',
]
>(
withItemsContextProvider(
@@ -55,7 +54,6 @@ export const Cascader = sveltify<
optionRender,
showSearch,
options,
- setSlotParams,
onLoadData,
...props
}) => {
@@ -105,7 +103,6 @@ export const Cascader = sveltify<
render: slots['showSearch.render']
? renderParamsSlot({
slots,
- setSlotParams,
key: 'showSearch.render',
})
: showSearchRenderFunction || showSearchConfig.render,
@@ -114,7 +111,14 @@ export const Cascader = sveltify<
: showSearch
}
loadData={onLoadData}
- optionRender={optionRenderFunction}
+ optionRender={
+ slots.optionRender
+ ? renderParamsSlot({
+ slots,
+ key: 'optionRender',
+ })
+ : optionRenderFunction
+ }
getPopupContainer={getPopupContainerFunction}
prefix={
slots.prefix ?
-
{/await}
{/if}
diff --git a/frontend/antd/cascader/option/package.json b/frontend/antd/cascader/option/package.json
index 34248320..4deea527 100644
--- a/frontend/antd/cascader/option/package.json
+++ b/frontend/antd/cascader/option/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/cascader/package.json b/frontend/antd/cascader/package.json
index da29c32a..47946d6d 100644
--- a/frontend/antd/cascader/package.json
+++ b/frontend/antd/cascader/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/cascader/panel/Index.svelte b/frontend/antd/cascader/panel/Index.svelte
index 017e44df..5c9bb290 100644
--- a/frontend/antd/cascader/panel/Index.svelte
+++ b/frontend/antd/cascader/panel/Index.svelte
@@ -1,80 +1,81 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
>
-
{/await}
{/if}
diff --git a/frontend/antd/cascader/panel/cascader.panel.tsx b/frontend/antd/cascader/panel/cascader.panel.tsx
index c11ed03a..5905780e 100644
--- a/frontend/antd/cascader/panel/cascader.panel.tsx
+++ b/frontend/antd/cascader/panel/cascader.panel.tsx
@@ -1,8 +1,10 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
import { useMemo } from 'react';
+import { useFunction } from '@utils/hooks/useFunction';
import { useValueChange } from '@utils/hooks/useValueChange';
import { renderItems } from '@utils/renderItems';
+import { renderParamsSlot } from '@utils/renderParamsSlot';
import { Cascader as ACascader, type CascaderPanelProps } from 'antd';
import { useItems, withItemsContextProvider } from '../context';
@@ -13,7 +15,7 @@ export const CascaderPanel = sveltify<
onLoadData?: (...args: any[]) => void;
children?: React.ReactNode;
},
- ['notFoundContent', 'expandIcon']
+ ['notFoundContent', 'expandIcon', 'optionRender']
>(
withItemsContextProvider(
['default', 'options'],
@@ -30,6 +32,7 @@ export const CascaderPanel = sveltify<
onValueChange,
value: props.value,
});
+ const optionRenderFunction = useFunction(props.optionRender);
const { items: slotItems } = useItems<['default', 'options']>();
const resolvedSlotItems =
slotItems.options.length > 0 ? slotItems.options : slotItems.default;
@@ -39,6 +42,11 @@ export const CascaderPanel = sveltify<
{
return (
options ||
diff --git a/frontend/antd/cascader/panel/package.json b/frontend/antd/cascader/panel/package.json
index 9bb1a881..27954b79 100644
--- a/frontend/antd/cascader/panel/package.json
+++ b/frontend/antd/cascader/panel/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/checkbox/Index.svelte b/frontend/antd/checkbox/Index.svelte
index bb98b92d..ec76fdf3 100644
--- a/frontend/antd/checkbox/Index.svelte
+++ b/frontend/antd/checkbox/Index.svelte
@@ -1,79 +1,77 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/checkbox/checkbox.tsx b/frontend/antd/checkbox/checkbox.tsx
index 9695d686..dc44385c 100644
--- a/frontend/antd/checkbox/checkbox.tsx
+++ b/frontend/antd/checkbox/checkbox.tsx
@@ -11,8 +11,8 @@ export const Checkbox = sveltify<
{...props}
ref={elRef}
onChange={(e) => {
- onChange?.(e);
onValueChange(e.target.checked);
+ onChange?.(e);
}}
/>
);
diff --git a/frontend/antd/checkbox/group/Index.svelte b/frontend/antd/checkbox/group/Index.svelte
index 836544f8..b4f72419 100644
--- a/frontend/antd/checkbox/group/Index.svelte
+++ b/frontend/antd/checkbox/group/Index.svelte
@@ -1,81 +1,75 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/checkbox/group/checkbox.group.tsx b/frontend/antd/checkbox/group/checkbox.group.tsx
index 9c0fa970..c81651bd 100644
--- a/frontend/antd/checkbox/group/checkbox.group.tsx
+++ b/frontend/antd/checkbox/group/checkbox.group.tsx
@@ -16,7 +16,6 @@ export const CheckboxGroup = sveltify<
const { items: slotItems } = useItems<['default', 'options']>();
const resolvedSlotItems =
slotItems.options.length > 0 ? slotItems.options : slotItems.default;
-
return (
<>
- {#if $mergedProps.visible}
-
{/await}
diff --git a/frontend/antd/checkbox/group/option/package.json b/frontend/antd/checkbox/group/option/package.json
index 2518ecef..18793283 100644
--- a/frontend/antd/checkbox/group/option/package.json
+++ b/frontend/antd/checkbox/group/option/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/checkbox/group/package.json b/frontend/antd/checkbox/group/package.json
index caca02f0..bee77759 100644
--- a/frontend/antd/checkbox/group/package.json
+++ b/frontend/antd/checkbox/group/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/checkbox/package.json b/frontend/antd/checkbox/package.json
index aad1d284..2fa1c247 100644
--- a/frontend/antd/checkbox/package.json
+++ b/frontend/antd/checkbox/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/collapse/Index.svelte b/frontend/antd/collapse/Index.svelte
index 347a432d..2373e63d 100644
--- a/frontend/antd/collapse/Index.svelte
+++ b/frontend/antd/collapse/Index.svelte
@@ -1,75 +1,62 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/collapse/collapse.tsx b/frontend/antd/collapse/collapse.tsx
index a22d18b5..564bb8fe 100644
--- a/frontend/antd/collapse/collapse.tsx
+++ b/frontend/antd/collapse/collapse.tsx
@@ -1,5 +1,4 @@
import { sveltify } from '@svelte-preprocess-react';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React, { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderItems } from '@utils/renderItems';
@@ -9,23 +8,10 @@ import { Collapse as ACollapse, type GetProps } from 'antd';
import { useItems, withItemsContextProvider } from './context';
type CollapseProps = GetProps;
-export const Collapse = sveltify<
- CollapseProps & {
- setSlotParams: SetSlotParams;
- },
- ['expandIcon']
->(
+export const Collapse = sveltify(
withItemsContextProvider(
['default', 'items'],
- ({
- slots,
- items,
- children,
- onChange,
- setSlotParams,
- expandIcon,
- ...props
- }) => {
+ ({ slots, items, children, onChange, expandIcon, ...props }) => {
const { items: slotItems } = useItems<['default', 'items']>();
const resolvedSlotItems =
slotItems.items.length > 0 ? slotItems.items : slotItems.default;
@@ -40,7 +26,7 @@ export const Collapse = sveltify<
}}
expandIcon={
slots.expandIcon
- ? renderParamsSlot({ slots, setSlotParams, key: 'expandIcon' })
+ ? renderParamsSlot({ slots, key: 'expandIcon' })
: expandIconFunction
}
items={useMemo(() => {
diff --git a/frontend/antd/collapse/item/Index.svelte b/frontend/antd/collapse/item/Index.svelte
index d64c790c..37757eee 100644
--- a/frontend/antd/collapse/item/Index.svelte
+++ b/frontend/antd/collapse/item/Index.svelte
@@ -1,99 +1,87 @@
-
-
-{#await AwaitedCollapseItem then CollapseItem}
-
- {#if $mergedProps.visible}
-
-
+ {@render children?.()}
{/if}
diff --git a/frontend/antd/collapse/item/package.json b/frontend/antd/collapse/item/package.json
index 0da9d083..66e6d58b 100644
--- a/frontend/antd/collapse/item/package.json
+++ b/frontend/antd/collapse/item/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/collapse/package.json b/frontend/antd/collapse/package.json
index bd26edfa..3f058691 100644
--- a/frontend/antd/collapse/package.json
+++ b/frontend/antd/collapse/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/color-picker/Index.svelte b/frontend/antd/color-picker/Index.svelte
index 5b369399..f529f402 100644
--- a/frontend/antd/color-picker/Index.svelte
+++ b/frontend/antd/color-picker/Index.svelte
@@ -1,91 +1,96 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
- {setSlotParams}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/color-picker/color-picker.tsx b/frontend/antd/color-picker/color-picker.tsx
index 34912791..629992b0 100644
--- a/frontend/antd/color-picker/color-picker.tsx
+++ b/frontend/antd/color-picker/color-picker.tsx
@@ -1,5 +1,4 @@
import { sveltify } from '@svelte-preprocess-react';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { useTargets } from '@utils/hooks/useTargets';
@@ -19,7 +18,6 @@ export const ColorPicker = sveltify<
...args: any[]
) => void;
value_format: 'rgb' | 'hex' | 'hsb';
- setSlotParams: SetSlotParams;
},
['panelRender', 'showText']
>(
@@ -34,7 +32,6 @@ export const ColorPicker = sveltify<
presets,
children,
value_format,
- setSlotParams,
slots,
...props
}) => {
@@ -63,12 +60,12 @@ export const ColorPicker = sveltify<
}, [presets, presetItems])}
showText={
slots.showText
- ? renderParamsSlot({ slots, setSlotParams, key: 'showText' })
+ ? renderParamsSlot({ slots, key: 'showText' })
: showTextFunction || showText
}
panelRender={
slots.panelRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'panelRender' })
+ ? renderParamsSlot({ slots, key: 'panelRender' })
: panelRenderFunction
}
onChange={(v, ...args) => {
@@ -84,8 +81,8 @@ export const ColorPicker = sveltify<
color: colors[value_format],
};
});
- onChange?.(gradientColors, ...args);
onValueChange(gradientColors);
+ onChange?.(gradientColors, ...args);
return;
}
const colors = {
@@ -93,8 +90,8 @@ export const ColorPicker = sveltify<
hex: v.toHexString(),
hsb: v.toHsbString(),
};
- onChange?.(colors[value_format], ...args);
onValueChange(colors[value_format]);
+ onChange?.(colors[value_format], ...args);
}}
>
{targets.length === 0 ? null : children}
diff --git a/frontend/antd/color-picker/package.json b/frontend/antd/color-picker/package.json
index f725b70b..d3e1d16b 100644
--- a/frontend/antd/color-picker/package.json
+++ b/frontend/antd/color-picker/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/color-picker/preset/Index.svelte b/frontend/antd/color-picker/preset/Index.svelte
index 2b5bb398..ab0d40cd 100644
--- a/frontend/antd/color-picker/preset/Index.svelte
+++ b/frontend/antd/color-picker/preset/Index.svelte
@@ -1,89 +1,69 @@
-
- {#if $mergedProps.visible}
-
{/await}
diff --git a/frontend/antd/color-picker/preset/package.json b/frontend/antd/color-picker/preset/package.json
index 742ac13e..d956e272 100644
--- a/frontend/antd/color-picker/preset/package.json
+++ b/frontend/antd/color-picker/preset/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/config-provider/Index.svelte b/frontend/antd/config-provider/Index.svelte
index 078bc8f4..ae7b08c6 100644
--- a/frontend/antd/config-provider/Index.svelte
+++ b/frontend/antd/config-provider/Index.svelte
@@ -1,74 +1,71 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/config-provider/config-provider.tsx b/frontend/antd/config-provider/config-provider.tsx
index 8c66d414..9ecc641a 100644
--- a/frontend/antd/config-provider/config-provider.tsx
+++ b/frontend/antd/config-provider/config-provider.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React, { useEffect, useState } from 'react';
import { StyleProvider } from '@ant-design/cssinjs';
import { useFunction } from '@utils/hooks/useFunction';
@@ -66,7 +65,6 @@ export const ConfigProvider = sveltify<
style?: React.CSSProperties;
id?: string;
component?: React.ComponentType;
- setSlotParams: SetSlotParams;
},
['renderEmpty']
>(
@@ -80,7 +78,6 @@ export const ConfigProvider = sveltify<
getTargetContainer,
getPopupContainer,
renderEmpty,
- setSlotParams,
children,
component,
...props
@@ -107,6 +104,7 @@ export const ConfigProvider = sveltify<
});
}, [localeProp]);
const ProviderComponent = component || AConfigProvider;
+
return (
@@ -120,7 +118,6 @@ export const ConfigProvider = sveltify<
slots.renderEmpty
? renderParamsSlot({
slots,
- setSlotParams,
key: 'renderEmpty',
})
: renderEmptyFunction
@@ -128,7 +125,6 @@ export const ConfigProvider = sveltify<
// switch bug
// key={`${algorithm.dark}`}
theme={{
- cssVar: true,
...props.theme,
algorithm: Object.keys(algorithm)
.map((algo) => {
diff --git a/frontend/antd/config-provider/package.json b/frontend/antd/config-provider/package.json
index b5b1a6fc..2e7d0170 100644
--- a/frontend/antd/config-provider/package.json
+++ b/frontend/antd/config-provider/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/date-picker/Index.svelte b/frontend/antd/date-picker/Index.svelte
index 80637993..7baff9b9 100644
--- a/frontend/antd/date-picker/Index.svelte
+++ b/frontend/antd/date-picker/Index.svelte
@@ -1,87 +1,85 @@
- {
- value = val;
+ updateProps({
+ value: val,
+ });
}}
- {setSlotParams}
>
-
{/await}
{/if}
diff --git a/frontend/antd/date-picker/date-picker.tsx b/frontend/antd/date-picker/date-picker.tsx
index 9a0ae08d..ae5e77cb 100644
--- a/frontend/antd/date-picker/date-picker.tsx
+++ b/frontend/antd/date-picker/date-picker.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderItems } from '@utils/renderItems';
@@ -24,7 +23,9 @@ function formatDayjs(date: any): dayjs.Dayjs {
return dayjs(date);
}
-function formatDate(dates: (dayjs.Dayjs | null | undefined)[] | dayjs.Dayjs) {
+function formatDate(
+ dates: (dayjs.Dayjs | null | undefined)[] | dayjs.Dayjs | null
+) {
if (Array.isArray(dates)) {
return dates.map((date) => {
return date ? date.valueOf() / 1000 : null;
@@ -44,7 +45,6 @@ export const DatePicker = sveltify<
...args: any[]
) => void;
onValueChange: (date: ReturnType) => void;
- setSlotParams: SetSlotParams;
},
[
'allowClear.clearIcon',
@@ -80,7 +80,6 @@ export const DatePicker = sveltify<
onValueChange,
onPanelChange,
children,
- setSlotParams,
elRef,
...props
}) => {
@@ -139,12 +138,12 @@ export const DatePicker = sveltify<
getPopupContainer={getPopupContainerFunction}
cellRender={
slots.cellRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'cellRender' })
+ ? renderParamsSlot({ slots, key: 'cellRender' })
: cellRenderFunction
}
panelRender={
slots.panelRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'panelRender' })
+ ? renderParamsSlot({ slots, key: 'panelRender' })
: panelRenderFunction
}
presets={useMemo(() => {
@@ -166,14 +165,13 @@ export const DatePicker = sveltify<
}}
onChange={(date, ...args) => {
const formattedDate = formatDate(date);
- onChange?.(formattedDate, ...args);
onValueChange(formattedDate);
+ onChange?.(formattedDate, ...args);
}}
renderExtraFooter={
slots.renderExtraFooter
? renderParamsSlot({
slots,
- setSlotParams,
key: 'renderExtraFooter',
})
: props.renderExtraFooter
diff --git a/frontend/antd/date-picker/package.json b/frontend/antd/date-picker/package.json
index 255df8a9..7f2ee5f0 100644
--- a/frontend/antd/date-picker/package.json
+++ b/frontend/antd/date-picker/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/date-picker/preset/Index.svelte b/frontend/antd/date-picker/preset/Index.svelte
index ccacba7e..f2f90125 100644
--- a/frontend/antd/date-picker/preset/Index.svelte
+++ b/frontend/antd/date-picker/preset/Index.svelte
@@ -1,97 +1,73 @@
-
- {#if $mergedProps.visible}
-
{/await}
diff --git a/frontend/antd/date-picker/preset/package.json b/frontend/antd/date-picker/preset/package.json
index 645a8c87..8397fff5 100644
--- a/frontend/antd/date-picker/preset/package.json
+++ b/frontend/antd/date-picker/preset/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/date-picker/range-picker/Index.svelte b/frontend/antd/date-picker/range-picker/Index.svelte
index 793821ce..5a75550a 100644
--- a/frontend/antd/date-picker/range-picker/Index.svelte
+++ b/frontend/antd/date-picker/range-picker/Index.svelte
@@ -1,91 +1,84 @@
- {
- value = val;
+ updateProps({ value: val });
}}
- {setSlotParams}
>
-
+ {@render children?.()}
+
{/await}
{/if}
diff --git a/frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx b/frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx
index 6cc60e5e..cda2d5fd 100644
--- a/frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx
+++ b/frontend/antd/date-picker/range-picker/date-picker.range-picker.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderItems } from '@utils/renderItems';
@@ -39,7 +38,6 @@ export const DateRangePicker = sveltify<
...args: any[]
) => void;
onValueChange: (dates: [number | null, number | null]) => void;
- setSlotParams: SetSlotParams;
},
[
'allowClear.clearIcon',
@@ -76,7 +74,6 @@ export const DateRangePicker = sveltify<
onPanelChange,
onCalendarChange,
children,
- setSlotParams,
elRef,
...props
}) => {
@@ -144,12 +141,12 @@ export const DateRangePicker = sveltify<
getPopupContainer={getPopupContainerFunction}
cellRender={
slots.cellRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'cellRender' })
+ ? renderParamsSlot({ slots, key: 'cellRender' })
: cellRenderFunction
}
panelRender={
slots.panelRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'panelRender' })
+ ? renderParamsSlot({ slots, key: 'panelRender' })
: panelRenderFunction
}
presets={useMemo(() => {
@@ -171,8 +168,8 @@ export const DateRangePicker = sveltify<
}}
onChange={(dates, ...args) => {
const formattedDates = formatDates(dates);
- onChange?.(formattedDates, ...args);
onValueChange(formattedDates);
+ onChange?.(formattedDates, ...args);
}}
onCalendarChange={(dates, ...args) => {
const formattedDates = formatDates(dates);
@@ -182,7 +179,6 @@ export const DateRangePicker = sveltify<
slots.renderExtraFooter
? renderParamsSlot({
slots,
- setSlotParams,
key: 'renderExtraFooter',
})
: props.renderExtraFooter
diff --git a/frontend/antd/date-picker/range-picker/package.json b/frontend/antd/date-picker/range-picker/package.json
index cf035a9e..c0d96786 100644
--- a/frontend/antd/date-picker/range-picker/package.json
+++ b/frontend/antd/date-picker/range-picker/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/descriptions/Index.svelte b/frontend/antd/descriptions/Index.svelte
index 4f91b9ba..abe48880 100644
--- a/frontend/antd/descriptions/Index.svelte
+++ b/frontend/antd/descriptions/Index.svelte
@@ -1,76 +1,64 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/descriptions/item/Index.svelte b/frontend/antd/descriptions/item/Index.svelte
index a19a04f6..d5823146 100644
--- a/frontend/antd/descriptions/item/Index.svelte
+++ b/frontend/antd/descriptions/item/Index.svelte
@@ -1,95 +1,75 @@
-
- {#if $mergedProps.visible}
-
-
+ {@render children?.()}
{/if}
diff --git a/frontend/antd/descriptions/item/package.json b/frontend/antd/descriptions/item/package.json
index dec14896..1b0a1805 100644
--- a/frontend/antd/descriptions/item/package.json
+++ b/frontend/antd/descriptions/item/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/descriptions/package.json b/frontend/antd/descriptions/package.json
index 0b4c4628..c8af7f60 100644
--- a/frontend/antd/descriptions/package.json
+++ b/frontend/antd/descriptions/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/divider/Index.svelte b/frontend/antd/divider/Index.svelte
index b9ef09c0..88839889 100644
--- a/frontend/antd/divider/Index.svelte
+++ b/frontend/antd/divider/Index.svelte
@@ -1,86 +1,74 @@
-
-
+ {@render children?.()}
- {:else if $mergedProps.value}
-
- {$mergedProps.value}
+ {:else if proceedProps.value}
+
+ {proceedProps.value}
{:else}
-
-
{/await}
{/if}
diff --git a/frontend/antd/drawer/drawer.tsx b/frontend/antd/drawer/drawer.tsx
index f9a71f1f..eda69daf 100644
--- a/frontend/antd/drawer/drawer.tsx
+++ b/frontend/antd/drawer/drawer.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderParamsSlot } from '@utils/renderParamsSlot';
@@ -13,9 +12,7 @@ function getConfig(value: T): Partial> {
return {} as any;
}
export const Drawer = sveltify<
- GetProps & {
- setSlotParams: SetSlotParams;
- },
+ GetProps,
[
'closeIcon',
'closable.closeIcon',
@@ -24,52 +21,39 @@ export const Drawer = sveltify<
'title',
'drawerRender',
]
->(
- ({
- slots,
- afterOpenChange,
- getContainer,
- drawerRender,
- setSlotParams,
- ...props
- }) => {
- const afterOpenChangeFunction = useFunction(afterOpenChange);
- const getContainerFunction = useFunction(getContainer);
- const drawerRenderFunction = useFunction(drawerRender);
- const closableConfig = getConfig(props.closable);
- return (
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/dropdown/button/Index.svelte b/frontend/antd/dropdown/button/Index.svelte
index 947c2029..681ad8fa 100644
--- a/frontend/antd/dropdown/button/Index.svelte
+++ b/frontend/antd/dropdown/button/Index.svelte
@@ -1,88 +1,70 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/dropdown/button/dropdown.button.tsx b/frontend/antd/dropdown/button/dropdown.button.tsx
index 35a4b901..78b45c49 100644
--- a/frontend/antd/dropdown/button/dropdown.button.tsx
+++ b/frontend/antd/dropdown/button/dropdown.button.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { useTargets } from '@utils/hooks/useTargets';
@@ -16,7 +15,6 @@ import {
export const DropdownButton = sveltify<
GetProps & {
- setSlotParams: SetSlotParams;
value?: string;
},
[
@@ -37,7 +35,6 @@ export const DropdownButton = sveltify<
dropdownRender,
popupRender,
buttonsRender,
- setSlotParams,
value,
...props
}) => {
@@ -62,7 +59,6 @@ export const DropdownButton = sveltify<
? renderParamsSlot({
key: 'buttonsRender',
slots,
- setSlotParams,
targets: buttonsRenderTargets,
})
: buttonsRenderFunction
@@ -80,7 +76,7 @@ export const DropdownButton = sveltify<
}, [menuItems, props.menu?.items]),
expandIcon: slots['menu.expandIcon']
? renderParamsSlot(
- { slots, setSlotParams, key: 'menu.expandIcon' },
+ { slots, key: 'menu.expandIcon' },
{ clone: true }
)
: props.menu?.expandIcon,
@@ -95,7 +91,6 @@ export const DropdownButton = sveltify<
slots.dropdownRender
? renderParamsSlot({
slots,
- setSlotParams,
key: 'dropdownRender',
})
: dropdownRenderFunction
@@ -103,7 +98,7 @@ export const DropdownButton = sveltify<
popupRender={
slots.popupRender
? renderParamsSlot(
- { slots, setSlotParams, key: 'popupRender' },
+ { slots, key: 'popupRender' },
{ clone: true }
)
: popupRenderFunction
diff --git a/frontend/antd/dropdown/button/package.json b/frontend/antd/dropdown/button/package.json
index f104ebef..8d5ed01a 100644
--- a/frontend/antd/dropdown/button/package.json
+++ b/frontend/antd/dropdown/button/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/dropdown/dropdown.tsx b/frontend/antd/dropdown/dropdown.tsx
index a5c9fcda..5349bd25 100644
--- a/frontend/antd/dropdown/dropdown.tsx
+++ b/frontend/antd/dropdown/dropdown.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderItems } from '@utils/renderItems';
@@ -16,7 +15,6 @@ import {
export const Dropdown = sveltify<
GetProps & {
innerStyle?: React.CSSProperties;
- setSlotParams: SetSlotParams;
},
[
'menu.expandIcon',
@@ -34,7 +32,6 @@ export const Dropdown = sveltify<
slots,
dropdownRender,
popupRender,
- setSlotParams,
...props
}) => {
const getPopupContainerFunction = useFunction(getPopupContainer);
@@ -60,7 +57,7 @@ export const Dropdown = sveltify<
}, [menuItems, props.menu?.items]),
expandIcon: slots['menu.expandIcon']
? renderParamsSlot(
- { slots, setSlotParams, key: 'menu.expandIcon' },
+ { slots, key: 'menu.expandIcon' },
{ clone: true }
)
: props.menu?.expandIcon,
@@ -76,7 +73,6 @@ export const Dropdown = sveltify<
? renderParamsSlot(
{
slots,
- setSlotParams,
key: 'dropdownRender',
},
{ clone: true }
@@ -88,7 +84,6 @@ export const Dropdown = sveltify<
? renderParamsSlot(
{
slots,
- setSlotParams,
key: 'popupRender',
},
{ clone: true }
diff --git a/frontend/antd/dropdown/package.json b/frontend/antd/dropdown/package.json
index 5cbe4a0f..38103f22 100644
--- a/frontend/antd/dropdown/package.json
+++ b/frontend/antd/dropdown/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/empty/Index.svelte b/frontend/antd/empty/Index.svelte
index 521a0c6b..67c55700 100644
--- a/frontend/antd/empty/Index.svelte
+++ b/frontend/antd/empty/Index.svelte
@@ -1,73 +1,61 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/empty/empty.tsx b/frontend/antd/empty/empty.tsx
index 1ad4d9ea..6b4a69b5 100644
--- a/frontend/antd/empty/empty.tsx
+++ b/frontend/antd/empty/empty.tsx
@@ -1,6 +1,7 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
import { Empty as AEmpty, type GetProps } from 'antd';
+import { isFunction } from 'lodash-es';
export const Empty = sveltify<
GetProps,
@@ -19,6 +20,7 @@ export const Empty = sveltify<
return props.image;
}
};
+
return (
{
+ if (isFunction(styles)) {
+ return styles(info);
+ }
+ return {
+ ...styles,
+ image: {
+ display: 'inline-block',
+ ...styles?.image,
+ },
+ };
}}
image={getImage()}
/>
diff --git a/frontend/antd/empty/package.json b/frontend/antd/empty/package.json
index 968ab06e..e53e4385 100644
--- a/frontend/antd/empty/package.json
+++ b/frontend/antd/empty/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/flex/Index.svelte b/frontend/antd/flex/Index.svelte
index 76182e64..65b85826 100644
--- a/frontend/antd/flex/Index.svelte
+++ b/frontend/antd/flex/Index.svelte
@@ -1,73 +1,61 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/flex/package.json b/frontend/antd/flex/package.json
index 968ab06e..e53e4385 100644
--- a/frontend/antd/flex/package.json
+++ b/frontend/antd/flex/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/float-button/Index.svelte b/frontend/antd/float-button/Index.svelte
index 1891fe5e..b2df0aed 100644
--- a/frontend/antd/float-button/Index.svelte
+++ b/frontend/antd/float-button/Index.svelte
@@ -1,77 +1,69 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/float-button/back-top/Index.svelte b/frontend/antd/float-button/back-top/Index.svelte
index bb49bb8f..ec533104 100644
--- a/frontend/antd/float-button/back-top/Index.svelte
+++ b/frontend/antd/float-button/back-top/Index.svelte
@@ -1,78 +1,72 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/float-button/group/package.json b/frontend/antd/float-button/group/package.json
index 934ecfe7..caa70ed5 100644
--- a/frontend/antd/float-button/group/package.json
+++ b/frontend/antd/float-button/group/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/float-button/package.json b/frontend/antd/float-button/package.json
index 942fb12d..331ea99c 100644
--- a/frontend/antd/float-button/package.json
+++ b/frontend/antd/float-button/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/form/Index.svelte b/frontend/antd/form/Index.svelte
index 94345fda..9bdd42b1 100644
--- a/frontend/antd/form/Index.svelte
+++ b/frontend/antd/form/Index.svelte
@@ -1,103 +1,98 @@
- {
- value: Record;
+ value?: Record;
onValueChange: (value: Record) => void;
- setSlotParams: SetSlotParams;
formAction?: 'reset' | 'submit' | 'validate' | null;
onResetFormAction: () => void;
}
@@ -22,7 +20,6 @@ export const Form = sveltify(
requiredMark,
onValuesChange,
feedbackIcons,
- setSlotParams,
slots,
onResetFormAction,
...props
@@ -62,7 +59,6 @@ export const Form = sveltify(
slots.requiredMark
? renderParamsSlot({
key: 'requiredMark',
- setSlotParams,
slots,
})
: requiredMark === 'optional'
diff --git a/frontend/antd/form/item/Index.svelte b/frontend/antd/form/item/Index.svelte
index 7ce66328..9ab6aa33 100644
--- a/frontend/antd/form/item/Index.svelte
+++ b/frontend/antd/form/item/Index.svelte
@@ -1,76 +1,66 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/form/item/form.item.tsx b/frontend/antd/form/item/form.item.tsx
index 6cb78d6d..7eb691c6 100644
--- a/frontend/antd/form/item/form.item.tsx
+++ b/frontend/antd/form/item/form.item.tsx
@@ -1,5 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
-import { FormItemContext } from '@svelte-preprocess-react/context';
+import { FormItemContext } from '@svelte-preprocess-react/react-contexts';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
diff --git a/frontend/antd/form/item/package.json b/frontend/antd/form/item/package.json
index 70a0a7e5..ea17d06e 100644
--- a/frontend/antd/form/item/package.json
+++ b/frontend/antd/form/item/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/form/item/rule/Index.svelte b/frontend/antd/form/item/rule/Index.svelte
index 69e1ba98..7da2dedd 100644
--- a/frontend/antd/form/item/rule/Index.svelte
+++ b/frontend/antd/form/item/rule/Index.svelte
@@ -1,73 +1,66 @@
-
- {#if $mergedProps.visible}
-
{/await}
diff --git a/frontend/antd/form/item/rule/package.json b/frontend/antd/form/item/rule/package.json
index 496f775d..65e2a47b 100644
--- a/frontend/antd/form/item/rule/package.json
+++ b/frontend/antd/form/item/rule/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/form/package.json b/frontend/antd/form/package.json
index f0cd1c5d..8ba4721e 100644
--- a/frontend/antd/form/package.json
+++ b/frontend/antd/form/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/form/provider/Index.svelte b/frontend/antd/form/provider/Index.svelte
index ac15cd75..cbfb622c 100644
--- a/frontend/antd/form/provider/Index.svelte
+++ b/frontend/antd/form/provider/Index.svelte
@@ -1,69 +1,63 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/form/provider/package.json b/frontend/antd/form/provider/package.json
index 33496ee6..bb973215 100644
--- a/frontend/antd/form/provider/package.json
+++ b/frontend/antd/form/provider/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/grid/col/Index.svelte b/frontend/antd/grid/col/Index.svelte
index f4a20f7d..b756f3d1 100644
--- a/frontend/antd/grid/col/Index.svelte
+++ b/frontend/antd/grid/col/Index.svelte
@@ -1,76 +1,69 @@
-
-
+ {@render children?.()}
{/if}
diff --git a/frontend/antd/grid/col/package.json b/frontend/antd/grid/col/package.json
index 7fcfeb0b..4106636b 100644
--- a/frontend/antd/grid/col/package.json
+++ b/frontend/antd/grid/col/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/grid/row/Index.svelte b/frontend/antd/grid/row/Index.svelte
index 22a4861f..f006b78e 100644
--- a/frontend/antd/grid/row/Index.svelte
+++ b/frontend/antd/grid/row/Index.svelte
@@ -1,73 +1,60 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/grid/row/package.json b/frontend/antd/grid/row/package.json
index 72bab38d..6d91b7c2 100644
--- a/frontend/antd/grid/row/package.json
+++ b/frontend/antd/grid/row/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/icon/Index.svelte b/frontend/antd/icon/Index.svelte
index 5756ac3a..54e2293a 100644
--- a/frontend/antd/icon/Index.svelte
+++ b/frontend/antd/icon/Index.svelte
@@ -1,75 +1,66 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/icon/icon.tsx b/frontend/antd/icon/icon.tsx
index e02375c3..66c1ebef 100644
--- a/frontend/antd/icon/icon.tsx
+++ b/frontend/antd/icon/icon.tsx
@@ -1,5 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
-import { useIconFontContext } from '@svelte-preprocess-react/context';
+import { useIconFontContext } from '@svelte-preprocess-react/react-contexts';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
import React, { useMemo } from 'react';
import * as icons from '@ant-design/icons';
diff --git a/frontend/antd/icon/iconfont-provider/Index.svelte b/frontend/antd/icon/iconfont-provider/Index.svelte
index 4befebdd..595e02a2 100644
--- a/frontend/antd/icon/iconfont-provider/Index.svelte
+++ b/frontend/antd/icon/iconfont-provider/Index.svelte
@@ -1,46 +1,52 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/icon/iconfont-provider/iconfont-provider.tsx b/frontend/antd/icon/iconfont-provider/iconfont-provider.tsx
index a500e3c2..455f7276 100644
--- a/frontend/antd/icon/iconfont-provider/iconfont-provider.tsx
+++ b/frontend/antd/icon/iconfont-provider/iconfont-provider.tsx
@@ -1,5 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
-import { IconFontContext } from '@svelte-preprocess-react/context';
+import { IconFontContext } from '@svelte-preprocess-react/react-contexts';
import React, { useMemo, useRef } from 'react';
import { createFromIconfontCN } from '@ant-design/icons';
import type { CustomIconOptions } from '@ant-design/icons/es/components/IconFont';
diff --git a/frontend/antd/icon/iconfont-provider/package.json b/frontend/antd/icon/iconfont-provider/package.json
index 4005caa8..77c7e136 100644
--- a/frontend/antd/icon/iconfont-provider/package.json
+++ b/frontend/antd/icon/iconfont-provider/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/icon/package.json b/frontend/antd/icon/package.json
index 2cfbc4d0..1c313730 100644
--- a/frontend/antd/icon/package.json
+++ b/frontend/antd/icon/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/image/Index.svelte b/frontend/antd/image/Index.svelte
index 57a701f6..5a597c96 100644
--- a/frontend/antd/image/Index.svelte
+++ b/frontend/antd/image/Index.svelte
@@ -1,94 +1,82 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/image/image.tsx b/frontend/antd/image/image.tsx
index 4be0f667..35c50274 100644
--- a/frontend/antd/image/image.tsx
+++ b/frontend/antd/image/image.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useFunction } from '@utils/hooks/useFunction';
import { omitUndefinedProps } from '@utils/omitUndefinedProps';
import { renderParamsSlot } from '@utils/renderParamsSlot';
@@ -14,9 +13,7 @@ function getConfig(value: T): Partial> {
}
type ImageProps = GetProps;
export const Image = sveltify<
- ImageProps & {
- setSlotParams: SetSlotParams;
- },
+ ImageProps & {},
[
'placeholder',
'preview.mask',
@@ -24,7 +21,7 @@ export const Image = sveltify<
'preview.toolbarRender',
'preview.imageRender',
]
->(({ slots, preview, setSlotParams, children, ...props }) => {
+>(({ slots, preview, children, ...props }) => {
const previewConfig = getConfig(preview);
const supportPreview =
slots['preview.mask'] ||
@@ -49,14 +46,12 @@ export const Image = sveltify<
toolbarRender: slots['preview.toolbarRender']
? renderParamsSlot({
slots,
- setSlotParams,
key: 'preview.toolbarRender',
})
: previewToolbarRenderFunction,
imageRender: slots['preview.imageRender']
? renderParamsSlot({
slots,
- setSlotParams,
key: 'preview.imageRender',
})
: previewImageRenderFunction,
diff --git a/frontend/antd/image/package.json b/frontend/antd/image/package.json
index e7ba95d7..ef0a35a1 100644
--- a/frontend/antd/image/package.json
+++ b/frontend/antd/image/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/image/preview-group/Index.svelte b/frontend/antd/image/preview-group/Index.svelte
index 56bf9834..10980e58 100644
--- a/frontend/antd/image/preview-group/Index.svelte
+++ b/frontend/antd/image/preview-group/Index.svelte
@@ -1,84 +1,71 @@
-
-
+ {@render children?.()}
+
{/await}
{/if}
-
-
diff --git a/frontend/antd/image/preview-group/package.json b/frontend/antd/image/preview-group/package.json
index 5925e7d8..1112ef29 100644
--- a/frontend/antd/image/preview-group/package.json
+++ b/frontend/antd/image/preview-group/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/input-number/Index.svelte b/frontend/antd/input-number/Index.svelte
index 53ce7501..b0d9a196 100644
--- a/frontend/antd/input-number/Index.svelte
+++ b/frontend/antd/input-number/Index.svelte
@@ -1,81 +1,84 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/input-number/package.json b/frontend/antd/input-number/package.json
index 38779fc3..d5b6196c 100644
--- a/frontend/antd/input-number/package.json
+++ b/frontend/antd/input-number/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/input/Index.svelte b/frontend/antd/input/Index.svelte
index 6a18655e..a2d914b4 100644
--- a/frontend/antd/input/Index.svelte
+++ b/frontend/antd/input/Index.svelte
@@ -1,86 +1,83 @@
- & {
onValueChange: (value: string) => void;
- setSlotParams: SetSlotParams;
},
[
'addonAfter',
@@ -29,7 +27,6 @@ export const Input = sveltify<
showCount,
onValueChange,
onChange,
- setSlotParams,
elRef,
...props
}) => {
@@ -60,7 +57,6 @@ export const Input = sveltify<
? {
formatter: renderParamsSlot({
slots,
- setSlotParams,
key: 'showCount.formatter',
})!,
}
diff --git a/frontend/antd/input/otp/Index.svelte b/frontend/antd/input/otp/Index.svelte
index 4780596a..0e5e6c12 100644
--- a/frontend/antd/input/otp/Index.svelte
+++ b/frontend/antd/input/otp/Index.svelte
@@ -1,80 +1,73 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
- {setSlotParams}
- />
+ >
+ {@render children?.()}
+
{/await}
{/if}
diff --git a/frontend/antd/input/otp/input.otp.tsx b/frontend/antd/input/otp/input.otp.tsx
index 3c65591f..27449183 100644
--- a/frontend/antd/input/otp/input.otp.tsx
+++ b/frontend/antd/input/otp/input.otp.tsx
@@ -1,5 +1,4 @@
import { sveltify } from '@svelte-preprocess-react';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useFunction } from '@utils/hooks/useFunction';
import { useValueChange } from '@utils/hooks/useValueChange';
import { renderParamsSlot } from '@utils/renderParamsSlot';
@@ -8,7 +7,6 @@ import { type GetProps, Input as AInput } from 'antd';
export const InputOTP = sveltify<
GetProps & {
onValueChange: (value: string) => void;
- setSlotParams: SetSlotParams;
},
['separator']
>(
@@ -17,7 +15,6 @@ export const InputOTP = sveltify<
onValueChange,
onChange,
children,
- setSlotParams,
elRef,
slots,
separator,
@@ -42,7 +39,6 @@ export const InputOTP = sveltify<
slots.separator
? renderParamsSlot({
slots,
- setSlotParams,
key: 'separator',
})
: separatorFunction || separator
diff --git a/frontend/antd/input/otp/package.json b/frontend/antd/input/otp/package.json
index 4d7e5a6d..6ca6c979 100644
--- a/frontend/antd/input/otp/package.json
+++ b/frontend/antd/input/otp/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/input/package.json b/frontend/antd/input/package.json
index 1e06b44d..b05ca714 100644
--- a/frontend/antd/input/package.json
+++ b/frontend/antd/input/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/input/password/Index.svelte b/frontend/antd/input/password/Index.svelte
index 67ae2612..34e7bd9e 100644
--- a/frontend/antd/input/password/Index.svelte
+++ b/frontend/antd/input/password/Index.svelte
@@ -1,92 +1,82 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
- {setSlotParams}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/input/password/input.password.tsx b/frontend/antd/input/password/input.password.tsx
index ece85034..dae6efcd 100644
--- a/frontend/antd/input/password/input.password.tsx
+++ b/frontend/antd/input/password/input.password.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { useValueChange } from '@utils/hooks/useValueChange';
@@ -11,7 +10,6 @@ import { type GetProps, Input as AInput } from 'antd';
export const InputPassword = sveltify<
GetProps & {
onValueChange: (value: string) => void;
- setSlotParams: SetSlotParams;
},
[
'iconRender',
@@ -32,7 +30,6 @@ export const InputPassword = sveltify<
onChange,
iconRender,
elRef,
- setSlotParams,
...props
}) => {
const countStrategyFunction = useFunction(count?.strategy);
@@ -61,7 +58,6 @@ export const InputPassword = sveltify<
slots.iconRender
? renderParamsSlot({
slots,
- setSlotParams,
key: 'iconRender',
})
: iconRenderFunction
@@ -71,7 +67,6 @@ export const InputPassword = sveltify<
? {
formatter: renderParamsSlot({
slots,
- setSlotParams,
key: 'showCount.formatter',
})!,
}
diff --git a/frontend/antd/input/password/package.json b/frontend/antd/input/password/package.json
index a1d844ab..7e1212ab 100644
--- a/frontend/antd/input/password/package.json
+++ b/frontend/antd/input/password/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/input/search/Index.svelte b/frontend/antd/input/search/Index.svelte
index bfdd86a6..dedfa308 100644
--- a/frontend/antd/input/search/Index.svelte
+++ b/frontend/antd/input/search/Index.svelte
@@ -1,89 +1,78 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
- {setSlotParams}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/input/search/input.search.tsx b/frontend/antd/input/search/input.search.tsx
index 1556b954..57db2de8 100644
--- a/frontend/antd/input/search/input.search.tsx
+++ b/frontend/antd/input/search/input.search.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { useValueChange } from '@utils/hooks/useValueChange';
@@ -11,7 +10,6 @@ import { type GetProps, Input as AInput } from 'antd';
export const InputSearch = sveltify<
GetProps & {
onValueChange: (value: string) => void;
- setSlotParams: SetSlotParams;
},
[
'addonAfter',
@@ -31,7 +29,6 @@ export const InputSearch = sveltify<
onValueChange,
onChange,
elRef,
- setSlotParams,
...props
}) => {
const countStrategyFunction = useFunction(count?.strategy);
@@ -60,7 +57,6 @@ export const InputSearch = sveltify<
? {
formatter: renderParamsSlot({
slots,
- setSlotParams,
key: 'showCount.formatter',
})!,
}
diff --git a/frontend/antd/input/search/package.json b/frontend/antd/input/search/package.json
index 199e28ca..4df8bcdc 100644
--- a/frontend/antd/input/search/package.json
+++ b/frontend/antd/input/search/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/input/textarea/Index.svelte b/frontend/antd/input/textarea/Index.svelte
index e087d762..2bd90ff2 100644
--- a/frontend/antd/input/textarea/Index.svelte
+++ b/frontend/antd/input/textarea/Index.svelte
@@ -1,91 +1,78 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
- {setSlotParams}
>
-
+ {@render children?.()}
+
{/await}
{/if}
-
-
diff --git a/frontend/antd/input/textarea/input.textarea.tsx b/frontend/antd/input/textarea/input.textarea.tsx
index 2472c12e..da06f54c 100644
--- a/frontend/antd/input/textarea/input.textarea.tsx
+++ b/frontend/antd/input/textarea/input.textarea.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { useValueChange } from '@utils/hooks/useValueChange';
@@ -11,7 +10,6 @@ import { type GetProps, Input as AInput } from 'antd';
export const InputTextarea = sveltify<
GetProps & {
onValueChange: (value: string) => void;
- setSlotParams: SetSlotParams;
},
['allowClear.clearIcon', 'showCount.formatter']
>(
@@ -23,7 +21,6 @@ export const InputTextarea = sveltify<
onValueChange,
onChange,
elRef,
- setSlotParams,
...props
}) => {
const countStrategyFunction = useFunction(count?.strategy);
@@ -52,7 +49,6 @@ export const InputTextarea = sveltify<
? {
formatter: renderParamsSlot({
slots,
- setSlotParams,
key: 'showCount.formatter',
})!,
}
diff --git a/frontend/antd/input/textarea/package.json b/frontend/antd/input/textarea/package.json
index cbf45dda..fa271510 100644
--- a/frontend/antd/input/textarea/package.json
+++ b/frontend/antd/input/textarea/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/layout/Base.svelte b/frontend/antd/layout/Base.svelte
index c4eab932..82d0c8e2 100644
--- a/frontend/antd/layout/Base.svelte
+++ b/frontend/antd/layout/Base.svelte
@@ -1,71 +1,67 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/layout/Index.svelte b/frontend/antd/layout/Index.svelte
index bc283720..9d6a02c1 100644
--- a/frontend/antd/layout/Index.svelte
+++ b/frontend/antd/layout/Index.svelte
@@ -1,10 +1,17 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/layout/sider/package.json b/frontend/antd/layout/sider/package.json
index e93c644e..9d9ca886 100644
--- a/frontend/antd/layout/sider/package.json
+++ b/frontend/antd/layout/sider/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/list/Index.svelte b/frontend/antd/list/Index.svelte
index 75eafc60..ed326726 100644
--- a/frontend/antd/list/Index.svelte
+++ b/frontend/antd/list/Index.svelte
@@ -1,80 +1,68 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/list/item/meta/Index.svelte b/frontend/antd/list/item/meta/Index.svelte
index 6f86bc1d..dd0a35d7 100644
--- a/frontend/antd/list/item/meta/Index.svelte
+++ b/frontend/antd/list/item/meta/Index.svelte
@@ -1,68 +1,58 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/list/item/meta/package.json b/frontend/antd/list/item/meta/package.json
index 1cf251bb..d83eddc6 100644
--- a/frontend/antd/list/item/meta/package.json
+++ b/frontend/antd/list/item/meta/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/list/item/package.json b/frontend/antd/list/item/package.json
index 729c77ae..413ad191 100644
--- a/frontend/antd/list/item/package.json
+++ b/frontend/antd/list/item/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/list/list.tsx b/frontend/antd/list/list.tsx
index 920635c7..9086950c 100644
--- a/frontend/antd/list/list.tsx
+++ b/frontend/antd/list/list.tsx
@@ -1,17 +1,14 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderParamsSlot } from '@utils/renderParamsSlot';
import { type GetProps, List as AList } from 'antd';
export const List = sveltify<
- GetProps & {
- setSlotParams: SetSlotParams;
- },
+ GetProps & {},
['footer', 'header', 'loadMore', 'renderItem']
->(({ slots, renderItem, setSlotParams, ...props }) => {
+>(({ slots, renderItem, ...props }) => {
const renderItemFunction = useFunction(renderItem);
return (
+ import {
+ getProps,
+ importComponent,
+ processProps,
+ } from '@svelte-preprocess-react/component';
+ import { getSlots } from '@svelte-preprocess-react/svelte-contexts/slot.svelte';
+ import cls from 'classnames';
+
+ const AwaitedMasonry = importComponent(() => import('./masonry'));
+
+ const props = $props();
+ const { gradio, getComponentProps, getAdditionalProps, children } = getProps<{
+ additional_props?: Record;
+ layout_change?: any;
+ }>(() => props);
+
+ const getProceedProps = processProps(
+ () => {
+ const {
+ visible,
+ _internal,
+ as_item,
+ elem_classes,
+ elem_id,
+ elem_style,
+ ...restProps
+ } = getComponentProps();
+ return {
+ gradio,
+ additionalProps: getAdditionalProps(),
+ _internal,
+ as_item,
+ restProps,
+ visible,
+ elem_id,
+ elem_classes,
+ elem_style,
+ };
+ },
+ {
+ layout_change: 'layoutChange',
+ }
+ );
+ const proceedProps = $derived(getProceedProps());
+
+ const slots = getSlots();
+
+
+{#if proceedProps.visible}
+ {#await AwaitedMasonry then Masonry}
+
+ {@render children?.()}
+
+ {/await}
+{/if}
diff --git a/frontend/antd/masonry/context.ts b/frontend/antd/masonry/context.ts
new file mode 100644
index 00000000..1e31f6cb
--- /dev/null
+++ b/frontend/antd/masonry/context.ts
@@ -0,0 +1,6 @@
+import { createItemsContext } from '@utils/createItemsContext';
+
+export const { withItemsContextProvider, useItems, ItemHandler } =
+ createItemsContext('antd-masonry-items');
+
+export * from '@utils/createItemsContext';
diff --git a/frontend/legacy/Markdown/gradio.config.js b/frontend/antd/masonry/gradio.config.js
similarity index 51%
rename from frontend/legacy/Markdown/gradio.config.js
rename to frontend/antd/masonry/gradio.config.js
index abd9137f..916857c0 100644
--- a/frontend/legacy/Markdown/gradio.config.js
+++ b/frontend/antd/masonry/gradio.config.js
@@ -1,3 +1,3 @@
import config from '../../defineConfig.js';
-export default config({ external: true });
+export default config();
diff --git a/frontend/antd/masonry/item/Index.svelte b/frontend/antd/masonry/item/Index.svelte
new file mode 100644
index 00000000..797edac7
--- /dev/null
+++ b/frontend/antd/masonry/item/Index.svelte
@@ -0,0 +1,80 @@
+
+
+{#await AwaitedMasonryItem then MasonryItem}
+
+ {#if proceedProps.visible}
+
+ {@render children?.()}
+
+ {/if}
+
+{/await}
+
+
diff --git a/frontend/antdx/attachments/file-card/gradio.config.js b/frontend/antd/masonry/item/gradio.config.js
similarity index 100%
rename from frontend/antdx/attachments/file-card/gradio.config.js
rename to frontend/antd/masonry/item/gradio.config.js
diff --git a/frontend/antd/masonry/item/masonry.item.tsx b/frontend/antd/masonry/item/masonry.item.tsx
new file mode 100644
index 00000000..32be0fc8
--- /dev/null
+++ b/frontend/antd/masonry/item/masonry.item.tsx
@@ -0,0 +1,15 @@
+import { sveltify } from '@svelte-preprocess-react';
+import React from 'react';
+import { type MasonryProps } from 'antd';
+
+import { ItemHandler, type ItemHandlerProps } from '../context';
+
+type MasonryItemType = NonNullable[number];
+
+export const MasonryItem = sveltify<
+ Partial & ItemHandlerProps
+>((props) => {
+ return {
+ return (
+ items ||
+ renderItems[number]>(
+ resolvedSlotItems
+ )
+ );
+ }, [items, resolvedSlotItems])}
+ />
+
+ );
+ }
+ )
+);
+
+export default Masonry;
diff --git a/frontend/antd/masonry/package.json b/frontend/antd/masonry/package.json
new file mode 100644
index 00000000..dc3c6f9b
--- /dev/null
+++ b/frontend/antd/masonry/package.json
@@ -0,0 +1,14 @@
+{
+ "name": "@modelscope-studio/antd-masonry",
+ "type": "module",
+ "exports": {
+ ".": {
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
+ },
+ "./package.json": {
+ "gradio": "./package.json",
+ "default": "./package.json"
+ }
+ }
+}
diff --git a/frontend/antd/mentions/Index.svelte b/frontend/antd/mentions/Index.svelte
index a246207d..bd93a1a6 100644
--- a/frontend/antd/mentions/Index.svelte
+++ b/frontend/antd/mentions/Index.svelte
@@ -1,78 +1,84 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
>
-
{/await}
{/if}
diff --git a/frontend/antd/mentions/option/Index.svelte b/frontend/antd/mentions/option/Index.svelte
index c1086d55..26535e4e 100644
--- a/frontend/antd/mentions/option/Index.svelte
+++ b/frontend/antd/mentions/option/Index.svelte
@@ -1,102 +1,71 @@
-
- {#if $mergedProps.visible}
-
{/await}
diff --git a/frontend/antd/mentions/option/package.json b/frontend/antd/mentions/option/package.json
index 295cd4af..743957d8 100644
--- a/frontend/antd/mentions/option/package.json
+++ b/frontend/antd/mentions/option/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/mentions/package.json b/frontend/antd/mentions/package.json
index 4b99168f..8eaf25c4 100644
--- a/frontend/antd/mentions/package.json
+++ b/frontend/antd/mentions/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/menu/Index.svelte b/frontend/antd/menu/Index.svelte
index 97f87e0b..38dee2f9 100644
--- a/frontend/antd/menu/Index.svelte
+++ b/frontend/antd/menu/Index.svelte
@@ -1,77 +1,71 @@
-((props) => {
+export const MenuItem = sveltify<
+ MenuItemProps & SubMenuProps & ItemHandlerProps
+>((props) => {
return (
{...props}
diff --git a/frontend/antd/menu/item/package.json b/frontend/antd/menu/item/package.json
index f078a35d..a7b645bd 100644
--- a/frontend/antd/menu/item/package.json
+++ b/frontend/antd/menu/item/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/menu/menu.tsx b/frontend/antd/menu/menu.tsx
index d2d3457a..b72c91b7 100644
--- a/frontend/antd/menu/menu.tsx
+++ b/frontend/antd/menu/menu.tsx
@@ -1,7 +1,7 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React, { useMemo } from 'react';
+import { useFunction } from '@utils/hooks/useFunction';
import { omitUndefinedProps } from '@utils/omitUndefinedProps';
import { renderItems } from '@utils/renderItems';
import { renderParamsSlot } from '@utils/renderParamsSlot';
@@ -13,10 +13,8 @@ import { useItems, withItemsContextProvider } from './context';
import './menu.less';
export const Menu = sveltify<
- GetProps & {
- setSlotParams: SetSlotParams;
- },
- ['expandIcon', 'overflowedIndicator']
+ GetProps & {},
+ ['expandIcon', 'overflowedIndicator', 'popupRender']
>(
withItemsContextProvider(
['default', 'items'],
@@ -27,12 +25,12 @@ export const Menu = sveltify<
onOpenChange,
onSelect,
onDeselect,
- setSlotParams,
...props
}) => {
const { items: slotItems } = useItems<['default', 'items']>();
const resolvedSlotItems =
slotItems.items.length > 0 ? slotItems.items : slotItems.default;
+ const popupRenderFunction = useFunction(props.popupRender);
return (
<>
{
- visible = v;
+ updateProps({
+ visible: v,
+ });
}}
>
-
{/await}
-
-
diff --git a/frontend/antd/message/package.json b/frontend/antd/message/package.json
index 6690b00d..c2d8089f 100644
--- a/frontend/antd/message/package.json
+++ b/frontend/antd/message/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/modal/Index.svelte b/frontend/antd/modal/Index.svelte
index c42604b0..17c7f0de 100644
--- a/frontend/antd/modal/Index.svelte
+++ b/frontend/antd/modal/Index.svelte
@@ -1,79 +1,62 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/modal/modal.tsx b/frontend/antd/modal/modal.tsx
index 52ea77df..b871bead 100644
--- a/frontend/antd/modal/modal.tsx
+++ b/frontend/antd/modal/modal.tsx
@@ -1,15 +1,12 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderParamsSlot } from '@utils/renderParamsSlot';
import { type GetProps, Modal as AModal } from 'antd';
export const Modal = sveltify<
- GetProps & {
- setSlotParams: SetSlotParams;
- },
+ GetProps,
[
'cancelButtonProps.icon',
'cancelText',
@@ -29,7 +26,6 @@ export const Modal = sveltify<
getContainer,
children,
modalRender,
- setSlotParams,
...props
}) => {
const afterOpenChangeFunction = useFunction(afterOpenChange);
@@ -83,7 +79,7 @@ export const Modal = sveltify<
}
footer={
slots.footer
- ? renderParamsSlot({ slots, setSlotParams, key: 'footer' })
+ ? renderParamsSlot({ slots, key: 'footer' })
: footerFunction ||
(props.footer === 'DEFAULT_FOOTER'
? undefined
@@ -94,7 +90,7 @@ export const Modal = sveltify<
title={slots.title ? {
- visible = v;
+ updateProps({ visible: v });
}}
>
-
{/await}
-
-
diff --git a/frontend/antd/modal/static/modal.static.tsx b/frontend/antd/modal/static/modal.static.tsx
index 48004912..97fbbef5 100644
--- a/frontend/antd/modal/static/modal.static.tsx
+++ b/frontend/antd/modal/static/modal.static.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React, { useEffect, useRef } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderParamsSlot } from '@utils/renderParamsSlot';
@@ -9,7 +8,6 @@ import type { ModalFuncWithPromise } from 'antd/es/modal/useModal';
export const ModalStatic = sveltify<
ModalFuncProps & {
- setSlotParams: SetSlotParams;
visible?: boolean;
type?: 'info' | 'success' | 'error' | 'warning' | 'confirm';
onVisible?: (visible: boolean) => void;
@@ -34,7 +32,6 @@ export const ModalStatic = sveltify<
getContainer,
children,
modalRender,
- setSlotParams,
onVisible,
onCancel,
onOk,
@@ -101,11 +98,11 @@ export const ModalStatic = sveltify<
props.closeIcon
),
footer: slots.footer
- ? renderParamsSlot({ slots, setSlotParams, key: 'footer' })
+ ? renderParamsSlot({ slots, key: 'footer' })
: props.footer,
title: slots.title ? {
- visible = v;
+ updateProps({
+ visible: v,
+ });
}}
>
-
{/await}
-
-
diff --git a/frontend/antd/notification/notification.tsx b/frontend/antd/notification/notification.tsx
index b75d6765..fa983cdb 100644
--- a/frontend/antd/notification/notification.tsx
+++ b/frontend/antd/notification/notification.tsx
@@ -13,7 +13,15 @@ export const Notification = sveltify<
visible?: boolean;
onVisible?: (visible: boolean) => void;
},
- ['btn', 'actions', 'closeIcon', 'description', 'icon', 'message']
+ [
+ 'btn',
+ 'actions',
+ 'closeIcon',
+ 'description',
+ 'icon',
+ 'message',
+ 'closable.closeIcon',
+ ]
>(
({
slots,
@@ -41,6 +49,12 @@ export const Notification = sveltify<
...props,
key: notificationKey,
btn: slots.btn ?
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/pagination/package.json b/frontend/antd/pagination/package.json
index e4670065..acb44162 100644
--- a/frontend/antd/pagination/package.json
+++ b/frontend/antd/pagination/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/pagination/pagination.tsx b/frontend/antd/pagination/pagination.tsx
index af3e7492..5d83e653 100644
--- a/frontend/antd/pagination/pagination.tsx
+++ b/frontend/antd/pagination/pagination.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderParamsSlot } from '@utils/renderParamsSlot';
@@ -9,7 +8,6 @@ import { type GetProps, Pagination as APagination } from 'antd';
export const Pagination = sveltify<
GetProps & {
children?: React.ReactNode;
- setSlotParams: SetSlotParams;
},
['showQuickJumper.goButton', 'itemRender']
>(
@@ -20,7 +18,6 @@ export const Pagination = sveltify<
onChange,
children,
itemRender,
- setSlotParams,
...props
}) => {
const itemRenderFunction = useFunction(itemRender);
@@ -33,10 +30,7 @@ export const Pagination = sveltify<
showTotal={showTotal ? showTotalFunction : undefined}
itemRender={
slots.itemRender
- ? renderParamsSlot(
- { slots, setSlotParams, key: 'itemRender' },
- { clone: true }
- )
+ ? renderParamsSlot({ slots, key: 'itemRender' }, { clone: true })
: itemRenderFunction
}
onChange={(page, pageSize) => {
diff --git a/frontend/antd/popconfirm/Index.svelte b/frontend/antd/popconfirm/Index.svelte
index f2c22de7..76e5abf3 100644
--- a/frontend/antd/popconfirm/Index.svelte
+++ b/frontend/antd/popconfirm/Index.svelte
@@ -1,79 +1,75 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/popconfirm/package.json b/frontend/antd/popconfirm/package.json
index fe5fff9e..05002b32 100644
--- a/frontend/antd/popconfirm/package.json
+++ b/frontend/antd/popconfirm/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/popconfirm/popconfirm.tsx b/frontend/antd/popconfirm/popconfirm.tsx
index a1708592..c01b288a 100644
--- a/frontend/antd/popconfirm/popconfirm.tsx
+++ b/frontend/antd/popconfirm/popconfirm.tsx
@@ -47,10 +47,10 @@ export const Popconfirm = sveltify<
props.cancelButtonProps?.icon
),
}}
- title={slots.title ?
-
{/await}
{/if}
diff --git a/frontend/antd/popover/package.json b/frontend/antd/popover/package.json
index 597b1773..801effd1 100644
--- a/frontend/antd/popover/package.json
+++ b/frontend/antd/popover/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/popover/popover.tsx b/frontend/antd/popover/popover.tsx
index f9fb0341..c22a4ec9 100644
--- a/frontend/antd/popover/popover.tsx
+++ b/frontend/antd/popover/popover.tsx
@@ -16,9 +16,15 @@ export const Popover = sveltify<
{...props}
afterOpenChange={afterOpenChangeFunction}
getPopupContainer={getPopupContainerFunction}
- title={slots.title ? & {
- setSlotParams: SetSlotParams;
- },
- ['statusRender']
->(({ setSlotParams, slots, statusRender, ...props }) => {
- const statusRenderFunction = useFunction(statusRender);
- return (
- & {}, ['statusRender']>(
+ ({ slots, statusRender, ...props }) => {
+ const statusRenderFunction = useFunction(statusRender);
+ return (
+ {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/radio/button/Index.svelte b/frontend/antd/radio/button/Index.svelte
index 38cfef38..e5d9fa08 100644
--- a/frontend/antd/radio/button/Index.svelte
+++ b/frontend/antd/radio/button/Index.svelte
@@ -1,84 +1,83 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/radio/button/package.json b/frontend/antd/radio/button/package.json
index ec80da14..18580565 100644
--- a/frontend/antd/radio/button/package.json
+++ b/frontend/antd/radio/button/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/radio/button/radio.button.tsx b/frontend/antd/radio/button/radio.button.tsx
index d74e5e9a..ddf3993b 100644
--- a/frontend/antd/radio/button/radio.button.tsx
+++ b/frontend/antd/radio/button/radio.button.tsx
@@ -21,8 +21,8 @@ export const Radio = sveltify<
}
ref={elRef}
onChange={(e) => {
- onChange?.(e);
onValueChange(e.target.checked);
+ onChange?.(e);
}}
/>
);
diff --git a/frontend/antd/radio/group/Index.svelte b/frontend/antd/radio/group/Index.svelte
index 4b236f1c..278ce547 100644
--- a/frontend/antd/radio/group/Index.svelte
+++ b/frontend/antd/radio/group/Index.svelte
@@ -1,84 +1,79 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/radio/group/option/Index.svelte b/frontend/antd/radio/group/option/Index.svelte
index 0b5dcd76..d3cb4aba 100644
--- a/frontend/antd/radio/group/option/Index.svelte
+++ b/frontend/antd/radio/group/option/Index.svelte
@@ -1,109 +1,100 @@
-
- {#if $mergedProps.visible}
-
{/await}
diff --git a/frontend/antd/radio/group/option/package.json b/frontend/antd/radio/group/option/package.json
index c93c2d0d..263f4e46 100644
--- a/frontend/antd/radio/group/option/package.json
+++ b/frontend/antd/radio/group/option/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/radio/group/package.json b/frontend/antd/radio/group/package.json
index bc2654c9..daff9e8a 100644
--- a/frontend/antd/radio/group/package.json
+++ b/frontend/antd/radio/group/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/radio/group/radio.group.tsx b/frontend/antd/radio/group/radio.group.tsx
index 427afdee..b6b5ef2a 100644
--- a/frontend/antd/radio/group/radio.group.tsx
+++ b/frontend/antd/radio/group/radio.group.tsx
@@ -1,5 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
-import { FormItemContext } from '@svelte-preprocess-react/context';
+import { FormItemContext } from '@svelte-preprocess-react/react-contexts';
import { useMemo } from 'react';
import { renderItems } from '@utils/renderItems';
import { type GetProps, Radio as ARadio } from 'antd';
@@ -31,8 +31,8 @@ export const RadioGroup = sveltify<
);
}, [optionItems, options])}
onChange={(e) => {
- onChange?.(e);
onValueChange(e.target.value);
+ onChange?.(e);
}}
>
diff --git a/frontend/antd/radio/package.json b/frontend/antd/radio/package.json
index 23aef293..a195a2ed 100644
--- a/frontend/antd/radio/package.json
+++ b/frontend/antd/radio/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/radio/radio.tsx b/frontend/antd/radio/radio.tsx
index d020d41b..4b29521b 100644
--- a/frontend/antd/radio/radio.tsx
+++ b/frontend/antd/radio/radio.tsx
@@ -21,8 +21,8 @@ export const Radio = sveltify<
}
ref={elRef}
onChange={(e) => {
- onChange?.(e);
onValueChange(e.target.checked);
+ onChange?.(e);
}}
/>
);
diff --git a/frontend/antd/rate/Index.svelte b/frontend/antd/rate/Index.svelte
index 2ba203ca..d6c95512 100644
--- a/frontend/antd/rate/Index.svelte
+++ b/frontend/antd/rate/Index.svelte
@@ -1,88 +1,86 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
- {setSlotParams}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/rate/package.json b/frontend/antd/rate/package.json
index fae33ef2..bb78d41e 100644
--- a/frontend/antd/rate/package.json
+++ b/frontend/antd/rate/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/rate/rate.tsx b/frontend/antd/rate/rate.tsx
index 31a9a009..854f502b 100644
--- a/frontend/antd/rate/rate.tsx
+++ b/frontend/antd/rate/rate.tsx
@@ -1,5 +1,4 @@
import { sveltify } from '@svelte-preprocess-react';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useFunction } from '@utils/hooks/useFunction';
import { renderParamsSlot } from '@utils/renderParamsSlot';
import { type GetProps, Rate as ARate } from 'antd';
@@ -8,7 +7,6 @@ export const Rate = sveltify<
GetProps & {
onValueChange: (value: number) => void;
children?: React.ReactNode;
- setSlotParams: SetSlotParams;
},
['character']
>(
@@ -18,11 +16,11 @@ export const Rate = sveltify<
onValueChange,
character,
onChange,
- setSlotParams,
elRef,
...props
}) => {
const characterFunction = useFunction(character, true);
+
return (
<>
-
{/await}
{/if}
diff --git a/frontend/antd/result/package.json b/frontend/antd/result/package.json
index 7f3d2a90..9aa37eb1 100644
--- a/frontend/antd/result/package.json
+++ b/frontend/antd/result/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/segmented/Index.svelte b/frontend/antd/segmented/Index.svelte
index 2af9c81f..345203cd 100644
--- a/frontend/antd/segmented/Index.svelte
+++ b/frontend/antd/segmented/Index.svelte
@@ -1,83 +1,89 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
>
-
{/await}
{/if}
diff --git a/frontend/antd/segmented/option/Index.svelte b/frontend/antd/segmented/option/Index.svelte
index ba33c847..f21b996b 100644
--- a/frontend/antd/segmented/option/Index.svelte
+++ b/frontend/antd/segmented/option/Index.svelte
@@ -1,90 +1,70 @@
-
- {#if $mergedProps.visible}
-
{/await}
diff --git a/frontend/antd/segmented/option/package.json b/frontend/antd/segmented/option/package.json
index e9e9c7ee..7f9d8348 100644
--- a/frontend/antd/segmented/option/package.json
+++ b/frontend/antd/segmented/option/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/segmented/package.json b/frontend/antd/segmented/package.json
index f1d43ad8..fa9777e9 100644
--- a/frontend/antd/segmented/package.json
+++ b/frontend/antd/segmented/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/segmented/segmented.tsx b/frontend/antd/segmented/segmented.tsx
index d6ac06bc..fcc49d4d 100644
--- a/frontend/antd/segmented/segmented.tsx
+++ b/frontend/antd/segmented/segmented.tsx
@@ -5,7 +5,8 @@ import { type GetProps, Segmented as ASegmented } from 'antd';
import { useItems, withItemsContextProvider } from './context';
-type SegmentedProps = GetProps;
+export type SegmentedProps = GetProps;
+
export const Segmented = sveltify<
SegmentedProps & {
onValueChange: (value: string | number) => void;
@@ -23,8 +24,8 @@ export const Segmented = sveltify<
{
- onChange?.(v);
onValueChange(v as string | number);
+ onChange?.(v);
}}
options={useMemo(() => {
// ['label','icon']
diff --git a/frontend/antd/select/Index.svelte b/frontend/antd/select/Index.svelte
index 647c882f..e584d31b 100644
--- a/frontend/antd/select/Index.svelte
+++ b/frontend/antd/select/Index.svelte
@@ -1,89 +1,87 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/select/option/package.json b/frontend/antd/select/option/package.json
index 527c382d..91f06aca 100644
--- a/frontend/antd/select/option/package.json
+++ b/frontend/antd/select/option/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/select/package.json b/frontend/antd/select/package.json
index 03094c7a..5b17e4a2 100644
--- a/frontend/antd/select/package.json
+++ b/frontend/antd/select/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/select/select.tsx b/frontend/antd/select/select.tsx
index ccc061d9..1e13fa4c 100644
--- a/frontend/antd/select/select.tsx
+++ b/frontend/antd/select/select.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderItems } from '@utils/renderItems';
@@ -12,7 +11,6 @@ import { useItems, withItemsContextProvider } from './context';
export const Select = sveltify<
GetProps & {
onValueChange: (value: string | number | (string | number)[]) => void;
- setSlotParams: SetSlotParams;
},
[
'allowClear.clearIcon',
@@ -46,7 +44,6 @@ export const Select = sveltify<
labelRender,
filterSort,
elRef,
- setSlotParams,
...props
}) => {
const getPopupContainerFunction = useFunction(getPopupContainer);
@@ -79,8 +76,8 @@ export const Select = sveltify<
);
}, [resolvedSlotItems, options])}
onChange={(v, ...args) => {
- onChange?.(v, ...args);
onValueChange(v as string);
+ onChange?.(v, ...args);
}}
allowClear={
slots['allowClear.clearIcon']
@@ -127,7 +124,6 @@ export const Select = sveltify<
slots.maxTagPlaceholder
? renderParamsSlot({
slots,
- setSlotParams,
key: 'maxTagPlaceholder',
})
: props.maxTagPlaceholder
@@ -137,7 +133,6 @@ export const Select = sveltify<
slots.dropdownRender
? renderParamsSlot({
slots,
- setSlotParams,
key: 'dropdownRender',
})
: dropdownRenderFunction
@@ -146,7 +141,6 @@ export const Select = sveltify<
slots.popupRender
? renderParamsSlot({
slots,
- setSlotParams,
key: 'popupRender',
})
: popupRenderFunction
@@ -155,7 +149,6 @@ export const Select = sveltify<
slots.optionRender
? renderParamsSlot({
slots,
- setSlotParams,
key: 'optionRender',
})
: optionRenderFunction
@@ -164,7 +157,6 @@ export const Select = sveltify<
slots.tagRender
? renderParamsSlot({
slots,
- setSlotParams,
key: 'tagRender',
})
: tagRenderFunction
@@ -173,7 +165,6 @@ export const Select = sveltify<
slots.labelRender
? renderParamsSlot({
slots,
- setSlotParams,
key: 'labelRender',
})
: labelRenderFunction
diff --git a/frontend/antd/skeleton/Index.svelte b/frontend/antd/skeleton/Index.svelte
index 52f891ca..70645c9c 100644
--- a/frontend/antd/skeleton/Index.svelte
+++ b/frontend/antd/skeleton/Index.svelte
@@ -1,73 +1,60 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/skeleton/avatar/Index.svelte b/frontend/antd/skeleton/avatar/Index.svelte
index 75e7bb1e..b0ec9109 100644
--- a/frontend/antd/skeleton/avatar/Index.svelte
+++ b/frontend/antd/skeleton/avatar/Index.svelte
@@ -1,75 +1,61 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/skeleton/avatar/package.json b/frontend/antd/skeleton/avatar/package.json
index 35aa5482..94e36420 100644
--- a/frontend/antd/skeleton/avatar/package.json
+++ b/frontend/antd/skeleton/avatar/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/skeleton/button/Index.svelte b/frontend/antd/skeleton/button/Index.svelte
index 1417e492..8c861f2b 100644
--- a/frontend/antd/skeleton/button/Index.svelte
+++ b/frontend/antd/skeleton/button/Index.svelte
@@ -1,75 +1,61 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/skeleton/button/package.json b/frontend/antd/skeleton/button/package.json
index 415a6d95..b30a59d4 100644
--- a/frontend/antd/skeleton/button/package.json
+++ b/frontend/antd/skeleton/button/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/skeleton/image/Index.svelte b/frontend/antd/skeleton/image/Index.svelte
index c4fb677a..831d3c68 100644
--- a/frontend/antd/skeleton/image/Index.svelte
+++ b/frontend/antd/skeleton/image/Index.svelte
@@ -1,75 +1,61 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/skeleton/image/package.json b/frontend/antd/skeleton/image/package.json
index 6467b271..00e30e54 100644
--- a/frontend/antd/skeleton/image/package.json
+++ b/frontend/antd/skeleton/image/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/skeleton/input/Index.svelte b/frontend/antd/skeleton/input/Index.svelte
index d673621c..c78fff7e 100644
--- a/frontend/antd/skeleton/input/Index.svelte
+++ b/frontend/antd/skeleton/input/Index.svelte
@@ -1,75 +1,61 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/skeleton/input/package.json b/frontend/antd/skeleton/input/package.json
index 011e2611..104f9b5d 100644
--- a/frontend/antd/skeleton/input/package.json
+++ b/frontend/antd/skeleton/input/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/skeleton/node/Index.svelte b/frontend/antd/skeleton/node/Index.svelte
index dae77478..1d119166 100644
--- a/frontend/antd/skeleton/node/Index.svelte
+++ b/frontend/antd/skeleton/node/Index.svelte
@@ -1,70 +1,59 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/skeleton/node/package.json b/frontend/antd/skeleton/node/package.json
index a4a7b24c..7ed2bc2e 100644
--- a/frontend/antd/skeleton/node/package.json
+++ b/frontend/antd/skeleton/node/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/skeleton/package.json b/frontend/antd/skeleton/package.json
index a8848a90..93eba12a 100644
--- a/frontend/antd/skeleton/package.json
+++ b/frontend/antd/skeleton/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/slider/Index.svelte b/frontend/antd/slider/Index.svelte
index c81e6b67..e8801608 100644
--- a/frontend/antd/slider/Index.svelte
+++ b/frontend/antd/slider/Index.svelte
@@ -1,84 +1,84 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
- {setSlotParams}
>
-
{/await}
{/if}
diff --git a/frontend/antd/slider/mark/Index.svelte b/frontend/antd/slider/mark/Index.svelte
index 0017f877..af213aec 100644
--- a/frontend/antd/slider/mark/Index.svelte
+++ b/frontend/antd/slider/mark/Index.svelte
@@ -1,97 +1,73 @@
-
- {#if $mergedProps.visible}
-
-
+ {@render children?.()}
{/if}
diff --git a/frontend/antd/slider/mark/package.json b/frontend/antd/slider/mark/package.json
index f7302d2a..9c6c59d8 100644
--- a/frontend/antd/slider/mark/package.json
+++ b/frontend/antd/slider/mark/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/slider/package.json b/frontend/antd/slider/package.json
index 7cb4695d..15a52e8c 100644
--- a/frontend/antd/slider/package.json
+++ b/frontend/antd/slider/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/slider/slider.tsx b/frontend/antd/slider/slider.tsx
index d6090485..ae1c413f 100644
--- a/frontend/antd/slider/slider.tsx
+++ b/frontend/antd/slider/slider.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderParamsSlot } from '@utils/renderParamsSlot';
@@ -39,7 +38,6 @@ export const Slider = sveltify<
SliderProps & {
onValueChange: (value: number | number[]) => void;
children?: React.ReactNode;
- setSlotParams: SetSlotParams;
},
['tooltip.formatter']
>(
@@ -54,12 +52,11 @@ export const Slider = sveltify<
tooltip,
step,
slots,
- setSlotParams,
...props
}) => {
const onSliderChange = (v: number | number[]) => {
- onChange?.(v as any);
onValueChange(v);
+ onChange?.(v as any);
};
const tooltipGetPopupContainerFunction = useFunction(
tooltip?.getPopupContainer
@@ -79,7 +76,6 @@ export const Slider = sveltify<
formatter: slots['tooltip.formatter']
? renderParamsSlot({
key: 'tooltip.formatter',
- setSlotParams,
slots,
})
: tooltipFormatterFunction,
diff --git a/frontend/antd/space/Index.svelte b/frontend/antd/space/Index.svelte
index 00a37121..448af26e 100644
--- a/frontend/antd/space/Index.svelte
+++ b/frontend/antd/space/Index.svelte
@@ -1,72 +1,60 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/space/compact/Index.svelte b/frontend/antd/space/compact/Index.svelte
index 2a118b09..6307e85c 100644
--- a/frontend/antd/space/compact/Index.svelte
+++ b/frontend/antd/space/compact/Index.svelte
@@ -1,73 +1,59 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/space/compact/package.json b/frontend/antd/space/compact/package.json
index c6865718..b874ec55 100644
--- a/frontend/antd/space/compact/package.json
+++ b/frontend/antd/space/compact/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/space/package.json b/frontend/antd/space/package.json
index 2f2bb790..c7177363 100644
--- a/frontend/antd/space/package.json
+++ b/frontend/antd/space/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/spin/Index.svelte b/frontend/antd/spin/Index.svelte
index 2a7fda1b..73a6daf1 100644
--- a/frontend/antd/spin/Index.svelte
+++ b/frontend/antd/spin/Index.svelte
@@ -1,75 +1,61 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/spin/package.json b/frontend/antd/spin/package.json
index ae3028cc..e1a9d8bc 100644
--- a/frontend/antd/spin/package.json
+++ b/frontend/antd/spin/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/splitter/Index.svelte b/frontend/antd/splitter/Index.svelte
index b500ea58..60511cad 100644
--- a/frontend/antd/splitter/Index.svelte
+++ b/frontend/antd/splitter/Index.svelte
@@ -1,75 +1,72 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/splitter/package.json b/frontend/antd/splitter/package.json
index f81675f0..26bf437d 100644
--- a/frontend/antd/splitter/package.json
+++ b/frontend/antd/splitter/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/splitter/panel/Index.svelte b/frontend/antd/splitter/panel/Index.svelte
index 730eb8fa..f3a8249e 100644
--- a/frontend/antd/splitter/panel/Index.svelte
+++ b/frontend/antd/splitter/panel/Index.svelte
@@ -1,85 +1,69 @@
-
- {#if $mergedProps.visible}
-
-
+ {@render children?.()}
{/if}
diff --git a/frontend/antd/splitter/panel/package.json b/frontend/antd/splitter/panel/package.json
index 79840404..03b83b8e 100644
--- a/frontend/antd/splitter/panel/package.json
+++ b/frontend/antd/splitter/panel/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/statistic/Index.svelte b/frontend/antd/statistic/Index.svelte
index e34cc794..f756d0fc 100644
--- a/frontend/antd/statistic/Index.svelte
+++ b/frontend/antd/statistic/Index.svelte
@@ -1,78 +1,64 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/statistic/countdown/Index.svelte b/frontend/antd/statistic/countdown/Index.svelte
index 608e608b..db8fc89a 100644
--- a/frontend/antd/statistic/countdown/Index.svelte
+++ b/frontend/antd/statistic/countdown/Index.svelte
@@ -1,76 +1,65 @@
-
-
+ {@render children?.()}
+
{/await}
{/if}
-
-
diff --git a/frontend/antd/statistic/countdown/package.json b/frontend/antd/statistic/countdown/package.json
index 8e94d069..b45af8d9 100644
--- a/frontend/antd/statistic/countdown/package.json
+++ b/frontend/antd/statistic/countdown/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/statistic/package.json b/frontend/antd/statistic/package.json
index 6e457ec3..71849740 100644
--- a/frontend/antd/statistic/package.json
+++ b/frontend/antd/statistic/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/statistic/statistic.tsx b/frontend/antd/statistic/statistic.tsx
index adaf1d4c..4aec9e06 100644
--- a/frontend/antd/statistic/statistic.tsx
+++ b/frontend/antd/statistic/statistic.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderParamsSlot } from '@utils/renderParamsSlot';
@@ -9,10 +8,9 @@ import { type GetProps, Statistic as AStatistic } from 'antd';
export const Statistic = sveltify<
GetProps & {
children: React.ReactNode;
- setSlotParams: SetSlotParams;
},
['prefix', 'suffix', 'title', 'formatter']
->(({ children, slots, setSlotParams, formatter, ...props }) => {
+>(({ children, slots, formatter, ...props }) => {
const formatterFunction = useFunction(formatter);
return (
<>
@@ -21,7 +19,7 @@ export const Statistic = sveltify<
{...props}
formatter={
slots.formatter
- ? renderParamsSlot({ slots, setSlotParams, key: 'formatter' })
+ ? renderParamsSlot({ slots, key: 'formatter' })
: formatterFunction
}
title={slots.title ?
-
+ {@render children?.()}
+
{/await}
{/if}
-
-
diff --git a/frontend/antd/statistic/timer/package.json b/frontend/antd/statistic/timer/package.json
index 7ef22ab1..f05ffff8 100644
--- a/frontend/antd/statistic/timer/package.json
+++ b/frontend/antd/statistic/timer/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/statistic/timer/statistic.timer.tsx b/frontend/antd/statistic/timer/statistic.timer.tsx
index 26d704c6..628e971b 100644
--- a/frontend/antd/statistic/timer/statistic.timer.tsx
+++ b/frontend/antd/statistic/timer/statistic.timer.tsx
@@ -3,10 +3,12 @@ import { ReactSlot } from '@svelte-preprocess-react/react-slot';
import React from 'react';
import { type GetProps, Statistic as AStatistic } from 'antd';
+export type StatisticTimer = GetProps & {
+ children: React.ReactNode;
+};
+
export const StatisticTimer = sveltify<
- GetProps & {
- children: React.ReactNode;
- },
+ StatisticTimer,
['prefix', 'suffix', 'title']
>(({ children, value, slots, ...props }) => {
return (
diff --git a/frontend/antd/steps/Index.svelte b/frontend/antd/steps/Index.svelte
index d38bfde4..0c101271 100644
--- a/frontend/antd/steps/Index.svelte
+++ b/frontend/antd/steps/Index.svelte
@@ -1,79 +1,62 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/steps/item/Index.svelte b/frontend/antd/steps/item/Index.svelte
index 04723552..a2b6a9c8 100644
--- a/frontend/antd/steps/item/Index.svelte
+++ b/frontend/antd/steps/item/Index.svelte
@@ -1,81 +1,64 @@
-
- {#if $mergedProps.visible}
-
-{/await}
+{#if proceedProps.visible}
+ {#await AwaitedStepsItem then StepsItem}
+
+ {@render children?.()}
+
+ {/await}
+{/if}
diff --git a/frontend/antd/steps/item/package.json b/frontend/antd/steps/item/package.json
index 533045f0..ca8b4ada 100644
--- a/frontend/antd/steps/item/package.json
+++ b/frontend/antd/steps/item/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/steps/item/steps.item.tsx b/frontend/antd/steps/item/steps.item.tsx
index 4578ffe7..24beecdf 100644
--- a/frontend/antd/steps/item/steps.item.tsx
+++ b/frontend/antd/steps/item/steps.item.tsx
@@ -1,10 +1,12 @@
import { sveltify } from '@svelte-preprocess-react';
import React from 'react';
-import type { StepProps } from 'antd';
+import type { StepsProps } from 'antd';
import { ItemHandler, type ItemHandlerProps } from '../context';
-export const StepsItem = sveltify((props) => {
+export const StepsItem = sveltify<
+ NonNullable[number] & ItemHandlerProps
+>((props) => {
return & {
- setSlotParams: SetSlotParams;
+ children?: React.ReactNode;
},
['progressDot']
>(
withItemsContextProvider(
['items', 'default'],
- ({ slots, items, setSlotParams, children, progressDot, ...props }) => {
+ ({ slots, items, children, progressDot, ...props }) => {
const { items: slotItems } = useItems<['items', 'default']>();
const resolvedSlotItems =
slotItems.items.length > 0 ? slotItems.items : slotItems.default;
@@ -37,7 +36,7 @@ export const Steps = sveltify<
progressDot={
slots.progressDot
? renderParamsSlot(
- { slots, setSlotParams, key: 'progressDot' },
+ { slots, key: 'progressDot' },
{ clone: true }
)
: progressDotFunction || progressDot
diff --git a/frontend/antd/switch/Index.svelte b/frontend/antd/switch/Index.svelte
index 776e2160..5136fb3a 100644
--- a/frontend/antd/switch/Index.svelte
+++ b/frontend/antd/switch/Index.svelte
@@ -1,78 +1,75 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/switch/package.json b/frontend/antd/switch/package.json
index 3a81efa0..420b2865 100644
--- a/frontend/antd/switch/package.json
+++ b/frontend/antd/switch/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/table/Index.svelte b/frontend/antd/table/Index.svelte
index a942d39b..63633840 100644
--- a/frontend/antd/table/Index.svelte
+++ b/frontend/antd/table/Index.svelte
@@ -1,73 +1,60 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/table/column-group/Index.svelte b/frontend/antd/table/column-group/Index.svelte
index a0c71dd3..7fb818f1 100644
--- a/frontend/antd/table/column-group/Index.svelte
+++ b/frontend/antd/table/column-group/Index.svelte
@@ -1,90 +1,67 @@
-
- {#if $mergedProps.visible}
-
+
{/await}
diff --git a/frontend/antd/table/column-group/package.json b/frontend/antd/table/column-group/package.json
index 0b211b78..d01a7cf9 100644
--- a/frontend/antd/table/column-group/package.json
+++ b/frontend/antd/table/column-group/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/table/column/Index.svelte b/frontend/antd/table/column/Index.svelte
index d1864e2c..1a01775f 100644
--- a/frontend/antd/table/column/Index.svelte
+++ b/frontend/antd/table/column/Index.svelte
@@ -1,186 +1,208 @@
-
- {#if $mergedProps.visible}
-
{/await}
diff --git a/frontend/antd/table/column/package.json b/frontend/antd/table/column/package.json
index 4d346167..41f90e4e 100644
--- a/frontend/antd/table/column/package.json
+++ b/frontend/antd/table/column/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/table/column/table.column.tsx b/frontend/antd/table/column/table.column.tsx
index 8429fe16..aa7f87d7 100644
--- a/frontend/antd/table/column/table.column.tsx
+++ b/frontend/antd/table/column/table.column.tsx
@@ -1,11 +1,10 @@
import { sveltify } from '@svelte-preprocess-react';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React from 'react';
import { createFunction } from '@utils/createFunction';
import { renderItems } from '@utils/renderItems';
import { renderParamsSlot } from '@utils/renderParamsSlot';
import { renderSlot } from '@utils/renderSlot';
-import { type TableColumnProps } from 'antd';
+import { type TableColumnProps as ATableColumnProps } from 'antd';
import {
useItems as useMenuItems,
@@ -13,16 +12,15 @@ import {
} from '../../menu/context';
import { ColumnItemHandler, type ItemHandlerProps } from '../context';
-export const TableColumn = sveltify<
- TableColumnProps &
- ItemHandlerProps & {
- setSlotParams: SetSlotParams;
- itemSlots: Record;
- }
->(
+export type TableColumnProps = ATableColumnProps &
+ ItemHandlerProps & {
+ itemSlots: Record;
+ };
+
+export const TableColumn = sveltify(
withMenuItemsContextProvider(
['filterDropdownProps.menu.items'],
- ({ setSlotParams, itemSlots: slots, ...props }) => {
+ ({ itemSlots: slots, ...props }) => {
const {
items: { 'filterDropdownProps.menu.items': dropdownMenuItems },
} = useMenuItems<['filterDropdownProps.menu.items']>();
@@ -34,7 +32,7 @@ export const TableColumn = sveltify<
...(itemProps.filterDropdownProps?.menu || {}),
items:
itemProps.filterDropdownProps?.menu?.items ||
- dropdownMenuItems.length > 0
+ dropdownMenuItems?.length > 0
? renderItems(dropdownMenuItems, {
clone: true,
})
@@ -42,7 +40,6 @@ export const TableColumn = sveltify<
expandIcon:
renderParamsSlot(
{
- setSlotParams,
slots: slots,
key: 'filterDropdownProps.menu.expandIcon',
},
@@ -61,7 +58,6 @@ export const TableColumn = sveltify<
dropdownRender: slots['filterDropdownProps.dropdownRender']
? renderParamsSlot(
{
- setSlotParams,
slots: slots,
key: 'filterDropdownProps.dropdownRender',
},
@@ -73,7 +69,6 @@ export const TableColumn = sveltify<
popupRender: slots['filterDropdownProps.popupRender']
? renderParamsSlot(
{
- setSlotParams,
slots: slots,
key: 'filterDropdownProps.popupRender',
},
diff --git a/frontend/antd/table/expandable/Index.svelte b/frontend/antd/table/expandable/Index.svelte
index d7469d29..ad63c347 100644
--- a/frontend/antd/table/expandable/Index.svelte
+++ b/frontend/antd/table/expandable/Index.svelte
@@ -1,120 +1,125 @@
-
- {#if $mergedProps.visible}
-
+
{/await}
diff --git a/frontend/antd/table/expandable/package.json b/frontend/antd/table/expandable/package.json
index 7903774c..49fcbeb9 100644
--- a/frontend/antd/table/expandable/package.json
+++ b/frontend/antd/table/expandable/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/table/package.json b/frontend/antd/table/package.json
index 30aa7610..d7b65337 100644
--- a/frontend/antd/table/package.json
+++ b/frontend/antd/table/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/table/row-selection/Index.svelte b/frontend/antd/table/row-selection/Index.svelte
index 3b46e8ac..c6078bf6 100644
--- a/frontend/antd/table/row-selection/Index.svelte
+++ b/frontend/antd/table/row-selection/Index.svelte
@@ -1,127 +1,117 @@
-
- {#if $mergedProps.visible}
-
+
{/await}
diff --git a/frontend/antd/table/row-selection/package.json b/frontend/antd/table/row-selection/package.json
index bf1eafd4..f2dbb877 100644
--- a/frontend/antd/table/row-selection/package.json
+++ b/frontend/antd/table/row-selection/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/table/row-selection/selection/Index.svelte b/frontend/antd/table/row-selection/selection/Index.svelte
index aeafd99e..89f13ef0 100644
--- a/frontend/antd/table/row-selection/selection/Index.svelte
+++ b/frontend/antd/table/row-selection/selection/Index.svelte
@@ -1,94 +1,78 @@
-
- {#if $mergedProps.visible}
-
+
{/await}
diff --git a/frontend/antd/table/row-selection/selection/package.json b/frontend/antd/table/row-selection/selection/package.json
index 975c06b9..af88e2e9 100644
--- a/frontend/antd/table/row-selection/selection/package.json
+++ b/frontend/antd/table/row-selection/selection/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/table/row-selection/table.row-selection.tsx b/frontend/antd/table/row-selection/table.row-selection.tsx
index 18d4f6cd..1b3acd75 100644
--- a/frontend/antd/table/row-selection/table.row-selection.tsx
+++ b/frontend/antd/table/row-selection/table.row-selection.tsx
@@ -24,7 +24,7 @@ export const TableRowSelection = sveltify<
return {
...itemProps,
selections:
- selectionsItems.length > 0
+ selectionsItems?.length > 0
? renderItems(selectionsItems)
: itemProps.selections,
};
diff --git a/frontend/antd/table/table.tsx b/frontend/antd/table/table.tsx
index d1037bdc..ae55eb9a 100644
--- a/frontend/antd/table/table.tsx
+++ b/frontend/antd/table/table.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React, { useMemo } from 'react';
import { createFunction } from '@utils/createFunction';
import { useFunction } from '@utils/hooks/useFunction';
@@ -27,9 +26,7 @@ function getConfig(value: T): Partial> {
type TableProps = GetProps;
export const Table = sveltify<
- TableProps & {
- setSlotParams: SetSlotParams;
- },
+ TableProps & {},
[
'footer',
'title',
@@ -65,7 +62,6 @@ export const Table = sveltify<
onRow,
onHeaderRow,
components,
- setSlotParams,
...props
}) => {
const {
@@ -172,7 +168,7 @@ export const Table = sveltify<
onHeaderRow={onHeaderRowFunction}
summary={
slots.summary
- ? renderParamsSlot({ slots, setSlotParams, key: 'summary' })
+ ? renderParamsSlot({ slots, key: 'summary' })
: summaryFunction
}
rowSelection={useMemo(() => {
@@ -236,7 +232,6 @@ export const Table = sveltify<
itemRender: slots['pagination.itemRender']
? renderParamsSlot({
slots,
- setSlotParams,
key: 'pagination.itemRender',
})
: paginationConfig.itemRender,
@@ -263,12 +258,12 @@ export const Table = sveltify<
}
footer={
slots.footer
- ? renderParamsSlot({ slots, setSlotParams, key: 'footer' })
+ ? renderParamsSlot({ slots, key: 'footer' })
: footerFunction
}
title={
slots.title
- ? renderParamsSlot({ slots, setSlotParams, key: 'title' })
+ ? renderParamsSlot({ slots, key: 'title' })
: props.title
}
/>
diff --git a/frontend/antd/tabs/Index.svelte b/frontend/antd/tabs/Index.svelte
index 4eb78584..5a594eab 100644
--- a/frontend/antd/tabs/Index.svelte
+++ b/frontend/antd/tabs/Index.svelte
@@ -1,81 +1,68 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/tabs/item/Index.svelte b/frontend/antd/tabs/item/Index.svelte
index b80b1427..601c3a51 100644
--- a/frontend/antd/tabs/item/Index.svelte
+++ b/frontend/antd/tabs/item/Index.svelte
@@ -1,93 +1,77 @@
-
-
-{#await AwaitedTabsItem then TabsItem}
-
- {#if $mergedProps.visible}
-
-
+ {@render children?.()}
{/if}
diff --git a/frontend/antd/tabs/item/package.json b/frontend/antd/tabs/item/package.json
index cefe2bfb..24f8d65c 100644
--- a/frontend/antd/tabs/item/package.json
+++ b/frontend/antd/tabs/item/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/tabs/package.json b/frontend/antd/tabs/package.json
index c52cec1f..d3d5cb53 100644
--- a/frontend/antd/tabs/package.json
+++ b/frontend/antd/tabs/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/tabs/tabs.tsx b/frontend/antd/tabs/tabs.tsx
index 92ca3183..82db68ad 100644
--- a/frontend/antd/tabs/tabs.tsx
+++ b/frontend/antd/tabs/tabs.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React, { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { omitUndefinedProps } from '@utils/omitUndefinedProps';
@@ -11,9 +10,7 @@ import { type GetProps, Tabs as ATabs } from 'antd';
import { useItems, withItemsContextProvider } from './context';
export const Tabs = sveltify<
- GetProps & {
- setSlotParams: SetSlotParams;
- },
+ GetProps & {},
[
'addIcon',
'removeIcon',
@@ -34,7 +31,6 @@ export const Tabs = sveltify<
more,
children,
renderTabBar,
- setSlotParams,
...props
}) => {
const indicatorSizeFunction = useFunction(indicator?.size);
@@ -62,7 +58,6 @@ export const Tabs = sveltify<
slots.renderTabBar
? renderParamsSlot({
slots,
- setSlotParams,
key: 'renderTabBar',
})
: renderTabBarFunction
diff --git a/frontend/antd/tag/Index.svelte b/frontend/antd/tag/Index.svelte
index 868f17fb..ea735bae 100644
--- a/frontend/antd/tag/Index.svelte
+++ b/frontend/antd/tag/Index.svelte
@@ -1,80 +1,66 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/tag/checkable-tag-group/Index.svelte b/frontend/antd/tag/checkable-tag-group/Index.svelte
new file mode 100644
index 00000000..bdf45c41
--- /dev/null
+++ b/frontend/antd/tag/checkable-tag-group/Index.svelte
@@ -0,0 +1,78 @@
+
+
+{#if proceedProps.visible}
+ {#await AwaitedCheckableTagGroup then CheckableTagGroup}
+ {
+ updateProps({ value: v });
+ }}
+ >
+ {@render children?.()}
+
+ {/await}
+{/if}
diff --git a/frontend/antd/tag/checkable-tag-group/context.ts b/frontend/antd/tag/checkable-tag-group/context.ts
new file mode 100644
index 00000000..334bbc0e
--- /dev/null
+++ b/frontend/antd/tag/checkable-tag-group/context.ts
@@ -0,0 +1,6 @@
+import { createItemsContext } from '@utils/createItemsContext';
+
+export const { withItemsContextProvider, useItems, ItemHandler } =
+ createItemsContext('antd-checkable-tag-group-options');
+
+export * from '@utils/createItemsContext';
diff --git a/frontend/antd/tag/checkable-tag-group/gradio.config.js b/frontend/antd/tag/checkable-tag-group/gradio.config.js
new file mode 100644
index 00000000..1992403d
--- /dev/null
+++ b/frontend/antd/tag/checkable-tag-group/gradio.config.js
@@ -0,0 +1,3 @@
+import config from '../../../defineConfig.js';
+
+export default config();
diff --git a/frontend/antd/tag/checkable-tag-group/option/Index.svelte b/frontend/antd/tag/checkable-tag-group/option/Index.svelte
new file mode 100644
index 00000000..9bc181c4
--- /dev/null
+++ b/frontend/antd/tag/checkable-tag-group/option/Index.svelte
@@ -0,0 +1,73 @@
+
+
+{#if proceedProps.visible}
+ {#await AwaitedCheckableTagGroupOption then CheckableTagGroupOption}
+
+ {@render children?.()}
+
+ {/await}
+{/if}
diff --git a/frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx b/frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx
new file mode 100644
index 00000000..49753ddd
--- /dev/null
+++ b/frontend/antd/tag/checkable-tag-group/option/checkable-tag-group.option.tsx
@@ -0,0 +1,13 @@
+import { sveltify } from '@svelte-preprocess-react';
+import React from 'react';
+import type { CheckableTagGroupProps } from 'antd/es/tag';
+
+import { ItemHandler, type ItemHandlerProps } from '../context';
+
+export const CheckableTagGroupOption = sveltify<
+ NonNullable['options']>[number] & ItemHandlerProps
+>((props) => {
+ return & {
+ onValueChange: (value: any) => void;
+ children?: React.ReactNode;
+ }
+>(
+ withItemsContextProvider(
+ ['options', 'default'],
+ ({ onChange, onValueChange, children, elRef, options, ...props }) => {
+ const { items: slotItems } = useItems<['options', 'default']>();
+ const resolvedSlotItems =
+ slotItems.options.length > 0 ? slotItems.options : slotItems.default;
+ return (
+ <>
+ {
+ return (
+ options ||
+ renderItems<
+ NonNullable<
+ GetProps['options']
+ >[number]
+ >(resolvedSlotItems, {
+ children: 'options',
+ clone: true,
+ })
+ );
+ }, [resolvedSlotItems, options])}
+ onChange={(v) => {
+ onValueChange(v);
+ onChange?.(v as any);
+ }}
+ />
+
+ );
+ }
+ )
+);
+
+export default CheckableTagGroup;
diff --git a/frontend/antd/tag/checkable-tag/Index.svelte b/frontend/antd/tag/checkable-tag/Index.svelte
index 847e2111..3279bd06 100644
--- a/frontend/antd/tag/checkable-tag/Index.svelte
+++ b/frontend/antd/tag/checkable-tag/Index.svelte
@@ -1,89 +1,76 @@
- {
- value = checked;
+ updateProps({ value: checked });
}}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/tag/checkable-tag/package.json b/frontend/antd/tag/checkable-tag/package.json
index ce1b1c46..bcbdd76c 100644
--- a/frontend/antd/tag/checkable-tag/package.json
+++ b/frontend/antd/tag/checkable-tag/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx b/frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx
index b873f444..ffc5147a 100644
--- a/frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx
+++ b/frontend/antd/tag/checkable-tag/tag.checkable-tag.tsx
@@ -21,8 +21,8 @@ export const CheckableTag = sveltify<
{...props}
icon={slots.icon ? {
- value = val;
+ style={proceedProps.elem_style}
+ className={cls(proceedProps.elem_classes, 'ms-gr-antd-time-picker')}
+ id={proceedProps.elem_id}
+ {...proceedProps.restProps}
+ {...proceedProps.additionalProps}
+ slots={slots.value}
+ value={proceedProps.additionalProps.value ?? proceedProps.value}
+ onValueChange={(v) => {
+ updateProps({
+ value: v,
+ });
}}
- {setSlotParams}
>
-
{/await}
{/if}
diff --git a/frontend/antd/time-picker/package.json b/frontend/antd/time-picker/package.json
index 32687b6b..0cf763a6 100644
--- a/frontend/antd/time-picker/package.json
+++ b/frontend/antd/time-picker/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/time-picker/range-picker/Index.svelte b/frontend/antd/time-picker/range-picker/Index.svelte
index 46e0cbf4..792a4f51 100644
--- a/frontend/antd/time-picker/range-picker/Index.svelte
+++ b/frontend/antd/time-picker/range-picker/Index.svelte
@@ -1,90 +1,85 @@
- {
- value = val;
+ updateProps({ value: val });
}}
- {setSlotParams}
>
-
{/await}
{/if}
diff --git a/frontend/antd/time-picker/range-picker/package.json b/frontend/antd/time-picker/range-picker/package.json
index 60da7ac4..a78d72d7 100644
--- a/frontend/antd/time-picker/range-picker/package.json
+++ b/frontend/antd/time-picker/range-picker/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx b/frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx
index ed952a15..0e7aeb1e 100644
--- a/frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx
+++ b/frontend/antd/time-picker/range-picker/time-picker.range-picker.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderParamsSlot } from '@utils/renderParamsSlot';
@@ -36,7 +35,6 @@ export const TimeRangePicker = sveltify<
...args: any[]
) => void;
onValueChange: (dates: [number | null, number | null]) => void;
- setSlotParams: SetSlotParams;
},
[
'allowClear.clearIcon',
@@ -69,7 +67,6 @@ export const TimeRangePicker = sveltify<
onPanelChange,
onCalendarChange,
children,
- setSlotParams,
elRef,
...props
}) => {
@@ -126,12 +123,12 @@ export const TimeRangePicker = sveltify<
getPopupContainer={getPopupContainerFunction}
cellRender={
slots.cellRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'cellRender' })
+ ? renderParamsSlot({ slots, key: 'cellRender' })
: cellRenderFunction
}
panelRender={
slots.panelRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'panelRender' })
+ ? renderParamsSlot({ slots, key: 'panelRender' })
: panelRenderFunction
}
onPanelChange={(dates, ...args) => {
@@ -140,8 +137,8 @@ export const TimeRangePicker = sveltify<
}}
onChange={(dates, ...args) => {
const formattedDates = formatDates(dates);
- onChange?.(formattedDates, ...args);
onValueChange(formattedDates);
+ onChange?.(formattedDates, ...args);
}}
onCalendarChange={(dates, ...args) => {
const formattedDates = formatDates(dates);
diff --git a/frontend/antd/time-picker/time-picker.tsx b/frontend/antd/time-picker/time-picker.tsx
index 39f78f1d..23b65645 100644
--- a/frontend/antd/time-picker/time-picker.tsx
+++ b/frontend/antd/time-picker/time-picker.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderParamsSlot } from '@utils/renderParamsSlot';
@@ -21,7 +20,9 @@ function formatDayjs(date: any): dayjs.Dayjs {
return dayjs(date);
}
-function formatDate(dates: (dayjs.Dayjs | null | undefined)[] | dayjs.Dayjs) {
+function formatDate(
+ dates: (dayjs.Dayjs | null | undefined)[] | dayjs.Dayjs | null
+) {
if (Array.isArray(dates)) {
return dates.map((date) => {
return date ? date.valueOf() / 1000 : null;
@@ -45,7 +46,6 @@ export const TimePicker = sveltify<
...args: any[]
) => void;
onValueChange: (date: number | string) => void;
- setSlotParams: SetSlotParams;
},
[
'allowClear.clearIcon',
@@ -77,7 +77,6 @@ export const TimePicker = sveltify<
onPanelChange,
onCalendarChange,
children,
- setSlotParams,
elRef,
...props
}) => {
@@ -121,12 +120,12 @@ export const TimePicker = sveltify<
getPopupContainer={getPopupContainerFunction}
cellRender={
slots.cellRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'cellRender' })
+ ? renderParamsSlot({ slots, key: 'cellRender' })
: cellRenderFunction
}
panelRender={
slots.panelRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'panelRender' })
+ ? renderParamsSlot({ slots, key: 'panelRender' })
: panelRenderFunction
}
onPanelChange={(date, ...args) => {
@@ -135,8 +134,8 @@ export const TimePicker = sveltify<
}}
onChange={(date, ...args) => {
const formattedDate = formatDate(date);
- onChange?.(formattedDate, ...args);
onValueChange(formattedDate as number);
+ onChange?.(formattedDate, ...args);
}}
onCalendarChange={(date, ...args) => {
const formattedDate = formatDate(date);
diff --git a/frontend/antd/timeline/Index.svelte b/frontend/antd/timeline/Index.svelte
index 7b2b3299..c595a2e1 100644
--- a/frontend/antd/timeline/Index.svelte
+++ b/frontend/antd/timeline/Index.svelte
@@ -1,72 +1,59 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/timeline/item/Index.svelte b/frontend/antd/timeline/item/Index.svelte
index 14e0bfe7..85914093 100644
--- a/frontend/antd/timeline/item/Index.svelte
+++ b/frontend/antd/timeline/item/Index.svelte
@@ -1,92 +1,64 @@
-
- {#if $mergedProps.visible}
-
-
+ {#if proceedProps.visible}
+ {@render children?.()}
{/if}
{/await}
-
-
diff --git a/frontend/antd/timeline/item/package.json b/frontend/antd/timeline/item/package.json
index 397ceb79..08b81e46 100644
--- a/frontend/antd/timeline/item/package.json
+++ b/frontend/antd/timeline/item/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/timeline/package.json b/frontend/antd/timeline/package.json
index 401e27e8..5c4452b9 100644
--- a/frontend/antd/timeline/package.json
+++ b/frontend/antd/timeline/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/tooltip/Index.svelte b/frontend/antd/tooltip/Index.svelte
index cde36b81..2fd12464 100644
--- a/frontend/antd/tooltip/Index.svelte
+++ b/frontend/antd/tooltip/Index.svelte
@@ -1,73 +1,69 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/tooltip/package.json b/frontend/antd/tooltip/package.json
index 11f0309f..301a67ea 100644
--- a/frontend/antd/tooltip/package.json
+++ b/frontend/antd/tooltip/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/tooltip/tooltip.tsx b/frontend/antd/tooltip/tooltip.tsx
index b06d47b6..d236ced6 100644
--- a/frontend/antd/tooltip/tooltip.tsx
+++ b/frontend/antd/tooltip/tooltip.tsx
@@ -14,7 +14,9 @@ export const Tooltip = sveltify, ['title']>(
{...props}
afterOpenChange={afterOpenChangeFunction}
getPopupContainer={getPopupContainerFunction}
- title={slots.title ?
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/tour/package.json b/frontend/antd/tour/package.json
index c3510ef4..4a377592 100644
--- a/frontend/antd/tour/package.json
+++ b/frontend/antd/tour/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/tour/step/Index.svelte b/frontend/antd/tour/step/Index.svelte
index 1a1e83de..bffa61af 100644
--- a/frontend/antd/tour/step/Index.svelte
+++ b/frontend/antd/tour/step/Index.svelte
@@ -1,96 +1,81 @@
-
- {#if $mergedProps.visible}
-
{/await}
diff --git a/frontend/antd/tour/step/package.json b/frontend/antd/tour/step/package.json
index c2f358e2..16110e29 100644
--- a/frontend/antd/tour/step/package.json
+++ b/frontend/antd/tour/step/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/tour/tour.tsx b/frontend/antd/tour/tour.tsx
index c5b17ef6..bf5db7cc 100644
--- a/frontend/antd/tour/tour.tsx
+++ b/frontend/antd/tour/tour.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React, { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { renderItems } from '@utils/renderItems';
@@ -12,7 +11,6 @@ import { useItems, withItemsContextProvider } from './context';
export const Tour = sveltify<
GetProps & {
children?: React.ReactNode;
- setSlotParams: SetSlotParams;
},
['closeIcon', 'indicatorsRender', 'actionsRender']
>(
@@ -25,7 +23,6 @@ export const Tour = sveltify<
onChange,
onClose,
getPopupContainer,
- setSlotParams,
indicatorsRender,
actionsRender,
...props
@@ -63,7 +60,6 @@ export const Tour = sveltify<
slots.actionsRender
? renderParamsSlot({
slots,
- setSlotParams,
key: 'actionsRender',
})
: actionsRenderFunction
@@ -72,7 +68,6 @@ export const Tour = sveltify<
slots.indicatorsRender
? renderParamsSlot({
slots,
- setSlotParams,
key: 'indicatorsRender',
})
: indicatorsRenderFunction
diff --git a/frontend/antd/transfer/Index.svelte b/frontend/antd/transfer/Index.svelte
index 3887b7a7..844d3c63 100644
--- a/frontend/antd/transfer/Index.svelte
+++ b/frontend/antd/transfer/Index.svelte
@@ -1,91 +1,86 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
- {setSlotParams}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/transfer/package.json b/frontend/antd/transfer/package.json
index 7bdd6254..25357c9d 100644
--- a/frontend/antd/transfer/package.json
+++ b/frontend/antd/transfer/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/transfer/transfer.tsx b/frontend/antd/transfer/transfer.tsx
index ba4cd1a9..67d04a12 100644
--- a/frontend/antd/transfer/transfer.tsx
+++ b/frontend/antd/transfer/transfer.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { useTargets } from '@utils/hooks/useTargets';
@@ -11,7 +10,6 @@ export const Transfer = sveltify<
GetProps & {
children?: React.ReactNode;
onValueChange: (value: (string | number)[]) => void;
- setSlotParams: SetSlotParams;
},
[
'selectionsIcon',
@@ -20,6 +18,7 @@ export const Transfer = sveltify<
'locale.notFoundContent',
'selectAllLabels',
'render',
+ 'actions',
]
>(
({
@@ -32,11 +31,11 @@ export const Transfer = sveltify<
locale,
onChange,
onValueChange,
- setSlotParams,
...props
}) => {
const titles = useTargets(children, 'titles');
const selectAllLabels = useTargets(children, 'selectAllLabels');
+ const actions = useTargets(children, 'actions');
const renderFunction = useFunction(render);
const listStyleFunction = useFunction(listStyle);
const footerFunction = useFunction(footer);
@@ -47,8 +46,8 @@ export const Transfer = sveltify<
{
- onChange?.(targetKeys, ...args);
onValueChange(targetKeys as (string | number)[]);
+ onChange?.(targetKeys, ...args);
}}
selectionsIcon={
slots.selectionsIcon ? (
@@ -69,7 +68,7 @@ export const Transfer = sveltify<
}
render={
slots.render
- ? renderParamsSlot({ slots, setSlotParams, key: 'render' })
+ ? renderParamsSlot({ slots, key: 'render' })
: renderFunction ||
((item) => ({
label: item.title || item.label,
@@ -79,7 +78,7 @@ export const Transfer = sveltify<
filterOption={filterOptionFunction}
footer={
slots.footer
- ? renderParamsSlot({ slots, setSlotParams, key: 'footer' })
+ ? renderParamsSlot({ slots, key: 'footer' })
: footerFunction || footer
}
titles={
@@ -90,6 +89,13 @@ export const Transfer = sveltify<
: props.titles
}
listStyle={listStyleFunction || listStyle}
+ actions={
+ actions.length > 0
+ ? actions.map((target, index) => {
+ return {
- value = val;
+ style={proceedProps.elem_style}
+ className={cls(proceedProps.elem_classes, 'ms-gr-antd-tree-select')}
+ id={proceedProps.elem_id}
+ {...proceedProps.restProps}
+ {...proceedProps.additionalProps}
+ slots={slots.value}
+ onValueChange={(v) => {
+ updateProps({
+ value: v,
+ });
}}
- {setSlotParams}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/tree-select/package.json b/frontend/antd/tree-select/package.json
index 00b433f7..01858a39 100644
--- a/frontend/antd/tree-select/package.json
+++ b/frontend/antd/tree-select/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/tree-select/tree-node/Index.svelte b/frontend/antd/tree-select/tree-node/Index.svelte
index c4e5699a..5ebfb091 100644
--- a/frontend/antd/tree-select/tree-node/Index.svelte
+++ b/frontend/antd/tree-select/tree-node/Index.svelte
@@ -1,103 +1,80 @@
-
-
+ {@render children?.()}
+
{/await}
{/if}
diff --git a/frontend/antd/tree-select/tree-node/package.json b/frontend/antd/tree-select/tree-node/package.json
index b2b3e659..df2b9838 100644
--- a/frontend/antd/tree-select/tree-node/package.json
+++ b/frontend/antd/tree-select/tree-node/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/tree-select/tree-select.tsx b/frontend/antd/tree-select/tree-select.tsx
index 4ca01312..8dbf1864 100644
--- a/frontend/antd/tree-select/tree-select.tsx
+++ b/frontend/antd/tree-select/tree-select.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React, { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { omitUndefinedProps } from '@utils/omitUndefinedProps';
@@ -16,7 +15,6 @@ export const TreeSelect = sveltify<
TreeSelectProps & {
onValueChange: (options: string | string[]) => void;
onLoadData?: (...args: any[]) => Promise;
- setSlotParams: SetSlotParams;
},
[
'allowClear.clearIcon',
@@ -47,7 +45,6 @@ export const TreeSelect = sveltify<
children,
maxTagPlaceholder,
elRef,
- setSlotParams,
onLoadData,
...props
}) => {
@@ -87,10 +84,10 @@ export const TreeSelect = sveltify<
}
),
dropdownRender: slots.dropdownRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'dropdownRender' })
+ ? renderParamsSlot({ slots, key: 'dropdownRender' })
: dropdownRenderFunction,
popupRender: slots.popupRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'popupRender' })
+ ? renderParamsSlot({ slots, key: 'popupRender' })
: popupRenderFunction,
allowClear: slots['allowClear.clearIcon']
? {
@@ -108,20 +105,19 @@ export const TreeSelect = sveltify<
props.prefix
),
switcherIcon: slots.switcherIcon
- ? renderParamsSlot({ slots, setSlotParams, key: 'switcherIcon' })
+ ? renderParamsSlot({ slots, key: 'switcherIcon' })
: props.switcherIcon,
getPopupContainer: getPopupContainerFunction,
tagRender: slots.tagRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'tagRender' })
+ ? renderParamsSlot({ slots, key: 'tagRender' })
: tagRenderFunction,
treeTitleRender: slots.treeTitleRender
- ? renderParamsSlot({ slots, setSlotParams, key: 'treeTitleRender' })
+ ? renderParamsSlot({ slots, key: 'treeTitleRender' })
: treeTitleRenderFunction,
filterTreeNode: filterTreeNodeFunction || filterTreeNode,
maxTagPlaceholder: slots.maxTagPlaceholder
? renderParamsSlot({
slots,
- setSlotParams,
key: 'maxTagPlaceholder',
})
: maxTagPlaceholder,
@@ -140,7 +136,6 @@ export const TreeSelect = sveltify<
maxTagPlaceholder,
onLoadData,
props,
- setSlotParams,
resolvedSlotItems,
slots,
tagRenderFunction,
@@ -155,8 +150,8 @@ export const TreeSelect = sveltify<
{...omitUndefinedProps(componentProps)}
ref={elRef}
onChange={(v, ...args) => {
- onChange?.(v, ...args);
onValueChange(v as string | string[]);
+ onChange?.(v, ...args);
}}
/>
diff --git a/frontend/antd/tree/Index.svelte b/frontend/antd/tree/Index.svelte
index 717b1e47..57218ec7 100644
--- a/frontend/antd/tree/Index.svelte
+++ b/frontend/antd/tree/Index.svelte
@@ -1,84 +1,79 @@
-
-
{/await}
{/if}
diff --git a/frontend/antd/tree/directory-tree/Index.svelte b/frontend/antd/tree/directory-tree/Index.svelte
index 25a233f3..bc19f31c 100644
--- a/frontend/antd/tree/directory-tree/Index.svelte
+++ b/frontend/antd/tree/directory-tree/Index.svelte
@@ -1,88 +1,82 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/tree/directory-tree/package.json b/frontend/antd/tree/directory-tree/package.json
index bd4c7e70..3ced8353 100644
--- a/frontend/antd/tree/directory-tree/package.json
+++ b/frontend/antd/tree/directory-tree/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/tree/package.json b/frontend/antd/tree/package.json
index e4245db8..3317c75c 100644
--- a/frontend/antd/tree/package.json
+++ b/frontend/antd/tree/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/tree/tree-node/Index.svelte b/frontend/antd/tree/tree-node/Index.svelte
index 3a486a04..81c73a80 100644
--- a/frontend/antd/tree/tree-node/Index.svelte
+++ b/frontend/antd/tree/tree-node/Index.svelte
@@ -1,97 +1,75 @@
-
-
-{#await AwaitedTreeTreeNode then TreeTreeNode}
-
- {#if $mergedProps.visible}
-
+
{/await}
diff --git a/frontend/antd/tree/tree-node/package.json b/frontend/antd/tree/tree-node/package.json
index c6843cfa..bed2681d 100644
--- a/frontend/antd/tree/tree-node/package.json
+++ b/frontend/antd/tree/tree-node/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/tree/tree.tsx b/frontend/antd/tree/tree.tsx
index 18218f34..7f49dcd7 100644
--- a/frontend/antd/tree/tree.tsx
+++ b/frontend/antd/tree/tree.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import React, { useMemo } from 'react';
import { useFunction } from '@utils/hooks/useFunction';
import { omitUndefinedProps } from '@utils/omitUndefinedProps';
@@ -15,7 +14,6 @@ type TreeProps = GetProps;
export const Tree = sveltify<
TreeProps & {
directory?: boolean;
- setSlotParams: SetSlotParams;
onLoadData?: (...args: any[]) => Promise;
},
[
@@ -40,7 +38,6 @@ export const Tree = sveltify<
onExpand,
children,
directory,
- setSlotParams,
onLoadData,
titleRender,
...props
@@ -84,13 +81,12 @@ export const Tree = sveltify<
? {
showLeafIcon: renderParamsSlot({
slots,
- setSlotParams,
key: 'showLine.showLeafIcon',
}),
}
: props.showLine,
icon: slots.icon
- ? renderParamsSlot({ slots, setSlotParams, key: 'icon' })
+ ? renderParamsSlot({ slots, key: 'icon' })
: props.icon,
switcherLoadingIcon: slots.switcherLoadingIcon ? (
- {#if $mergedProps._internal.layout}
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/typography/link/Index.svelte b/frontend/antd/typography/link/Index.svelte
index aa30731f..62e0e04f 100644
--- a/frontend/antd/typography/link/Index.svelte
+++ b/frontend/antd/typography/link/Index.svelte
@@ -1,12 +1,11 @@
- &
GetProps & {
component: 'title' | 'paragraph' | 'text' | 'link';
- setSlotParams: SetSlotParams;
value?: string;
},
[
@@ -47,7 +45,6 @@ export const TypographyBase = sveltify<
copyable,
editable,
ellipsis,
- setSlotParams,
value,
...props
}) => {
@@ -141,7 +138,6 @@ export const TypographyBase = sveltify<
? renderParamsSlot(
{
key: 'ellipsis.symbol',
- setSlotParams,
slots,
},
{ clone: true }
diff --git a/frontend/antd/upload/Index.svelte b/frontend/antd/upload/Index.svelte
index 2613108f..596e1b99 100644
--- a/frontend/antd/upload/Index.svelte
+++ b/frontend/antd/upload/Index.svelte
@@ -1,88 +1,85 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
upload={async (files) => {
return (
- (await gradio.client.upload(await prepare_files(files), root)) || []
+ (await proceedProps.gradio.shared.client.upload(
+ await prepare_files(files),
+ proceedProps.gradio.shared.root
+ )) || []
).map((file, i) => {
if (!file) {
return file;
@@ -93,12 +90,8 @@
};
});
}}
- {setSlotParams}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/upload/dragger/Index.svelte b/frontend/antd/upload/dragger/Index.svelte
index 0c75d548..1536755a 100644
--- a/frontend/antd/upload/dragger/Index.svelte
+++ b/frontend/antd/upload/dragger/Index.svelte
@@ -1,94 +1,99 @@
- {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
upload={async (files) => {
return (
- (await gradio.client.upload(await prepare_files(files), root)) || []
- );
+ (await proceedProps.gradio.shared.client.upload(
+ await prepare_files(files),
+ proceedProps.gradio.shared.root
+ )) || []
+ ).map((file, i) => {
+ if (!file) {
+ return file;
+ }
+ return {
+ ...file,
+ uid: files[i].uid,
+ };
+ });
}}
- {setSlotParams}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/upload/dragger/package.json b/frontend/antd/upload/dragger/package.json
index b68a119d..a2b1ff9e 100644
--- a/frontend/antd/upload/dragger/package.json
+++ b/frontend/antd/upload/dragger/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/upload/dragger/upload.dragger.tsx b/frontend/antd/upload/dragger/upload.dragger.tsx
index 2395e3d9..1d5e8fe6 100644
--- a/frontend/antd/upload/dragger/upload.dragger.tsx
+++ b/frontend/antd/upload/dragger/upload.dragger.tsx
@@ -1,5 +1,4 @@
import { sveltify } from '@svelte-preprocess-react';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useEffect, useMemo, useState } from 'react';
import type { FileData } from '@gradio/client';
import { useFunction } from '@utils/hooks/useFunction';
@@ -24,7 +23,6 @@ export const UploadDragger = sveltify<
onChange?: (value: string[]) => void;
upload: (files: RcFile[]) => Promise<(FileData | null)[]>;
fileList: FileData[];
- setSlotParams: SetSlotParams;
},
[
'showUploadList.extra',
@@ -51,10 +49,22 @@ export const UploadDragger = sveltify<
onValueChange,
onRemove,
fileList: fileListProp,
- setSlotParams,
maxCount,
+ accept,
...props
}) => {
+ const acceptConfig = getConfig(accept);
+ const acceptFilterFunction = useFunction(acceptConfig.filter, true);
+ const resolvedAccept: typeof accept =
+ typeof accept === 'boolean'
+ ? accept
+ : accept
+ ? {
+ ...acceptConfig,
+ format: acceptConfig.format,
+ filter: acceptFilterFunction || acceptConfig.filter,
+ }
+ : undefined;
const supportShowUploadListConfig =
slots['showUploadList.downloadIcon'] ||
slots['showUploadList.removeIcon'] ||
@@ -117,6 +127,7 @@ export const UploadDragger = sveltify<
return (
{
@@ -251,28 +262,24 @@ export const UploadDragger = sveltify<
downloadIcon: slots['showUploadList.downloadIcon']
? renderParamsSlot({
slots,
- setSlotParams,
key: 'showUploadList.downloadIcon',
})
: showUploadListConfig.downloadIcon,
removeIcon: slots['showUploadList.removeIcon']
? renderParamsSlot({
slots,
- setSlotParams,
key: 'showUploadList.removeIcon',
})
: showUploadListConfig.removeIcon,
previewIcon: slots['showUploadList.previewIcon']
? renderParamsSlot({
slots,
- setSlotParams,
key: 'showUploadList.previewIcon',
})
: showUploadListConfig.previewIcon,
extra: slots['showUploadList.extra']
? renderParamsSlot({
slots,
- setSlotParams,
key: 'showUploadList.extra',
})
: showUploadListConfig.extra,
diff --git a/frontend/antd/upload/package.json b/frontend/antd/upload/package.json
index d07c445d..276fa140 100644
--- a/frontend/antd/upload/package.json
+++ b/frontend/antd/upload/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/upload/upload.tsx b/frontend/antd/upload/upload.tsx
index 1c6c1123..c9f7f87b 100644
--- a/frontend/antd/upload/upload.tsx
+++ b/frontend/antd/upload/upload.tsx
@@ -1,5 +1,4 @@
import { sveltify } from '@svelte-preprocess-react';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useEffect, useMemo, useState } from 'react';
import type { FileData } from '@gradio/client';
import { useFunction } from '@utils/hooks/useFunction';
@@ -25,7 +24,6 @@ export const Upload = sveltify<
onChange?: (value: string[]) => void;
upload: (files: RcFile[]) => Promise<(FileData | null)[]>;
fileList: FileData[];
- setSlotParams: SetSlotParams;
},
[
'showUploadList.extra',
@@ -53,9 +51,21 @@ export const Upload = sveltify<
onRemove,
maxCount,
fileList: fileListProp,
- setSlotParams,
+ accept,
...props
}) => {
+ const acceptConfig = getConfig(accept);
+ const acceptFilterFunction = useFunction(acceptConfig.filter, true);
+ const resolvedAccept: typeof accept =
+ typeof accept === 'boolean'
+ ? accept
+ : accept
+ ? {
+ ...acceptConfig,
+ format: acceptConfig.format,
+ filter: acceptFilterFunction || acceptConfig.filter,
+ }
+ : undefined;
const supportShowUploadListConfig =
slots['showUploadList.downloadIcon'] ||
slots['showUploadList.removeIcon'] ||
@@ -119,6 +129,7 @@ export const Upload = sveltify<
return (
{
@@ -252,28 +263,24 @@ export const Upload = sveltify<
downloadIcon: slots['showUploadList.downloadIcon']
? renderParamsSlot({
slots,
- setSlotParams,
key: 'showUploadList.downloadIcon',
})
: showUploadListConfig.downloadIcon,
removeIcon: slots['showUploadList.removeIcon']
? renderParamsSlot({
slots,
- setSlotParams,
key: 'showUploadList.removeIcon',
})
: showUploadListConfig.removeIcon,
previewIcon: slots['showUploadList.previewIcon']
? renderParamsSlot({
slots,
- setSlotParams,
key: 'showUploadList.previewIcon',
})
: showUploadListConfig.previewIcon,
extra: slots['showUploadList.extra']
? renderParamsSlot({
slots,
- setSlotParams,
key: 'showUploadList.extra',
})
: showUploadListConfig.extra,
diff --git a/frontend/antd/watermark/Index.svelte b/frontend/antd/watermark/Index.svelte
index eb78d15d..ee8b5433 100644
--- a/frontend/antd/watermark/Index.svelte
+++ b/frontend/antd/watermark/Index.svelte
@@ -1,76 +1,64 @@
-
-
{/await}
{/if}
-
-
diff --git a/frontend/antd/watermark/package.json b/frontend/antd/watermark/package.json
index 26c38a1e..77b9c5ff 100644
--- a/frontend/antd/watermark/package.json
+++ b/frontend/antd/watermark/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antdx/CHANGELOG.md b/frontend/antdx/CHANGELOG.md
index 247f0933..1df71eab 100644
--- a/frontend/antdx/CHANGELOG.md
+++ b/frontend/antdx/CHANGELOG.md
@@ -1,5 +1,17 @@
# @modelscope-studio/antdx
+## 2.0.0-beta.1
+
+### Features
+
+- [`e009cd0`](https://github.com/modelscope/modelscope-studio/commit/e009cd0408d4505f4105e494af192c6f832fa48c) - complete new features of antd & antdx. Thanks [@Col0ring](https://github.com/Col0ring)!
+
+## 2.0.0-beta.0
+
+### Misc Changes
+
+- [`26ea248`](https://github.com/modelscope/modelscope-studio/commit/26ea2485990098ea60e95ff8b3e71dad713a3aba) - migrate to Gradio 6.0, Ant Design 6.0, Ant Design X 2.0. Thanks [@Col0ring](https://github.com/Col0ring)!
+
## 1.6.1
No significant changes to this package were made in this release.
diff --git a/frontend/antdx/actions/Index.svelte b/frontend/antdx/actions/Index.svelte
index ec9e7ede..8d8bb15a 100644
--- a/frontend/antdx/actions/Index.svelte
+++ b/frontend/antdx/actions/Index.svelte
@@ -1,70 +1,76 @@
-
-
{/await}
{/if}
diff --git a/frontend/antdx/actions/action-item/Index.svelte b/frontend/antdx/actions/action-item/Index.svelte
new file mode 100644
index 00000000..e66bf489
--- /dev/null
+++ b/frontend/antdx/actions/action-item/Index.svelte
@@ -0,0 +1,98 @@
+
+
+{#if proceedProps.visible}
+ {#await AwaitedActionsActionItem then ActionsActionItem}
+
+ {@render children?.()}
+
+ {/await}
+{/if}
diff --git a/frontend/antdx/actions/action-item/actions.action-item.tsx b/frontend/antdx/actions/action-item/actions.action-item.tsx
new file mode 100644
index 00000000..7e824d09
--- /dev/null
+++ b/frontend/antdx/actions/action-item/actions.action-item.tsx
@@ -0,0 +1,22 @@
+import { sveltify } from '@svelte-preprocess-react';
+import React from 'react';
+import type { ActionsProps } from '@ant-design/x';
+
+import { ItemHandler, type ItemHandlerProps } from '../context';
+
+export const ActionsActionItem = sveltify<
+ Partial[number]> & ItemHandlerProps
+>((props) => {
+ return (
+
+ {...props}
+ allowedSlots={['default', 'subItems']}
+ itemChildrenKey="subItems"
+ itemChildren={(items) => {
+ return items.subItems.length > 0 ? items.subItems : items.default;
+ }}
+ />
+ );
+});
+
+export default ActionsActionItem;
diff --git a/frontend/antdx/actions/action-item/gradio.config.js b/frontend/antdx/actions/action-item/gradio.config.js
new file mode 100644
index 00000000..1992403d
--- /dev/null
+++ b/frontend/antdx/actions/action-item/gradio.config.js
@@ -0,0 +1,3 @@
+import config from '../../../defineConfig.js';
+
+export default config();
diff --git a/frontend/antdx/actions/action-item/package.json b/frontend/antdx/actions/action-item/package.json
new file mode 100644
index 00000000..0be1840a
--- /dev/null
+++ b/frontend/antdx/actions/action-item/package.json
@@ -0,0 +1,14 @@
+{
+ "name": "@modelscope-studio/antdx-actions.action-item",
+ "type": "module",
+ "exports": {
+ ".": {
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
+ },
+ "./package.json": {
+ "gradio": "./package.json",
+ "default": "./package.json"
+ }
+ }
+}
diff --git a/frontend/antdx/actions/actions.tsx b/frontend/antdx/actions/actions.tsx
index fc9cbe1d..238799bd 100644
--- a/frontend/antdx/actions/actions.tsx
+++ b/frontend/antdx/actions/actions.tsx
@@ -1,39 +1,121 @@
import { sveltify } from '@svelte-preprocess-react';
import React, { useMemo } from 'react';
import { Actions as XActions, type ActionsProps } from '@ant-design/x';
-import type { ActionItem } from '@ant-design/x/es/actions/interface';
+import type { ItemType } from '@ant-design/x/es/actions/interface';
+import { createFunction } from '@utils/createFunction';
import { renderItems } from '@utils/renderItems';
-import classNames from 'classnames';
+import { renderParamsSlot } from '@utils/renderParamsSlot';
+import { renderSlot } from '@utils/renderSlot';
+
+import {
+ useItems as useMenuItems,
+ withItemsContextProvider as withMenuItemsContextProvider,
+} from '../../antd/menu/context';
import { useItems, withItemsContextProvider } from './context';
-export const Actions = sveltify>(
- withItemsContextProvider(
- ['default', 'items'],
- ({ children, items, className, ...props }) => {
- const { items: slotItems } = useItems<['default', 'items']>();
- const resolvedSlotItems =
- slotItems.items.length > 0 ? slotItems.items : slotItems.default;
-
- return (
- <>
- {
- return (
- items ||
- renderItems(resolvedSlotItems, {
+export const Actions = sveltify<
+ Partial,
+ [
+ 'dropdownProps.dropdownRender',
+ 'dropdownProps.popupRender',
+ 'dropdownProps.menu.expandIcon',
+ 'dropdownProps.menu.overflowedIndicator',
+ 'dropdownProps.menu.items',
+ ]
+>(
+ withMenuItemsContextProvider(
+ ['dropdownProps.menu.items'],
+ withItemsContextProvider(
+ ['default', 'items'],
+ ({ children, items, dropdownProps, slots, ...props }) => {
+ const { items: slotItems } = useItems<['default', 'items']>();
+ const resolvedSlotItems =
+ slotItems.items.length > 0 ? slotItems.items : slotItems.default;
+ const {
+ items: { 'dropdownProps.menu.items': dropdownMenuItems },
+ } = useMenuItems<['dropdownProps.menu.items']>();
+
+ const modifiedDropdownProps = useMemo(() => {
+ const dropdownMenu = {
+ ...(dropdownProps?.menu || {}),
+ items:
+ dropdownProps?.menu?.items || dropdownMenuItems?.length > 0
+ ? renderItems(dropdownMenuItems, {
+ clone: true,
+ })
+ : undefined,
+ expandIcon:
+ renderParamsSlot(
+ {
+ slots: slots,
+ key: 'dropdownProps.menu.expandIcon',
+ },
+ {
clone: true,
- }) ||
- []
- );
- }, [items, resolvedSlotItems])}
- />
-
- );
- }
+ }
+ ) || dropdownProps?.menu?.expandIcon,
+ overflowedIndicator:
+ renderSlot(slots['dropdownProps.menu.overflowedIndicator']) ||
+ dropdownProps?.menu?.overflowedIndicator,
+ };
+
+ const modifiedProps = {
+ ...(dropdownProps || {}),
+ dropdownRender: slots['dropdownProps.dropdownRender']
+ ? renderParamsSlot(
+ {
+ slots: slots,
+ key: 'dropdownProps.dropdownRender',
+ },
+ {
+ clone: true,
+ }
+ )
+ : createFunction(dropdownProps?.dropdownRender),
+ popupRender: slots['dropdownProps.popupRender']
+ ? renderParamsSlot(
+ {
+ slots: slots,
+ key: 'dropdownProps.popupRender',
+ },
+ {
+ clone: true,
+ }
+ )
+ : createFunction(dropdownProps?.popupRender),
+ menu:
+ Object.values(dropdownMenu).filter(Boolean).length > 0
+ ? dropdownMenu
+ : undefined,
+ } as NonNullable;
+
+ return Object.values(modifiedProps).filter(Boolean).length > 0
+ ? dropdownProps
+ : undefined;
+ }, [dropdownMenuItems, dropdownProps, slots]);
+
+ return (
+ <>
+ {
+ return (
+ items ||
+ renderItems(resolvedSlotItems, {
+ clone: true,
+ children: 'subItems',
+ }) ||
+ []
+ );
+ }, [items, resolvedSlotItems])}
+ />
+
+ );
+ }
+ )
)
);
diff --git a/frontend/antdx/actions/audio/Index.svelte b/frontend/antdx/actions/audio/Index.svelte
new file mode 100644
index 00000000..e048e4b1
--- /dev/null
+++ b/frontend/antdx/actions/audio/Index.svelte
@@ -0,0 +1,59 @@
+
+
+{#if proceedProps.visible}
+ {#await AwaitedActionsAudio then ActionsAudio}
+
+ {@render children?.()}
+
+ {/await}
+{/if}
diff --git a/frontend/antdx/actions/audio/actions.audio.tsx b/frontend/antdx/actions/audio/actions.audio.tsx
new file mode 100644
index 00000000..5f1394a9
--- /dev/null
+++ b/frontend/antdx/actions/audio/actions.audio.tsx
@@ -0,0 +1,16 @@
+import { sveltify } from '@svelte-preprocess-react';
+import React from 'react';
+import { Actions } from '@ant-design/x';
+import type { ActionsAudioProps } from '@ant-design/x/es/actions/ActionsAudio';
+
+export const ActionsAudio = sveltify(
+ ({ slots: _slots, ...props }) => {
+ return (
+ <>
+
+ {@render children?.()}
+
+ {/await}
+{/if}
diff --git a/frontend/antdx/actions/copy/actions.copy.tsx b/frontend/antdx/actions/copy/actions.copy.tsx
new file mode 100644
index 00000000..bdaf5424
--- /dev/null
+++ b/frontend/antdx/actions/copy/actions.copy.tsx
@@ -0,0 +1,21 @@
+import { sveltify } from '@svelte-preprocess-react';
+import { ReactSlot } from '@svelte-preprocess-react/react-slot';
+import React from 'react';
+import { Actions } from '@ant-design/x';
+import type { ActionsCopyProps } from '@ant-design/x/es/actions/ActionsCopy';
+
+export const ActionsCopy = sveltify(
+ ({ slots, children, ...props }) => {
+ return (
+ <>
+
+ {@render children?.()}
+
+ {/await}
+{/if}
diff --git a/frontend/antdx/actions/feedback/actions.feedback.tsx b/frontend/antdx/actions/feedback/actions.feedback.tsx
new file mode 100644
index 00000000..f73b9b9c
--- /dev/null
+++ b/frontend/antdx/actions/feedback/actions.feedback.tsx
@@ -0,0 +1,15 @@
+import { sveltify } from '@svelte-preprocess-react';
+import React from 'react';
+import { Actions, type ActionsFeedbackProps } from '@ant-design/x';
+
+export const ActionsFeedback = sveltify(
+ ({ slots: _slots, ...props }) => {
+ return (
+ <>
+
-
{/await}
{/if}
diff --git a/frontend/antdx/actions/item/actions.item.tsx b/frontend/antdx/actions/item/actions.item.tsx
index 78757dc0..49193511 100644
--- a/frontend/antdx/actions/item/actions.item.tsx
+++ b/frontend/antdx/actions/item/actions.item.tsx
@@ -1,20 +1,33 @@
import { sveltify } from '@svelte-preprocess-react';
+import { ReactSlot } from '@svelte-preprocess-react/react-slot';
import React from 'react';
-import type { ActionsProps } from '@ant-design/x';
-
-import { ItemHandler, type ItemHandlerProps } from '../context';
+import { Actions, type ActionsItemProps } from '@ant-design/x';
export const ActionsItem = sveltify<
- Partial[number]> & ItemHandlerProps
->((props) => {
+ Partial,
+ ['defaultIcon', 'runningIcon']
+>(({ slots, children, ...props }) => {
return (
-
- {...props}
- allowedSlots={['default']}
- itemChildren={(items) => {
- return items.default.length > 0 ? items.default : undefined;
- }}
- />
+ <>
+ {
- value = v;
+ updateProps({
+ value: v,
+ });
}}
upload={async (files) => {
return (
- (await gradio.client.upload(await prepare_files(files), root)) || []
+ (await proceedProps.gradio.shared.client.upload(
+ await prepare_files(files),
+ proceedProps.gradio.shared.root
+ )) || []
).map((file, i) => {
if (!file) {
return file;
@@ -93,12 +90,8 @@
};
});
}}
- {setSlotParams}
>
-
{/await}
{/if}
-
-
diff --git a/frontend/antdx/attachments/attachments.tsx b/frontend/antdx/attachments/attachments.tsx
index df4db24b..8b4f4af2 100644
--- a/frontend/antdx/attachments/attachments.tsx
+++ b/frontend/antdx/attachments/attachments.tsx
@@ -1,6 +1,5 @@
import { sveltify } from '@svelte-preprocess-react';
import { ReactSlot } from '@svelte-preprocess-react/react-slot';
-import type { SetSlotParams } from '@svelte-preprocess-react/slot';
import { useEffect, useMemo, useState } from 'react';
import {
Attachments as XAttachments,
@@ -11,11 +10,11 @@ import { useFunction } from '@utils/hooks/useFunction';
import { useTargets } from '@utils/hooks/useTargets';
import { omitUndefinedProps } from '@utils/omitUndefinedProps';
import { renderParamsSlot } from '@utils/renderParamsSlot';
-import { type UploadFile } from 'antd';
+import { type ImageProps, type UploadFile } from 'antd';
import type { RcFile } from 'antd/es/upload';
import { noop } from 'lodash-es';
-import type { FileCardProps } from './file-card/file-card';
+import type { BaseFileCardProps } from '../file-card/base';
const isUploadFile = (file: FileData | UploadFile): file is UploadFile => {
return !!(file as UploadFile).name;
@@ -28,13 +27,18 @@ function getConfig(value: T): Partial> {
return {} as any;
}
+declare module '@ant-design/x' {
+ export interface AttachmentsProps {
+ imageProps?: ImageProps;
+ }
+}
+
export const Attachments = sveltify<
Omit & {
onValueChange?: (value: FileData[]) => void;
onChange?: (value: string[]) => void;
upload: (files: RcFile[]) => Promise<(FileData | null)[]>;
items: FileData[];
- setSlotParams: SetSlotParams;
},
[
'showUploadList.extra',
@@ -70,14 +74,26 @@ export const Attachments = sveltify<
onValueChange,
onRemove,
items,
- setSlotParams,
placeholder,
getDropContainer,
children,
maxCount,
imageProps,
+ accept,
...props
}) => {
+ const acceptConfig = getConfig(accept);
+ const acceptFilterFunction = useFunction(acceptConfig.filter, true);
+ const resolvedAccept: typeof accept =
+ typeof accept === 'boolean'
+ ? accept
+ : accept
+ ? {
+ ...acceptConfig,
+ format: acceptConfig.format,
+ filter: acceptFilterFunction || acceptConfig.filter,
+ }
+ : undefined;
// imageProps
const previewConfig = getConfig(imageProps?.preview);
const supportPreview =
@@ -163,7 +179,6 @@ export const Attachments = sveltify<
}, [fileList]);
const targets = useTargets(children);
const uploadDisabled = props.disabled || uploading;
-
return (
<>
{children}
@@ -21,7 +30,12 @@ export const Alert = sveltify<
closable={
slots['closable.closeIcon']
? {
- ...(typeof props.closable === 'object' ? props.closable : {}),
+ ...(typeof props.closable === 'object'
+ ? props.closable
+ : {
+ ...closableConfig,
+ afterClose: closableAfterCloseFunction,
+ }),
closeIcon: {children}
{children}
@@ -34,8 +33,8 @@ export const CheckboxGroup = sveltify<
);
}, [resolvedSlotItems, options])}
onChange={(v: any[]) => {
- onChange?.(v);
onValueChange(v);
+ onChange?.(v);
}}
/>
diff --git a/frontend/antd/checkbox/group/option/Index.svelte b/frontend/antd/checkbox/group/option/Index.svelte
index 5dcfae9e..d1673c87 100644
--- a/frontend/antd/checkbox/group/option/Index.svelte
+++ b/frontend/antd/checkbox/group/option/Index.svelte
@@ -1,107 +1,98 @@
--
-
{children}
+ {children}
@@ -62,7 +60,6 @@ export const Menu = sveltify<
{
key: 'expandIcon',
slots,
- setSlotParams,
},
{
clone: true,
@@ -77,6 +74,19 @@ export const Menu = sveltify<
props.overflowedIndicator
)
}
+ popupRender={
+ slots.popupRender
+ ? renderParamsSlot(
+ {
+ key: 'popupRender',
+ slots,
+ },
+ {
+ clone: true,
+ }
+ )
+ : popupRenderFunction
+ }
/>
);
diff --git a/frontend/antd/menu/package.json b/frontend/antd/menu/package.json
index 21d1e57c..ffd62229 100644
--- a/frontend/antd/menu/package.json
+++ b/frontend/antd/menu/package.json
@@ -3,12 +3,12 @@
"type": "module",
"exports": {
".": {
- "default": "./Index.svelte",
- "gradio": "./Index.svelte"
+ "gradio": "./Index.svelte",
+ "default": "./Index.svelte"
},
"./package.json": {
- "default": "./package.json",
- "gradio": "./package.json"
+ "gradio": "./package.json",
+ "default": "./package.json"
}
}
}
diff --git a/frontend/antd/message/Index.svelte b/frontend/antd/message/Index.svelte
index ea2c175a..1f5bd996 100644
--- a/frontend/antd/message/Index.svelte
+++ b/frontend/antd/message/Index.svelte
@@ -1,81 +1,77 @@
-{children}
@@ -30,12 +28,12 @@ export const Rate = sveltify<
{...props}
ref={elRef}
onChange={(v) => {
- onChange?.(v);
onValueChange(v);
+ onChange?.(v);
}}
character={
slots.character
- ? renderParamsSlot({ slots, setSlotParams, key: 'character' })
+ ? renderParamsSlot({ slots, key: 'character' })
: characterFunction || character
}
/>
diff --git a/frontend/antd/result/Index.svelte b/frontend/antd/result/Index.svelte
index 5f28ee14..d71c4bb4 100644
--- a/frontend/antd/result/Index.svelte
+++ b/frontend/antd/result/Index.svelte
@@ -1,70 +1,60 @@
-{children}
+ {children}
- {children}
+ {children}
+ {children}
+